一文带你详细了解Open API设计规范

写在前面：

OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。

此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。

在这里插入图片描述

背景

Open API 和前端页面一样，一直都是产品的门面， Open API 不规范，会拉低产品的专业性。在云场景下，很多用户会选择自建门户，对接云产品的 Open API，这对我们提出的诉求便是构建一套成熟的 Open API 机制。

站在业务角度，有一些指导原则，指导我们完善 Open API 机制：

前端页面使用的接口和 Open API 提供的接口是同一套接口
任意的前端页面接口都应该有对应的 Open API

最近由于业务需求，我参与研发的云产品 CSB 需要对外开放 Open API，原本不是什么难事，因为阿里云内部的 Open API 开放机制已经非常成熟了，根本不需要我去设计，但这次的需求主要是针对一些独立部署的场景，需要自行设计一套规范，那就意味着，需要对 Open API 进行一些规范约束了，站在技术角度，阿里云有很多的 API 开放标准可供我们参考，一些开源产品的 Open API 文档也都非常完善。

总之，一方面，我会取其精华，另一方面，要考虑自身产品输出形态的特殊性。本文将围绕诸多因素，尝试探讨出一份合适的 Open API 开放规范。

Open API 设计考虑因素

一个完善的 Open API 规范到底应该规范哪些东西？

站在设计角度，需要考虑：命名规范，构成规范，路径规范，出入参规范，数据类型规范，统一返回值规范，错误码规范，分页规范。

站在团队角度，团队中的后端初级中级开发以及前端研发是否有足够的经验，领悟并落地好制定的 API 规范。同时，伴随着人员流动，这份 Open API 规范是否可以很好地被传承下去。

站在行业角度，需要考虑提供 Open API 的产品所在的市场是否已经成熟，API 风格可能已经有了对应的规范。

站在产品角度，每个产品适合的 API 风格是不同的，下文会着重探讨这一角度。

总之，Open API 的设计是很难形成定论的一个东西，我在介绍自身产品最终采用的 Open API 规范之前，会先来聊一下大家耳熟能详的一些概念，例如 restful。

restful 规范之争

有人的地方就会有江湖。

有代码的地方也是如此。

如果你在码圈混，一定听说过 restful 规范：

增删改查应分别声明为：POST、DELETE、PUT、PATCH、GET
不应该出现动词，动词统一由 HTTP Method 表示
体现出“资源”的抽象
利用 pathVariable，queryParam，header，statusCode 表达很多业务语义

restful 规范看似美好，但如果你真正尝试过落地，一定会遇到一些类似的问题：

以用户登录接口为例，此类接口难以映射到资源的增删改查
以查询最近 7 个小时内的接口请求错误率为例，衍生到诸如 graphQL 这类复杂的查询场景，往往需要 json 结构，GET 是无法实现这一点的，只有 POST 才可以传递

基于此，restful 规范逐渐有了反对的声音：

强行让所有的事物都“资源”化一下，有悖于开发常识，接口不一定都能够通过简单的增删改查来映射
复杂的查询语义不一定能够用 GET 表达

restful 风格的拥趸者，不乏对这些反对言论进行抨击，社区中不免有“拒绝 restful 风格的主要是低水平不思进取的架构师和前后端程序员们，不会设计是人的问题，不是规范的问题”此类的言论。同时对 restful 进行了升华：复杂参数的检索问题，在 restful 语义中本就应当归类为 post，因为该行为并不是对资源的定位（GET），而是对资源的检索（POST）

这显然刺激了 restful 风格反对者的神经，不屑道：呵，愚蠢的 restful 原教旨主义者呀。

不知道你是 restful 的拥趸者还是反对者？亦或是，中立者。

restful 之争暂时到此为止，这番争论纯属虚构，看官不必计较。无论你如何看待 restful，下面我的论述，你都可以作为一个中立者，否则效果减半。

ROA 与 RPC

API 设计并不只有 restful 一种规范，在更大的视角中，主流的 API 设计风格其实可以分为

面向资源的设计，即 ROA（Resource oriented architecture）
面向过程的设计，即 RPC（Remote Procedure Call）

restful 便是 ROA 风格的典型例子，而 RPC 风格则相对而言不太容易被大家熟知，但实际上可能大多数的系统的接口是 RPC 风格的，只不过 RPC 风格这个概念不太为人所知。

以用户模块的 CRUD 为例，对比下两个风格：

ROA 风格

创建用户（POST）

Request:
POST /users

{"name": "kirito", "age": 18}

Response:
HTTP 201 Created

{"id": 1, "name": "kirito", "age": 18}

查询用户（GET）

Request:
GET /users/1

Response:
HTTP 200 OK

{"id": 1, "name": "kirito", "age": 18}

查询用户列表（GET）

Request:
GET /users

Response:
HTTP 200 OK

{[{"id": 1, "name": "kirito", "age": 18}], "next": "/users?offset=1"}

创建/修改用户(PUT)

Request:
PUT /users/1

{"name": "kirito", "age": 19}

Response:
HTTP 200 OK

{"id": 1, "name": "kirito", "age": 19}

修改用户（PATCH）

Request:
PATCH /users/1

{"age": 20}

Response:
HTTP 200 OK

{"id": 1, "name": "kirito", "age": 20}

删除用户（DELETE）

Request:
DELETE /users/1

Response:
HTTP 204 No Content

ROA 风格和 restful 规范说明的是一回事，为方便其与 RPC 风格接口的对比，特此说明上面示例的一些值得关注的点：

使用 HTTP 响应码（200，201，204），完成 HTTP 语义与业务语义的映射，异常流也出现 404，401 等情况（出于篇幅考虑，本文未做异常流的介绍）
PATCH 部分修改资源，请求体是修改部分的内容；PUT 创建/修改资源，请求体是新资源全部的内容
id 是资源定位符，而 age、name 则为属性

RPC 风格

创建用户（POST）

Request:
POST /user/createUser

{"name": "kirito", "age": 18}

Response:
HTTP 200 OK

{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 18}}

查询用户（POST）

Request:
POST /user/getUser

{"id": 1}

Response:
HTTP 200 OK

{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 18}}

查询用户列表（POST）

Request:
POST /user/listUsers

Response:
HTTP 200 OK

{"code": 0, "message": "", "data": {"user": [{"id": 1, "name": "kirito", "age": 18}], "next": "/user/listUsers?offset=1"}}

修改用户(POST)

Request:
POST /user/modifyUser

{"id": 1, "name": "kirito", "age": 19}

Response:
HTTP 200 OK

{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 19}}

修改用户名称(POST)

Request:
POST /user/modifyUserAge

{"id": 1, "age": 20}

Response:
HTTP 200 OK

{"code": 0, "message": "", "data": {"id": 1, "name": "kirito", "age": 20}}

删除用户（DELETE）

Request:
POST /user/deleteUser

{"id": 1}

Response:
{"code": 0, "message": ""}

RPC 风格不像 restful 一类的 ROA 风格存在一些约定俗成的规范，每个业务系统在落地时，都存在差异，故此处只是笔者个人的经验之谈，但愿读者能够求同存异：

user 为模块名，不需要像 ROA 风格使用复数形式
使用明确的动宾结构，而不是将 CRUD 映射到 HTTP Method，HTTP Method 统一使用 POST，查询场景也可以使用 GET
返回值中携带 code、message 和 data，来映射响应状态及响应信息，一般可以自行定义 code 的状态码，本文使用 0 标识请求成功，message 仅在业务响应失败时有意义，data 代表业务响应结果

如何选择 RPC 和 ROA，则需要根据产品自身的业务情况进行决策。有如下的指导原则：

有复杂业务逻辑的 API ，无法使用简单的增、删、改、查描述时宜使用 RPC 风格。
如果业务所属行业标准要求 restful 风格 API 或 ROA 能够满足业务需求，宜使用 ROA 风格。

AWS 主要采用 RPC 风格，Azure、Google 主要采用 ROA（restful）风格，阿里云 OpenAPI 同时支持 RPC 和 ROA，以 RPC 为主。

尽管规范是无罪的，但在 ROA 风格在实践过程中，我还是见识过不少“坑”的：

要求资源先行，即先设计资源，后设计接口，对软件开发流程要求较高
错误的 ROA 设计案例 1：tomcat 等应用服务器在处理 DELETE 方法的 HTTP 请求时，默认不允许携带 request body，需要显式开启，导致删除失败。（此案例为设计者的问题，复杂的删除场景，不应当映射成 DELELE，而应改成 POST，DELETE 不应当携带 request body）
错误的 ROA 设计案例 2：restful 路径中携带的参数，可能会引发正则匹配的问题，例如误将邮箱作为路径参数，或者多级路径匹配的冲突问题（此案例为设计者的问题，复杂的查询场景，不应当映射成 GET，而应改成 POST，path 中只应该出现资源定位符，而不应当携带属性）
响应码为 404 时，较难区分是真的 path 不存在，还是资源不存在
不利于对接网关等需要配置路由转发的场景

CSB 的 Open API 规范希望满足以下的需求：

后端开发设计接口时，有明确的设计思路，不至于因为一个接口到底用 POST 还是 GET 实现而纠结，不用花费太多时间在资源的抽象上（这并不是说明资源是不需要被设计的）
前端开发对接接口时，能够较快地与后端协同，并且利于前端接口的封装
用户对接 Open API 时，整体风格一致，模块清晰

综上，在设计风格选择上，我计划采取 RPC 的设计规范。总结一下 RPC 风格的优势：

API 设计难度较低，容易落地
阿里云大多数成熟的 IAAS 层产品使用 RPC 规范
适合复杂业务场景

一个详细的 RPC 接口文档示例

创建服务

请求参数

序号	字段中文名	字段英文名	数据类型	必填	说明
1	名称	name	string	是	显示名称
2	协议	protocol	string	是	枚举值：http/grpc/webservice
3	负载均衡	lb	string	是	枚举值：random/roundrobin
4	上游类型	upstreamType	string	是	枚举值：fixed/discovery
5	节点列表	nodes	array	否	upstreamType=fixed 时必填，示例：[{“host”: “1.1.1.1”,“port”: “80”,“weight”: “1”}]
6	来源id	originId	string	否
7	服务名称	serviceName	string	否	注册中心中的名称，upstreamType=discovery 时必填
8	服务描述	description	string	否
9	网关id	gatewayId	string	是

返回参数

序号	字段中文名	字段英文名	数据类型	说明
1	响应码	code	int	0
2	响应信息	message	string
3	响应结果	data	string	返回服务 id

请求示例

POST /service/createService

Request:
{
  "name": "httpbin",
  "protocol": "http",
  "lb": "random",
  "upstreamType": "fixed",
  "nodes": [
    {
      "host": "httpbin.org",
      "port": "80",
      "weight": "1"
    }
  ],
  "gatewayId": "gw-1qw2e3e4"
}

Response:
{
  "code": 0,
  "message": "",
  "serviceId": "s-1qw2e3e4"
}

API 命名规范

API 应使用拼写正确的英文，符合语法规范，包括单复数、时态和语言习惯
不能出现多个含义相近但功能无实际差别的 API，如同时存在 /user/getUser 和 /user/describeUser
语言习惯：禁止使用拼音
如下常见场景的命名规则是固定的
- 日期时间类型的参数应命名为 XxxxTime。例如：CreateTime
常用操作名称规范
- create：创建
- modify：变更
- delete：删除
- get：获取单个资源详情
- list：获取资源列表
- establishRelation：建立资源关系
- destroyRelation：销毁资源关系