API契约：与架构关联的API规范

几周前，我和一个团队一起审查系统架构，他们有一张漂亮的C4图。容器定义清晰，关系标注明确。一切看起来很棒——直到有人问"订单服务和支付网关之间的API到底长什么样？"

沉默。图表上写着"REST/JSON"。OpenAPI规范在另一个代码仓库中。实际的端点列表在一个自从上一个实习生离开后就没更新过的Notion页面里。一个API面三个信息源，而且没有一个一致。

这种情况极其常见。API规范是代码库中最精确、最机器可读的产物之一。然而在架构文档中，它们是不可见的。你只能看到一个方框、一个箭头和一个协议标签。实际的契约——端点、模式、字段——完全在别处。

我们构建了API契约来解决这个问题。你的API规范现在存在于你的架构内部，与实现和使用它们的元素相关联。

四种协议，一个归属

现代系统很少只使用一种协议。你的公共API是REST，内部服务通过gRPC通信，前端通过GraphQL获取数据。每种都有自己的规范格式、工具链和文档生态系统。

Archyl的API契约支持全部四种：

OpenAPI / Swagger — 导入你的OpenAPI 3.x或Swagger 2.0规范，获得由Scalar驱动的交互式参考查看器。端点按分组展示，参数有文档说明，模式可展开。这与专用API文档工具提供的体验相同，直接嵌入到你的架构工作区中。

gRPC / Protocol Buffers — 粘贴或同步你的.proto定义。查看器渲染服务、方法、消息类型和枚举，带有语法高亮和正确缩进。不再需要在proto文件中寻找服务暴露了什么。

GraphQL — 导入你的schema并探索类型、查询、变更和订阅。如果你配置了服务器端点，还能获得完整的GraphiQL playground——编写查询、对实际API执行、交互式探索schema，所有这些都无需离开Archyl。

AsyncAPI — 使用AsyncAPI规范定义你的事件驱动API。查看器渲染通道、操作、消息模式和服务器绑定，带有完整的语法高亮。无论你使用Kafka、RabbitMQ、NATS还是WebSocket，AsyncAPI契约都能记录你的服务生产和消费的事件。

从Git导入或直接粘贴

API规范会变化。端点被添加、字段被弃用、新版本发布。如果你的文档需要手动复制粘贴才能保持更新，那它就不会保持更新。

这就是为什么API契约支持两种来源模式：

Git同步将你的契约连接到代码仓库中的规范文件。指向你的openapi.yaml、service.proto、schema.graphql或asyncapi.yaml，Archyl直接获取内容。当上游规范变更时，点击同步即可更新契约。这适用于Archyl支持的所有Git提供商——GitHub、GitLab、Bitbucket、Azure DevOps和自托管实例。

手动模式适用于不在git中保存规范的团队，或快速原型设计。直接粘贴你的规范内容并就地编辑。适合在服务存在之前起草契约，或导入你无法控制的第三方API规范。

两种模式都支持版本控制，你可以跟踪正在记录的契约版本。

与架构关联

这是API契约超越普通规范查看器的地方。

每个契约都可以关联到一个或多个C4元素——系统、容器、组件或代码元素。OpenAPI规范可以关联到提供服务的API网关容器。gRPC proto可以关联到实现它的微服务组件。GraphQL schema可以关联到暴露它的BFF（Backend for Frontend）。

这些链接是双向的。从契约中可以看到它关联了哪些架构元素。从图表上元素的详情面板中可以看到哪些契约描述了它的API面。在画布上右键点击容器时，可以直接从上下文菜单中关联和取消关联契约。

这弥合了我在开头描述的差距。当有人问"这两个服务之间的API是什么样的？"时，答案只需一次点击。不在另一个工具中，不在另一个仓库中——就在图表上。

事件通道

事件驱动架构出了名地难以文档化。哪个服务发布到哪个主题？消息模式是什么？谁在消费？

Archyl的事件通道为你的异步通信带来可见性。每个AsyncAPI契约自动展示它定义的通道——主题、队列、流——并将它们映射到生产和消费事件的C4元素。

在图表上，事件通道以不同的连接类型出现，使得哪些关系是同步API调用、哪些是异步事件流一目了然。这对理解系统行为至关重要：两个服务之间的REST调用与发布到消息代理的事件具有完全不同的可靠性和耦合特性。

你也可以独立于AsyncAPI契约创建事件通道，这对记录没有正式规范的遗留消息系统或专有协议很有用。

交互式查看器

我们不希望契约只是原始文本。每种协议都有专门构建的查看器：

OpenAPI查看器渲染完全交互式的API参考。端点按标签组织，带有可展开的请求/响应模式、参数文档和认证详情。如果你定义了服务器URL，查看器会显示它们，以便开发者知道向哪里发送请求。这是真正的API文档体验，而不是语法高亮的YAML转储。

Protocol Buffer查看器以正确的语法着色渲染proto定义，使服务、RPC和消息结构易于浏览。

GraphQL查看器高亮显示类型、字段和指令。当你配置了服务器端点时，第二个标签页会打开完整的GraphiQL playground。你可以编写并对实际API执行查询，通过自省探索schema，测试变更——所有这些都嵌入在Archyl中。如果你的GraphQL API有多个环境（预发布、生产），可以定义多个服务器条目并在它们之间切换。

AsyncAPI查看器渲染你的事件驱动API定义，包括通道列表、消息模式和服务器/代理配置。每个通道显示其操作（发布/订阅）、负载模式和绑定——为开发者提供事件驱动通信面的清晰画面。

如何开始

进入任何项目，从侧边栏打开API契约部分。点击"添加契约"并选择你的协议类型和来源模式。

对于Git来源的契约，连接一个仓库（或复用已连接到项目的仓库），指定文件路径和分支，Archyl将获取规范。对于手动契约，直接粘贴内容。

创建后，前往图表并将契约关联到相关的C4元素。从那时起，任何探索架构的人都可以从图表本身深入到实际的API面。

为什么这很重要

架构图擅长展示结构——存在什么以及事物如何连接。但它们在接口方面一直很薄弱。标注"REST/HTTPS"的关系箭头几乎不能告诉你两个服务之间实际流动的是什么。发布到Kafka主题的事件更加不透明——除非你在那里就有AsyncAPI规范和通道映射。

API契约填补了这个空白。它们为箭头增加了精确性。当新团队成员查看你的架构，看到移动应用和API网关之间的连接时，他们可以立即打开OpenAPI规范，准确了解有哪些端点可用、交换了什么数据结构、需要什么认证。

这是真正有价值的架构文档。不是因为有人强制要求，而是因为它回答了每天都会出现的真实问题。

已经在使用Archyl管理架构？在你的项目中探索API契约功能。刚接触这个平台？了解C4模型以及AI驱动的发现如何自动生成你的架构图。