自动化 API 交付——API 设计评审：检查那些无法自动化的内容

本章内容包括

了解什么是 API 评审
开展 API 评审
衡量评审的有效性

假设你刚创建了一个新的 API，并且 API 定义文件已经通过了 CI/CD 流水线中所有自动化的提交阶段检查。你发起了一个 Pull Request（PR），希望将这次修改合并到 API 定义项目的主分支。那么，是否还需要同事来审查你 PR 中的 API 定义变更呢？答案是：需要。

和同事甚至潜在用户一起审查 API 变更提案，可以获得自动化检查无法提供的反馈。这也是一个回顾自动化检查报告的机会。在本章中，我将讨论如何在 APIOps 工作流中开展 API 评审，以便获得同事的反馈。虽然所有参与 API 设计的不同角色的人都会对本章感兴趣，但对于负责 API 一致性、担任 API 产品负责人或类似角色的人来说，学习如何建立高效的 API 评审流程尤为有益。

5.1 什么是 API 设计评审？

API 评审的目的，是从同事和内部 API 使用者那里获取对 API 设计的反馈，以改进设计并检查其是否符合组织的 API 可用性和一致性标准。

在 APIOps 的背景下，当你为 API 定义文件的更改发起 PR 时（见图 5.1），就在设计阶段启动 API 评审。评审应当在你运行了自动化的代码规范检查（linting）和破坏性变更检查之后进行，因此它不同于传统那种仅依赖人工、容易出错地对照组织 API 风格指南进行检查的 API 评审。

在 APIOps 中，API 评审是对自动化治理检查的补充，由人工来检查那些无法自动化的事项。比如，设计中是否包含了所有相关的 API 操作？团队是否认可资源和资源属性的命名？在评审过程中，你可能会发现新的、一致性方面的问题，这些问题将来可以通过自动化来防止，并且你可以记录下来，为其编写自动化检查。

你可以采用异步或面对面的方式进行 API 评审。

在异步 API 评审中，API 设计人员会通过提交一个包含 API 定义变更的 PR（Pull Request）向同事发出评审请求。评审人员可以查看这个 PR，其中包含 API 定义的变更及相关元数据，还可以渲染 API 定义，查看 API 参考文档的样子，并对自动生成的 API Mock 发起试验请求，看看它的行为表现。他们可以在自己方便的时间，通过 GitHub、GitLab 或 Bitbucket 等 Git 协作工具，在版本控制系统中发布评审意见。API 设计人员稍后可以阅读并处理这些意见，并进行必要的修改。对于变更较小或严格遵循组织风格指南的 API 设计，这种轻量化的评审与批准流程是首选。

但有些 API 设计变更 PR 则需要面对面的评审（即现场 API 设计评审会议）。这可能是因为 PR 涉及 API 的大面积变更，或者需要 API 设计人员为评审人员解释大量背景信息，才能让他们理解设计。此外，设计可能由一个尚不成熟的团队提出，他们需要帮助来入门组织的 API "设计优先"方法、API 产品化思维（外向思考、以用户为中心），或者需要在将领域建模应用到 API（即 API 建模）时获得指导。在面对面评审中，API 评审人员会与 API 设计人员一起讨论 PR，理解变更动因、了解设计决策的理由、检查 API 的一致性，并提供改进 API 设计的详细建议与支持。

你也可以采用混合方式：一些组织会先进行异步评审，如有需要（通常是重大 API 变更或需要深入讨论的变更），再安排面对面评审。在小型组织中，评审流程可以较为非正式，可能只需要一个同事参与；而在大型组织中，可能会有专门的 API 治理团队负责 API 评审。需要强调的是，无论评审是面对面的还是异步的，都应在自动化检查完成之后进行。

当评审人员对 PR 感到满意时，就会批准它，这意味着形成了一个一致认可的 API 合约，服务端团队和客户端团队都可以基于此开展开发工作，从而实现并行推进，提高交付速度。

不过，评审人员不仅要在 API 定义变更通过 PR 提交时提供反馈，还应在 API 设计的早期阶段介入。根据领域的复杂性，API 设计人员可以基于用户故事或工作故事（工作故事将在后面讨论）、用户旅程以及领域模型，为 API 创建业务操作与数据模型。API 评审人员可以帮助设计人员评审这一 API 模型，确保设计人员对齐正确的限界上下文，并遵循单一职责、封装等原则。

领域驱动设计（Domain-Driven Design，DDD）

领域模型是业务概念、关系和工作流的结构化表示，这些概念、关系和工作流被表示为具备行为与数据的相互关联的软件对象。领域驱动设计（Domain-Driven Design，DDD）因 Eric Evans 在其著作《领域驱动设计：软件核心复杂性应对之道》（Addison-Wesley，2003）中的推广而广为人知。DDD 是一种软件设计方法，它聚焦于在深入理解业务领域的基础上构建领域模型。

DDD 帮助软件团队建立一种通用语言------一种共享的、普遍的、严格的语言，使团队可以与领域专家和用户以明确且一致的方式识别和交流领域概念。这种通用语言应当被嵌入到正在构建的软件系统中。

DDD 的一个模式是**限界上下文（Bounded Context）**的概念。这是一种在建模大型业务领域时的处理方法，即将领域模型拆分为多个组（限界上下文），并明确地定义它们之间的关系。在每个限界上下文内部，领域术语与概念的定义保持一致。

在 API 模型和 API 操作在概念层面上定义完成后，API 设计人员就可以将这一设计转换为 OpenAPI 定义文件的变更。他们会使用组织的 API 风格指南来指导创建或更新 API 定义文件，以确保符合组织的规范。同时，他们会引用并包含任何需要的共享、可复用的 OpenAPI 组件库，这样既避免了从零开始编写，又能让 API 评审过程更轻松，因为定义中复用了已批准的组件。

设计人员会将变更提交为 PR，并运行自动化检查。如果代码规范检查（linting）或破坏性变更检查出现错误，API 设计人员应在 API 评审前检查并修复问题。当 PR 准备好进行评审时，API 评审人员会进行审查、批准、拒绝，或将其安排到面对面评审进一步讨论。该流程如图 5.2 所示。

在评审 PR 时，谁来决定这个 PR 是否需要召开设计评审会议？

API 评审人员应根据自己的判断来决定。通常，如果 API 设计在某些方面与 API 风格指南有重大偏离，需要比 PR 评论更深入的讨论，或者引入了新的 API 设计模式，那么评审人员可以邀请 API 设计人员参加一次 API 评审会议。

除了让同事审查 API 以改进一致性和可用性这一核心收益外，API 评审还有其他价值。API 评审对于内部团队来说具有同步与协调 的作用，因为它会涉及到相关方，包括任何对 API 变更感兴趣或受到影响的团队。例如，可能是需要调用该 API 的内部团队、需要测试该 API 的同事、产品团队，以及技术文档编写人员。评审会议是一个很好的机会，让各个团队了解变更内容、提供反馈，并理解该变更对他们所管理的应用程序或平台部分的影响。

API 评审还具有教育意义。想要提升 API 设计技能的团队成员可以加入 API 评审会议，学习如何设计和评审 API。

💡 提示：

对于仅有少量开发团队且外部 API 接口规模不大的小型组织来说，可能不会有独立的 API 治理或评审小组，因此也不需要复杂的 API 评审流程。团队成员之间结对或简单讨论 API 设计可能就足够了。对于业务领域简单、API 操作数量较少的接口而言，本章后续提到的"创建和评审 API 资源模型"的建议可能会显得大材小用。此类团队只需设置基础的自动化代码规范检查（linting）即可达到可接受的 API 一致性水平。

需要注意的是，API 评审 PR 虽然可以帮助 API 设计人员获得同事的反馈，但要想获得更广泛的外部 API 使用者的反馈，设计人员仍需将变更发布到外部。根据 API 的稳定性级别（见 4.10.2 节的讨论），发布 Alpha 或 Beta 版本的 API 可以让 API 使用者提前试用、进行实验，并进一步反馈 API 设计。

5.2 开展 API 评审会议

假设你是 API 治理团队中的一名 API 评审人员。现在有一个 API 设计 PR 已经提交，并且你的几位 API 评审同事已经审查过，并决定需要与 API 设计人员开会，讨论他们的一些设计决策。你被要求主持这次 API 设计评审会议。那么，你会如何开始？

下面是一个建议的 API 评审会议流程，你可以根据需要进行调整：

安排评审会议并邀请参与者
在会议中介绍评审议程
提供评审的业务背景
评审 API 资源模型
评审 API 定义并记录评审反馈
记录新的 API 设计模式或发现的风格指南缺口
在会议结束时请参与者填写简短调查问卷

接下来我们将详细说明这些步骤，从为什么要进行评审开始。

5.2.1 安排会议并邀请参与者

对于要进行评审的 API，会议主持人应邀请所有来自构建和使用该 API 团队的相关利益方。这些人员可能来自不同的角色，包括工程师、产品负责人、产品经理、业务分析师、技术文档编写人员等。

在组织 API 评审会议时，可以将参与者分为三类角色：

API 设计人员（API designers）
通常是负责创建或更新 API 定义文件的开发人员。设计 API 往往需要多人协作，也会涉及不同角色的配合------包括产品负责人、产品经理、架构师等。本书中提到的 "API 设计人员"，是指提出 API 设计变更方案的团队。
API 评审人员（API reviewers）
这些人负责审查 API 设计变更，必须包括具有丰富 API 设计经验的工程师。对于大型组织，这可能是专门的 API 治理团队成员；也可能是负责 API 网关的 API 平台团队、安全专家、技术文档编写人员，以及负责开发者门户或开发者体验的团队。
主持人（Facilitator）
负责组织并主持 API 评审会议，包括安排时间、做会议记录，以及在需要时引导讨论。

确定利益相关方非常重要，以下问题可以帮助主持人识别这些人员：

谁将集成并调用这个 API？除了外部 API 使用者，是否有一个或多个内部团队会使用它，并希望参与到他们将调用的 API 设计中？
谁将为这个 API 创建指南文档和教程？参与撰写文档的技术文档人员可能需要了解 API 的背景，并对 API 描述字段提出编辑建议。
是否有安全专家、安全工程师或安全测试团队希望参与 API 的安全防护或安全测试？
是否有 API 平台团队将负责通过 API 网关暴露该 API？
谁是对这个 API 感兴趣的解决方案架构师和工程师？
谁是对这个 API 感兴趣的产品负责人或产品经理？

这个清单并不完整，但可以作为参考。此外，我建议将 API 评审会议对所有感兴趣的人开放，比如通过内部沟通渠道发布会议邀请和提醒。正如前面提到的，API 评审会议同时具备教育意义 和信息交流的功能，将其开放给潜在的 API 评审人员参与，是培养新评审人员的有效方式。

5.2.2 介绍评审议程

对于正式的 API 评审会议，建议主持人在会议开始时先向参与者介绍会议议程。这可以让参与者明确会议的结构和在规定时间内要讨论的范围，从而避免会议陷入无休止的设计争论。同时，这也是向新参与者介绍组织内部 API 评审运作方式的好机会。

以下是一个示例 API 设计评审议程，你可以根据组织的实际情况进行调整：

确认相关利益方是否到场
介绍 API 评审主题
评审 API 资源模型
评审 REST API 元素：
- 摘要与描述
- 幂等性要求
- API 路径
- 正常请求与响应数据结构
- 错误信息
- 安全方案
记录发现的新 API 模式或风格指南缺口
进行会议结束调查

制定标准化的 API 评审会议议程，可以帮助不同主持人更一致地开展评审，减少对特定个人的依赖。

5.2.3 提供评审的业务背景

在确认会议中有合适的参与者（通常包括工程、产品以及其他必要角色）之后，应先介绍评审主题。

为了帮助与会人员理解需要评审的变更，主持人需要介绍业务背景 ，解释 API 用户试图实现的目标，并在可能的情况下展示用户旅程（用户旅程将在 5.3.1 节 进一步讨论）。在主持 API 评审时，我通常会让 API 设计人员用 3 到 5 分钟介绍他们 API 变更的业务背景，并向与会者征求问题，确保所有人都理解。

另一种让与会者对 API 要做的事情有总体认识的方法，是展示一个 API 概要（API profile） ，用简明的方式说明 API 的工作内容。
表 5.1 给出了一个示例。

表 5.1 API 概要示例

项目	描述
API 名称	Product Catalog API（产品目录 API）
API 价值主张	一个用于发现 Acme 公司丰富产品的 API，帮助用户找到为他们宠物提供护理的商品
API 消费者	终端用户是浏览 Acme 宠物用品产品以进行购买的顾客。客户端 API 开发人员将使用该 API 构建三个终端用户渠道：Acme 移动应用、Acme 网店，以及合作伙伴网店。
工作故事（Job stories）	故事 1 ：当我想了解 Acme 提供了哪些产品时，我希望可以按类别浏览 Acme 产品目录，以便找到让我感兴趣的新颖宠物产品。故事 2：当我想了解 Acme 提供了哪些产品时，我希望可以在 Acme 产品目录中搜索特定宠物产品，以便查看产品详情并决定是否购买。（备注：搜索功能将在第二阶段提供）
访问级别	公共 API，可供 Acme 自有数字渠道和注册合作伙伴使用
使用计划	Acme 移动应用：每分钟 10 次请求Acme 网店：每分钟 10 次请求合作伙伴网店：每分钟 8 次请求
安全模型	API 请求应使用 OAuth2 进行授权。MVP 阶段仅提供读取权限范围（read scope），随着功能扩展会增加更多权限范围。

工作故事与数字能力（Job Stories and Digital Capabilities）

工作故事（Job Story） 是一种经过增强的用户故事写法，应用了 Jobs to Be Done (JTBD) 思维方式。它聚焦于触发情境 、用户想要实现的动机/目标 以及期望结果。

例如，在 表 5.2 中的 Product Catalog API 案例中，一个工作故事可以是：

"当我需要为我的宠物购买护理产品时，我希望能在该类别中发现一系列优质并附带高质量评价的产品，从而选择我喜欢的那一个。"

JTBD 框架 的核心是找出客户"雇用"某个产品或服务来完成的目标或"工作"。它帮助产品经理洞察驱动客户购买产品或服务的潜在需求和动机。

API 使用者会调用 API 来完成特定任务，而清晰地表达这个"工作"，能帮助产品经理设计出更优的 API 产品。

基于工作故事，API 团队可以推导出 API 所需具备的高层任务或数字化能力，以支持该"工作"。

关于如何通过工作故事和数字能力来识别 API 的需求、范围和边界，可参考 James Higginbotham 的《Principles of Web API Design》（Addison-Wesley, 2021）。

API 价值主张画布（API Value Proposition Canvas）

另一种为评审人员提供业务背景的技巧，是展示 API 价值主张画布（也称 API 价值主张接口画布，value proposition interface canvas）。

API 价值主张画布是一种模板，用于定义 API 所提供的价值------它明确说明 API 功能如何解决 API 使用者的痛点（pains）以及帮助他们实现想要的收益（gains） 。

这是 API 设计早期阶段的一种工具，可促进工程师、架构师、产品经理、业务负责人及其他利益相关方的讨论，从而共同定义并达成一致意见：API 应该做什么。

该画布分为两个主要部分：

左侧：消费者（客户）画像部分
描述 API 使用者需要完成的工作，以及他们在过程中遇到的痛点和想要获得的收益。
右侧：价值地图部分
展示可以组合起来提供 API 的内部数据源、内部 API、应用程序及流程，从而缓解 API 使用者的痛点或创造收益。

左侧和右侧在一个接口处相遇，这个接口是一个包含API 为使用者提供的价值声明 的方框，如 图 5.3 所示。

在 API 设计阶段填写 API 价值主张图时，你可以按照图 5.3 中所示的编号顺序进行。图 5.4 展示了一个产品目录 API的部分填写完成的 API 价值主张图。在下一节中，将会补充 API 区域中的操作和资源内容。

API 价值主张画布在 Andrea Zulian 和 Amancio Bouza 的著作《API Product Management》（Leanpub，2017）中有描述，他们称之为"价值主张接口画布"（value proposition interface canvas）。API 价值主张画布是 Alexander Osterwalder 的价值主张画布 （Value Proposition Canvas，www.strategyzer.com/canvas/valu... Marjukka Niinioja 的 APIOps Cycles 方法的第一步之一。

APIOps Cycles 方法简介

APIOps Cycles 方法 （www.apiopscycles.com/the-method）... Osaango 的 Marjukka Niinioja 开发，是一种协作式、精益的 API 解决方案创建与 API 策略制定方法。它从关注 API 需要满足的业务需求和支持的商业模式入手，帮助组织定义：

需要哪些 API

如何设计新的 API

如何改进现有 API

该方法包含 八个阶段：

业务优先与 API 画布
从 API 价值主张画布、API 商业模式画布和客户旅程地图入手，帮助利益相关者（架构师、方案负责人、产品经理、业务分析师等）回答应该构建哪些 API 以及原因。利益相关者可以提供细节并就以下方面达成一致：哪些 API 为业务带来最大价值、目标 API 消费者、API 需要提供的好处、开发 API 的成本，以及 API 对收入流的影响。这些问题与 API 的价值主张及其对商业模式的影响相关。

关注开发者体验
定义如何确保 API 能被目标 API 消费者发现并使用，以及组织打算如何支持和建设开发者社区。

最小可行 API 架构
定义满足每个 API 非功能性需求所需的最小架构，以优化 API 的开发节奏。

构建 API
设计数据和交互模型、制作 API 原型并实现 API，遵循组织的 API 风格指南，考虑国际和行业数据标准、通用标识符及数据时效性等要求。

API 审核
使用检查清单对 API 原型、设计或生产版本进行审核，确认其符合组织的 API 指南。

发布 API
定义需要发布的 API 资产（产品与技术文档、规格说明等）及其发现和使用方式。

监控、测量与分析
定义并监控业务与技术指标，以衡量 API 的性能与成功程度。

学习与改进
通过回顾 API 行为的定性与定量数据，改进 API 开发流程与 API 本身。

除方法官网外，还可在 Jarkko Moilanen、Marjukka Niinioja 和 Marko Seppänen 合著的《API Economy 101》（Books on Demand，2019）中找到更多各阶段的细节。

5.2.4 审查 API 资源模型

在条件允许的情况下，审查预期的 API 操作列表和 API 计划暴露的数据模型是有价值的。与 API 设计者和利益相关者就明确的 API 模型达成一致，有助于解决创建 API 定义时可能出现的一些问题，并且将该模型捕获到 API 设计流程中是一个重要步骤。

例如，在《Principles of Web API Design》（Addison-Wesley Professional，2021）中，James Higginbotham 提出了 Align-Define-Design-Refine (ADDR) API 设计流程，这是一个 设计优先 的 API 流程，包含七个步骤：

确定能带来客户成果的数字能力
捕获用户为实现成果需要执行的活动步骤和任务
按数字能力分组确定 API 边界
建立 API 配置文件，定义 API 应提供的资源和操作
针对选定架构风格（REST、GraphQL、gRPC 等）进行高层次 API 设计
优化 API 设计，结合设计反馈提升用户体验
提供 API 参考文档与入门指南

在第四步（建立 API 配置文件，即 API 所基于的概念数据模型和操作）产出物上，邀请不同角色和团队参与审查并达成共识，可以让各方对数据模型及其描述用语形成共同理解。该模型及其操作函数可以用实体关系图（ERD）、表格等方式捕获。

示例：考虑一个简单的 产品目录 API ，其数据模型由产品、评论和类别组成。这些构成了 RESTful API 暴露的核心资源：

一个产品资源可以有零个或多个评论
一个评论仅关联到一个产品
一个产品可以属于一个或多个类别
一个类别可以包含零个或多个产品

图 5.5 使用 乌鸦脚表示法 展示了这些资源之间的关系。

💡 提示：乌鸦脚表示法是一种实体关系图表示方式，用三叉形"多"符号表示关系中的多的一方。更多内容可参考：vertabelo.com/blog/crow-s...

假设该 API 还支持对这些对象执行以下操作：listCategories 、listProducts 、viewProduct 、listProductReviews 和 viewReview，如表 5.2 所示。定义好这个 API 模型后，团队就可以有一个参考，用来判断这些功能和数据如何转换成 OpenAPI 中的 RESTful API 设计。

表 5.2 产品目录 API 的 API 操作表

操作名称	操作描述	参与者	Web 资源	请求	响应
listCategories	列出所有类别	客户	Category	按字段筛选、按字段排序、排序方向、页面大小、分页游标	Category
listProducts	列出所有产品	客户	Product	按字段筛选、按字段排序、排序方向、页面大小、分页游标	Product
viewProduct	查看某个产品的详细信息	客户	Product	产品 ID	Product
listProductReviews	列出某个产品的所有评论	客户	Review	按字段筛选、按字段排序、排序方向、页面大小、分页游标	Reviews
viewReview	查看某个产品的评论	客户	Review	产品 ID、评论 ID	Reviews

这些 API 操作和资源同样可以放入价值主张图中的 API 模块中，从而完成 API 价值主张画布，如图 5.6 所示。

你已经了解了高层级的需求和期望的 API 模型。

但这个新的 API 将如何融入 Acme 的微服务架构呢？

Acme 的 API 网关负责身份验证 ，并将所有通过身份验证的请求代理到 产品目录 API 服务 。
产品目录 API 服务 实现了 API 产品接口，并负责协调对后端微服务的请求，这些微服务包括：产品服务 、类别服务 和评论服务。

这些服务提供了产品目录 API 所需的数据，API 可以利用这些数据来组合并返回响应，如图 5.7 所示。

结合所需的 API 操作和资源模型的上下文，评审人员现在对 API 的领域有了较好的理解，并且已经准备好审查 API 定义文件。

虽然这是一个简化的场景，但在实际工作中，提供类似的上下文信息会很有用，这能让评审人员对问题域有总体认识，并帮助他们理解这些内容应如何转化为 REST API 操作。

5.2.5 审查 API 定义

此时，就可以对设计变更的 PR 进行深入评审了。

如果团队已经针对 PR 运行并通过了一套全面的自动化 lint 检查 和破坏性变更检查 ，那么 API 评审人员就不必再针对这些项目进行重复检查。

要记住，引入自动化的目标之一就是减少评审所需的时间。

因此，评审人员应重点关注 API 风格指南中未被自动化检查覆盖的部分 以及一般性设计问题。

他们还应查看自动化检查报告，看看是否存在需要关注的 INFO 或 WARN 级别问题。

另外，如果评审人员在第一次查看 PR 时记录了任何评论，这个阶段的评审也应重点处理这些问题。

在评审时，我发现使用一个检查清单 很有帮助。假设组织的 API 风格指南中大多数建议都已经通过自动化检查来执行，那么检查清单主要列出人工需要关注的问题。

如果组织还没有一套完整的 API 定义自动化检查，那么评审人员就需要考虑更多细节上的风格一致性检查。

当然，这并不是评审人员时间的最佳利用方式（因此需要 lint 和自动化！），所以 API 治理职能应尽可能将这些检查自动化。

以下是示例检查清单：

检查自动化检查的报告
确认自动化检查（lint 检查和破坏性变更检查）已成功完成，并且报告中没有需要关注的警告。
考虑用户旅程
设计变更是否有助于实现用户想要完成的工作？
浏览渲染后的 API 参考文档，检查 API 文档是否清晰描述了 API 的目标以及它帮助用户完成的任务。
检查 Web 资源模型与领域模型是否一致
确认 API 设计是否包含需求中规定的正确操作和资源。
是否有缺失的操作？API 操作是否在正确的 API 边界内？
注意不一致之处以及不清晰的属性或资源命名，并在 PR 中评论指出。
在真实项目中，这时应与同事讨论术语差异。
DDD 中的"通用语言"概念同样适用于 API。
API 设计的可扩展性
思考未来如何扩展 API，无论是扩展现有操作还是添加新操作。
描述、摘要和示例是否清晰易懂
检查 info 对象中的 API 描述、各端点操作的描述以及消息属性的描述。
确认描述正确并对集成 API 的开发人员有意义。
检查 API 定义中的示例值是否尽可能有用且真实。
错误响应是否完整并使用了正确的错误码
确认 HTTP 错误码适用于该操作，并且没有缺失重要的响应场景。
检查失败响应体中的自定义错误字段是否合理。
幂等性要求是否满足
当一个端点是幂等的时，相同的请求可以多次运行，但服务器上的状态更改只会发生一次。
检查 API 操作是否天然幂等，或在需要时是否有幂等性 key。
考虑 API 设计的非功能性方面
包括安全性、分页以及其他可能影响性能的设计因素。
除了身份验证和授权之外，还应考虑请求和响应消息的结构与验证等安全指南。
第 9 章会讨论 lint 安全检查。

注意：根据 HTTP 规范，GET、PUT 和 DELETE 天然是幂等的；POST 和 PATCH 则不是。

如果在需要幂等的操作中使用了 POST 或 PATCH（例如支付接口），必须添加幂等性 key 以检测并处理重复请求。

在 API 评审会议中，我通常让评审人员将反馈作为 PR 评论提交，并一起讨论最重要的问题。

以这种方式记录评审反馈有助于主持人跟踪问题的解决情况。

5.2.6 记录新的 API 模式或风格指南缺口

API 评审会议是发现新 API 模式的好机会，这些模式可能需要纳入组织的风格指南中。

会议还可能揭示风格指南中的模糊点 和缺口，这些会导致 API 设计人员对某些设计元素的处理缺乏明确指导。

API 评审主持人应记录这些内容，与相关职能部门（例如 API 治理团队或内部 API 实践社区）进一步讨论，

可能会促使更新 API 风格指南和 lint 规则。

主持人应注意发现这些缺口，并思考如何改进风格指南来覆盖这些情况。

5.2.7 会后调查

为了改进今后的评审会议，主持人可以在会议结束时请参与者填写一个简短的反馈问卷（1~2 个问题）。

我会在 5.5 节进一步讨论这个内容。

你已经了解了开展 API 设计评审的基本结构。接下来，让我们看看团队在 API 评审中通常会面临的一些挑战。

5.3 API 评审的挑战

以下是我在 API 设计评审中常见的一些挑战：

让经验不足的 API 设计师和评审人员持续采用自外而内、以用户为中心的视角
当 API 建模不佳时所需的额外评审工作量
API 评审发生在设计过程过晚阶段的问题
决定应用何种评审深度的挑战

5.3.1 采用以用户为中心的方法

对于经验不足的 API 设计师来说，采用用户视角 进行 API 设计有时很困难。

这种问题往往表现为：API 设计为了方便后端实现而牺牲了 API 使用者的可用性，或者文档质量差。

大量 API 评审精力都花在让团队转向用户视角上，即从终端用户旅程地图出发，反向推导设计（见图 5.8）。

一个可行的办法是让 API 设计团队提交的不仅是 OpenAPI 定义文件，还包括 API 的早期草稿和指南文档。

先编写 API 指南文档可以帮助设计人员从用户的视角来看待 API。

另一个有助于评审人员培养以用户为中心视角的有用工具是用户旅程地图 。

用户旅程地图（也称为客户旅程地图）是一种可视化方法，用于展示用户在与产品或服务交互以完成某个目标或任务时所经历的过程。

用户旅程是从执行操作的角色或用户画像视角绘制的。它描述了场景、角色希望实现的目标、用户旅程中的不同阶段或高层次环节，以及用户在这些阶段执行的操作。

服务蓝图 是在用户旅程地图基础上的进一步扩展，它描述了用户在旅程中交互的各种服务组件（例如，提供者的 API）。

服务蓝图有助于评审人员将视角从"内向外"（即由内部流程和系统驱动用户体验决策）转变为"外向内"，聚焦用户的行动和思考。

提示：想了解更多服务蓝图内容，可访问 Nielsen Norman Group 的网页：mng.bz/aEeB

服务蓝图可以帮助设计师和评审人员关注用户旅程中各阶段的用户行为和机会，进而设计出更具扩展性的 API，以适应未来可能出现的新需求。

不过，用户旅程地图只有在 API 评审阶段才可用，前提是 API 设计人员在设计过程中提前创建了该地图。

这时，像 APIOps Cycles 方法这类方法就非常有用，因为它的第一阶段------"以业务为先的 API 画布"------会引导设计师创建用户旅程。

更多相关信息可见：www.apiopscycles.com/method/api-...

5.3.2 评审前建模不佳

RESTful API 设计基于对 API 资源、资源之间关系以及资源操作的理解。

当经验不足的设计师没有做好适当的 API 建模时，API 评审通常会发现该 API 未遵循 RESTful 规范的问题，

这可能导致冗长的评审讨论。

帮助团队做好 API 建模能解决这些问题，但最好是在设计初期就完成，这也是下文要讲的内容。

5.3.3 评审发生在设计流程后期

API 评审会议和自动化检查能很好地发现设计提案中的一致性和可用性问题，

但这通常已经为时过晚。

评审人员在设计早期介入，向团队提供设计工具和指导，可以带来更大价值。

这包括确保团队能够找到 API 风格指南，使用 API lint 工具，以及参与正确的 API 建模和服务设计。

API 评审和自动化检查不能替代设计团队的早期参与。

5.3.4 决定评审深度

有时团队不确定是否应对所有类型的 API（内部、合作伙伴、公开）都采用相同级别的治理。

一旦自动化检查集成进流水线，扩展至更多 API 定义文件的成本较低，因此应尽可能多覆盖。

而 API 评审需要人员协调与安排，耗费时间多，成本较高。

经验法则是：

仅对面向外部的 API（公开和合作伙伴）或有潜力成为面向外部的 API 进行设计评审会议。

永远不会对外暴露的内部 API 不必强制经过同样严格的评审（但设计人员如果愿意，也可主动申请评审）。

API 设计原则层级结构

在《API Product Management》一书中，Andrea Zulian 和 Amancio Bouza 提出了 API 设计原则的层级结构。

他们指出，一个有价值的 API 的基础原则是为 API 客户（即使用 API 功能完成其任务的终端用户）提供清晰的价值主张，

而 API 产品经理的职责就是帮助定义和验证这一价值主张。

在此基础上，下一层原则是为集成该 API 的开发者创造良好的开发者体验。

这包括提供优秀的 API 文档、无障碍的入门流程（如提供 API 密钥或其他身份验证机制）、沙盒环境以测试 API、API SDK 等。

API 管理平台和开发者门户使这些成为可能。

层级结构中的第三层原则是定义 API 哲学。

这意味着基于价值主张和开发者体验的约束，应用 API 治理、API 风格指南和 API 工程知识，

如下图所示。

Andrea 和 Amancio 主张，API 的价值主张是最关键的，其次是开发者体验。在需要在 API 设计原则中做权衡时，他们建议应在 API 哲学层面做调整，以确保价值主张和开发者体验不受影响。这是在审查 API 时值得牢记的有用指导。

5.4 评审效果的衡量

假设你已经在 API 设计的 PR 上实施了自动化检查，并建立了在必要时进行 API 设计评审会议的流程，那么你如何衡量这些流程的效果呢？

5.4.1 自动化检查

通过自动化检查，你可以跟踪因自动化检测发现的 lint 问题、重大变更缺陷以及 API 一致性问题（API 一致性将在第 6 和 7 章中讨论），从而为 API 设计质量维持一个评分。

对于小团队而言，将这些检测结果存储为 CI 服务器中的构建产物即可满足需求。

但对于较大的团队，可能需要一个 API 记分板，用于收集和展示这些 API 一致性和设计质量的指标。

5.4.2 设计评审会议

收集 API 设计人员对 API 评审会议有多大帮助的反馈很重要，这些反馈可以用于改进和微调评审流程。

我推荐两种收集评审会议反馈的方式------基于会议的反馈和定期反馈。

基于会议的反馈 ：评审会议结束时，由主持人请 API 设计团队填写一个简短匿名调查，通常通过链接提供。调查旨在收集会议的实用性反馈。

两个问题通常足够：

1）用 1 到 5 星评级会议的价值（例如，"你认为此次评审会议对提升 API 设计质量有多大帮助？"）；

2）开放式问题收集任何建议（例如，"你有哪些改进意见？"）。

定期反馈 ：例如每年一到两次，向 API 设计人员收集更全面的反馈。

调查内容可以是关于整体 API 设计、可用性、文档、规范一致性及避免重大变更的 Likert 量表问题，并包含开放式评论。示例如下：

复制代码

API 设计评审有助于改进我们 API 的整体设计。  
强烈反对 | 反对 | 中立 | 赞同 | 强烈赞同

API 设计评审有助于提升我们 API 的可用性。  
强烈反对 | 反对 | 中立 | 赞同 | 强烈赞同

API 设计评审有助于改进我们的 API 文档。  
强烈反对 | 反对 | 中立 | 赞同 | 强烈赞同

API 设计评审有助于提升我们 API 与组织 API 风格指南的一致性。  
强烈反对 | 反对 | 中立 | 赞同 | 强烈赞同

API 设计评审帮助团队避免做出破坏性变更。  
强烈反对 | 反对 | 中立 | 赞同 | 强烈赞同

你有哪些改进建议？

随着时间推移，对比这些反馈结果，可以反映设计评审改进工作的效果。

除了收集 API 设计人员的反馈外，API 评审人员或组织中的 API 治理团队也可以召开敏捷回顾会议，探讨如何改进 API 设计评审流程。

此外，根据 API 治理团队规模及其服务的团队数量，API 评审人员还可以跟踪一个关键绩效指标（KPI）------待处理的 API 设计 PR 数量。

例如，GitHub 和 Bitbucket 这类托管的版本控制服务会提供 PR 统计报告。

评审团队应力求快速响应 API 设计 PR，并保持等待评审的 PR 平均开放时间较短。

5.5 定义你的 API 设计评审流程

为了促进大规模高效的 API 设计评审，文档化你的流程非常重要，这有助于减少歧义和混乱，提高设计评审的一致性。文档化还简化了新成员的培训和入职过程，并有助于你分析和改进评审流程本身。

对于大规模构建 API 的大型组织，通常会有一个中央 API 治理团队，负责维护对外 API 的设计质量和一致性标准，并定义团队在公开 API 时需要经历的设计评审流程。

软件团队在 API 项目的性质和范围、现有实践、组织文化等方面差异很大，因此没有一套适用于所有团队的通用 API 设计评审流程规则。每个团队应根据自身实际情况考虑哪些指导原则能解决其面临的问题。不过，以下各小节为团队在创建 API 设计评审流程文档时提供了一些建议。

5.5.1 确保文档易于发现

将 API 设计评审流程文档放在团队能够轻松找到的位置，比如内部 Wiki 页面或共享文档。我的组织内部调查显示，大多数利益相关者更喜欢把该文档（连同 API 风格指南）放在与 API 定义文件相同的仓库中。不论放在哪里，文档都应易于查找和链接，因为团队会经常引用它。

5.5.2 定义原则和目标

概述指导 API 评审流程设计的价值观和原则。比如，你可能决定更看重 API 对消费者的易用性和直观性，而不是反映组织内部技术系统和架构。借鉴敏捷宣言，你可能更看重快速响应业务对 API 设计变更的需求，而非严格遵循既定设计或计划。

你可以包括"外部 API 应优先设计并评审（设计优先）"，因为先设计并与同事评审设计，能带来更佳的 API 设计和用户体验，同时降低实现成本。

另一原则可能是，API 评审者及最终用户应能通过阅读 API 参考文档和指南理解 API 的功能，这意味着提供的文档必须充分且易于理解。

以上仅为示例，请结合你团队实际情况制定合适的价值观和原则。

基于这些原则，API 设计评审流程应追求以下目标，并可以设定相应的衡量指标：

质量------提升 API 设计质量和与标准的一致性。
速度------减少设计变更评审和批准所需时间。
可靠性------设定期望，及时安排并完成评审，帮助项目经理、产品经理和销售团队按计划满足客户承诺和交付截止。关键在于确保评审人员的足够容量。
灵活性------针对不同规模的评审进行优化，既能处理小改动（如给已有接口添加属性），也能支持大型改动（如新增整个 API）。同时适应评审优先级根据交付计划变化进行调整。
成本------降低评审成本。评审需要关键工程师、架构师、产品经理、安全专家等参与，长时间面对面会议成本高昂，应确保评审价值大于成本，避免设计错误、延期、沟通不畅和无效会议带来的浪费。

5.5.3 描述评审流程指标

在 5.4 节中，我提到了一些衡量 API 评审有效性的关键绩效指标（KPI），评审流程文档应描述这些指标，方便相关人员了解和查看性能数据。

5.5.4 明确流程中的角色和职责

大规模设计评审时，应明确谁负责哪些工作。如 5.2.1 节提及，API 设计评审的三个主要角色是 API 设计者、API 评审者和评审主持人。

提示

定义角色和职责的一种方法是使用责任分配矩阵（RACI 表），它列出任务并定义谁负责（Responsible）、谁承担最终责任（Accountable）、谁需要被咨询（Consulted）以及谁需被告知（Informed）。详见：www.mindtools.com/agn584l/the...

举例来说：

评审主持人负责管理评审的行政事务，包括安排会议、确保评审 PR、工单和状态看板更新、分配评审人员、确保按时完成评审、确保利益相关者能找到所需信息。小型组织可能不需要专职主持人。
API 评审者负责提供评审反馈，最好以 PR 评论形式记录。大型组织可能有专职评审，小型组织则可能依赖志愿者或临时评审。评审者应安排时间进行评审，并具备对 API 仓库的 PR 批准权限。
API 设计者负责提交 API 设计变更供评审，需负责与评审者讨论并实施建议的修改。

5.5.5 按需安排面对面评审

如果你已经有 CI/CD 流水线自动检查 API 设计变更 PR，且设计者也随 PR 提供支持的 API 指南草稿（将发布在开发者门户），可以考虑仅在评审者或设计者请求时才举行面对面会议，比如 PR 讨论无法解决问题时。

理想情况下，评审者应能通过 API 定义文件和相关文档理解并评审设计变更。API 消费者主要依赖文档理解 API，因此评审者也应如此，无需依赖会议中人员解释。鉴于会议时间成本较高，应仅在必要时安排面对面评审。

5.5.6 按需区分 API 评审级别

流程中最好明确组织内不同类别 API 需要的治理级别，帮助团队判断是否需请求 API 治理团队评审。可以用表格描述每类 API 所需的评审级别。

表 5.3 示例：

API 类别	外部暴露的 API	自动化 CI/CD 检查	内部开发团队 PR 评审	治理团队 PR 评审
内部 API	否	是	是	否
内部 API（可外部化）	是	是	是	可选但推荐
私有 API	是	是	是	是
外部 API	是	是	是	是

5.5.7 明确审批步骤

遵循"设计优先"原则，流程文档应明确标志设计变更被接受的动作，比如批准并合并 PR 或变更关联评审工单状态。这样能支持并行开发，避免开发团队在设计尚未定型时就开始实现。

5.5.8 审批后变更

审批步骤并不意味着设计一旦批准后就不能修改。如果实施过程中需要复审设计，设计者可以发起新的设计变更 PR 并通知评审者和相关人员（如前端团队），按常规流程评审和合并。

对于轻微修改，应尽快完成。敏捷流程欢迎变更，即使开发后期也允许调整，以满足客户竞争优势（参考敏捷宣言）。

5.5.9 明确如何标识例外

有时确有合理理由偏离组织的 API 风格指南，比如扩展旧版 API。流程应明确设计者如何标识这种例外情况及其原因，一种做法是在 OpenAPI 定义中使用自定义扩展标记相关组件，并附上文档说明。评审主持人应评估是否需更新 lint 规则，对此类例外做忽略处理。

5.5.10 描述评审优先级的确定方式

小团队可能无此需求，但拥有大量 API 的组织，评审主持人可能需对设计变更提案进行优先级排序。评审流程文档应明确优先级判断标准，如交付目标日期等，有助于实现"可靠性"目标。

支持优先级标签的代码协作平台（如 GitHub）可用 PR 标签分配优先级，或者用关联工单的优先级标签。

5.5.11 提供预计评审时间

为了保证"可靠性"，描述设计者应等待中央治理团队评审 PR 的时间范围有助于产品和项目经理合理计划，并对客户及其他利益相关者设定预期。可按评审类型分类，例如：

表 5.4 示例：

变更类型	评审时间（工作日）
扩展现有端点上的资源属性	最多 1 天
为现有资源添加新端点	最多 2 天
添加新资源和新端点	最多 5 天

5.5.12 让评审工作可见化

一些大型团队会将评审 PR 关联到工单，治理团队用状态看板展示工单状态；其他团队则用 PR 标签显示优先级。这样方便设计者和利益相关者了解进展。

评审主持人需确保工单状态和 PR 标签及时更新。状态看板示例状态包括：

待办：PR 创建，等待分配和优先级排序
已分配或已排期：PR 分配

5.6 API 评审示例

到目前为止，我介绍了一个简单的 API 评审方法。但也值得看看那些大规模构建 API 的组织是如何进行 API 评审的。下面我们来看两个例子------微软 Azure 和谷歌。

5.6.1 微软 Azure 的 API 监管（API Stewardship）

微软 Azure 开发部门推行 API 监管的理念。他们将 API 监管定义为尽早与内部开发团队合作，帮助他们将良好的 API 设计实践融入开发流程。目标是创建一种文化，帮助 Azure 内部开发团队设计和构建易用、在 Azure 产品间保持一致、符合行业规范且可扩展的 API。

API 监管团队由经验丰富的从业者组成，包括客户成功现场团队成员、Azure 服务工程师、SDK 架构师、CTO 办公室成员等。组织内任何对 API 感兴趣的人都可以参与，这是一个开放的兴趣小组，也包括热心的志愿者。

该团队采用三管齐下的方法推进 API 监管：

第一，在 API 设计阶段就介入，教育团队 API 设计流程，帮助他们定义 API 风格指南、API 文档和破坏性变更策略，还提供团队所需的通用 API 和服务设计支持内容。
第二，为团队提供基础设施和工具，实现对 PR 的自动 API 设计检查（包括代码风格和破坏性变更检测），并自动生成客户端库、移动 SDK、模拟服务器、REST API 文档等 API 工件。他们自动检测的 API 指南内容覆盖了三分之二，剩下的由设计评审覆盖。
第三，通过 API 设计评审和 API 预览赋能团队。在设计评审时，API 监管团队先让团队介绍 API 领域和目标，然后用 Swagger 编辑器查看 OpenAPI 定义文件中的请求/响应示例，寻找常见设计陷阱（如幂等性和分页设计）。接着讨论代码流程、API 未来演进、多态性、批量操作等设计决策。设计评审中也包含产品经理，因为设计决策可能影响产品方向。除了设计评审，他们还帮助团队设计 API 预览阶段（即实验性质的早期版本供客户集成），并明确预览目标，以便从早期用户获得反馈。

提示：想了解更多微软 Azure 监管模式，可以看 Mike Kistler 和 Mark Weitzel 的演讲《Building APIs at Scale: Moving from API governance to API stewardship》（链接：www.youtube.com/watch?v=sbo... Adrian Hal 的《Lessons Learned on the Azure API Stewardship Journey》（链接：mng.bz/gv0E）。

在 Azure，API 监管需要投入专门的人员，包括产品经理和架构师，并创建支持内容和工具。重点是让团队在设计阶段就能做好 API 设计，而不是在 API 一般可用阶段才进行治理和监管，那时很多变更已难以实施。

5.6.2 谷歌的 API 改进提案流程（API Improvement Proposal）

谷歌的 API 设计评审旨在确保 Google API 简单、直观且与现有 API 保持一致。谷歌的 API 风格指南是一个高层次且简明的文档，称为 API 改进提案（API Improvement Proposal，简称 AIP；网址：aip.dev）。谷歌还提供了一个.xn--4gqvd6l81b843dp5jn99cncg/) linter 工具（网址：linter.aip.dev），用于检测,-w41hw87m3uhtns/) API 是否符合 AIP 规范。并非所有 AIP 指南都能用 lint 规则表达，设计者仍需仔细阅读理解 AIP。

Google 要求在发布面向用户的 API（无论是 Beta 版本，还是正式对外开放的稳定版本）前必须经过 API 设计评审。内部仅供 Googler 或内部工具使用的 API 则不强制。

谷歌 API 治理团队有少数专职评审员，同时还有大量有 API 设计经验的志愿评审工程师。评审者从 API 的操作、资源及面向用户的文档角度，以新手用户的视角审查设计，并确保其符合 AIP 且具备良好的扩展性。API 设计评审通常通过谷歌内部代码审查工具异步完成（对 PR 进行评审）。复杂问题无法通过讨论解决时，设计者可以联系评审员安排半小时会议。

提示：想了解谷歌如何引入 API 设计评审来解决质量与一致性问题，可参见 2016 年谷歌论文《API Design Reviews at Scale》（CHI'16 Extended Abstracts，链接：research.google/pubs/pub452...

谷歌的评审流程还会告知设计者评审所需时间。对现有 API 的增量变更一般几天内完成，新建小型 API 大约一周，较大 API 则可能耗时更长。

5.6.3 Slack 的 API 设计评审流程

Slack 的 API 设计从开发团队定义 API 用例和设计目标开始，创建 API 定义文件，并在内部 #api-decisions Slack 频道分享进行评审。该频道聚集了跨职能的评审和利益相关者，涵盖工程、产品管理、开发者关系和安全等。对某些变更，异步评审即可批准；对另一些，需要更深入讨论，设计者会安排在固定的 API 办公时间内与评审员进行面对面评审。

内部评审结束后，API 定义文件还需经过一轮面向精选合作伙伴的审查，收集反馈。处理完反馈后，API 进入实现阶段，并提供给部分合作伙伴进行预览和 Beta 测试，继续根据反馈完善后再公开发布。

更多信息请参见 Slack 博客《How We Design Our APIs at Slack》（链接：mng.bz/eoGv）。

5.6.4 Kubernetes 的 API 评审流程

Kubernetes（网址：kubernetes.io/）是一个管理容器化应用... CPU、内存等指标的应用部署和扩缩容机制。其控制平面包含一个 API 服务器，提供 REST API 来管理 Kubernetes 对象状态，客户端可通过该 API 配置工作负载和容器。Kubernetes API 规模庞大，包含数百个端点。为了支持 API 扩展，资源被分为多个 API 组，且这些组有版本管理。核心组（legacy）使用路径前缀 /api/v1/（如 GET /api/v1/namespaces/test/pods），其他组使用 /apis/$GROUP_NAME/$VERSION（如 /apis/batch/v1/）。

Kubernetes API 设计评审流程（链接：mng.bz/ppX8）描述了项目如... API 评审维护 API 一致性和可用性。流程明确哪些 API 变更必须强制评审（如核心 API 变更），哪些是自愿评审。Kubernetes 有一套 API 风格指南，称为 API 约定，API 设计者提交变更 PR 前需阅读并遵循该约定。PR 需说明变更目标，并关联一个已完成的 Kubernetes 增强提案（类似功能或需求文档）。

API 评审员和协调员定期对评审请求进行分类。符合项目要求的请求会加入 API 评审委员会（一个状态看板，用于展示待评审 PR 状态和评审员负载）。协调员（项目中称为主持人）根据发布版本目标、项目负责人反馈、变更大小与复杂度、变更稳定性（正式 > 测试版 > 预览版）调整评审优先级，保证高优先级变更优先评审。协调员根据评审员容量和领域知识分配评审任务，减轻评审员的行政事务负担，安排必要的面对面评审会议。

API 评审看板的状态流转包括：待办 > 已分配 > 进行中 > 变更请求 > 评审完成。通过的 PR 会链接到实现 PR 供代码审查，极少数 PR 可能被拒绝（如不属于 Kubernetes 项目的变更）。

流程文档给设计者一个时间预期：优先级评审和调度最长一周，首次评审最多三周。

想成为 Kubernetes API 评审员，需深入掌握 API 风格指南，理解项目结构和系统架构，参与导师指导的初期评审，导师帮助培训并促成正式评审员身份。

总结

在 APIOps 的 API 评审中，你会在自动化检查完成后对 API 设计的 PR 进行审查。你的评审目标是发现自动化检查无法发现的问题。

API 评审可以采用异步方式或面对面进行，评审者可以在 PR 上留下评审意见。

在 API 评审时，采用以消费者为中心的方法，从 API 消费者使用的 API 定义开始，向后推导到内部接口。确保在开始评审前理解问题的背景和上下文。

大型组织中的 API 评审通常涉及 API 设计者、API 评审者和 API 评审协调员。评审还应包括对 API 评审感兴趣的同事。

用户调查是衡量 API 设计评审会议效果的有效方式。自动检查报告可以被收集，用于维护 API 设计质量评分。