API 契约

API 契约让您将 API 规范附加到架构元素上，使文档和设计保持同步。Archyl 支持 OpenAPI（REST）、gRPC、GraphQL、AsyncAPI 和 MCP 契约，并可选择与 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、消息队列
MCP	MCP `tools/list` (JSON)	暴露给 AI 智能体的工具

创建契约

手动输入

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

Git 同步

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

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

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

同步行为

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

MCP 服务器

MCP（Model Context Protocol）服务器向 AI 智能体暴露工具——每个工具都有名称、描述,以及用于其输入的 JSON Schema。这个工具面同样是一份契约:它定义了智能体被允许做什么。Archyl 将其记录为 MCP 契约类型。

与其他类型不同,MCP 服务器的工具通常不是仓库里的某个文件——权威的列表只在运行时通过 tools/list 调用存在。因此 MCP 契约支持两种来源。

粘贴工具列表

点击新建契约并选择 MCP
将来源保持为手动
粘贴服务器的 tools/list JSON——形如 { "tools": [ ... ] } 的对象
点击创建

Archyl 会校验该文档并渲染每个工具。

从实时端点发现

让 Archyl 直接从运行中的服务器拉取工具:

点击新建契约,选择 MCP,并选择 Live endpoint 作为来源
输入服务器 URL 并选择传输方式（HTTP 或 SSE）
如果服务器需要认证,选择令牌的放置位置——请求头（如 X-API-Key）或查询参数——并输入令牌
点击发现工具——Archyl 会连接、执行握手,并列出每个工具及其参数
检查发现的工具,然后点击创建

之后如需刷新工具,编辑该契约并再次运行发现工具。

发现在你的浏览器中执行,而非 Archyl 的服务器上。 你的令牌永远不会离开浏览器——Archyl 存储发现到的工具和连接信息（URL、传输方式、请求头/参数名称）,但绝不存储令牌本身。由于调用源自你的机器,它也能触及 localhost 或你私有网络中的服务器。

唯一的要求:MCP 服务器必须允许本站点的来源（CORS）,你的浏览器才能读取响应。对于你掌控的服务器,这只是一处小的配置改动;否则,使用上面的粘贴选项。

MCP 工具查看器

每个工具都会显示其名称、描述和输入参数（从其 JSON Schema 派生）,并可按工具查看原始 schema。与其他契约类型一样,查看器为只读,并反映已存储的工具列表。

将契约关联到架构

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

添加关联

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

查看关联的契约

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

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

服务端入口

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

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

规范查看器

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

OpenAPI — 按标签分组的端点，包含请求/响应模式、参数和示例
gRPC — 服务定义、RPC 方法和消息类型
GraphQL — 类型、查询、变更和订阅
AsyncAPI — 通道、消息和模式
MCP — 工具,每个都带有其描述和输入参数（来自其 JSON Schema）

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

事件通道

事件通道记录架构中的异步消息传递——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