DevOps落地笔记-12|API管理：微服务时代的必备工具

上一课时主要介绍了使用持续集成这个实践来保证开发中的软件处于可工作的状态，解决的是开发后期才集成导致的无法集成或功能无法使用的问题。

最近几年，软件架构也在不断升级，逐渐采用前后端分离、微服务的体系结构。前后端分离使得前端和后端充分解耦，在高并发情况下，后端可以按需扩展，前端和后端通过 API 接口定义的契约进行通信。API 接口也会随着业务需求的变化不断改变，但 API 接口改变但调用方没有改变时就使得软件不可用。另外，调用方也不了解有哪些 API 接口可以使用，使用的规范是什么，由此也导致了很多管理问题。今天要介绍的内容——API 管理，就是要将 API 的生命周期、API 的注册、使用、版本等管理起来，为调用方提供统一的 API 管控平台。

什么是 API 管理？

API 是 Application Programming Interface（应用编程接口）的简称。API 用于将应用程序本身的能力和数据提供给用户使用，比如微信的 openAPI 接口，百度地图的 openAPI 接口等。用户使用这些 API 可以开发出更具创新的应用程序，提供更丰富的用户体验。

API 管理就是有效管理企业内部各服务提供的 API 接口，管理 API 接口的创建、测试、发布等生命周期，以及 API 接口的版本、并提供 API 开发者门户供开发人员查看。服务的 API 接口在构建时自动的注册到 API 管理平台的 API Gateway 中，其他调用方可以通过 API Gateway 访问这些接口提供的服务，并基于 API Gateway 进行 API 的自动化测试，保证 API 的正确性和健壮性。

RESTful API

目前最常用的 API 架构风格是 REST API。它没有严格的标准，但提供了一些要遵循的指导原则和约束条件。Roy Fielding（罗伊·菲尔丁）在它的博士论文中描述了这些限制，并创造了Representational State Transfer（代表性状态转移）这个名字。

REST 依赖于无状态、可缓存和客户端和服务器端通信协议（如 HTTP）。通过遵循 REST 的原则并将其应用于 HTTP 等无状态协议，开发人员可以构建出从任何设备和操作系统调用的 API 接口。API 接口是客户端与服务器端通信的桥梁，设计良好的 RESTful API 是微服务时代企业应用程序成功的必备条件。

REST的原则

下面是构建 RESTful 架构的几个限制条件。

& 统一接口描述：统一接口用于定义客户端和服务器端之间通信的契约。该契约规定了交互的机制和格式以及客户端如何访问服务器端资源。只要遵循该契约，客户端和服务器端的应用程序就可以独立开发，有利于构建前后端分离的架构。

& 客户端-服务器端：客户端和服务器端这种调用约束构建了松耦合和可扩展的 Web 体系结构。只要客户端和服务器端都遵循统一的接口，他们就可以独立开发，不管使用的是何种开发语言。

& 无状态：无状态是 RESTful 服务的重要原则。它规定 Web 服务器不需要记住客户端的状态。状态信息可以作为变量包含在 URL 中，也可以作为查询参数、Header 参数或者请求体。服务器处理后，通过 Header 和响应体返回给客户端。这样做有助于减少服务器端维护和传输客户端状态的负担，从而提高服务器端的可伸缩性。

& 可缓存性：缓存是 RESTful 服务的另一个原则。它提高了服务器端应用程序的可伸缩性和整体性能。一般情况下，服务器端可以指定缓存响应的有效期。根据有效期，客户端决定是使用缓存响应还是单独请求获取实时数据。缓存响应数据可以提高客户端的响应速度。

& 分层系统：是指在客户端应用与服务器端之间增加一个中间层，一般为代理或网关。可以用于实现安全性、缓存、流量限制、负载均衡等。在中间层实现缓存和负载均衡可以提高系统的可伸缩性。

构建 RESTful API 的最佳实践

API 的设计应该简单而直观的，这样开发人员才能更容易的使用。下面总结了一些设计 RESTful API 的简易方法。

& 使用 RESTful URL 设计 API。根据资源的逻辑分组设计 API。API URL 应指向资源/子资源的集合或者集合中的单个实体。例如 /customers 指向了客户集合，而 /customers/{customerId} 指向了客户集合中的单个客户实体。

& 使用 HTTP 动词对资源执行 CRUD 操作。使用 POST 用于创建新资源，GET 用于读取资源，PUT 用于更新资源，DELETE 用于删除资源。另外，可以考虑使用 PATCH 对部分资源更新。

& 当 HTTP 动词无法映射到操作时，使用 URL 中的操作。有时候，对资源的操作无法映射到 HTTP 动词，比如：register、activate 等操作不能直接映射到 HTTP 动词。这些操作可能适用于单个资源或者一组资源集合。这时，可以将该操作视为 URL 中的一个子资源或者一个资源的一个动作。例如：/customers/123/activate 或者 /customers/123/actions:activate。

& API 版本。版本控制提供了一种平滑升级和迭代 API 的方法。可以同时支持多个版本的 API，这样就为客户端升级到新版本和注销旧版本提供了时间。最常用的版本控制的方法是在 URL 路径中包含版本信息。

API 管理平台架构图

如今，用户会通过多种类型的数字终端来访问企业的数据和服务。为了满足用户的需求，企业需要以敏捷、灵活、安全和可扩展的方式提供数据和服务。API 是企业对外提供数据和服务的通道。它允许应用程序可以使用像 HTTP 这样轻量级的协议实现通信。随着 API 的不断增加，对 API 的管理就变得格外重要。开头介绍了 API 管理包含的功能，下面介绍一下 API 管理平台的架构图。
在这里插入图片描述
结构图所示包含两个部分：API 管理控制台和API Gateway。

& API 管理控制台：

包含 API 声明周期的管理、API 开发者门户等功能。API 创建完成后通过自动化的方式注册到 API Gateway 中并在管理控制台中以待测试的状态显示。测试完成的 API 以待发布的状态显示，发布完成的 API 以已发布的状态显示。在管理控制台中能清晰的展示 API 的提供者、API 的状态、API 的测试报告等信息。API 管理控制台的用户为 API 的使用者、提供者和管理者。

& API Gateway：

负责转发其他服务的 API 请求并对请求做拦截处理。API 部署到环境中时会注册到 API Gateway 中，其他客户端可以通过 API Gateway 调用后台的服务，完成 API 接口的自动化测试和性能测试。API Gateway 的调用者为 App、Web 或小程序等。

API 生命周期管理

下面主要介绍一下 API 生命周期管理。该功能提供了 API 从创建、测试到发布的全过程以及后期迭代的版本管理。API 管理员可以管理 API 的使用策略、调用者、调用者权限等，比如只有已发布的 API 才能被其他调用者使用。为了防止 API 调用的混乱，只有具备权限的调用者才能调用等。

API 创建

开发人员能够设计 REST API 接口，有两种方式可以设计并创建 API。

& 基于 API 设计器生成 API。

该方法主要在项目初期使用。API 的设计可以帮助梳理项目的功能和实现逻辑，并基于设计的 API 自动化生成代码。目前比较成熟的工具是 Swagger Editor。Swagger Editor 可以在浏览器中使用 YAML 编写服务 OpenAPI 规范的 API 文档，并能够实时预览文档以及自动化生成代码。Swagger Editor 是一个开源工具，可以集成到 API 管理平台。

& 从代码扫描生成。

该方法主要在项目中后期使用。在项目迭代过程中，会不断更新现有的 API 接口和增加新 API 接口。此时最好的更新 API 的方法是自动化扫描，这样就能保证生成的 API 接口与代码中是一致的。目前常用的工具也是 Swagger，可以在项目中添加依赖和配置即可生成。

API 测试

开发人员开发完 API 后，在持续集成阶段会将 API 接口同步到 API 管理平台，当前状态为新增或待测试。API 的测试包含几个部分：API 的接口逻辑、API 文档和 API 的性能测试。

API 接口逻辑

API 接口定义了客户端和服务器端通信的契约。包含所需的输入参数和 API 的预期响应。在进行 API 接口测试时要测试不同参数的组合对结果的影响，包含正确和错误的情况。以下面查询产品信息的接口为例：

https://api.devops.com/v1/products

该接口会接收多个可选参数作为输入，包含 category、name 等，比如以下。

https://api.devops.com/v1/products?category=computer

在进行该接口测试时的测试用例有：

& 当不传任何参数时，接口的默认行为是什么？

& 当传入正确的参数、正确的值时，接口的行为是什么？

& 当传入的参数名不正确时，接口的行为是什么？

& 当传入的参数不包含值时，接口的行为是什么？

& 当传入的参数值不正确时，接口的行为是什么？

…

API 文档的测试

API 测试时需要验证 API 接口文档是否是正确且最新的。当发布新版本的 API 时，应更新 API 文档到当前版本。API 文档应该和 API 一样是有版本控制的，并且 API 文档应该是自动化生成，这样既能保证 API 文档与代码的一致性，也能保证 API 文档的正确性。目前常用的 API 文档生成工具，还是 Swagger。通过在当前项目中引入下面依赖。

<dependency>

     <groupId>io.springfox</groupId>

     <artifactId>springfox-boot-starter</artifactId>

      <version>3.0.0</version>

</dependency>

并添加如下 SwaggerConfig 类即可生成 API 文档。

@Configuration

public class SwaggerConfig {



    @Bean

    Docket docket() {

        return new Docket(DocumentationType.OAS_30)

                .select()

                //配置需要扫描的controller位置

                .apis(RequestHandlerSelectors.any())

                //配置路径

                .paths(PathSelectors.any())

                //构建

                .build()

                //文档信息

                .apiInfo(apiInfo());

    }



    private ApiInfo apiInfo() {

        return new ApiInfoBuilder().title("DevOps OpenAPI").version("1.0.0")

                .description("<p>DevOps OpenAPI 文档描述，此处省略500字<p>")

                .termsOfServiceUrl("http://www.devops.com")

                .license("http://unlicense.org")

                .contact(new Contact("","","admin@devops.com"))

                .build();

    }



}

如果要想检查每次提交有没有 API 接口的变更，可以参考微软 Azure 的一个开源项目 openapi-diff。

API 性能测试

API 不仅是对外提供获取数据的服务，并且能够在负载下很好的工作。大多数情况下，应用程序的整体性能取决于为应用程序提供基础的 API 性能。因此，API 的性能和负载测试就显得非常重要。API 性能测试的步骤如下。

第一步：收集有关API的性能要求数据，包含以下信息：

& 每个 API 每秒请求数的平均吞吐量；

& 在给定的峰值处理请求的最大数量；

& 客户端应用程序预期的并发用户数，能够预测 API 在负载下预期处理的并发连接总数。

在决定 API 测试的性能要求后，在实际测试时就要以该要求为标准进行验证。如果未达到该要求，就要调整和优化 API 平台的参数，从而获得更好的吞吐量。如果通过优化仍然未达到要求，就应该考虑更高配置的硬件设施。

第二步：选择性能测试的方法。

& 基线测试：该测试的目的是找出系统在正常预期负载下的表现，测试结果用于分析 API 响应时间的平均值和峰值。

& 负载测试：在负载测试期间，增加负载，以研究在不断增长的流量下 API 的性能。可以查看的指标有响应时间、吞吐量等。该测试的目的是了解预期的系统行为和处理预期峰值负载的能力。

& 压力测试：该测试的目的是找到平台的临界点，确定系统可以处理的最大吞吐量。当随着流量逐渐增加，直到性能开始下降或 API 调用的错误开始增加时便到达临界点。

& 浸泡测试：该测试的目的是指当系统长时间测试时是否有任何系统不稳定的问题。

第三步：选择合适的工具或平台进行测试。

目前有很多开源的工具可以执行 API 性能测试，其中比较常用的有 JMeter 和 LoadUI 等。

API 发布

API 经过测试达到可发布的要求后即可发布，发布后的 API 可以被其他客户端使用。

版本管理

当 API 发布后，开发人员就会根据 API 定义的契约在客户端应用程序中使用它。客户端应用程序是强依赖该 API 的，如果 API 发生变化，就会导致客户端应用程序不可用。随着时间的推移，API 的变化是不可避免的，比如有新需求可能会导致 API 的变化。因此，需要通过版本管理的方式降低 API 的变化对客户端的影响。

API 版本的原则有：

& API 版本不应该破坏任何现有客户端；

& 尽可能少频率的变更 API 的主版本号；

& 进行向后兼容的变更，避免生成新的 API 版本；

& API 版本不应该与软件版本直接挂钩。

API 版本的管理方法。

& 使用 URL 管理：API 通常由 URL 标识，所以在URL中加入版本控制是有意义的，也是目前最常用的方法。比如：https://api.devops.com/v1/products https://api.devops.com/2018/products 等；

& 使用 HTTP Header 管理：在 Header 中指定 API 的版本，比如使用 X-API-Version 的 header 标识。

& 使用查询参数管理：在查询条件中指定版本，比如 https://api.devops.com/products?version=2

这几种方法每种方法都能实现 API 版本控制的目的，采用任何一种方法都需要与客户端进行协商，客户端也需要采用该方法调用 API，这个机制是要统一的。

总结

这个课时主要以 RESTful API 这种风格为例介绍了 API 的原则和最佳实践。API 是目前微服务时代非常关键的部分，将软件的各个组成部分串联在一起，形成一个整体对外提供服务，对 API 的有效管理也能加快软件开发的速度和提升软件的质量。在大多数企业里，API 这部分并为形成一个统一的平台，只是利用一些零散的工具完成不同部分的开发和测试工作。