documenting-contracts

记录契约

必需背景： technical-writing 技能（硬性规则、真实性规则、风格）。

概述

契约文档面向一位看不到代码、即将依赖代码的陌生读者。核心原则：**穷尽记录线上的内容，并让每项细节各归其位；调用方的语言和领域术语才是线格式，而不是实现所用的类型。**契约属于参考类内容，因此核心参考规则适用：涵盖每个端点、每个字段和每种错误。

何时调用，何时不调用

记录机器会调用或解析的内容时调用：REST 和 RPC 端点、消息队列和主题、Webhook、CLI 命令、文件格式。旧项目迁移活动（documenting-legacy-codebases）中的 api-reference.md 就是此技能的文档。不要用于内部代码接口，代码本身会记录这些接口；也不要用于配置参考，它们应遵循核心参考规则，写入 config-reference.md。判断契约设计是否合理不在此范围内：此技能记录的是现有契约。

唯一归处与生成式规范

如果存在 OpenAPI 或 AsyncAPI 规范，或代码会生成此类规范，则该规范负责字段表。Markdown 只记录规范无法表达的内容（语义、副作用、顺序、缺省与 null 的区别），并链接到规范；绝不要在生成的字段表旁边手动维护另一份字段表，否则两处内容会逐渐不一致。下方目录适用于不存在机器可读规范的情况；编写此类规范不属于本文档的职责。

四个细节层级

每个层级都有自己的归处；作者应将出现在错误层级的细节移至负责该细节的层级：

层级	调用方的问题	归处
索引	这里有哪些内容	端点、消息和命令表
语义	调用后会发生什么	按端点、消息和命令编写的说明：副作用、已发布的事件、幂等性、重新投递、退出行为、特殊情况
结构	哪些内容会在线上传输	DTO 目录：每个 DTO 一张字段表
示例	内容看起来是什么样	每个 DTO 最多一个说明性示例

应重点查找各层级间的重复内容：端点章节重复列出其 DTO 的字段；示例暗中加入表中没有的字段。

DTO 目录

每个 DTO 只定义一次，并在各处引用：

• 使用线类型，而非编程语言类型。 string (date, ISO 8601)、number (64-bit integer)、string (decimal)：列中应说明在线上传输的内容，且足够完整，不需要读者用实现类型来推断。超出使用方原生数字类型的范围或精度的 64 位整数属于线格式信息；产生该整数的类型名称则不属于。
• 每个 DTO 单独一行 Source，注明所属类或架构文件。参考类内容允许以此作为证据锚点，就像配置参考会提供绑定证据一样。
• Required 有三种状态：yes、no，或 if <condition>，并注明条件。
• 在适用处说明省略与 null 的区别；对于用于替换式写入的 DTO，则始终要说明，因为被省略的字段不会出现在结果中。如果服务端会在字段省略时采用默认值，则应在 Default 列中注明该值。
• 枚举使用独立表格，并说明每个值的含义；嵌套对象应链接到其自身的目录条目，绝不在行内再次复制。
• 使用领域术语描述约束：例如“过去的日期”“1..100 个字符”“必须引用现有预算策略”；这些约束应依据代码实际执行的验证规则。

模板

# API reference: <service>

## Conventions
[Once, never per endpoint: base path, auth, content type, the error
envelope, global (de)serialization behavior, idempotency defaults.]

## Endpoints
| Method | Path | Purpose | Request | Response | Errors |
|---|---|---|---|---|---|
| POST | `/thing` | Create a thing | [ThingRequest](#thingrequest) | 200 [Thing](#thing) | 422, 404 |

### POST /thing
[Semantics only: side effects, events published, idempotency, quirks.
No field lists; the index and catalog are not repeated.]

## Messages
| Direction | Destination | Payload | Reply | On error |
|---|---|---|---|---|
| in | `thing.create` | [ThingRequest](#thingrequest) | `thing.created` | `thing.create.error` |

### thing.create
[Semantics only: redelivery, ordering, events published, quirks;
what differs from the sibling transport is called out here.]

## Commands
| Command | Purpose | Arguments | Output |
|---|---|---|---|

### <command>
[Semantics only: side effects, idempotency, exit behavior, quirks.]

## DTOs
### ThingRequest
Source: `api/ThingRequest`

| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|

[Omitted versus null, where it matters. At most one illustrative example.]

### Thing
[Response shapes are catalog entries like any other.]

## Errors
| Status | When | Body |
|---|---|---|

规则

• 以序列化器为准，而非类。 线上的内容取决于配置的序列化器所输出和接受的内容：全局修剪器、省略 null 值的映射器或自定义日期格式，都会在不改动任何 DTO 的情况下改变契约。在编写任何字段行之前，先查看序列化配置。
• 不对称之处就是语义。 在一种传输方式上发布事件、而在另一种方式上不发布的变更，或跳过了同类端点所执行步骤的端点，都要从语义层面进行说明。
• 示例仅供说明，绝非规范。 每个 DTO 最多提供一个示例，并明确标注；示例不得包含表格中没有的字段。表格才是契约。
• 错误只编目一次，以信封格式加状态码表的形式列出；端点只需注明适用的条目。命令失败也按同样方式编目，依据退出代码分类。
• 完整性可核验。 端点数量和 DTO 数量与其他核心事实规则一样，都是分母；旧版活动应在其覆盖清单中记录这些数量、对应的命令及日期。