API 规范和设计
内容介绍
1. 大环境介绍
2. API与服务开放
3. API定义
4. 模型
5. 总结
01. 大环境介绍
大家好，我是阿里云开发工程师黄湘龙（楚骧），在 API 网关领域深耕了九年，今天由我来为大家分享 API 规范与设计 Topic ，随着微服务架构和原生技术的发展，API First 已经成为公认优秀的软件研发方法。 API 设计对于服务架构的成功至关重要，良好的 API 设计不仅能提升系统的可维护性，还能增加用户的体验，并确保安全性和性能。为了确保 API 的设计既高效又易于理解与使用，遵循一定的设计规范是非常重要的。目前 Open API 已经成为事实上的 API 标准，市面上大多数 API 网关类的云产品都是基于 Open API 规范去提供标准的产品能力。今天由我来给大家介绍，如何给予 Open API 3.0 标准来设计一套 API 规范。
今天的分享分为四部分，第一部分是整体介绍，通过 Open API 将后端服务开放给 Consomer ，建议一种经过实践的 API 组织方法。第二部分详细描述，如何通过 Open API 规范去定义 API ，包括请求、参数、应答等。第三部分介绍模型的定义，在请求和应答的Body中都可以通过模型来规范业务属性。第四部分为小结，总结本次分享的所有知识点。
02. API与服务开放
首先我们来了解 API 是一套对外开放接口的集合，它允许不同系统和服务之间进行交互。在当今的软件生态系统中， API 成为连接不同平台和服务的桥梁。 Open API 是一种用于描述 Restful API 的标准格式，它允许用户以机器和人类都容易理解的方式定义 API 的功能。接下来让我们了解 Open API 规范是如何描述 API 的，假设我们有两个服务，如左图所示，
Group Service 和 User Service 两个服务中都有不同数量的接口对外提供服务，在 Open API 规范中并没有服务的概念，所有的接口都是扁平的。使用Method和Pass来区分接口 ，Open API 提供了Tax的属性，允许使用Tax来表述服务的概念，可以在接口上配置Tag用来标记该机构所属的服务。我们可以看到左边的 Group Service 服务包含了五个以上的接口， User Service 也包含了一定数量的接口。我们通过 Open API 定义把 API 中接口具象化，基于 Open API 的定义，Provider 可以给看 Consumer 提供标准的接口文档以及 SDK 等等，从而达到通过标准提供便捷性的目的。左边的两个服务是用户看不见的一些接口，通过中间的 Open API 的规范描述，形成一个看得见的接口列表，包括所有的接口列表、参数、应答、模型、认证信息等等。
例子中，我们把对于两个类型的服务 User 和 Group 的接口放到一个 Open API 文档中统一管理，这种 API 的组织形式，在 API 整体设计时有一定的局限性，所以业务属性都必须定义在业务 Pass 中，我们建议按照实际的服务维度去组织接口，一个后端服务一个接口档会更加清晰明了，扩展性也会更好。
在阿里云的云原生 API 网关中，我们也是如此建议大家使用的，把一个后端服务所有需要对外开放的接口组织到一个 API 中进行管理。一个 API 可以包含多个不同的接口， API 的所有接口的后台服务为同一个，可以单独为每个接口设置不同的策略，也可以在整体API 上配置策略，这是一个原生 API 网关定义的 API 详情，包含了 API 的名称、所有接口列表、后端服务的名称等等，用户可以在接口层面增加不同的入站和出站的策略。
根据上一节我们对 API 组织形式的推荐使用方式。我们将同一个服务中的所有需要对外开放的接口定义到一个 Open API 规范文档中。下面我们结合 Open API 3.0 的规范，看看需要将哪些属义定义清楚，才不会产生歧义。
03. API 定义
一个 API 定义包含以下四个基本模块。
(1) 基本信息：包括 API 名称，功能描述等。
(2) 接口本身：包括所有接口列表和接口的请求和应答的定义。
(3) 数据模型：数据模型接口的请求和应答中都需用到的了数据模型，比如说User Group 等实体对象对应的数据模型。
(4) 身份认证：可以为不同的接口定义不同的身份认证方式，包括 AppKeyAuth 、OAuth2 、 OpenID Connect常见的认证方式。
3.1 基本信息
下面我们将针对这四个模块做详细的一个介绍。
(1) 基本信息：包括 API 名称， API 的描述，API版本，版权信息、联系人等等。
(2) 服务地址：我们可以把 API 对外开放的服务地址以 Servers 的标签定义出来。我们对外开放 API 的时候可以提供多个 Url 对外提供开放服务、开放能力。例子：语义就是本 API 可以通过两个 Url 的访问，第一个 Url 是一个泛域名，可以把 Username 定义到 Url 中。第二个 Url 是一个固定地址，一个是 HTTPS 对外提供服务，一个是HTTP，而且第二个 Url 因为使用的非标端口，所以需要把端口给标志出来。如果是标准的一个端口，比如80、443就不用标注了。
(3) Base Path 属性：Base Path 是 OAS 2.0 提供出来的概念，用来定义 API 内所有接口的登录器。后来在 OAS 3.0时，把 Base Path 通信协议域名等属性合到了 Url 这个属性中，合并后服务地址的表述更加直观了。目前原生 API 网关依然保留了 OAS 2.0 这个概念、 Base Path 概念，主要是为了用户在定义 API 时更加方便的分别定义域名的根路径。在原生 API 网关中，建议使用后端服务来定义 Base Path ，会更加清晰明了。
(4) 版本：在 OAS 规范中可以以描述的形式在基本信息中定义 API 的版本，在原生 API 网关中允许用户在 Path/Header/Query三个位置来指定 API 的版本，比如在Pass中配置的版本是唯一，就可以通过视频中这个地址来访问 API 中所有唯一的接口。
3.2 接口基本信息
接口的定义：接口的基本信息包括了三个比较重要的概念，一个 Path ，一个 Method ，还有就是接口名称。
(1) Path ：Path 也就是路径，以斜杠开头，结尾不带斜杠。建议使用明确的语义来作为路径，一般使用动词加宾语的结构，把操作类型和操作的对象语义明确出来，以达到减少歧义的目的，比如说Get By Status、Create Order、Update Extension 等等，允许在 Path 中定义变量。如果定义的变量，那么此变量是必填的，建议使用小驼峰格式或者使用中划线来分隔，不允许使用其它的特殊符号。
(2) Method ：对应HTTP请求中的 Method ，常见的是GET/POST/PUT/ DELETE 。纯 Restfull 模式一般 Path 和 Method 来表述接口的定义，但是我们经过观察纯 Restfull 模式有一定的使用局限性，现在国内大家使用的次数不多，还是习惯把语义清晰的定义带入到 Path 中。
(3) 接口名称：在 Open API 的规范中是需要为每个接口来设定一个接口名称，接口名称的命名建议使用驼峰的命名规范，包含大小写字母，不应该包含其它字母，符合动词加宾语的结构，比如说 Create Order。
3.3 请求参数
请求参数需要定义的属性比较多，包括参数的名称、参数的位置、参数的类型。参数如果以数组的形态该如何表述、参数是否可以为空值或者是否可以为让值、是否必填，取值范围等等，都是需要定义清楚的。
(1) 参数名称：一般建议使用小驼蜂的方式，需要重点强调的是参数名称如果在同一产品中，我们尽量保证名称唯一，不允许出现一名多义，相同含义的参数在不同的 API 中也需要保持一致。
(2) 参数位置：包含四个位置 Path 、 Query 、 Header 和 Cookie 。
(3) 参数类型：在 Open API 中，我们定义了几个基本的特殊类型，如String、Number、Integerl、Boolean、Array 等等，每一个参数类型都有属于自己的参数格式。 Number举例，Number的参数类型下面有Float 、Double 、Int32 、Int64等等参数格式。
(4) 数组：在请求参数中，除了基本的参数类型还可以是数组，有多种数组格式，最简单的格式就是以逗号分割。下面这个例子就可以看到12，34，56这三个字都是以逗号分割的。
(5) 空值与可空参数：针对参数，如果我们传导一个空参数，可能产生理解上的歧义，我们是可以明确拒绝这种空参数的，我们也可以配置参数且是否允许传 Null 值，还有如果参数可以设置它必填或者是选填的前提下，也可以设置参数的默认值。但是需要注意一点，如果配置参数是必填的，那就不允许设置默认值，这两点是互斥的。
(6) 取值范围与枚举：我们可以定义参数的取值范围，比如说一个数字参数，我们可以定义它0~100 ，比如说字符串参数可以定义是几种枚举中的一个。
3.4 请求Body
除了请求参数，还需把请求的 Body 定义清楚，请求到 Body 需要定义的内容包括： Body 的内容是否必填， Body 的 Content-Type 。
目前用的比较多的是 Json 或者是 Form 或者 XML，但重点是参数的模型，是 Body 内容使用的数据模型，可以在文档中直接定义，也可以引用模型后面的名称。下面在模型那一节会给大家仔细讲解模型定义的方式。
3.5 应答
可以看到左边这个图是包含了多个应答码的参数应答定义。
每一个应答码都可以定义自己的 Description Content，每个应答都是以状态码开头，比如说200、404等等。通常1XX表示了请求已经被接收的临时应答。2XX表示本次应答是成功的，3XX表示这是重定向应答，4XX表示请求是不合法的，5XX表示服务端出现问题。每个应答码都需要更详细 Description ，除了应答码我们还可以在应答中定义一些 Header ，比如说自定义的错误码。其实在整个系统中有一个自定义的错误码，可以让后端服务快速定义为问题，也可以将一些留空数值返回给客户端，告诉客户端这一分钟还能发多少请求或是服务端忙碌，需要多长时间才能够继续发请求等等。Content使用 Content-Type 和模型来描述 Body 以及刚才请求的 Body 是相同的，后面再仔细介绍一下模型的相关定义。
04. 模型
目前比较流行的就是使用JSON Schema 来规范模型。
这套规范知识即支持多种复杂的数据结构，也支持模型嵌套。不仅支持各种模型之间的组合方式，同时支持继承与多态的一个形态，能够比较全面地描述业务模型，这也是 Open API 使用的一个规范。如图就是模型的定义，它可以定义模型具体包含哪些字段，以及每个字段的数据类型、数据格式和样例，并且每字段可以是另外一个模型，也就是嵌套模型。还可使用这一套规范来定义 Map 类型的结构， Map的 Key默认为字符串，Value 可以是自定义。下面是一个名称为Message的Map的定义。我们可以看到Key为字符串，所以就不需要定义了，只需要定义 Value 的值，同时Value 又可以是另外一个对象。
4.1 模型-组合
模型可以通过OneOf 、 AnyOf 、 AllOf 、 Not四个关键词来表述不同对象的组织形态。
OneOf比较好理解，也就是我们定义了两个模型，这个请求是第一模型或是第二模型。 AnyOf 是符合模型的一个或多个都是合法的。AllOf 语义是必须符合列表中的所有模型才是合法的。 AnyOf 来举例，因为 AnyOf 是比较复杂的一个模型的形态，所以我们定义了两个模型，一个模型Age是必填参数，一个模型 Pet_type 是必填参数。对于Post/Pets 这个接口而言，使用的 AnyOf 关键字需要加两个子模型去定义 Body，语义是只要符合两个子模型中的任意一个模型，就是合法模型。下面三个 Body 都是合法的，大家可以感受一下，第一个Age是符合PetByType这个模型。第二个它有 Pet_Type，它就符合 Pet_Type 这个模型的定义。然后第三个是既有 Age 又有 Pet_Type，那么它也是合法的。对于第四个，它因为既没有 Age，也没有 Pet_Type，所以它就不是合法的。
4.2 模型-继承与多态
我们使用 AllOf 可以实现基层的形态，可看到如图的模型定义。
它有一个BasicErrorModel，我们定义的一个基础的 Model，然后在基础的Model上，我们定义一个 ExtendedErrorModel，它包含了基础的 Model和一些自定义的属性， Open API 通过使用 OneOf 来达到实现多态的目的。我们定义两个模型，一个 SimpleObject，一个是 ComplexObject，两个模型都需要定一个 ObjectType 的必填属性，客户端根据应答中的 ObjectType 来区分应答内容是 SimpleObject 还是 ComplexObject。
4.3 认证
接下来我们来讲一下认证方面的知识， API 提供者需要为不同的接口设置不同的认证授权方案，确保所有的接口都不会被越权访问。下面我们在右边列出了一些常见的认证授权方案。
BasicAuth 是一个基础的认证授权方案，它在请求途中携带了授权信息。比如一个用户名加一个密码，被 Base64 放在请求中发送到 Authorization 中，我们可以看到这个例子，Authorization 中有一个 Basic 的字段，同时Basic 后面是用户名密码被 Basic 丢失之后的一个字符串。我们也支持 BearAuth 把 Token 发送到 Authorization 中，以Bear 的修饰符发送到服务器端，格式如例子。我们还支持 ApiKeyAuth 是 API 网关常见的一种认证形态，客户端把 ApiKey 放到约定的位置，发送到服务器端做鉴权。还有常见的 OAuth2 和 OpenID Connect，OAuth2 是一种授权协议，它为客户端提供的用户数据有限访问权限，OAuth2 允许资源所用者保护资源服务器的内容同时无需共享其凭证。为此 OAuth2 服务器会发出 Access Token，客户端应用可以使用 Access Token代表自用所有者去访问受保护的资源。 OpenID Connect 是一个基于 OAuth2 的一个协议构建的身份认证层，由 OAuth2 提供商支持，它定义了一个登录流程，使客户端能够对用户进行身份认证，并且获得用户的信息，比如用户名，电子邮件等等，所有的信息都包含在 JWT 中。然后客户端把 JWT 发送到网关层，网关使用 JWK 也就是一个功要解决 JWT ，来保证身份认证的能力。
05. 总结
API First 是目前公认的先进软件开发模，建议大家在项目中尽量使用 API First 的模式去主导项目，并且使用 Open API 作 API 的设计，建议以后端应用的维度去组织接口开放 API，一个后端应用中所有的接口作为 API 对外开放，服务名称和版本号统一放置在 API 的根路径上，接口定义中只需要定义和接口相关的路径就完成了，清晰明了更具扩展性。
本次分享还介绍了 Open API 定义 API 的具体方式，其中包括 API 对外提供服务的 Url ，请求中的参数的具体定义，请求 Body 和应答 Body 的定义方式。本次分享介绍了如何去定义模型，如何使用 OneOf、 AnyOf、 AllOf 等关键词去实现模型的组合，实现继承与多态的形态。本次还介绍了主流的认证鉴权方式，阿里云原生 API 网关是完全基于 Open API 为基础的一个云产品，全面融合了云原生网关与 API 网关的优势。
我的分享到此结束谢谢大家。
