导读：本文为 API 开发实用指南以及如何保证稳定、连贯，如何设计可组合的业务资源 API 的研发最佳实践。

简介

API 规范文档是一种纯技术型开发工作，但从前几乎没有多少机会让业务和企业相关进行有意义且有用的设计。

在构建可重用、稳定、连贯和可组合的 API 的企业 API 结构时，由企业指导的、面向领域的 API 设计实践是必不可少的。

API 设计目标

API 设计阶段以域数据模型的捕获和验证以及业务资源的状态生命周期为中心。数据/REST 模型的质量对 API 的可用性、可演化性和安全性有着重大影响。

协作设计研讨会和建模工具将允许来自企业所有者、领域架构师、数据建模师、安全架构师、REST 和 EDA SME、技术总监和开发人员等相关群体与同一领域进行交互数据模型。

通过这种方式，领域模型“充当一种无处不在的语言，帮助软件开发人员和领域专家之间进行交流”（Fowler，M 2014，BoundedContext），从而达到最大化协作，提供尽可能紧密的反馈循环，并确保领域模型，保持最终来源的真实。

使资源 API 与业务领域保持一致

从记录系统业务服务管理的业务信息、事件和流程中，抽象出一个或多个规范的业务资源 API。

业务资源表示系统的名词，例如“应用程序”和“申请人”。它们提供与业务功能交互的上下文，代表业务领域的业务事实，并且当一致建模、可发现和可订阅时，它们将成为联合数据平台的支柱。

可组合性设计

微服务架构和 REST 架构风格通过将编排责任从资源服务器转移到客户端来实现解耦、自助服务和重用。

这种责任转移允许业务系统为其业务资源和功能构建稳定并通用的接口，而无需与客户端系统紧耦合，这反过来又允许客户端系统通过自助服务集成组合数据，而不会阻塞对外部的依赖。

API 客户端通常希望访问有关特定业务对象的核心信息，而并非复杂的数据结构，并且用户希望访问速度更快。 

一个好的 REST 模型，其关注的是在客户系统可能感兴趣的业务数据的粒度与内聚单元之间找到平衡（尽管对他们的需求来说不是多余的）。

简而言之，API 的设计需要平衡一些可组合性与内聚性。

早期和持续的利益相关者参与

业务领域专业知识和企业 API 设计标准为 API 设计阶段提供基础信息。

REST 模型为外部系统提供了通用标准、通用 RESTful 操作与业务对象、数据和流程安全交互的方法。模型的质量对 API 的可用性、可演化性和安全性有重大影响。

有许多利益相关方投资于塑造和验证模型，他们的角色可能包括：

• 企业主（领域专家）

• 领域架构师

• 企业架构师（企业、安全、数据）

• API 平台 REST 中小企业

• 技术主管/API 开发人员

• 紧密结合的客户端应用程序团队

计划流程

在项目的规划阶段，确定并聘请来自上述每个利益相关者群体的代表。思考是否可能有密切合作的客户应用程序团队，或其他投资方可以提供有价值的反馈，并从每个团队中选出一名代表。

请记住，该过程是迭代的

尽早捕捉自己对该领域的理解。可以使用协作工具和可共享的模型，来征求利益相关者的更正和意见。

准备

确定将用于流程的工具，并确保为建模者和利益相关者提供可访问权限。开发人员/建模人员应在开始流程之前应该熟悉工具、流程和企业API 设计标准。

对于遗留系统采用“自下而上”分析，可能会有更大的帮助。

API 设计标准编写

根据您的组织环境，定制资源 API 设计标准的 八步指南。如下：

1. 举办设计研讨会

与领域 SME 建立初始研讨会——那些对业务流程、监管义务等有深入了解的领域。协作的面向领域的设计研讨会，如事件性头脑风暴，是一个相互发现、验证和就模型、边界和业务事件达成一致的讨论区.

当与许多利益相关者一起举办设计研讨会（现场或在线会议）时，协作白板工具将使你能够捕获、共享和验证对业务事件、流程、参与者和实体的观点。事件风暴技术可以为设计研讨会提供一些结构，以及一种获取有关领域的集体知识的方法。

来看下图：

Event Storming 流程的简要概述如下：

• 确定场景：对要捕获的过程，进行简短而集中的要点描述。

• 识别事件：在领域中发生的事情，用过去时写成并表示为流程或顺序。

• 捕获命令和聚合/实体：以及适当的参与者、外部系统、流程/策略和问题/热点。

• 识别限界上下文：公共语言和功能的独立集群——每个限界上下文都应该“解耦”，表达自己的模型和自己的 API。

事件风暴过程使用彩色“便签”（物理或数字均可）来探索、组织和迭代场景中的新兴元素。研讨会的时间限制阶段是该过程的重要组成部分。

经过验证的业务事件、命令、聚合和实体的高级视图是域数据模型的关键输入。

2. 数据建模并持续验证

在协作数据建模工具中捕获设计研讨会中出现的聚合/实体，并让关键利益相关者参与验证和丰富模型，并充分考虑企业命名约定。

与企业数据架构师和领域架构师一起探索行业模型和形式的适用性，以及地址数据结构等“企业”实体架构类型的重用。

当就记录系统管理的数据达成基线协议，请就适用于数据的分类、警告和控制寻求安全架构的建议，然后在模型中针对每个实体进行注释。

接下来考虑 REST 建模指南，并在模型开发时验证具有API 能力的 REST SME 的可组合性和内聚性。

在开发 REST 层时，需要考虑Enterprise API Path Conventions和HTTP Request and Response Protocol。

尽可能广泛地向更广泛的利益相关者群体迭代和传播重大模型更改，你的API设计工具应有助于通知利益相关者。

3. 生成并完善您的 API 规范

当模型相对稳定时，创建模型的版本化快照并生成原型 API 规范以供技术审查和验证。版本对齐的 API 规范是根据标准和符合政策的规则或模板从 REST 模型生成的。

在准备发布之前，您可以选择使用初始版本“0.xx”原型 API 规范。请记住，除了初始 V1 之外，主要版本增量必须仅适用于对生产（“实时”）API 的重大更改。

API 规范的验证和完善

API 定义文档，无论是手工制作的、生成的还是预先存在的，都需要进行审查和技术 验证，并且在许多情况下需要进一步完善。

使用具有 OpenAPI/AsyncAPI 文档检查支持的 IDE——它将提供有关 API 质量和强制性 API 文档规则的即时反馈。

API 文档 linting 规则应明确定义。Spectral OpenAPI 规则作为基本 OpenAPI 文档规则集被广泛引用。

有关 API 文档 linting 的更多信息：

API文档规则

• 使用 OpenAPI 文档和 Linting 规则提高 API 的质量和一致性

• 模型驱动，API 优先开发

API 优先是一种微服务或模块化服务开发模型，它将 API 视为与业务功能和有关域的业务事实进行交互的主要方式。当这些 API“产品”被简化以实现一致性和可重用性时，它们将有助于构建一个丰富且可组合的联合数据平台。

API作为服务的初级产品，首先被设计出来，并作为服务实现的模板。当从经过验证的领域模型和 API 定义文档构建时，产品团队可以利用代码生成器来加速开发。

根据 API 定义文档，OpenAPI 和 AsyncAPI 生成器可以自动为支持的语言（例如 Java/Spring、Node.js）创建一致的脚手架/骨架实现。模拟服务器和 API 测试也可以从 API 规范文档中生成。

对于 API 优先和模型驱动的开发，API 规范的来源必须是模型驱动的设计实践，如上文所述，API 规范的真实来源必须是经过验证的领域模型。

遗留和专有 COTS/SaaS API

没有可共享数据模型的遗留或 COTS/SaaS API 定义文档更难以验证、发展和映射到企业环境。然而，当组织向新平台和架构过渡时，就会出现这种情况。考虑：

• 使用模型驱动设计工具追溯捕获 API 数据模型。

• 
  

• API 和/或 OpenAPI 文档的哪些元素可以迭代改进/重构以符合 API 和文档规则。

• 战术“反腐败层”集成解决方案是否可以提供整净且一致的 API。

API 设计工具与设计工作室工具

“事件风暴”技术是以白板为中心的设计工作坊，适合现场在线协作。Judith Birmoser 的 Miro 数字白板平台的事件风暴模板是一种简单的入门方法。

领域数据建模和模型驱动设计工具

领域建模工具应该支持源代码控制，以及跨模型及其衍生工件的语义版本管理 ——有助于维护已发布 API 的通用性和可追溯性的功能。

其他强烈支持模型驱动开发的平台功能包括设计时模型验证、状态生命周期文档（例如状态生命周期图）、依赖关系的映射和管理、通知管理以及模型可发现性、共享和重用。

域数据建模工具（具有广泛不同的功能集）包括：

• 行业领域数据建模平台

• 视觉范式

• Mendix 低代码平台

• Sparx EA + OpenAPI 插件

• API 规范技术验证工具

Spectral是一种广泛使用的开源 OpenAPI/AsyncAPI 文档 linter，具有可扩展的规则集。以下工具支持 Spectral linting：

• Jargon平台支持域数据和 REST 模型层的 Spectral linting。

• Visual Studio Code：通过 Stoplight 安装“Spectral”扩展。规则错误和警告列在问题控制台中，并在进行更改时动态更新。

• Stoplight Studio：上传 OpenAPI 或 AsyncAPI 规范，spectral 将提供即时动态反馈。警告图标将切换并排视图。

• CI/CD 管道：除了对您的软件源代码进行自动 Sonarqube 分析外，集成和构建管道还可以支持对您的 OpenAPI 定义进行光谱检查，以确保及时反馈文档质量问题。

• 代码生成工具

有各种可用于不同编程语言的本地可配置生成器。以下为一些资源：

• OpenAPI 设计和文档工具 | 昂首阔步

• OAS OpenAPI 生成器：https://openapi-generator.tech/docs/generators/和https://github.com/OpenAPITools/openapi-generator

• 各种 OpenAPI 工具：https: //openapi.tools/

测试并生成API

以下是支持从 OpenAPI 和/或 AsyncAPI 规范文档生成测试的测试平台的（非详尽）列表：

Postman API 平台、Thunder Client — VS Code 的扩展、karatelabs/karate、Pact (pact.io)、Katalon 质量管理、Insomnia API 开发平台、SOAPUI、REST-Assured + Tcases

总结

API规范文档是个纯技术型文档。它通常在开发工作中生成，而技术能力较低的用户很难理解。

如果没有指导性的 API 设计实践文档，大部分企业很难控制业务 API 的质量。

为了最大化利益相关者协作的机会并提供尽可能紧密的反馈循环，最重要的是在将任何内容提交给代码之前捕获、共享和验证 REST 模型。明确定义和支持的 API 设计实践可以确保 API 及其底层数据模型都是可见的、可重用的与可管理化。