导读:本文为 API 开发实用指南以及如何保证稳定、连贯,如何设计可组合的业务资源 API 的研发最佳实践。
简介
API 客户端通常希望访问有关特定业务对象的核心信息,而并非复杂的数据结构,并且用户希望访问速度更快。
一个好的 REST 模型,其关注的是在客户系统可能感兴趣的业务数据的粒度与内聚单元之间找到平衡(尽管对他们的需求来说不是多余的)。
简而言之,API 的设计需要平衡一些可组合性与内聚性。
有许多利益相关方投资于塑造和验证模型,他们的角色可能包括:
企业主(领域专家)
领域架构师
企业架构师(企业、安全、数据)
API 平台 REST 中小企业
技术主管/API 开发人员
紧密结合的客户端应用程序团队
请记住,该过程是迭代的
尽早捕捉自己对该领域的理解。可以使用协作工具和可共享的模型,来征求利益相关者的更正和意见。
1. 举办设计研讨会
与领域 SME 建立初始研讨会——那些对业务流程、监管义务等有深入了解的领域。协作的面向领域的设计研讨会,如事件性头脑风暴,是一个相互发现、验证和就模型、边界和业务事件达成一致的讨论区.
当与许多利益相关者一起举办设计研讨会(现场或在线会议)时,协作白板工具将使你能够捕获、共享和验证对业务事件、流程、参与者和实体的观点。事件风暴技术可以为设计研讨会提供一些结构,以及一种获取有关领域的集体知识的方法。
来看下图:
Event Storming 流程的简要概述如下:
确定场景:对要捕获的过程,进行简短而集中的要点描述。
识别事件:在领域中发生的事情,用过去时写成并表示为流程或顺序。
捕获命令和聚合/实体:以及适当的参与者、外部系统、流程/策略和问题/热点。
识别限界上下文:公共语言和功能的独立集群——每个限界上下文都应该“解耦”,表达自己的模型和自己的 API。
事件风暴过程使用彩色“便签”(物理或数字均可)来探索、组织和迭代场景中的新兴元素。研讨会的时间限制阶段是该过程的重要组成部分。
经过验证的业务事件、命令、聚合和实体的高级视图是域数据模型的关键输入。
在协作数据建模工具中捕获设计研讨会中出现的聚合/实体,并让关键利益相关者参与验证和丰富模型,并充分考虑企业命名约定。
与企业数据架构师和领域架构师一起探索行业模型和形式的适用性,以及地址数据结构等“企业”实体架构类型的重用。
当就记录系统管理的数据达成基线协议,请就适用于数据的分类、警告和控制寻求安全架构的建议,然后在模型中针对每个实体进行注释。
接下来考虑 REST 建模指南,并在模型开发时验证具有API 能力的 REST SME 的可组合性和内聚性。
在开发 REST 层时,需要考虑Enterprise API Path Conventions和HTTP Request and Response Protocol。
尽可能广泛地向更广泛的利益相关者群体迭代和传播重大模型更改,你的API设计工具应有助于通知利益相关者。
对于 API 优先和模型驱动的开发,API 规范的来源必须是模型驱动的设计实践,如上文所述,API 规范的真实来源必须是经过验证的领域模型。
使用模型驱动设计工具追溯捕获 API 数据模型。
API 和/或 OpenAPI 文档的哪些元素可以迭代改进/重构以符合 API 和文档规则。
战术“反腐败层”集成解决方案是否可以提供整净且一致的 API。
领域建模工具应该支持源代码控制,以及跨模型及其衍生工件的语义版本管理 ——有助于维护已发布 API 的通用性和可追溯性的功能。
其他强烈支持模型驱动开发的平台功能包括设计时模型验证、状态生命周期文档(例如状态生命周期图)、依赖关系的映射和管理、通知管理以及模型可发现性、共享和重用。
域数据建模工具(具有广泛不同的功能集)包括:
行业领域数据建模平台
视觉范式
Mendix 低代码平台
Sparx EA + OpenAPI 插件
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/
Postman API 平台、Thunder Client — VS Code 的扩展、karatelabs/karate、Pact (pact.io)、Katalon 质量管理、Insomnia API 开发平台、SOAPUI、REST-Assured + Tcases
总结
API规范文档是个纯技术型文档。它通常在开发工作中生成,而技术能力较低的用户很难理解。
如果没有指导性的 API 设计实践文档,大部分企业很难控制业务 API 的质量。
为了最大化利益相关者协作的机会并提供尽可能紧密的反馈循环,最重要的是在将任何内容提交给代码之前捕获、共享和验证 REST 模型。明确定义和支持的 API 设计实践可以确保 API 及其底层数据模型都是可见的、可重用的与可管理化。