文档驱动开发（DDD）：从 RFC 规范到自动化 API 契约校验

AI新角度

1人浏览 · 2026-09-07 15:33:43

AI新角度 · 2026-09-07 15:33:43 发布

文档驱动开发（DDD）：从 RFC 规范到自动化 API 契约校验

封面信息图

在团队协作规模扩大后，最容易出现的研发混乱往往是“代码先行、文档滞后”。

前端同学等着联调，后端接口改了字段却只在聊天软件里随口提了一句；架构师设计了跨服务的通信协议，开发实现时却由于理解偏差少传了幂等键——最后问题全部堆积在提测联调阶段，引发大量的扯皮和返工。

解决这一问题的根本方案是推行文档驱动开发（Documentation-Driven Development）：在动手写第一行业务实现代码之前，必须先产出标准化的设计规范文档（RFC）与机器可验证的 OpenAPI/Protobuf 契约文件，并将其纳入 CI 门禁自动化校验。

RFC（Request for Comments）流程规范

任何涉及新功能模块、公共组件重构或跨团队接口变更的需求，作者必须先提交一份轻量级的 RFC Markdown 文档到仓库的 docs/rfcs/ 目录下，发起 PR 进行评审。

一份高质量的 RFC 必须包含五个核心章节：

背景与业务矛盾（Problem Statement）：为什么要启动这项变更？
非目标声明（Non-Goals）：明确本次绝对不做哪些事情，防止需求无节制蔓延。
接口契约设计（API Contract & Data Schema）：精确到每个字段的类型、必填性、枚举值及边界示例。
架构权衡与替代方案（Alternatives Considered）：为什么选择了方案 A 而不是方案 B？各自的优缺点是什么？
迁移与兼容性计划（Migration & Rollback）：旧数据如何平滑迁移？上线失败如何回滚？

<!-- RFC 模板关键段落示例 -->
# RFC-024: 支付网关统一多渠道分账接口设计

## 1. 契约定义 (OpenAPI 3.1 摘要)
paths:
  /api/v1/settlements:
    post:
      summary: 创建分账单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSettlementRequest'

将 API 契约变成机器可验证的代码门禁

单靠人工阅读 RFC 很容易出现“文档写了一套，代码实现是另一套”的脱节。我们通过 CI 流水线建立了自动化契约校验与防破坏性变更检查。

1. 静态 OpenAPI Lint 检查

使用 spectral 工具在 CI 阶段严格扫描 API 定义文件的规范性：

# 运行契约规约检查
spectral lint api/openapi.yaml --ruleset .spectral.yaml

规约规则包括：所有接口必须定义 4xx/5xx 错误响应结构、字段命名必须统一为 camelCase 或 snake_case、所有路径必须包含标签和描述。

2. 自动化破坏性变更（Breaking Change）拦截

使用 oasdiff 工具对比当前分支与主干分支的 API 契约 Diff。如果发现删除了已有字段、修改了已有字段的类型、或者在请求入参中新增了必填字段，流水线将自动阻断合并：

# GitHub Actions 契约对比
- name: Check API Breaking Changes
  run: |
    # 从主干分支下载基准契约
    git show origin/main:api/openapi.yaml > base.yaml
    # 执行破坏性变更比对
    oasdiff breaking base.yaml api/openapi.yaml --fail-on ERR

[BREAKING ERROR]: schema removed property 'merchant_id' in response '/api/v1/settlements' (200)
[BREAKING ERROR]: changed optional property 'notify_url' to required in request

双向代码生成：契约即单一真实数据源

在文档驱动模式下，API 契约文件是系统的单一真实数据源（Single Source of Truth）：

服务端：通过 oapi-codegen（Go）或 fastapi-codegen（Python）从 YAML 自动生成路由骨架、入参结构体校验器和中间件接口。开发者只需实现对应的接口方法，无需手写重复的参数校验。
客户端：前端和外部调用方通过 openapi-typescript 自动生成全套 TypeScript 类型定义与 SDK。当后端契约更新并合并后，前端一键拉取即可在编译期发现类型不兼容。