1. 从“规格散落一地”说起OpenSpec 到底想解决什么问题做过中大型项目的人大概都有过这种体验需求文档在飞书里接口定义在 Swagger 里数据库字段在某个 Excel 里前端同学按自己的理解写了一套类型后端同学按另一套理解写了 DTO测试同学又根据口口相传的“约定”写用例。等到联调那天才发现字段名对不上、枚举值少了一个、分页参数一个用 page 一个用 offset。这种“规格漂移”几乎是所有多人协作项目的通病而且越到后期越难收拾。OpenSpec 就是冲着这个痛点来的。它是一套围绕“规格即代码”理念构建的开放规范工具链核心思路是把项目里那些散落各处的接口定义、数据模型、行为约定统一收敛成机器可读、人也可读的规格文件然后基于这份规格自动派生出类型定义、校验逻辑、文档、Mock 数据甚至测试骨架。你可以把它理解成“项目契约的单一事实来源”——一份规格改一次所有下游产物跟着变谁也别想偷偷改字段。我第一次接触 OpenSpec 是在一个前后端分离的中台项目里当时团队有 6 个后端、4 个前端、2 个测试接口数量接近 200 个。项目中期需求变更频繁几乎每周都有字段增删靠人工同步文档根本追不上。引入 OpenSpec 之后我们把接口规格集中管理前端直接从规格生成 TypeScript 类型后端用规格做请求校验测试用规格生成用例模板联调阶段的扯皮至少减少了一半。这篇文章就把我这段时间踩过的坑、总结出来的用法完整地分享出来适合正在被接口协作折磨的开发者、技术负责人以及想了解“规格驱动开发”到底怎么落地的人。2. OpenSpec 的整体设计思路与方案选型2.1 为什么是“规格优先”而不是“代码优先”传统做法里代码是事实来源文档是事后补的。接口写完了顺手在 Swagger 注解里补两句或者干脆等测试来问了才补文档。这种模式的问题在于文档永远滞后于代码而且没人能保证文档和代码一致。等到文档和代码打架的时候你信谁只能去翻代码那文档就彻底失去了意义。OpenSpec 走的是反过来的路先把规格写清楚规格是事实来源代码是规格的产物。这个思路在业界其实早有实践比如 Protocol Buffers 用 .proto 文件定义消息格式gRPC 用 .proto 生成客户端和服务端代码OpenAPI 用 YAML 描述接口再生成各种语言的 SDK。OpenSpec 的定位更偏向“项目级规格中枢”它不只管接口还管数据模型、枚举、错误码、甚至一些业务规则约束。选规格优先的理由很实在规格文件是纯文本可以进 Git可以走 Code Review可以 diff可以回滚。任何一次字段变更都会在 PR 里留下痕迹谁改的、为什么改、影响了哪些下游一目了然。而代码优先模式下字段变更可能藏在某个 commit 的几十行改动里Review 的人根本注意不到。2.2 OpenSpec 的核心组成与工作流OpenSpec 的工作流可以概括成四步定义规格、校验规格、生成产物、消费产物。定义规格这一步你写的是 OpenSpec 自己的规格描述文件通常以 .ospec 或者 .yaml 为后缀里面用结构化的方式描述实体、字段、类型、约束、接口路径、请求响应结构。校验规格这一步OpenSpec 提供 CLI 工具会检查规格文件本身的语法是否正确、引用是否完整、类型是否匹配、有没有循环依赖。生成产物这一步根据配置可以输出 TypeScript 类型、JSON Schema、Mock 数据、接口文档、测试用例骨架等。消费产物这一步就是各个角色在自己的工作流里用这些产物。这套流程的价值在于“一次定义多处消费”。举个具体例子你在规格里定义了一个 User 实体有 id、name、email、status 四个字段status 是枚举 active/inactive/banned。那么前端生成的 TypeScript 类型里 status 就是联合类型后端生成的校验逻辑里 status 只能取这三个值Mock 数据里 status 会随机从三个值里挑文档里 status 的说明会自动带上枚举列表。任何一处改了枚举值所有产物同步更新不存在遗漏。2.3 和其他方案相比OpenSpec 的取舍市面上做接口规格的工具不少OpenAPI/Swagger 是最主流的JSON Schema 也常被用来做数据校验gRPC 的 proto 在微服务场景里很常见。OpenSpec 和它们相比有几个明显的取舍。第一OpenSpec 更强调“项目级”而不是“单接口级”。OpenAPI 描述的是一个个独立的接口接口之间的关系、共享的实体定义、全局的错误码在 OpenAPI 里表达起来比较别扭。OpenSpec 把实体、枚举、错误码这些公共部分抽出来做全局定义接口只是引用它们这样在大型项目里维护成本低很多。第二OpenSpec 的规格文件更偏向“可读性优先”。OpenAPI 的 YAML 写复杂接口时嵌套层级很深读起来费劲。OpenSpec 在语法设计上做了简化用更接近自然语言的结构描述同时保留了机器可解析的能力。这一点在团队协作里很重要因为规格文件是要给人看的不是只给机器看的。第三OpenSpec 不绑定具体语言和框架。它生成的是中间产物比如 JSON Schema 和类型定义你再根据这些产物去适配自己的技术栈。这意味着你可以在 Java 后端、TypeScript 前端、Python 脚本之间共享同一份规格不会被某个框架锁死。当然OpenSpec 也不是没有代价。引入一套新的规格体系意味着团队要学习新的语法和工具链初期会有一定的学习成本。而且规格文件的维护本身也需要纪律如果没人认真写规格工具再好也白搭。我的经验是先在核心模块试点跑通流程之后再逐步推广不要一上来就全量迁移。3. 核心细节解析与实操要点3.1 规格文件的结构实体、枚举、接口三件套OpenSpec 的规格文件通常分成三个主要部分实体定义、枚举定义、接口定义。实体定义描述数据模型枚举定义描述有限取值集合接口定义描述请求响应的结构。这三者之间通过引用关联实体可以引用枚举接口可以引用实体。先看实体定义。一个实体通常包含名称、描述、字段列表。每个字段有名称、类型、是否必填、默认值、约束条件。类型可以是基础类型string、number、boolean、integer、float也可以是数组、对象、或者引用其他实体。约束条件包括最小值、最大值、最小长度、最大长度、正则表达式等。entities: User: description: 系统用户 fields: id: type: integer required: true description: 用户唯一标识 name: type: string required: true minLength: 1 maxLength: 32 email: type: string required: true format: email status: type: enum ref: UserStatus required: true default: active枚举定义相对简单就是一组命名常量。enums: UserStatus: description: 用户状态 values: - active - inactive - banned接口定义描述路径、方法、请求参数、请求体、响应体、错误码。apis: getUser: method: GET path: /api/users/{id} description: 获取用户详情 params: id: type: integer required: true in: path responses: 200: type: object ref: User 404: type: object ref: ErrorResponse这三部分组合起来就构成了一份完整的规格。写规格的时候有几个要点一是命名要统一实体名用大驼峰字段名用小驼峰枚举值用下划线或者小驼峰都行但要全项目一致二是描述要写清楚别偷懒描述会直接进文档写得好省得后面口头解释三是约束要写全能加校验的地方都加上后面生成的校验逻辑会直接用这些约束。3.2 类型系统与引用机制避免循环依赖的坑OpenSpec 的类型系统支持基础类型、数组、对象、引用。引用是最容易出问题的地方尤其是循环引用。比如 A 实体有一个字段引用 BB 又有一个字段引用 A这种在业务上很常见比如用户有部门部门有负责人也是用户。如果规格文件里直接互相引用生成类型的时候可能会死循环。OpenSpec 处理循环引用的方式是延迟解析。在规格文件里你可以正常写引用工具在生成产物的时候会检测循环然后根据配置决定是生成可空引用还是拆分成独立的类型。我的建议是在业务允许的情况下尽量把循环引用拆开比如用户引用部门的时候只存 departmentId部门引用负责人的时候只存 ownerId需要完整对象的时候再单独查。这样规格更清晰生成的类型也不会太复杂。另一个坑是引用的路径问题。OpenSpec 支持跨文件引用你可以把实体定义拆到多个文件里用 import 或者 include 引入。跨文件引用的时候要注意路径的相对性以及循环 import 的问题。我的做法是按领域拆分文件比如 user.ospec、order.ospec、common.ospeccommon 里放公共枚举和错误码其他文件引用 commoncommon 不引用任何业务文件这样就不会有循环。3.3 约束与校验让规格真正“能打”规格文件如果只是描述结构那和普通文档没区别。OpenSpec 的价值在于约束可以被工具消费变成真正的校验逻辑。所以写规格的时候约束一定要写全。常见的约束包括字符串的 minLength、maxLength、pattern数字的 minimum、maximum、exclusiveMinimum、exclusiveMaximum数组的 minItems、maxItems、uniqueItems对象的 required 字段列表。这些约束在生成 JSON Schema 的时候会直接映射过去后端可以用 JSON Schema 校验请求前端可以用它做表单校验。entities: Product: fields: name: type: string required: true minLength: 2 maxLength: 64 price: type: number required: true minimum: 0.01 maximum: 999999.99 tags: type: array items: type: string maxItems: 10 uniqueItems: true这里有个实操心得约束不要写得太死。比如 price 的 maximum 设成 999999.99看起来合理但如果业务上出现了一个超大订单规格就得改一改就要走一遍生成流程。我的做法是业务上明确的硬约束写死业务上不确定的软约束放宽或者不写把校验留给业务代码。规格的作用是保证结构一致不是替代所有业务校验。还有一个细节是默认值的处理。OpenSpec 支持给字段设默认值生成 Mock 数据的时候会用默认值生成类型的时候默认值会体现在注释里。但要注意默认值不等于必填一个字段可以有默认值但仍然是可选的。这个区别在生成校验逻辑的时候很重要可选字段缺失是合法的必填字段缺失才报错。4. 实操过程与核心环节实现4.1 环境准备与 CLI 安装OpenSpec 的 CLI 工具是核心入口安装方式取决于你的技术栈。如果是 Node.js 环境通常通过 npm 全局安装如果是其他环境可以下载独立的二进制包。安装完成之后用openspec --version验证一下。npm install -g openspec-cli openspec --version安装完之后在项目根目录初始化 OpenSpec 配置。初始化命令会生成一个 openspec.config.yaml 文件里面配置规格文件的位置、生成产物的输出目录、生成器类型等。openspec init生成的配置文件大概长这样specDir: ./specs outputDir: ./generated generators: - typescript - jsonschema - mock - docs这里有个坑outputDir 不要设在 src 目录里面否则生成的文件会被打包工具当成源码处理可能导致循环依赖或者打包体积膨胀。我的做法是生成到项目根目录的 generated 文件夹然后在 tsconfig 或者构建配置里把 generated 加入 include 路径但不加入编译入口。4.2 编写第一份规格文件假设我们要做一个简单的用户管理模块先写实体和枚举。enums: UserStatus: values: - active - inactive - banned entities: User: description: 系统用户 fields: id: type: integer required: true name: type: string required: true minLength: 1 maxLength: 32 email: type: string required: true format: email status: type: enum ref: UserStatus required: true default: active createdAt: type: string format: date-time required: true然后写接口。apis: listUsers: method: GET path: /api/users description: 分页查询用户列表 params: page: type: integer required: false default: 1 minimum: 1 pageSize: type: integer required: false default: 20 minimum: 1 maximum: 100 status: type: enum ref: UserStatus required: false responses: 200: type: object properties: total: type: integer items: type: array items: ref: User createUser: method: POST path: /api/users description: 创建用户 body: type: object ref: User exclude: - id - createdAt responses: 201: type: object ref: User 400: type: object ref: ErrorResponse注意 createUser 的 body 里用了 exclude把 id 和 createdAt 排除掉因为这两个字段是服务端生成的。OpenSpec 支持这种基于实体的裁剪避免重复定义。4.3 生成产物与集成到项目规格写完之后运行生成命令。openspec generate生成命令会读取配置把规格转换成各种产物。以 TypeScript 为例生成的类型文件大概是这样export type UserStatus active | inactive | banned; export interface User { id: number; name: string; email: string; status: UserStatus; createdAt: string; } export interface ListUsersParams { page?: number; pageSize?: number; status?: UserStatus; } export interface ListUsersResponse { total: number; items: User[]; }前端直接 import 这些类型写请求的时候就有完整的类型提示。后端如果用 Node.js可以用生成的 JSON Schema 做请求校验。const Ajv require(ajv); const ajv new Ajv(); const validate ajv.compile(require(./generated/schemas/createUser.body.json)); app.post(/api/users, (req, res) { if (!validate(req.body)) { return res.status(400).json({ error: validate.errors }); } // 业务逻辑 });这里有个实操细节生成的 JSON Schema 文件名最好带上接口名和位置比如 createUser.body.json、listUsers.params.json这样在代码里引用的时候一目了然。OpenSpec 的生成器通常支持自定义命名模板可以在配置里指定。4.4 把生成流程接入 CI规格文件改了之后产物必须重新生成否则代码和规格就不一致了。手动跑生成命令容易忘最好的做法是接入 CI。在 CI 里加一步先跑openspec generate然后检查 generated 目录有没有变化如果有变化说明有人改了规格但没重新生成产物直接让 CI 失败。openspec generate if [ -n $(git status --porcelain generated/) ]; then echo Generated files are out of date. Please run openspec generate and commit the changes. exit 1 fi这个检查看起来简单但非常有效。它强制所有人改规格之后必须重新生成产物保证仓库里的产物和规格始终一致。我见过太多项目规格改了但产物没更新结果代码里用的还是旧类型联调的时候才发现问题。5. 常见问题与排查技巧实录5.1 规格校验报错引用找不到这是最常见的问题通常是因为引用的名称拼错了或者引用的实体定义在另一个文件里但没有正确 import。排查的时候先看报错信息里提到的引用名称然后在规格文件里全局搜索这个名称确认定义存在且路径正确。如果用了跨文件引用检查 import 语句的路径是不是相对于当前文件。OpenSpec 的路径解析通常是相对于规格根目录而不是相对于当前文件这一点和很多工具不一样容易搞混。我的习惯是统一用相对于 specDir 的路径避免相对路径的歧义。5.2 生成的类型有循环引用导致编译报错前面提到过循环引用的问题。如果生成的 TypeScript 类型里出现了 A 引用 B、B 引用 A 的情况TypeScript 编译器可能会报错或者推断出 any。解决办法有两个一是改规格把循环引用拆成 ID 引用二是在生成器配置里开启循环引用处理让生成器把循环的字段标记为可选或者用接口分离。我一般优先改规格因为循环引用在业务上往往意味着模型设计有问题。比如订单引用用户、用户引用订单列表这种双向引用在查询的时候很容易导致 N1 问题拆成单向引用反而更合理。5.3 生成产物和手写代码冲突有时候项目里已经有一些手写的类型定义引入 OpenSpec 之后生成的类型和手写的类型重名或者结构不一致导致编译冲突。解决办法是逐步迁移先把新模块用 OpenSpec 管理老模块保持手写等新模块跑顺了再逐步把老模块迁过来。迁移的时候用类型别名做过渡比如export type LegacyUser OldUser;等所有引用都改完之后再删掉老类型。5.4 规格文件太大维护困难项目大了之后规格文件可能几千行改一个字段要翻半天。解决办法是按领域拆分文件每个领域一个文件公共部分抽到 common 文件。拆分之后用 import 关联生成的时候 OpenSpec 会自动合并。拆分的粒度建议按业务模块来比如 user、order、product、payment每个模块内部再按实体、接口分文件。问题现象可能原因排查方向解决办法引用找不到名称拼错或路径错误全局搜索引用名称修正名称或 import 路径类型循环引用实体互相引用检查实体关系拆成 ID 引用或开启循环处理产物与手写代码冲突类型重名检查类型定义逐步迁移用别名过渡规格文件过大未按领域拆分检查文件组织按模块拆分公共部分抽离生成产物未更新忘记跑生成命令检查 git status接入 CI 强制检查5.5 独家避坑技巧规格的版本管理规格文件一定要进 Git而且要和代码在同一个仓库里。我见过有的团队把规格单独放一个仓库结果规格和代码的版本对不上发布的时候不知道该用哪个版本的规格。同一个仓库里规格和代码一起提交一起打 tag版本天然一致。另外规格的变更要走 Code Review而且 Review 的人里最好有前端和后端各一个。因为规格变更影响的是双方只让后端 Review 可能忽略前端的兼容性问题。我们团队的做法是规格文件的 PR 必须至少有一个前端和一个后端 approve 才能合并这个规则看起来麻烦但确实避免了很多联调问题。6. 规格驱动开发的延伸玩法6.1 用规格生成 Mock 服务OpenSpec 生成的 Mock 数据可以直接喂给 Mock 服务前端在后端接口没写好之前就能联调。Mock 服务读取生成的 JSON Schema根据 Schema 生成符合结构的假数据前端请求 Mock 服务拿到的响应结构和真实接口一致。这样前端不用等后端后端也不用为了前端临时写假接口。Mock 数据生成的时候有几个配置项值得注意一是是否使用默认值如果字段有默认值Mock 数据会用默认值二是数组的长度范围可以配置最小和最大长度三是字符串的生成规则比如 email 格式的字段会生成合法的邮箱地址。这些配置在 openspec.config.yaml 里可以调整。6.2 用规格生成测试用例骨架测试同学最头疼的是接口用例写不完尤其是字段多、组合多的时候。OpenSpec 可以根据规格生成测试用例骨架把必填字段、可选字段、边界值都列出来测试同学只需要补充具体的测试数据和预期结果。这不能完全替代人工设计用例但能省掉大量重复劳动。生成的测试骨架通常包含正常请求用例所有必填字段都有合法值、缺字段用例逐个缺失必填字段、边界值用例最小值、最大值、超限值、类型错误用例字段类型不对。这些用例覆盖了大部分基础场景测试同学在此基础上补充业务逻辑相关的用例就行。6.3 规格与文档的联动OpenSpec 生成的文档是静态的 HTML 或者 Markdown可以部署到内部文档站点。文档里的字段说明、枚举值、约束条件都来自规格规格改了文档自动更新不存在文档滞后的问题。而且文档里可以标注每个字段的变更历史谁在哪个版本改的方便追溯。文档生成的时候建议开启“示例”功能每个接口自动生成请求和响应的示例。示例数据来自 Mock 生成器结构和真实接口一致。这样看文档的人不用自己脑补请求长什么样直接复制示例改改就能用。6.4 多语言项目的规格共享如果项目里有多种语言比如 Java 后端、TypeScript 前端、Python 数据脚本OpenSpec 的规格可以作为共享的契约。Java 用生成的 JSON Schema 做校验TypeScript 用生成的类型做开发Python 用生成的 Schema 做数据清洗。一份规格三种语言消费谁也不用猜别人的数据结构。实现这个的关键是生成器要支持多语言输出。OpenSpec 的生成器是可扩展的社区里有各种语言的生成器插件也可以自己写。写生成器的时候注意保持产物的命名风格和语言习惯一致比如 Java 的类名用大驼峰Python 的变量名用下划线这些可以在生成器配置里指定。7. 我个人的一些实操体会规格驱动开发这件事工具只是一半另一半是团队的习惯。我见过工具用得很好但规格写得一塌糊涂的团队也见过工具一般但规格维护得很认真的团队后者的协作效率明显更高。所以引入 OpenSpec 的时候别只盯着工具怎么用更要建立“改代码先改规格”的纪律。另外规格的粒度要适中。太粗了起不到约束作用太细了维护成本高。我的经验是接口的路径、方法、请求响应结构、必填字段、枚举值这些必须写进规格业务逻辑相关的校验比如“用户余额不足不能下单”留给代码。规格管的是“长什么样”代码管的是“能不能做”两者分工明确。最后说一个实际收益引入 OpenSpec 之后我们团队的接口联调时间从平均两天缩短到半天字段不一致导致的 bug 减少了大概七成。这个收益不是工具自动带来的而是因为规格强制大家在写代码之前先把接口想清楚。很多时候联调出问题不是因为技术难而是因为双方对接口的理解不一致规格就是消除这种不一致的最直接手段。
