1. 为什么需要Spec-kit规范驱动的断点在哪1.1 SDD的核心理念规范是唯一的事实源SDDSpecification-Driven Development规范驱动开发说起来并不神秘团队里只要有文档习惯或多或少都在实践它的雏形。先写需求规格再写详细设计然后编码最后测试验收——这听起来像经典的瀑布流但SDD的真正内核不是流程顺序而是“规范作为单一事实源”这个原则。我见过不少团队把接口文档、数据库设计文档、测试用例文档分别维护结果就是同一个字段在不同文档里出现三种类型、两种命名等到联调时才发现你对齐的是上一版的文档。SDD要解决的问题正是这个让所有后续产物——接口定义、数据模型、测试断言、甚至部署配置——都从同一份规范推导出来而不是各写各的。这份规范需要机器可读否则它只是又一个被人手动同步的文档。Spec-kit做的事情就是把这个机器可读、可解析、可校验的规范文件变成整个开发链路的起点。它不是替代设计而是把设计意图通过结构化描述固化下来让代码生成器、校验器、测试框架都能在这份规范上对齐。1.2 规范与代码脱节的三种典型场景先聊三个我实际踩过的坑这基本就是SDD落地时最常见的断点。第一个坑规范写完了代码不认。团队里规范文档写得非常完整字段、边界、状态机都画得清清楚楚。可到了编码阶段开发还是照着接口文档或者自己的理解去写实现。规范里的字段长度限制是128代码里的校验写的是64等测试发现这个不一致时已经过去两个迭代了。这不是人不认真而是每个人的信息同步路径不同——有人看规范有人看旧代码有人直接问上游。第二个坑规范改起来太痛。业务上要加一个字段理论上应该先改规范再同步代码、数据库脚本、测试用例。但实际操作里改代码最快改数据库其次改规范文档基本排在最后甚至不做。结果规范越来越偏离现实最后彻底变成没人看的摆设。为什么会这样因为改一次规范的边际成本太高涉及的单据太多还没有自动化工具帮忙同步。第三个坑规范形态不够结构化。很多团队所谓的规范其实就是Markdown里的大段落文字风控条件、字段含义混在一起。人读起来没问题但机器无从下手。想做个自动校验得先写一堆正则去捉文档里的表格等于给文档做逆解析维护成本比直接改代码还大。Spec-kit这类工具的切入点就是针对这三个断点规范必须结构化、必须可校验、必须能自动派生产物。它把“写规范”从文档动作变成编程动作规范本身就是代码的一部分。1.3 Spec-kit在团队协作里的实际定位作为一个工程化工具Spec-kit不负责替你设计业务也不负责写出所有业务逻辑。它的位置更像是一个“规范编译器”输入是结构化的规格文件输出是可编译、可运行、可校验的工程资产。从这个角度看Spec-kit的定位很明确它服务的是规范与代码之间的翻译层。在团队协作中它承担四个职能统一口径所有人的设计讨论都围绕规范文件展开而不是代码细节。自动校验规范里写明的约束会被转成代码里的运行时校验、数据库约束和测试断言。快速生成接口层、数据访问层、测试桩的初版代码可以一键生成减少机械性劳动。持续追踪规范变了生成的产物能通过重新生成和diff高亮出来让变更不再悄悄发生。这意味着从流程上看Spec-kit把SDD从“先写文档再开发”的模式变成了“维护规范代码跟着规范跑”的模式。后面我会用一个用户模块的完整案例来演示这条链路。2. 理解Spec-kit从规范文本到工程产物的完整链路2.1 规范文件的形态YAML还是Markdown在决定Spec-kit的规范格式时我首先排除了纯Markdown。原因很简单Markdown擅长表达阅读逻辑但在表达约束关系、字段类型、嵌套结构时非常暧昧。一个表格里某列是“必填”机器怎么判断“必填”和“选填”人眼能分辨解析器很难。我更推荐用YAML或JSON作为规范载体。YAML因为注释友好、层级清晰、diff可读性强是我在团队里的首选。下面这个示例就是一个用户模块的规范片段spec: module: user version: 1.0.0 entities: - name: User description: 系统用户 fields: - name: id type: uuid required: true immutable: true - name: nickname type: string required: true maxLength: 32 - name: email type: string format: email required: true unique: true - name: status type: enum values: [active, disabled, deleted] default: active indexes: - name: idx_user_email fields: [email] unique: true behaviors: - name: createUser http: method: POST path: /api/v1/users input: - nickname - email output: - id - nickname - email - status errors: - emailExists - invalidEmail这份规范的可读性不输给Markdown表格但它的结构足够规整解析器可以直接处理。Spec-kit在读取后会构建一个内部的模型这个模型贯穿后续的校验和生成流程。规范文件的版本号也非常重要后续所有产物都会带上这个版本号方便追踪变更。2.2 三层处理管线解析、校验、生成Spec-kit的核心是一条三层处理管线。理解它等于理解了整个工具的骨架。第一层解析Parse。这一步把YAML或JSON读入内存转换成结构化的领域模型。解析器会检查语法错误、未知字段、类型错误。我在使用中发现解析器最需要注意的坑是类型联想——比如YAML里email的minLength没写工具要不要默认给个值我的建议是不要猜测宁可报错也不要补默认值。规范的意义在于显式默认值一旦补了就会掩盖规范里的真实意图。第二层校验Validate。解析成功不等于规范有效。校验层会执行两类检查结构完整性检查每个实体是否至少有一个主键每个行为引用的输入字段是否都在实体里定义过枚举值是否重复这类问题在规范早期最容易出现。一致性检查字段的type、format、约束条件是否符合平台规则。举个例子type是uuid就不能同时声明patternformat是email就不应该同时设置maxLength小于5的荒谬值。校验失败时Spec-kit会输出包含文件路径、字段路径和错误原因的诊断信息。这个诊断信息我非常看重它直接决定工具在团队里是受欢迎还是被嫌弃。如果错误信息说“第14行errors字段未知”团队里人人会用如果只说“解析失败”那基本就没人愿意碰了。第三层生成Generate。校验通过后Spec-kit会在内存模型上执行多组生成器。每个生成器负责一种产物OpenAPI文档、数据库DDL、Typescript接口类型、JavaDTO、测试桩、Mock数据。生成器采用模板驱动的方式所以团队可以自定义模板来适配自己的技术栈。之所以强调“可自定义模板”是因为大多数团队使用的框架不是Spec-kit内置的那几款。比如我之前的团队用的是Gin框架就需要自己写一套Go的模板。这个扩展机制让Spec-kit能在不同技术栈之间存活下来。2.3 与OpenAPI、AsyncAPI等方案的边界在哪里用Spec-kit的时候很多熟悉OpenAPI的同学会问我有OpenAPI不就行了吗为什么还要Spec-kit这个问题非常关键。OpenAPI描述的是接口层它是一个非常好的“接口规范”但它有两个局限第一它不覆盖领域模型和数据持久化层你很难在OpenAPI里表达“这个字段在数据库里建唯一索引”第二OpenAPI偏重描述“接口是什么样”而不是“业务约束应该满足什么”像emailExists这种业务错误在纯OpenAPI里表达起来很别扭。Spec-kit的思路是内部的中间模型是业务导向的OpenAPI只是它的一个下游产物。你可以用Spec-kit生成的OpenAPI文档再喂给其他工具链但反过来不行——因为OpenAPI缺少实体建模和约束表达的完整性。我这里不是说Spec-kit要取代OpenAPI而是它们层次不同。Spec-kit更像一个前置设计层OpenAPI是它的输出物之一。如果团队已经在用OpenAPI可以把Spec-kit放在上游生成OpenAPI后再走原有的代码生成和Mock服务流程。3. 实操落地用Spec-kit从零驱动一个用户服务3.1 初始化项目与目录约定先准备环境。假设团队用的是Node.js生态我这边用的版本是Node 20 LTS通过npm安装Spec-kitnpm install -g spec-kit装完后创建一个项目目录并初始化规范仓库mkdir spec-demo cd spec-demo spec-kit init --template minimalinit命令会生成一个推荐的目录结构。我的习惯是把规范、模板、产出物分开spec-demo/ ├── specs/ │ └── user.yaml ├── templates/ │ └── go_gin/ │ ├── model.gotmpl │ ├── controller.gotmpl │ └── dto.gotmpl ├── generated/ │ ├── api/ │ ├── model/ │ └── docs/ ├── spec-kit.config.yml └── package.jsonspecs目录放规格文件是团队评审的核心对象templates目录放自定义模板generated目录是生成产物不要手动改这是血泪教训。手动改了再生成diff会非常痛苦而且容易把业务修复覆盖掉。生成的代码应该被视为编译产物而不是源码。3.2 编写用户模块的完整规范上面已经给了一部分YAML片段这里我再补全它让它可以被Spec-kit实际跑到生成阶段spec: module: user version: 1.0.0 entities: - name: User description: 系统用户 fields: - name: id type: uuid required: true immutable: true - name: nickname type: string required: true minLength: 2 maxLength: 32 - name: email type: string format: email required: true unique: true - name: status type: enum values: [active, disabled, deleted] default: active indexes: - name: idx_user_email fields: [email] unique: true behaviors: - name: createUser http: method: POST path: /api/v1/users input: - nickname - email output: - id - nickname - email - status errors: - emailExists - invalidEmail - name: getUserById http: method: GET path: /api/v1/users/{id} input: - id output: - id - nickname - email - status这里我想重点展开几个容易被忽略的细节第一个是immutable: true。id字段创建后不允许修改。如果让代码生成器感知这个约束生成的update方法就不会包含这个字段避免了数据被意外覆盖。这个约束如果放在自然语言文档里开发很容易漏掉但放到规范里生成器就能强制执行。第二个是unique: true和索引定义同时出现。我在这两个地方都写了unique看起来冗余但含义不同字段级unique是业务约束索引是物理实现。Spec-kit会校验它们是否一致——如果规范里字段声明unique但没有对应的唯一索引定义会给出警告。这个设计是为了兼顾DDD式思维和数据库工程实际。第三个是errors列表。我在behaviors里显式声明了这个行为可能抛出的错误。生成器会据此生成错误码枚举前端也可以直接引用。以前这些错误码散落在后端代码和前端常量里对齐全靠开会现在只需要加一行。写完之后跑一下校验spec-kit validate specs/user.yaml如果一切正常输出大概是✔ parsed 1 spec file(s) ✔ validated 1 entity(ies), 2 behavior(s) ✔ no issues found有了这个输出就可以进入生成阶段了。3.3 生成接口层与数据层代码接下来用内置模板生成文档和代码spec-kit generate --specs specs/user.yaml --out generated这会在generated目录下生成多组文件。我挑几个典型的看。生成的OpenAPI文档片段openapi: 3.0.1 info: title: user version: 1.0.0 paths: /api/v1/users: post: operationId: createUser requestBody: required: true content: application/json: schema: type: object properties: nickname: type: string maxLength: 32 email: type: string format: email responses: 200: description: success content: application/json: schema: type: object properties: id: type: string format: uuid nickname: type: string email: type: string status: type: string enum: [active, disabled, deleted]生成的数据库DDL片段CREATE TABLE users ( id UUID PRIMARY KEY, nickname VARCHAR(32) NOT NULL, email VARCHAR(255) NOT NULL, status VARCHAR(16) NOT NULL DEFAULT active, CONSTRAINT uk_user_email UNIQUE (email) ); CREATE INDEX idx_user_email ON users(email);这里有个细节email我声明了format: email但没有写maxLength生成器在选择VARCHAR长度时按255处理。这个默认值来自模板引擎不是Spec-kit硬编码。所以如果你的团队要求email字段更短需要在模板或者规范里显式设置。这也是之前说的——模板决定了生成产物的细节风格。如果使用自定义模板还可以生成服务端的DTO和路由注册代码。以Go Gin模板为例生成后的handler骨架大概是func CreateUser(c *gin.Context) { var req CreateUserRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } // TODO: implement business logic c.JSON(200, UserDTO{}) }生成的代码不会是完整的业务实现重点是DTO结构、请求校验和路由注解都已经对齐了规范。业务逻辑留白正好也避免了一个常见误区——不要期待工具能替你写业务它负责的是把规范固定下来让你写业务时不用分心处理接口细节。3.4 把规范校验接入CI流水线日常开发中规范与代码最容易出现漂移。要防止这个问题我强烈建议把spec校验和生成差异检查接入CI。我在GitHub Actions里加了一个简单的工作流name: spec-check on: pull_request: paths: - specs/** - templates/** jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g spec-kit - run: spec-kit validate specs/*.yaml - run: spec-kit generate --specs specs/user.yaml --out generated --check--check参数很关键它会让生成器把生成结果和当前仓库里的generated目录对比不一致就返回非零退出码。这样开发者改了规范但没有重新生成代码CI就会拦下这个PR。同时我还会在PR模板里加一个问题“本次改动是否由规范文件驱动”这听着像行政规定但实际作用是不断提醒团队代码变更的源头应该体现在spec文件里而不是悄无声息地散落在handler和mapper中。4. 常见问题与排查技巧实录4.1 五个高频问题的排查速查表在使用Spec-kit的过程中我和团队陆续遇到过不少问题。这里整理一个速查表方便你对照排障问题现象可能原因排查思路解析报“未知字段”YAML里拼写错误或用了没注册的属性检查字段名在规范中增加自定义属性需要先扩展schema校验报“字段未在实体中定义”behavior的input引用了一个不存在的字段核对input字段名与entities里的定义注意大小写生成的DDL里唯一索引缺失只有字段级unique没定义indexes补上indexes定义并保持两边一致生成的OpenAPI里没有错误码behavior的errors列表为空在behaviors里显式列出业务错误重新生成后大量diff有人手动改过generated目录删除generated目录重新生成或引入CI检查机制这里面我最想强调的是最后一个问题。手动改生成代码的诱惑非常大因为改起来非常快几秒钟就解决问题。但代价是后续每次生成都要处理冲突最终可能整个generated目录退化成手工代码规范又成了摆设。与其这样不如建立一个明确的约定generated是构建产物一切改动回到spec和模板里做。4.2 其它常见问题与处理建议除了上面的表格我再补充几个实际工作中容易碰到的细节问题。闭包结构嵌套导致模板取值困难。Spec-kit的模板引擎支持点号路径取值但嵌套实体和枚举组合在一起时模板会变得很难读。我的建议是模板里只做基础映射复杂的派生逻辑比如字段级默认值来自另一个字段的枚举放在生成器的预处理函数里模板保持干净。模板一旦复杂到需要写大量逻辑维护成本会直线上升。多人并行修改同一份spec文件。这个和普通代码冲突一样但spec的语义冲突更难发现。比如两个分支都加了同一个字段但类型不同文erge时代码能并规范却出现了二义性。我碰到的处理方式是在CI里加一个spec-kit merge-check命令专门扫描合并后是否存在同名实体属性冲突。这个命令不解决所有问题但能挡住最明显的那类重复定义。空值的处理逻辑要提前约定。规范里type是string但没有required——那么生成代码时是输出pointer类型还是string类型不同团队的偏好不同。Spec-kit默认生成的是可区分空值的指针类型比如Go的*string但如果你是Java团队可能更想用Optional。这种平台相关的细节一定要早早在模板里固化不然每个人生成的代码风格都不一样。4.3 我在实际使用中的几点心得最后分享几个纯经验层面的内容。第一规范文件别追求大而全。刚开始用Spec-kit时我恨不得把所有业务规则全部塞进YAML里结果规范写得比代码还长评审没人愿意看。后来我给自己定了一个简单标准凡是影响接口契约、数据结构、约束规则的内容进规范凡是纯业务编排逻辑留在代码里。这个界限划清楚后spec文件才真正变成一个可维护的产品。第二规范的版本要跟随模块而非项目。规范文件里有一个version字段我建议把它和模块的API版本绑定而不是和整个项目的发布版本绑定。这样用户服务的v1和订单服务的v1互不干扰演化时各自升级清晰得多。第三一定一定把spec文件纳入code review范围。很多团队重视代码评审却忽略了规范评审。其实规范的评审价值比代码更高——因为它影响面更大一次错误的字段定义会导致生成的所有代码都错。每份spec变更都应当被仔细review就像review核心库代码一样。结尾关于Spec-kit继续扩展的几个方向我自己目前用得最多的是接口和数据层的生成场景但Spec-kit的模板机制让它还有不少扩展空间。比如Event定义生成在消息驱动架构里事件主题、payload格式、消费组名都可以放在规范里描述向后端生成发布者向前端生成消息类型定义。又比如状态机定义把状态迁移的合法路径写进YAML然后生成校验代码能有效防止非法状态跳跃。再比如契约测试的seed数据规范里的字段定义可以直接作为测试数据生成的依据。这些方向不一定是Spec-kit现在的官方能力但工具既然提供了“规范→中间模型→多模版生成”的核心链路后面就能持续演化。我个人体会是真正让Spec-kit起作用的关键不是工具本身多强大而是团队愿意把“写规范”当作开发的一部分而不是开发完再补的文档。把一个聪明的工具放到一个不认规范的流程里它的价值发挥不出来反过来哪怕工具朴素一点只要团队认认真真维护规范文件产出的代码质量和协作效率都会有明显提升。
1. 为什么需要Spec-kit规范驱动的断点在哪1.1 SDD的核心理念规范是唯一的事实源SDDSpecification-Driven Development规范驱动开发说起来并不神秘团队里只要有文档习惯或多或少都在实践它的雏形。先写需求规格再写详细设计然后编码最后测试验收——这听起来像经典的瀑布流但SDD的真正内核不是流程顺序而是“规范作为单一事实源”这个原则。我见过不少团队把接口文档、数据库设计文档、测试用例文档分别维护结果就是同一个字段在不同文档里出现三种类型、两种命名等到联调时才发现你对齐的是上一版的文档。SDD要解决的问题正是这个让所有后续产物——接口定义、数据模型、测试断言、甚至部署配置——都从同一份规范推导出来而不是各写各的。这份规范需要机器可读否则它只是又一个被人手动同步的文档。Spec-kit做的事情就是把这个机器可读、可解析、可校验的规范文件变成整个开发链路的起点。它不是替代设计而是把设计意图通过结构化描述固化下来让代码生成器、校验器、测试框架都能在这份规范上对齐。1.2 规范与代码脱节的三种典型场景先聊三个我实际踩过的坑这基本就是SDD落地时最常见的断点。第一个坑规范写完了代码不认。团队里规范文档写得非常完整字段、边界、状态机都画得清清楚楚。可到了编码阶段开发还是照着接口文档或者自己的理解去写实现。规范里的字段长度限制是128代码里的校验写的是64等测试发现这个不一致时已经过去两个迭代了。这不是人不认真而是每个人的信息同步路径不同——有人看规范有人看旧代码有人直接问上游。第二个坑规范改起来太痛。业务上要加一个字段理论上应该先改规范再同步代码、数据库脚本、测试用例。但实际操作里改代码最快改数据库其次改规范文档基本排在最后甚至不做。结果规范越来越偏离现实最后彻底变成没人看的摆设。为什么会这样因为改一次规范的边际成本太高涉及的单据太多还没有自动化工具帮忙同步。第三个坑规范形态不够结构化。很多团队所谓的规范其实就是Markdown里的大段落文字风控条件、字段含义混在一起。人读起来没问题但机器无从下手。想做个自动校验得先写一堆正则去捉文档里的表格等于给文档做逆解析维护成本比直接改代码还大。Spec-kit这类工具的切入点就是针对这三个断点规范必须结构化、必须可校验、必须能自动派生产物。它把“写规范”从文档动作变成编程动作规范本身就是代码的一部分。1.3 Spec-kit在团队协作里的实际定位作为一个工程化工具Spec-kit不负责替你设计业务也不负责写出所有业务逻辑。它的位置更像是一个“规范编译器”输入是结构化的规格文件输出是可编译、可运行、可校验的工程资产。从这个角度看Spec-kit的定位很明确它服务的是规范与代码之间的翻译层。在团队协作中它承担四个职能统一口径所有人的设计讨论都围绕规范文件展开而不是代码细节。自动校验规范里写明的约束会被转成代码里的运行时校验、数据库约束和测试断言。快速生成接口层、数据访问层、测试桩的初版代码可以一键生成减少机械性劳动。持续追踪规范变了生成的产物能通过重新生成和diff高亮出来让变更不再悄悄发生。这意味着从流程上看Spec-kit把SDD从“先写文档再开发”的模式变成了“维护规范代码跟着规范跑”的模式。后面我会用一个用户模块的完整案例来演示这条链路。2. 理解Spec-kit从规范文本到工程产物的完整链路2.1 规范文件的形态YAML还是Markdown在决定Spec-kit的规范格式时我首先排除了纯Markdown。原因很简单Markdown擅长表达阅读逻辑但在表达约束关系、字段类型、嵌套结构时非常暧昧。一个表格里某列是“必填”机器怎么判断“必填”和“选填”人眼能分辨解析器很难。我更推荐用YAML或JSON作为规范载体。YAML因为注释友好、层级清晰、diff可读性强是我在团队里的首选。下面这个示例就是一个用户模块的规范片段spec: module: user version: 1.0.0 entities: - name: User description: 系统用户 fields: - name: id type: uuid required: true immutable: true - name: nickname type: string required: true maxLength: 32 - name: email type: string format: email required: true unique: true - name: status type: enum values: [active, disabled, deleted] default: active indexes: - name: idx_user_email fields: [email] unique: true behaviors: - name: createUser http: method: POST path: /api/v1/users input: - nickname - email output: - id - nickname - email - status errors: - emailExists - invalidEmail这份规范的可读性不输给Markdown表格但它的结构足够规整解析器可以直接处理。Spec-kit在读取后会构建一个内部的模型这个模型贯穿后续的校验和生成流程。规范文件的版本号也非常重要后续所有产物都会带上这个版本号方便追踪变更。2.2 三层处理管线解析、校验、生成Spec-kit的核心是一条三层处理管线。理解它等于理解了整个工具的骨架。第一层解析Parse。这一步把YAML或JSON读入内存转换成结构化的领域模型。解析器会检查语法错误、未知字段、类型错误。我在使用中发现解析器最需要注意的坑是类型联想——比如YAML里email的minLength没写工具要不要默认给个值我的建议是不要猜测宁可报错也不要补默认值。规范的意义在于显式默认值一旦补了就会掩盖规范里的真实意图。第二层校验Validate。解析成功不等于规范有效。校验层会执行两类检查结构完整性检查每个实体是否至少有一个主键每个行为引用的输入字段是否都在实体里定义过枚举值是否重复这类问题在规范早期最容易出现。一致性检查字段的type、format、约束条件是否符合平台规则。举个例子type是uuid就不能同时声明patternformat是email就不应该同时设置maxLength小于5的荒谬值。校验失败时Spec-kit会输出包含文件路径、字段路径和错误原因的诊断信息。这个诊断信息我非常看重它直接决定工具在团队里是受欢迎还是被嫌弃。如果错误信息说“第14行errors字段未知”团队里人人会用如果只说“解析失败”那基本就没人愿意碰了。第三层生成Generate。校验通过后Spec-kit会在内存模型上执行多组生成器。每个生成器负责一种产物OpenAPI文档、数据库DDL、Typescript接口类型、JavaDTO、测试桩、Mock数据。生成器采用模板驱动的方式所以团队可以自定义模板来适配自己的技术栈。之所以强调“可自定义模板”是因为大多数团队使用的框架不是Spec-kit内置的那几款。比如我之前的团队用的是Gin框架就需要自己写一套Go的模板。这个扩展机制让Spec-kit能在不同技术栈之间存活下来。2.3 与OpenAPI、AsyncAPI等方案的边界在哪里用Spec-kit的时候很多熟悉OpenAPI的同学会问我有OpenAPI不就行了吗为什么还要Spec-kit这个问题非常关键。OpenAPI描述的是接口层它是一个非常好的“接口规范”但它有两个局限第一它不覆盖领域模型和数据持久化层你很难在OpenAPI里表达“这个字段在数据库里建唯一索引”第二OpenAPI偏重描述“接口是什么样”而不是“业务约束应该满足什么”像emailExists这种业务错误在纯OpenAPI里表达起来很别扭。Spec-kit的思路是内部的中间模型是业务导向的OpenAPI只是它的一个下游产物。你可以用Spec-kit生成的OpenAPI文档再喂给其他工具链但反过来不行——因为OpenAPI缺少实体建模和约束表达的完整性。我这里不是说Spec-kit要取代OpenAPI而是它们层次不同。Spec-kit更像一个前置设计层OpenAPI是它的输出物之一。如果团队已经在用OpenAPI可以把Spec-kit放在上游生成OpenAPI后再走原有的代码生成和Mock服务流程。3. 实操落地用Spec-kit从零驱动一个用户服务3.1 初始化项目与目录约定先准备环境。假设团队用的是Node.js生态我这边用的版本是Node 20 LTS通过npm安装Spec-kitnpm install -g spec-kit装完后创建一个项目目录并初始化规范仓库mkdir spec-demo cd spec-demo spec-kit init --template minimalinit命令会生成一个推荐的目录结构。我的习惯是把规范、模板、产出物分开spec-demo/ ├── specs/ │ └── user.yaml ├── templates/ │ └── go_gin/ │ ├── model.gotmpl │ ├── controller.gotmpl │ └── dto.gotmpl ├── generated/ │ ├── api/ │ ├── model/ │ └── docs/ ├── spec-kit.config.yml └── package.jsonspecs目录放规格文件是团队评审的核心对象templates目录放自定义模板generated目录是生成产物不要手动改这是血泪教训。手动改了再生成diff会非常痛苦而且容易把业务修复覆盖掉。生成的代码应该被视为编译产物而不是源码。3.2 编写用户模块的完整规范上面已经给了一部分YAML片段这里我再补全它让它可以被Spec-kit实际跑到生成阶段spec: module: user version: 1.0.0 entities: - name: User description: 系统用户 fields: - name: id type: uuid required: true immutable: true - name: nickname type: string required: true minLength: 2 maxLength: 32 - name: email type: string format: email required: true unique: true - name: status type: enum values: [active, disabled, deleted] default: active indexes: - name: idx_user_email fields: [email] unique: true behaviors: - name: createUser http: method: POST path: /api/v1/users input: - nickname - email output: - id - nickname - email - status errors: - emailExists - invalidEmail - name: getUserById http: method: GET path: /api/v1/users/{id} input: - id output: - id - nickname - email - status这里我想重点展开几个容易被忽略的细节第一个是immutable: true。id字段创建后不允许修改。如果让代码生成器感知这个约束生成的update方法就不会包含这个字段避免了数据被意外覆盖。这个约束如果放在自然语言文档里开发很容易漏掉但放到规范里生成器就能强制执行。第二个是unique: true和索引定义同时出现。我在这两个地方都写了unique看起来冗余但含义不同字段级unique是业务约束索引是物理实现。Spec-kit会校验它们是否一致——如果规范里字段声明unique但没有对应的唯一索引定义会给出警告。这个设计是为了兼顾DDD式思维和数据库工程实际。第三个是errors列表。我在behaviors里显式声明了这个行为可能抛出的错误。生成器会据此生成错误码枚举前端也可以直接引用。以前这些错误码散落在后端代码和前端常量里对齐全靠开会现在只需要加一行。写完之后跑一下校验spec-kit validate specs/user.yaml如果一切正常输出大概是✔ parsed 1 spec file(s) ✔ validated 1 entity(ies), 2 behavior(s) ✔ no issues found有了这个输出就可以进入生成阶段了。3.3 生成接口层与数据层代码接下来用内置模板生成文档和代码spec-kit generate --specs specs/user.yaml --out generated这会在generated目录下生成多组文件。我挑几个典型的看。生成的OpenAPI文档片段openapi: 3.0.1 info: title: user version: 1.0.0 paths: /api/v1/users: post: operationId: createUser requestBody: required: true content: application/json: schema: type: object properties: nickname: type: string maxLength: 32 email: type: string format: email responses: 200: description: success content: application/json: schema: type: object properties: id: type: string format: uuid nickname: type: string email: type: string status: type: string enum: [active, disabled, deleted]生成的数据库DDL片段CREATE TABLE users ( id UUID PRIMARY KEY, nickname VARCHAR(32) NOT NULL, email VARCHAR(255) NOT NULL, status VARCHAR(16) NOT NULL DEFAULT active, CONSTRAINT uk_user_email UNIQUE (email) ); CREATE INDEX idx_user_email ON users(email);这里有个细节email我声明了format: email但没有写maxLength生成器在选择VARCHAR长度时按255处理。这个默认值来自模板引擎不是Spec-kit硬编码。所以如果你的团队要求email字段更短需要在模板或者规范里显式设置。这也是之前说的——模板决定了生成产物的细节风格。如果使用自定义模板还可以生成服务端的DTO和路由注册代码。以Go Gin模板为例生成后的handler骨架大概是func CreateUser(c *gin.Context) { var req CreateUserRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } // TODO: implement business logic c.JSON(200, UserDTO{}) }生成的代码不会是完整的业务实现重点是DTO结构、请求校验和路由注解都已经对齐了规范。业务逻辑留白正好也避免了一个常见误区——不要期待工具能替你写业务它负责的是把规范固定下来让你写业务时不用分心处理接口细节。3.4 把规范校验接入CI流水线日常开发中规范与代码最容易出现漂移。要防止这个问题我强烈建议把spec校验和生成差异检查接入CI。我在GitHub Actions里加了一个简单的工作流name: spec-check on: pull_request: paths: - specs/** - templates/** jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g spec-kit - run: spec-kit validate specs/*.yaml - run: spec-kit generate --specs specs/user.yaml --out generated --check--check参数很关键它会让生成器把生成结果和当前仓库里的generated目录对比不一致就返回非零退出码。这样开发者改了规范但没有重新生成代码CI就会拦下这个PR。同时我还会在PR模板里加一个问题“本次改动是否由规范文件驱动”这听着像行政规定但实际作用是不断提醒团队代码变更的源头应该体现在spec文件里而不是悄无声息地散落在handler和mapper中。4. 常见问题与排查技巧实录4.1 五个高频问题的排查速查表在使用Spec-kit的过程中我和团队陆续遇到过不少问题。这里整理一个速查表方便你对照排障问题现象可能原因排查思路解析报“未知字段”YAML里拼写错误或用了没注册的属性检查字段名在规范中增加自定义属性需要先扩展schema校验报“字段未在实体中定义”behavior的input引用了一个不存在的字段核对input字段名与entities里的定义注意大小写生成的DDL里唯一索引缺失只有字段级unique没定义indexes补上indexes定义并保持两边一致生成的OpenAPI里没有错误码behavior的errors列表为空在behaviors里显式列出业务错误重新生成后大量diff有人手动改过generated目录删除generated目录重新生成或引入CI检查机制这里面我最想强调的是最后一个问题。手动改生成代码的诱惑非常大因为改起来非常快几秒钟就解决问题。但代价是后续每次生成都要处理冲突最终可能整个generated目录退化成手工代码规范又成了摆设。与其这样不如建立一个明确的约定generated是构建产物一切改动回到spec和模板里做。4.2 其它常见问题与处理建议除了上面的表格我再补充几个实际工作中容易碰到的细节问题。闭包结构嵌套导致模板取值困难。Spec-kit的模板引擎支持点号路径取值但嵌套实体和枚举组合在一起时模板会变得很难读。我的建议是模板里只做基础映射复杂的派生逻辑比如字段级默认值来自另一个字段的枚举放在生成器的预处理函数里模板保持干净。模板一旦复杂到需要写大量逻辑维护成本会直线上升。多人并行修改同一份spec文件。这个和普通代码冲突一样但spec的语义冲突更难发现。比如两个分支都加了同一个字段但类型不同文erge时代码能并规范却出现了二义性。我碰到的处理方式是在CI里加一个spec-kit merge-check命令专门扫描合并后是否存在同名实体属性冲突。这个命令不解决所有问题但能挡住最明显的那类重复定义。空值的处理逻辑要提前约定。规范里type是string但没有required——那么生成代码时是输出pointer类型还是string类型不同团队的偏好不同。Spec-kit默认生成的是可区分空值的指针类型比如Go的*string但如果你是Java团队可能更想用Optional。这种平台相关的细节一定要早早在模板里固化不然每个人生成的代码风格都不一样。4.3 我在实际使用中的几点心得最后分享几个纯经验层面的内容。第一规范文件别追求大而全。刚开始用Spec-kit时我恨不得把所有业务规则全部塞进YAML里结果规范写得比代码还长评审没人愿意看。后来我给自己定了一个简单标准凡是影响接口契约、数据结构、约束规则的内容进规范凡是纯业务编排逻辑留在代码里。这个界限划清楚后spec文件才真正变成一个可维护的产品。第二规范的版本要跟随模块而非项目。规范文件里有一个version字段我建议把它和模块的API版本绑定而不是和整个项目的发布版本绑定。这样用户服务的v1和订单服务的v1互不干扰演化时各自升级清晰得多。第三一定一定把spec文件纳入code review范围。很多团队重视代码评审却忽略了规范评审。其实规范的评审价值比代码更高——因为它影响面更大一次错误的字段定义会导致生成的所有代码都错。每份spec变更都应当被仔细review就像review核心库代码一样。结尾关于Spec-kit继续扩展的几个方向我自己目前用得最多的是接口和数据层的生成场景但Spec-kit的模板机制让它还有不少扩展空间。比如Event定义生成在消息驱动架构里事件主题、payload格式、消费组名都可以放在规范里描述向后端生成发布者向前端生成消息类型定义。又比如状态机定义把状态迁移的合法路径写进YAML然后生成校验代码能有效防止非法状态跳跃。再比如契约测试的seed数据规范里的字段定义可以直接作为测试数据生成的依据。这些方向不一定是Spec-kit现在的官方能力但工具既然提供了“规范→中间模型→多模版生成”的核心链路后面就能持续演化。我个人体会是真正让Spec-kit起作用的关键不是工具本身多强大而是团队愿意把“写规范”当作开发的一部分而不是开发完再补的文档。把一个聪明的工具放到一个不认规范的流程里它的价值发挥不出来反过来哪怕工具朴素一点只要团队认认真真维护规范文件产出的代码质量和协作效率都会有明显提升。
