主要设计点

对于开放的平台而言，主要涉及的问题有以下几点

规范API设计风格和命名规则
版本管理问题
服务端容错设计以及错误信息设计
注意资源分配和流量管控
架构质量属性要求

规范API设计风格和命名规则

常用的Api设计模式：

常见的有RPC(Remote Procedure Call)和ROA(the Rest-Oriented Architecture)两种模式
- 面向资源的设计，即 ROA（Resource oriented architecture）
  - 简洁、规范性强
- 面向过程的设计，即 RPC（Remote Procedure Call）
  - 清晰、好应用、适合复杂业务
  - 需要规范命名，如创建等操作用createXxxx 等
个人推荐最终使用RPC的规范的原因
- API 设计难度较低，容易落地
- 很多云服务产品，大多数成熟的 IAAS 层产品使用 RPC 规范
- 适合复杂业务场景
针对RPC的命名没有明确规范，我们根据我们的实际情况对命名进行规范，如如创建等操作用createXxxx，删除用delXxxx

Api风格需要考虑的问题：

在命名API时，需要遵循一定的范式以确保整体风格的一致性。在动词、名词、和介词的组合方面，需要精心设计，以使API看起来更加统一，降低用户理解的成本。
对于类似的操作，应该采用规范的命名方式，使用公共的标准词汇，以便同类型的操作更容易被理解。例如，在涉及读操作时，可以根据场景选择使用Read、Query、Describe、List或Get等动词，避免使用晦涩奇怪的词汇，提高可读性。
针对广泛使用的参数，需要尽可能保持一致，以避免在不同产品中表达混乱。例如，对于分页参数，可以统一使用PageNumber或PageNum，以确保统一性和可理解性。
在处理常见场景（如幂等、分页、异步API）时，应该制定统一的设计规范，以确保用户在不同API中获得一致的体验，避免引发混淆。
在设计错误码时，需要考虑如何统一公共错误码，以及如何清晰地表达业务错误。公共错误码的设计应当遵循统一的规范，而业务错误码则需要能够明确传达错误的细节，以便用户能够准确理解发生了什么问题。

统一Api 风格的重要性

OpenAPI并不一定非要选择 RESTFul 风格，但一定要统一设计风格。以下说明确定分格的必要性

便于维护和管理
- 一方面是便于管理
- 因为风格不统一，导致开发者对于不同的接口没有一个明确的范式，需要理解成本带来的学习成本高的问题。
- 因为风格不统一，导致开发者需要针对不同的接口做不同的适配层，重复建设。
对外口碑和评价问题
- 开发者对于你的能力和团队水平的评估
- 开发者可以通过对于接口风格、文档质量等多个角度的评估来评价你的产品的质量和结果。
- 虽然开发者并非企业的绝对决策者，但对于那些高度依赖开放性和集成性的业务而言，开发者的评价尤为重要。出色的开发者评价，将会使企业在进行集成相关的决策时，更加放心地进行选择。

版本管理

Api 版本管理和新旧版本的兼容问题

【版本变更的客观原因】
- 同一接口可能由于市场变化，业务线变化等， API接口一定是不断迭代的。
  - 不兼容旧版本接口，可能出现的问题：
    - OpenAPI的用户来说，不兼容的变更意味着需要通知所有的外部开发者，并确保他们完成相应的更新。然而，这个时间节点和周期并不容易控制，跨企业的优先级对齐、时间节点对齐、以及出现问题时的技术支持，都可能会导致OpenAPI变更周期变得非常长，让维护人员感到疲惫不堪。
  - 兼容旧版本接口，可能出现的问题：
    - 与普通的内部使用的API不同，对外的API需要照顾到客户的技术更新周期和条件；
    - 所以我们通常都需要版本管理，这对OpenAPI 接口的设计带来了挑战，维护多个版本的API带来的成本也相当高昂。
【Api变更成本太高】O云服务API直接面向用户，由于调用量巨大，版本变更的影响范围也更广，因此版本更新需谨慎处理。尤其对于旧接口使用的第三方开发者。

版本管理的关键技术点

【及时标记下线接口，将低维护成本】
- 将存量中设计不好的 OpenAPI 标记为 deprecated，引导增量开发者升级使用新版的 API，卡住存量的 API 的新增使用用户。
- 那怕是废弃的接口，也可能需要1-2年才能下线接口。无法下线的 OpenAPI 最终将会指向不断增加的维护成本。毕竟，即使我们可以不在旧版的 OpenAPI 中去提供新的 Feature ，但依然要针对旧版本的 OpenAPI 提供安全更新，这会导致团队的研发成本越来越高。
- 必要时，制定一个接口下线计划，并且通知开发者，下线计划时间不宜太短，建议6个月以上，给开发者足够的时间对接口进行升级。（这里如果合同有签订相关条约的话，最好备注一下）
【版本管理技术实现的思路】
- 通过aop来做版本的校验的选择，这样对代码侵入性最低，后期维护更加简单，有以下情况需要考虑
  - 没有携带版本信息
  - 携带版本信息错误
  - 携带版本信息正确

服务端容错设计以及错误信息设计

需要考虑可能的异常处理、常见性能优化的技术点以及如何更好地传递错误信息

【统一的响应格式和内容】如果有国际化场景，我建议使用英文来描述错误信息。
【确定接口请求是同步、异步、timeout时间】
- 【如果是异步的话】
  - 确定客户获取结果的方式
    - 推送、轮询（拉取）、推拉结合
    - 建议使用推拉结合，即同时使用推送和轮询，主动推送的时候，应该能支持重试，最好是使用延时任务队列实现”最大努力推送“。
    - 客户轮询的接口，注意对接口的访问频率进行限制
  - 由于异步请求，应该提前将数据校验做到位，及时响应给客户。例如user身份信息是否存在，这个校验应该在异步处理之前，提前做好校验，以免在后续过程发生错误，到时候还得想办法将错误信息通知客户。
【统一的错误码设计】
- 设计要点：
  - 每个接口的错误码可以被枚举
    - 这里不是说所有的接口错误类型都要丢给客户，小概率或者系统内部的错误可以用”Unexpected Exception“来cover，对于第三方开发者而言，也是一种可以被枚举的错误码
  - 表达充分
  - 规范简洁
    - 建议参考相关云服务OpenAPI的文档，如百度云、阿里云等，原因如下：
      - 比较规范
      - 降低开发者的学习成本

资源管理和流量管控

如何收费
如何限制资源倾斜（公平性）
如何控制意外流量等等

考虑OpenAPI体系

API发布后，为了确保用户能够顺利地使用API，配套设施至关重要。这包括SDK、文档、以及工具链的集成，而关注点则在于如何保障这些资源的准确性、及时性和一致性。开发工程师通常不太喜欢编写文档，而专业的文档编写者可能不太了解技术，再加上国际化的考虑，这使得整个过程充满了挑战。

sdk
文档（多国语）
教程（多国语）
开发者平台
后台
考虑架构质量
- 可伸缩
- 高可用（SLA）

OpenAPI设计之初容易踩的坑

大部分公司前期的OpenAPI的开放能力会涉及几个问题
- 一个是开发什么能力？
- 怎么计费？
- 有什么业务场景？
- 如何设计接口使其通用性和便用性能达到平衡？
- 建立OpenAPI生态的计划，例如开发者平台、文档、社区等等

由于大部分公司前期的OpenAPI可能一开始不会设计好，绝大多数人没有机会从头设计一个全新的 OpenAPI 系统，大多是需要一边跑一边换轮子的。所以需要注意以下几点：

要做好摸索典型业务场景和变更接口的心理准备，在这个心理准备下，在接口的迭代和设计中，我们不要求接口一下子能满足客户的要求，而是在跟第三方开发者对接的过程中，不断确定接口的适用性以及确定客户的要求。
在对接经验或者开发者不多的情况下，不要花太多时间在思考和设计接口适用性上，除非你们的业务以及沉淀了很久了，有很多对接开发者经验。接口的通用性和便用性需要达到一个非常好的平衡，这种平衡是需要实践和经验来验证的，不是靠空想的。
- 举个例子：我们之前设计了一个堪称可以适用客户不同需求的接口，但是客户用下来发现，由于接口过于灵活，导致客户对接成本高，我们维护成本也高。后面我们把这些接口和文档全部deprecated ，采用更适合客户要求的接口。后面也证明了后上的这些接口更加适合实际的业务场景

cloud.tencent.com/developer/a… 浅析 Open API 设计规范

developer.aliyun.com/article/718… 云服务OpenAPI设计的7大挑战

www.ixiqin.com/2023/09/14/… 为什么API设计那么重要

juejin.cn/post/726820… 如何为开放平台设计一个安全好用的OpenApi

maimai.cn/article/det… OpenAPI 标准规范，了解一下？

云服务OpenAPI的设计要点