OpenSpec规格驱动开发实战：从契约同步到代码生成

1. 为什么我们需要重新审视“规格驱动开发”

第一次接触 OpenSpec 这个概念，是在一个前后端联调频繁扯皮的深夜。前端说接口字段对不上，后端说文档里写得清清楚楚，翻出那份三个月前的 Word 文档，发现最后一次更新还停留在需求评审那天。这种场景做开发的人都不陌生——规格文档和代码实现之间的鸿沟，几乎是所有协作型项目的通病。

OpenSpec 要解决的就是这个问题。它不是某个具体的库或框架，而是一套以规格文件为核心、让规格与代码同步演进的开发方法论与工具链。核心思路很直接：把接口定义、数据结构、行为约束这些“契约”从散落的文档里抽出来，变成机器可读、可校验、可生成代码的结构化文件，让规格本身成为开发流程的一等公民。

说白了，OpenSpec 想做的事情是：让规格不再是写完就扔的废纸，而是能真正驱动开发、校验实现、自动生成产物的活文档。它适合谁？后端工程师用它定义 API 契约，前端工程师用它生成类型定义和 mock 数据，测试工程师用它生成用例骨架，技术负责人用它做架构约束的自动化检查。只要你的项目涉及多人协作、接口对接、或者需要长期维护，OpenSpec 这套思路就值得认真看一看。

我在这篇文章里会从设计思路、核心机制、实操落地、踩坑排查几个维度，把 OpenSpec 这套东西拆开讲透。不是照本宣科翻译文档，而是把我自己趟过的路、踩过的坑、总结出来的经验都倒出来，让你能直接抄作业。

2. OpenSpec 的核心设计思路拆解

2.1 规格即代码：把契约从文档搬进仓库

传统开发流程里，规格文档和代码是两条平行线。产品经理写 PRD，架构师画接口文档，开发照着文档写代码，写完就各走各的。文档放在 Confluence 或者飞书里，代码放在 Git 仓库里，两者之间没有任何强制关联。时间一长，文档过期了没人知道，代码改了什么也没人同步回文档。

OpenSpec 的第一个核心设计就是把规格文件放进代码仓库，和代码一起版本管理。规格文件用结构化的格式（通常是 YAML 或 JSON）描述接口的输入输出、字段类型、约束条件、错误码等信息。这样做的好处很实在：

• 版本同步：规格文件和代码在同一个 commit 里，改代码必须改规格，review 的时候一眼就能看出契约有没有变。
• 可追溯：通过 git log 就能查到某个字段是什么时候加的、为什么加的，比翻聊天记录靠谱得多。
• 可校验：规格文件是机器可读的，可以写脚本自动检查代码实现是否符合规格定义。

我自己的做法是在项目根目录建一个specs/目录，按模块划分子目录，每个接口一个 YAML 文件。比如specs/user/create_user.yaml描述创建用户的接口契约。这个文件里不仅写字段类型，还写清楚哪些字段必填、哪些可选、默认值是什么、错误码有哪些。写的时候麻烦一点，但后面省下来的沟通成本是十倍百倍的。

2.2 单向数据流：规格是唯一真相来源

OpenSpec 的第二个设计原则是规格作为唯一真相来源（Single Source of Truth）。什么意思？就是当规格和代码冲突时，以规格为准；当规格和文档冲突时，以规格为准；当规格和口头约定冲突时，还是以规格为准。

这个原则听起来简单，落地的时候需要团队达成共识。我见过不少团队引入了规格文件，但开发还是习惯性地先改代码再补规格，结果规格永远滞后于代码，慢慢就没人看了。正确的做法应该是反过来：先改规格，再改代码，CI 流水线里加一步校验，规格和代码不一致就直接构建失败。

具体怎么校验？可以在 CI 里跑一个脚本，读取规格文件，然后检查代码里的路由定义、参数校验逻辑、返回结构是否和规格一致。不一致就报错，强制开发者先更新规格。这个机制一开始会让人觉得麻烦，但坚持两周之后，团队就会习惯这种“规格先行”的节奏，后面接口联调的时候几乎不会再出现字段对不上的情况。

2.3 代码生成：从规格自动产出多端产物

OpenSpec 最实用的能力之一是代码生成。既然规格文件已经用结构化格式描述了接口契约，那就可以基于它自动生成各种产物：

• 后端：生成路由骨架、参数校验中间件、Swagger/OpenAPI 文档
• 前端：生成 TypeScript 类型定义、API 请求函数、Mock 数据
• 测试：生成接口测试用例骨架、边界值测试数据
• 文档：生成 Markdown 格式的接口文档，自动发布到文档站点

这样做的好处是消除手工同步的成本。以前改一个字段，后端改代码、前端改类型、测试改用例、文档改描述，四个地方都要动，漏一个就出问题。现在只改规格文件，其他产物全部自动生成，改一处生效四处。

我实测下来，一个中等规模的项目（大概 50 个接口），引入代码生成之后，接口联调阶段的时间从平均 3 天缩短到半天。前端不用等后端写完再动手，直接拿生成的类型和 mock 数据就能开发；后端也不用反复给前端解释字段含义，规格文件里写得明明白白。

2.4 渐进式采用：不要求一次性重构

很多团队听到“规格驱动开发”就觉得要推倒重来，其实 OpenSpec 的设计是支持渐进式采用的。你可以先从新接口开始用规格文件，老接口慢慢补；也可以先只做代码生成，不做 CI 校验；还可以先在一个小模块试点，跑通了再推广到全项目。

这种渐进式的设计很务实。我自己的经验是，不要一上来就搞全量迁移，那样阻力太大，很容易半途而废。正确的做法是选一个正在开发的新模块，用 OpenSpec 的方式写规格、生成代码、跑通流程，让团队看到实际效果，然后再逐步扩大范围。等大家都尝到甜头了，再推动老接口的规格补全，这时候阻力就小多了。

3. 核心细节解析与实操要点

3.1 规格文件的结构设计

OpenSpec 的规格文件通常用 YAML 编写，结构上分为几个核心部分。我以一个用户注册接口为例，展示一个完整的规格文件应该包含哪些内容：

# specs/user/register.yaml meta: name: user.register version: 1.0.0 description: 用户注册接口 author: backend-team updated_at: 2024-01-15 request: method: POST path: /api/v1/user/register content_type: application/json headers: - name: X-Request-Id type: string required: true description: 请求追踪ID body: - name: username type: string required: true min_length: 3 max_length: 32 pattern: "^[a-zA-Z0-9_]+$" description: 用户名，仅允许字母数字下划线 - name: password type: string required: true min_length: 8 max_length: 64 description: 密码，至少8位 - name: email type: string required: false format: email description: 邮箱，可选 - name: invite_code type: string required: false description: 邀请码 response: success: code: 200 body: - name: user_id type: integer description: 用户ID - name: username type: string description: 用户名 - name: created_at type: string format: datetime description: 创建时间 errors: - code: 40001 http_status: 400 message: 用户名已存在 trigger: username 重复 - code: 40002 http_status: 400 message: 密码强度不足 trigger: password 不符合规则 - code: 40003 http_status: 400 message: 邀请码无效 trigger: invite_code 不存在或已过期

这个结构看起来字段不少，但每个字段都有明确用途。meta部分用于版本管理和追溯，request部分定义输入契约，response部分定义输出契约和错误码。写的时候确实比随手写个接口文档麻烦，但这份规格文件后面能生成代码、能校验实现、能生成文档，一次投入多次收益。

注意：规格文件里的字段命名要和代码里的命名保持一致，不要出现规格里叫user_id、代码里叫userId的情况。建议在项目初期就定好命名规范，后面所有规格文件都遵循同一套规则。

3.2 字段类型系统的设计考量

OpenSpec 的字段类型系统需要覆盖常见的业务场景，同时保持足够的表达力。我在实际使用中总结了几类必须支持的类型和约束：

设计类型系统的时候有一个关键取舍：要不要支持嵌套对象。支持嵌套会让规格文件更灵活，但也会增加代码生成的复杂度。我的建议是适度支持，允许一层嵌套，但不要搞太深。大部分接口用扁平结构就能表达清楚，嵌套太深反而增加理解和维护成本。

另一个取舍是枚举值怎么表达。可以用enum关键字列出所有可能值，也可以用pattern做正则匹配。我倾向于用enum，因为枚举值可以生成 TypeScript 的联合类型，前端用起来更安全。比如状态字段status的枚举值是["active", "inactive", "banned"]，生成的 TS 类型就是"active" | "inactive" | "banned"，传错值编译期就能发现。

3.3 代码生成的模板设计

代码生成的核心是模板。OpenSpec 工具链通常会提供一套默认模板，但实际项目里往往需要定制。我以生成 TypeScript 类型定义为例，展示一个模板的设计思路：

// templates/typescript_type.tpl {{#each interfaces}} export interface {{pascalCase name}}Request { {{#each request.body}} {{#if required}}{{name}}: {{tsType type}}{{else}}{{name}}?: {{tsType type}}{{/if}}; {{/each}} } export interface {{pascalCase name}}Response { {{#each response.success.body}} {{name}}: {{tsType type}}; {{/each}} } {{/each}}

这个模板用 Handlebars 语法编写，遍历规格文件里的接口定义，生成对应的 TypeScript 接口。tsType是一个辅助函数，把 OpenSpec 的类型映射到 TypeScript 类型：string映射到string，integer映射到number，datetime映射到string，array映射到Array<T>。

模板设计有几个经验点：

• 命名转换要统一：规格文件里用 snake_case，生成的 TS 类型用 PascalCase，字段用 camelCase。这个转换规则要在模板里统一处理，不要每个模板各写一套。
• 注释要保留：规格文件里的description字段应该生成到代码注释里，这样前端在 IDE 里 hover 就能看到字段说明，不用去翻文档。
• 可选字段要标记：required: false的字段在 TS 里要加?，这样前端调用的时候编译器会提醒可能为 undefined。

提示：模板不要写得太复杂，能覆盖 80% 的常见场景就行。剩下 20% 的特殊情况，允许开发者手工调整生成的代码，但要在文件头加注释说明“此文件由 OpenSpec 生成，手工修改部分可能在下次生成时丢失”。

3.4 校验机制的实现方式

OpenSpec 的校验机制分两个层面：规格文件自身的校验和代码实现与规格的一致性校验。

规格文件自身的校验相对简单，就是检查 YAML 格式是否正确、必填字段是否缺失、类型定义是否合法。这个可以用 JSON Schema 来做，定义一个 meta-schema，然后用它校验所有规格文件。CI 里跑一遍，有问题的规格文件直接报错。

代码实现与规格的一致性校验要复杂一些，需要根据具体的技术栈来实现。以 Node.js 后端为例，可以在启动时读取规格文件，然后检查路由注册、参数校验中间件、返回结构是否和规格一致。我写过一个简单的校验脚本，核心逻辑是这样的：

// scripts/validate_spec.js const fs = require('fs'); const yaml = require('js-yaml'); const path = require('path'); function loadSpecs(specDir) { const specs = []; const files = fs.readdirSync(specDir, { recursive: true }); for (const file of files) { if (file.endsWith('.yaml')) { const content = fs.readFileSync(path.join(specDir, file), 'utf8'); specs.push(yaml.load(content)); } } return specs; } function validateRoutes(app, specs) { const routes = app._router.stack .filter(layer => layer.route) .map(layer => ({ method: Object.keys(layer.route.methods)[0].toUpperCase(), path: layer.route.path })); for (const spec of specs) { const expected = { method: spec.request.method, path: spec.request.path }; const found = routes.find(r => r.method === expected.method && r.path === expected.path); if (!found) { console.error(`规格中定义的接口未实现: ${expected.method} ${expected.path}`); process.exit(1); } } console.log('所有规格接口均已实现'); }

这个脚本在应用启动时跑一遍，确保规格里定义的接口都有对应的路由实现。反过来也可以检查代码里有没有规格未定义的“野生接口”，有的话就报错，强制开发者先补规格。

4. 完整实操流程与核心环节实现

4.1 环境准备与工具链搭建

开始用 OpenSpec 之前，需要先把工具链搭起来。核心工具包括：

• 规格文件解析器：读取 YAML 规格文件，输出结构化的规格对象
• 代码生成器：基于模板和规格对象，生成各端代码
• 校验器：检查规格文件合法性和代码一致性
• 文档生成器：把规格文件转成可读的接口文档

这些工具可以自己写，也可以用现成的开源方案。我自己的做法是先用现成方案跑通流程，再根据项目需求定制。一开始不要追求大而全，能生成类型定义和做基本校验就够了，后面再逐步扩展。

安装步骤大致如下：

# 初始化项目 mkdir openspec-demo && cd openspec-demo npm init -y # 安装核心依赖 npm install js-yaml handlebars commander # 创建目录结构 mkdir -p specs/user specs/order templates scripts generated

目录结构的设计原则是规格、模板、生成产物分开存放。specs/放规格文件，templates/放代码生成模板，generated/放生成的代码。generated/目录可以加到.gitignore里，因为它是自动生成的，不需要版本管理。

4.2 编写第一个规格文件

环境搭好之后，从最简单的接口开始写规格。我建议选一个字段少、逻辑简单、但实际会用到的接口，比如健康检查或者获取当前用户信息。这样能快速跑通流程，建立信心。

以获取用户信息接口为例：

meta: name: user.get_profile version: 1.0.0 description: 获取当前登录用户信息 request: method: GET path: /api/v1/user/profile headers: - name: Authorization type: string required: true description: 认证令牌 response: success: code: 200 body: - name: user_id type: integer description: 用户ID - name: username type: string description: 用户名 - name: email type: string format: email description: 邮箱 - name: avatar_url type: string format: url description: 头像地址 - name: created_at type: string format: datetime description: 注册时间 errors: - code: 40100 http_status: 401 message: 未登录或令牌无效

写规格文件的时候有几个细节要注意：

• 路径要写完整：包括版本前缀/api/v1，不要只写/user/profile，否则生成的路由和实际路由对不上。
• 认证信息要标注：Authorization头是必填的，要在规格里写清楚，这样生成的文档和测试用例都会带上认证逻辑。
• 错误码要成体系：不要随便编错误码，建议按模块划分号段。比如用户模块用 401xx，订单模块用 402xx，这样排查问题的时候一看错误码就知道是哪个模块。

4.3 实现代码生成器

规格文件写好后，接下来实现代码生成器。核心逻辑是：读取规格文件 → 解析成对象 → 套用模板 → 输出代码文件。

// scripts/generate.js const fs = require('fs'); const path = require('path'); const yaml = require('js-yaml'); const Handlebars = require('handlebars'); // 注册辅助函数 Handlebars.registerHelper('pascalCase', (str) => { return str.split(/[._-]/).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(''); }); Handlebars.registerHelper('camelCase', (str) => { const pascal = str.split(/[._-]/).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(''); return pascal.charAt(0).toLowerCase() + pascal.slice(1); }); Handlebars.registerHelper('tsType', (type) => { const map = { string: 'string', integer: 'number', number: 'number', boolean: 'boolean', datetime: 'string', array: 'Array<any>', object: 'Record<string, any>' }; return map[type] || 'any'; }); function loadSpecs(specDir) { const specs = []; const files = fs.readdirSync(specDir, { recursive: true }); for (const file of files) { if (file.endsWith('.yaml')) { const content = fs.readFileSync(path.join(specDir, file), 'utf8'); specs.push(yaml.load(content)); } } return specs; } function generate(specs, templatePath, outputPath) { const template = Handlebars.compile(fs.readFileSync(templatePath, 'utf8')); const result = template({ interfaces: specs }); fs.writeFileSync(outputPath, result); console.log(`生成文件: ${outputPath}`); } const specs = loadSpecs('./specs'); generate(specs, './templates/typescript_type.tpl', './generated/api_types.ts');

这个生成器跑一遍，就能把所有规格文件里的接口定义转成 TypeScript 类型。前端项目直接引用generated/api_types.ts，就能获得完整的类型提示。

4.4 集成到 CI 流水线

代码生成和校验要集成到 CI 流水线里，才能发挥最大价值。我的做法是在 CI 里加三个步骤：

1. 规格校验：检查所有规格文件格式是否合法
2. 代码生成：重新生成所有产物，检查是否有未提交的变更
3. 一致性校验：检查代码实现是否和规格一致

# .github/workflows/openspec.yml name: OpenSpec Check on: [push, pull_request] jobs: spec-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '18' - run: npm install - name: 校验规格文件 run: node scripts/validate_spec.js - name: 生成代码 run: node scripts/generate.js - name: 检查生成产物是否有变更 run: | if [[ -n $(git status --porcelain generated/) ]]; then echo "生成产物有变更，请本地运行 generate 后提交" exit 1 fi

这个流水线跑起来之后，任何人改了规格文件但忘了重新生成代码，CI 就会失败，提醒他补上。改了代码但没改规格，一致性校验也会失败。这样就能强制保证规格和代码始终同步。

注意：CI 里的代码生成步骤要确保环境一致，Node 版本、依赖版本都要锁定，否则不同机器生成的代码可能有细微差异，导致 CI 误报。

5. 常见问题与排查技巧实录

5.1 规格文件冲突怎么处理

多人协作的时候，规格文件冲突是常见问题。两个人同时改了同一个接口的规格，合并的时候就会冲突。处理这类冲突有几个原则：

• 先沟通再合并：冲突了不要急着解决，先找对方确认谁的改动是最终版本，避免合错了。
• 小步提交：规格文件的改动要小步提交，不要攒一大堆改动一次性提交，那样冲突范围会很大。
• 用版本号标记：规格文件里的version字段要随改动递增，合并的时候以版本号高的为准。

我自己的习惯是，每次改规格文件之前先git pull一下，确保本地是最新的。改完之后立刻提交，不要拖。如果确实冲突了，用git diff仔细看两边的改动，确认哪些字段是新增的、哪些是修改的、哪些是删除的，然后手工合并。

5.2 生成的代码不符合预期怎么办

代码生成的结果和预期不符，通常有几个原因：

排查的时候，先用一个最小的规格文件测试，确认模板本身没问题，再逐步增加字段，定位到具体是哪个字段出了问题。不要一上来就用复杂的规格文件调试，那样很难定位。

5.3 老项目怎么渐进式引入

老项目引入 OpenSpec 最大的阻力是存量接口太多，补规格工作量太大。我的建议是分三步走：

第一步：新接口先行。所有新开发的接口必须写规格文件，走代码生成流程。老接口暂时不动，但要在文档里标注“待补规格”。

第二步：高频接口优先补。把调用量最大、改动最频繁的接口先补上规格。这些接口补规格的收益最高，因为改动频繁意味着沟通成本高，规格化之后能省很多事。

第三步：批量补全。等团队习惯了规格驱动开发的节奏，再安排专门的时间批量补全剩余接口的规格。这时候可以用脚本辅助，从现有的 Swagger 文档或者代码注释里提取信息，自动生成规格文件初稿，人工再校对一遍。

我实测下来，一个 50 个接口的项目，按这个节奏走，大概两个月能完成全量规格化。前期会慢一点，但后面接口联调和维护的效率提升非常明显。

5.4 规格文件太啰嗦怎么精简

有人觉得规格文件写起来太啰嗦，一个简单接口要写几十行 YAML。这个问题确实存在，但要看怎么权衡。我的经验是该啰嗦的地方不能省，能省的地方尽量省。

必须写的：接口路径、方法、请求字段、响应字段、错误码。这些是契约的核心，省了就失去意义了。

可以省的：description字段如果字段名本身已经很清楚，可以省略；meta里的author如果不是必须的，可以省略；错误码的trigger字段如果message已经说清楚了，可以省略。

另外可以用规格片段复用来减少重复。比如多个接口都有分页参数，可以把分页参数抽成一个片段，用$ref引用。这样既保证了规格的完整性，又避免了重复编写。

# specs/common/pagination.yaml page: type: integer required: false default: 1 min: 1 description: 页码 page_size: type: integer required: false default: 20 min: 1 max: 100 description: 每页数量

然后在接口规格里引用：

request: query: - $ref: '#/specs/common/pagination.yaml#/page' - $ref: '#/specs/common/pagination.yaml#/page_size'

5.5 团队不配合怎么推动

推动 OpenSpec 落地，技术问题好解决，人的问题最难。我见过不少团队技术方案很好，但推不动，最后不了了之。分享几个我总结的推动技巧：

• 先做出样板：不要一上来就要求所有人写规格，自己先在一个模块里跑通，拿出实际效果。比如“用了规格生成之后，这个模块的联调时间从 3 天缩短到半天”，用数据说话。
• 降低起步门槛：提供模板和脚本，让写规格文件变得简单。不要让人从零开始写 YAML，给一个模板，填空就行。
• 绑定流程：把规格校验加到 CI 里，不写规格就构建失败。这个需要技术负责人支持，但效果最直接。
• 定期回顾：每周或者每两周回顾一次规格化的进展，表扬做得好的，帮助遇到困难的。让这件事保持热度，不要冷下去。

我自己的体会是，推动任何工程实践落地，技术只占三成，剩下七成是沟通和坚持。OpenSpec 这套东西本身不复杂，难的是让团队接受并坚持用下去。一旦用顺了，大家就回不去了，因为确实省事。

6. 进阶玩法：让规格发挥更大价值

6.1 基于规格生成 Mock 服务

规格文件不仅能生成类型定义，还能生成 Mock 服务。原理很简单：读取规格文件里的响应结构，自动生成符合结构的假数据，然后起一个本地服务返回这些数据。前端不用等后端写完就能开发，后端也不用为了联调专门写临时接口。

// scripts/mock_server.js const express = require('express'); const yaml = require('js-yaml'); const fs = require('fs'); const path = require('path'); const app = express(); const specs = loadSpecs('./specs'); for (const spec of specs) { const method = spec.request.method.toLowerCase(); const routePath = spec.request.path; app[method](routePath, (req, res) => { const mockData = {}; for (const field of spec.response.success.body) { mockData[field.name] = generateMockValue(field); } res.json({ code: 200, data: mockData }); }); } function generateMockValue(field) { switch (field.type) { case 'string': if (field.format === 'email') return 'test@example.com'; if (field.format === 'url') return 'https://example.com/avatar.png'; if (field.format === 'datetime') return new Date().toISOString(); return `mock_${field.name}`; case 'integer': return Math.floor(Math.random() * 1000); case 'boolean': return true; default: return null; } } app.listen(3001, () => console.log('Mock 服务启动在 3001 端口'));

这个 Mock 服务跑起来之后，前端直接连本地 3001 端口就能拿到符合规格的假数据，开发效率提升非常明显。

6.2 基于规格生成测试用例

规格文件里定义了字段的类型、约束、错误码，这些信息可以直接用来生成测试用例。比如username字段有min_length: 3和max_length: 32的约束，就可以自动生成边界值测试：长度为 2 的字符串、长度为 3 的字符串、长度为 32 的字符串、长度为 33 的字符串。

// scripts/generate_tests.js function generateBoundaryTests(field) { const tests = []; if (field.min_length !== undefined) { tests.push({ name: `${field.name} 长度小于最小值`, value: 'a'.repeat(field.min_length - 1), expect: 'fail' }); tests.push({ name: `${field.name} 长度等于最小值`, value: 'a'.repeat(field.min_length), expect: 'pass' }); } if (field.max_length !== undefined) { tests.push({ name: `${field.name} 长度等于最大值`, value: 'a'.repeat(field.max_length), expect: 'pass' }); tests.push({ name: `${field.name} 长度大于最大值`, value: 'a'.repeat(field.max_length + 1), expect: 'fail' }); } return tests; }

生成的测试用例覆盖了边界情况，测试工程师只需要补充业务逻辑相关的用例，基础的类型和约束测试全部自动生成。这样既保证了覆盖率，又节省了人力。

6.3 基于规格做接口变更影响分析

规格文件版本化之后，可以通过对比不同版本的规格文件，分析接口变更的影响范围。比如某个字段从必填改成可选，哪些调用方会受影响？某个错误码被删除了，哪些地方还在处理这个错误码？

这个分析可以做成一个脚本，在 CI 里跑，每次规格变更时自动输出影响报告：

# 对比两个版本的规格文件 node scripts/diff_spec.js specs/user/register.yaml HEAD~1 specs/user/register.yaml HEAD

输出结果类似：

接口 user.register 发生以下变更： - 字段 email 从 required 改为 optional（影响：前端可以不再传 email） - 新增错误码 40004（影响：调用方需要处理新的错误情况） - 字段 invite_code 被删除（影响：调用方如果传了 invite_code 会被忽略）

这个影响报告可以自动发到团队群里，让相关方及时知道接口变了，提前做好适配。

7. 我踩过的那些坑

7.1 规格文件不要写太细

一开始我追求规格文件的完整性，把每个字段的长度、正则、默认值都写得清清楚楚。结果发现维护成本太高，改一个字段要改好几个地方，而且很多约束其实代码里已经做了，规格里再写一遍是重复劳动。

后来我调整了策略：规格文件只写契约层面的信息，不写实现层面的细节。比如字段类型、是否必填、错误码这些必须写，但具体的正则表达式、复杂的业务校验规则可以放到代码里，规格文件里只写一句“符合业务规则”就行。这样既保证了契约的清晰，又避免了过度设计。

7.2 代码生成不要追求 100% 覆盖

我一开始想做到所有代码都从规格生成，包括路由、控制器、服务层、数据访问层。结果发现生成的代码太死板，稍微复杂一点的业务逻辑就表达不了，最后还是得手工改，改完下次生成又覆盖了，非常痛苦。

后来我调整了范围：只生成那些重复性高、变化少、手工写容易出错的代码，比如类型定义、API 请求函数、Mock 数据、基础校验中间件。业务逻辑代码还是手工写，但可以从生成的骨架开始改。这样既享受了代码生成的便利，又保留了灵活性。

7.3 校验不要太严格

CI 里的校验一开始我设得很严格，规格和代码有任何不一致就构建失败。结果发现有些情况是合理的，比如代码里加了一个规格里没写的内部调试接口，或者某个字段的实际处理逻辑比规格里写的更宽松。这些情况都让 CI 失败，搞得大家很烦。

后来我调整了策略：核心接口严格校验，边缘情况允许例外。在规格文件里加一个strict: false的标记，标记为 false 的接口不做一致性校验。这样既保证了核心契约的严肃性，又给了边缘情况一些灵活空间。

7.4 文档生成要有人看

规格文件能生成文档，但生成的文档如果没人看，那就白生成了。我见过不少团队把文档生成到某个角落里，从来没人打开过。文档要发挥作用，必须放到大家日常会看到的地方。

我的做法是把生成的文档集成到内部的 API 管理平台里，开发、测试、前端都能方便地查到。另外在代码 review 的时候，如果接口有变更，要求 reviewer 对照生成的文档确认变更是否符合预期。这样文档就成了流程的一部分，而不是一个可有可无的附属品。

8. 一些实用的经验建议

如果你准备在团队里引入 OpenSpec，我有几个建议可以帮你少走弯路。

从一个小模块开始。不要一上来就全项目推广，选一个正在开发的新模块，用 OpenSpec 的方式跑一遍完整流程。跑通之后，把经验和数据整理出来，再向其他模块推广。

工具链要简单。不要一开始就搞复杂的工具链，能用脚本解决的就用脚本，能手工做的就先手工做。等流程跑顺了，再逐步把手工环节自动化。工具越简单，维护成本越低，越容易坚持下去。

规格文件要 review。规格文件的变更要和代码变更一样走 review 流程。review 的时候重点关注：字段类型是否合理、错误码是否成体系、是否有破坏性变更。规格 review 通过了，代码实现才有依据。

定期清理过期规格。项目迭代过程中，有些接口会被废弃，对应的规格文件也要及时删除或标记为 deprecated。不要留着过期的规格文件，那样会误导后来的人。

保持规格和代码同步。这是最重要的一条。规格和代码一旦不同步，规格就失去了价值。CI 校验是保证同步的手段，但更重要的是团队形成“改代码必须改规格”的意识。这个意识需要时间培养，但一旦形成，收益是长期的。

我在实际项目里用 OpenSpec 这套方法大概一年半，最大的感受是接口联调从“扯皮大会”变成了“对一下规格就行”。前端不再需要反复问后端字段含义，后端也不再需要给每个调用方解释错误码。规格文件成了团队之间的共同语言，沟通效率提升非常明显。当然，这套方法不是银弹，它解决的是契约同步的问题，解决不了业务逻辑复杂的问题。但对于任何涉及多人协作、多端对接的项目，OpenSpec 这套思路都值得认真考虑。