【API生命周期看护】API设计与评审

一、基本概念

正如我们在上一篇关于API规划与定义的文章中所说，当云服务产品经理完成对需求的初步分解后，会将其中的相关特性归纳为一个个服务所需对外提供的OpenAPI。对于这些API本身，如何进行细化、定义，确保性能规格、功能要点、安全合规等，则需要走到API生命周期的下一步骤：API的设计与评审。

二、API设计与评审要点

1、基本流程

一般而言，每个流程都有自身的工具平台进行赋能，这点在各个DevOps平台都有体现。在API规划与定义阶段，我们一般是通过，而在
首先，从角色分工的角度来看，API的设计与评审主要是由云服务架构师以及云服务负责人（SL）共同决定的：架构师会对接口基本需要实现的功能范围进行定义，并对目标客户类型、SLA、安全类别等内容进行定义；而对于API的具体RESTful样式、参数定义、规范性兼容性等具体细节，则会有云服务
其次，在SL完成接口设计后，会通过提交评审的方法对接口进行检查与审核，同时根据API的开放程度不同，评审流程也有所区别：

• 对于服务内部使用的API，评审仅仅会经过其他服务SL或架构师，进行基础审核即可；
• 对于服务对外提供的OpenAPI，接口的评审流程则会自动走到产品部层级的API TMG，由专门的API技术专家进行审核、评估；

同时，API的设计评审平台也会自动地对API设计文档——一般为Yaml文件，进行包括接口规范性、兼容性、安全性等一些列问题的自动检查，在评审发起前发现接口问题，敦促服务设计方进行整改。
这里，当整体接口设计文档完成优化修改、解决相关问题并完成评审后，服务会通过工具平台对当前微服务下的接口设计文档进行基线化并归档，方便下次进行接口设计时进行版本迭代与对比。
当规范的接口yaml文档得到基线化与版本管理后，开发人员、测试人员、资料人员均会以这一份文档进行相关处理：

• 对于开发人员，可利用相关代码生成框架，基于设计文档自动生成接口功能代码，保证设计与实现的一致性。
• 对于测试人员，根据对应yaml文档生成测试AW（ActionWord），并在自动化测试平台编写测试用例，提升用例编写效率与准确性。
• 对于资料人员，基于文档自动生成平台，可直接将接口设计文档转换为规范的word等格式的接口文字文档，减少文档编写的工作量与疏漏。

2、设计分析过程

在接口的设计分析过程中，我们一般将其分为以下五个步骤进行：

（1）明确接口角色

在最初阶段，我们需要对API能力开放明确定义：接口究竟是为谁开放的，这有助于我们回到在API定义阶段5W中的Why的问题。

（2）定义资源模型

由于这里所定义的接口均是RESTful的，因此接口所操作的资源类型也需要进行妥善定义。一般而言，RESTful接口文档在后半部分均为具体资源：definitions，本质上就是接口所对应的数据模型定义：模型名称、字段类型、取值范围等等。

（3）梳理交互场景

对于接口的交互场景也需要进行妥善梳理：数据面还是管理面？是数据获取类型还是状态检查类型？是每天一次的低频场景，还是每分钟数千次的高频场景？这些都是需要根据需求进行详细设计的。

（4）设计云服务SLA

所谓SLA，也即“服务等级协议”，指的是服务提供商与客戶之间定义的正式承诺，是具备法律效益的。
对于云服务而言，一般会包含多个微服务，每个微服务均会包含多个RESTful API，而RESTful API的最低可用性指标决定了微服务的最低可用性指标，同时也决定了系统的最低可用性指标，属于典型的短板效应。
对于SLA，一般我们从请求成功率、可用性、数据一致性、吞吐量、响应时间等维度进行评判。

（5）分析安全合规

API的安全与合规风险评估从本质上来说是会贯穿整个API生命周期的，包括但不限于身份认证、数据加密、身份追踪、流量管理、身份验证与授权等方面。

三、评估方法

在指标维度层面，我们一般利用API纳管率、API规范率、API评审率和API基线化率来衡量。

1、API纳管率

所谓API纳管率，指的是服务在接口设计平台通过数字化管理的接口个数，与服务总体接口个数的占比。
这里，服务总体接口我们一般使用运行态的接口发现统计数据。
总体来说，API纳管率越高，说明API设计数字化看护水准越高。

2、API规范率

对于API设计接口文档而言，数字化平台会自动进行文档规范性检查。这里，我们使用没有规范性问题的接口数，与总接口数的比例，来表示服务总体的API规范率，一般应当达到100%。

3、API评审率

由于OpenAPI的设计均需要经过设计评审，因此这里，我们使用得到评审的OpenAPI数量与总体OpenAPI数量的比值，用以表示服务的API评审率。
一般而言，API评审率越高，说明API设计评审流程越规范，避免未知接口开放。

4、API基线化率

所谓API基线化，也即上面我们提到了将整体API文档基线化并归档，作为API迭代版本。这里，我们使用经过经过基线化的API数量与总API数量的比值来代表API基线化率。

四、小结

API设计与评审虽然在API生命周期看护中是比较靠前的位置，但重要程度可以说是最高的。目前云服务之间的调用关系混乱、无序，以及服务的众多质量问题，很大程度上都是API没有经过妥善设计而导致的。
在API First的理念中，API最初的设计yaml是核心，是一切的源头：不管是开发、测试、文档，还是跨部门协作，可参考文章：API First——微服务架构下API接口驱动设计与开发，这里不再赘述。