API 契约

API 契约让您将 API 规范附加到架构元素上，使文档和设计保持同步。Archyl 支持 OpenAPI（REST）、gRPC、GraphQL 和 AsyncAPI 契约，并可选择与 Git 同步。

支持的契约类型

类型	格式	使用场景
HTTP (REST)	OpenAPI 3.x (YAML/JSON)	REST API、Webhook
gRPC	Protocol Buffers (.proto)	服务间 RPC
GraphQL	GraphQL SDL (.graphql)	查询 API
Async	AsyncAPI (YAML/JSON)	事件驱动 API、消息队列

创建契约

手动输入

导航到您的项目
打开 API 契约 选项卡
点击 新建契约
填写契约详情：
- 名称 — 描述性名称（如"用户服务 API"）
- 类型 — HTTP、gRPC、GraphQL 或 Async
- 版本 — 语义版本（如 1.0.0）
- 端点 — API 的基础 URL
- 描述 — API 的功能
在编辑器中粘贴或编写规范内容
点击创建

Git 同步

您可以从 Git 仓库同步契约，而非手动维护：

点击 新建契约 并选择 Git 作为源类型
选择已连接的仓库
指定规范文件的路径（如 api/openapi.yaml）
设置要跟踪的分支（默认为仓库的默认分支）
Archyl 拉取规范内容并保持同步

您还可以使用 glob 模式匹配多个文件。例如，api/**/*.yaml 将匹配 api/ 目录下的所有 YAML 文件。

同步行为

创建契约时从仓库获取规范
使用同步按钮手动拉取最新版本
契约卡片上显示最后同步时间

将契约关联到架构

API 契约与 C4 元素关联后变得更有意义。一个契约可以关联到系统、容器、组件或代码元素。

添加关联

打开契约详情页
点击 关联到元素
选择 C4 层级（系统、容器、组件或代码）
选择目标元素
关联将同时出现在契约和元素详情面板中

查看关联的契约

在图表上，右键点击任意元素可打开其详情面板。关联的 API 契约显示在契约部分，包含：

契约名称和版本
协议类型标签（HTTP、gRPC、GraphQL、Async）
完整规范的链接

服务端入口

每个契约可以定义多个服务端入口——用于记录不同的环境或区域。

字段	描述
URL	服务端基础 URL（如 `https://api.example.com/v1`）
描述	环境或用途（如"生产环境"、"预发布环境"）

规范查看器

Archyl 通过交互式查看器渲染您的 API 规范：

OpenAPI — 按标签分组的端点，包含请求/响应模式、参数和示例
gRPC — 服务定义、RPC 方法和消息类型
GraphQL — 类型、查询、变更和订阅
AsyncAPI — 通道、消息和模式

查看器为只读模式，始终反映契约的当前内容。

事件通道

事件通道记录架构中的异步消息传递——Kafka 主题、SQS 队列、RabbitMQ 交换机等。

创建事件通道

导航到您的项目
打开 事件通道 选项卡
点击 新建通道
配置通道：

字段	描述
名称	通道名称（如"订单创建事件"）
方向	`produce` 或 `consume`
代理类型	Kafka、NATS、SQS、RabbitMQ、Redis、Pulsar 或自定义
主题名称	实际的主题或队列名称
模式格式	JSON Schema、Avro、Protobuf 或 Text
值模式	事件负载模式定义

关联到架构

事件通道遵循与 API 契约相同的关联模型。将通道关联到生产或消费其事件的系统、容器或组件。这使得消息流在架构图上直接可见。

最佳实践

保持规范更新

对存放在代码库中的规范使用 Git 同步
按语义版本管理契约版本
API 变更时更新契约

关联一切

每个提供 API 的容器都应至少有一个关联的契约
将事件通道关联到生产者和消费者
使用关联使图表自文档化

按服务组织

每个服务或限界上下文一个契约
使用与架构命名匹配的描述性名称
在契约版本字段中包含 API 版本

记录服务端

为每个环境添加服务端入口
包含内部和外部端点
随着基础设施变更保持 URL 更新

后续步骤

事件通道 — 记录异步消息传递
架构变更请求 — 提出架构变更建议
发布管理 — 跨系统跟踪部署

API 契约 - Archyl Docs