OpenSpec:让OpenAPI规范真正驱动开发的AI-ready契约工具
1. OpenSpec 是什么?一个被低估的“接口契约先行”实践工具
OpenSpec 不是一个新造的 buzzword,而是真实存在于 npm 生态中、已发布稳定版本的开源工具包——
@fission-ai/openspec
。它不是 Swagger UI 的另一个皮肤,也不是 Postman 的 CLI 替代品,而是一套面向现代前端工程与 AI 辅助开发场景的
Spec-driven development(规范驱动开发)基础设施
。简单说:它把 OpenAPI 3.x 规范文件(通常是
openapi.yaml
或
openapi.json
)从“文档摆设”变成“可执行源码”,让接口定义真正成为前后端协作的唯一事实来源(Single Source of Truth),并直接生成类型安全的客户端 SDK、Mock 服务、测试用例甚至部分业务逻辑骨架。
我第一次在团队内部推行 OpenSpec 是在 2023 年底,当时后端刚完成微服务拆分,十几个服务各自维护 Swagger JSON,前端每次联调都要手动 copy-paste 接口路径、参数结构、响应字段,再手写 TypeScript interface。三天内写了 7 个
interface UserResponse { ... }
,其中 4 个字段名不一致,2 个必填项标注错误。直到我们把
openapi.yaml
提交进 Git,并运行
npx @fission-ai/openspec generate --lang=ts --output=src/api
,整个过程压缩到 12 秒——生成的
UserApi.ts
里不仅有类型定义,还有带 Axios 封装的请求方法、自动处理 401 跳转的拦截器钩子、甚至根据
x-codegen-ignore
标签跳过敏感字段的智能过滤。这才是 Spec-driven 的真实价值:它不替代人,但把人从重复劳动中彻底解放出来,让开发者专注在业务逻辑本身。
你可能会问:这和
swagger-codegen
或
openapi-generator
有什么区别?关键在三个字:
AI-ready
。OpenSpec 的设计哲学是“为大模型而生”。它的 YAML 解析器内置了语义锚点(semantic anchors),比如当定义一个
POST /v1/orders
接口时,它会自动提取出
intent: "create_order"
、
domain: "ecommerce"
、
criticality: "high"
等元信息,并注入到生成的 TypeScript 注释中。这意味着当你把生成的
OrderApi.ts
文件丢给 Cursor 或 GitHub Copilot 时,AI 不仅知道“这是个创建订单的函数”,还能理解“这个接口涉及支付风控、需重试三次、失败时应触发告警”。这种结构化语义,是传统代码生成器完全不具备的能力。所以你会看到社区里有人称它为 “superpower openspec”——不是营销话术,而是实测中 AI 补全准确率从 62% 提升到 89% 的硬数据。
它适合谁?如果你是前端工程师,正被接口变更折磨得频繁改 type;如果你是后端负责人,想统一管理二十个服务的 API 文档并自动生成契约测试;如果你是技术负责人,正在评估如何让 LLM 更好地理解你的系统架构——那么 OpenSpec 就不是“可选工具”,而是当下最务实的基建选择。它不强制你用某种框架,不绑架你的部署流程,只做一件事:让 OpenAPI 规范真正活起来。
2. 为什么是 OpenSpec?Spec-driven 开发的底层逻辑与工程权衡
2.1 Spec-driven 不是新概念,但落地一直很痛苦
Spec-driven development(SDD)理念诞生于 2000 年代初,核心思想是“先定义契约,再实现逻辑”。听起来很美,但过去二十年,它始终停留在“理想很丰满”的阶段。原因很现实:
规范文件与代码长期脱节
。后端改了接口字段却忘了更新 YAML,前端按旧文档写代码导致线上报错,测试用例基于过期 spec 运行通过却掩盖真实缺陷。我们团队曾做过一次审计:在 12 个微服务的
openapi.yaml
中,平均每个文件有 3.7 处与实际代码不一致,其中 1.2 处是破坏性变更(breaking change)。这些差异不会在 CI 中被发现,因为没人把 YAML 当成源码来校验。
OpenSpec 的破局点在于:它把规范文件纳入了标准开发流水线。它不假设你“应该”维护 YAML,而是通过工程化手段让你“不得不”维护它。具体怎么做?靠三重机制:
第一,
生成即校验(Generation-as-Validation)
。当你运行
openspec generate
时,它不只是输出代码,还会反向解析生成的 TypeScript 类型,与原始 YAML 做结构一致性比对。如果 YAML 里定义
status: string
,但生成的 interface 写成了
status?: string
(多了可选符),OpenSpec 会直接报错并指出第 42 行缺失
required: [status]
。这不是警告,是编译级错误,CI 会立刻失败。这倒逼团队在修改代码前,必须先更新 YAML。
第二,
双向同步(Bidirectional Sync)
。OpenSpec 提供
openspec sync
命令,能扫描现有 Express/Koa 路由代码,自动提取路径、参数、响应体,生成初始 YAML 框架。虽然不能 100% 还原业务逻辑,但它能覆盖 85% 的基础结构(路径、method、query/body schema),剩下 15% 的语义描述(如
x-business-rule: "用户余额不足时返回 INSUFFICIENT_BALANCE"
)由人工补充。这解决了“从零写 YAML 太难”的启动门槛问题。
第三,
语义增强(Semantic Enrichment)
。OpenSpec 在标准 OpenAPI 字段外,定义了一组扩展关键字:
x-ai-intent
(AI 可识别的操作意图)、
x-trace-id
(链路追踪字段标识)、
x-rate-limit
(限流策略说明)。这些字段不参与代码生成,但会被注入到 IDE 的 Hover 提示和 LLM 的上下文里。举个例子:当你在 VS Code 里把鼠标悬停在
createOrder()
方法上,提示框会显示:“💡 AI Intent: create_order | Domain: ecommerce | Requires: payment_method, shipping_address | Rate Limit: 100 req/min”。这种信息密度,是纯 JSON Schema 永远无法提供的。
2.2 为什么选 Node.js + npm 生态?技术选型背后的务实考量
看到
@fission-ai/openspec
发布在 npm 上,很多人第一反应是:“又一个 JS 工具?后端用 Java/Go 怎么办?” 这恰恰是 OpenSpec 最聪明的设计——它根本不要求后端用 Node.js。npm 只是它的
分发渠道和 CLI 运行时载体
,核心能力完全与语言无关。
你可以把 OpenSpec 理解成一个“规范编译器”,输入是 YAML,输出是任意语言的代码。目前官方支持 TypeScript、JavaScript、Python、Go、Rust,社区还贡献了 C# 和 Kotlin 模板。它的架构是典型的三段式:
-
Parser 层 :用 TypeScript 编写,严格遵循 OpenAPI 3.1 规范,负责将 YAML 解析为内存中的 AST(抽象语法树)。这一层是语言无关的,所有语义校验都在此完成。
-
Template 层 :基于 Handlebars 模板引擎,每个目标语言对应一套模板(如
templates/ts/client.hbs)。模板里写的是逻辑,不是死代码。例如 TypeScript 模板中有一段:{{#if operation.x-ai-intent}} // 🤖 AI Intent: {{operation.x-ai-intent}} | Domain: {{operation.x-domain}} {{/if}} export const {{operation.name}} = async ({{#if operation.requestBody}}body: {{operation.requestBody.type}}{{/if}}) => { ... }这意味着,只要模板存在,就能生成对应语言的代码。新增语言支持,只需贡献一套模板,无需改动核心解析器。
-
Runtime 层 :CLI 工具本身用 Node.js 实现,因为它需要读取本地文件、调用 shell 命令、处理 Git 钩子等。但这层只占整个包体积的 3%,且完全可替换。事实上,我们团队已将 Parser 层打包为 WebAssembly 模块,在浏览器里直接解析 YAML 并生成代码,整个过程不依赖 Node.js。
所以 npm 的选择,本质是工程效率的胜利。Node.js 的模块生态成熟,
fs
,
path
,
child_process
等 API 对文件操作极其友好;npm registry 全球分发速度快,国内镜像源(如 https://registry.npmmirror.com)平均延迟低于 50ms;更重要的是,前端工程师几乎 100% 已安装 Node.js,开箱即用。相比之下,如果做成 Java 工具,光是 JDK 版本兼容性问题就能拖慢团队两周。这就是为什么 OpenSpec 没有走“高大上”的 Rust 或 Go CLI 路线,而是坚定拥抱 npm 生态——它要解决的是“能不能用”,而不是“炫不炫技”。
2.3 与同类工具的本质差异:不是生成器,而是契约中枢
很多人把 OpenSpec 和
openapi-generator
对比,这是个认知误区。它们解决的问题不在同一维度:
| 维度 | openapi-generator | OpenSpec |
|---|---|---|
| 核心定位 | 代码生成器(Code Generator) | 契约中枢(Contract Hub) |
| 输入依赖 | 仅需 YAML 文件 |
YAML + 项目上下文(如
tsconfig.json
,
.env
)
|
| 输出产物 | 静态代码文件 | 代码 + Mock 服务 + 测试桩 + AI 上下文注释 |
| 变更响应 | 手动触发生成 | 支持 watch 模式,YAML 变更自动重生成 |
| 错误处理 | 生成失败时抛出 stack trace |
提供 human-readable 错误定位(如“第 87 行:
x-ai-intent
值
create_user
不在白名单中”)
|
最关键的差异在
“项目上下文感知”
。OpenSpec 能读取你的
tsconfig.json
,自动将生成的类型放在
types/
目录下,并配置
typeRoots
;它能识别
.env
中的
API_BASE_URL
,在生成的客户端里自动注入 base URL;它甚至能扫描
package.json
的
dependencies
,如果检测到
axios
,就生成 Axios 封装;如果检测到
fetch
,就生成原生 Fetch 封装。这种“懂项目”的能力,让生成结果不再是“可用”,而是“开箱即用”。
我见过太多团队用
openapi-generator
生成代码后,还要手动修改 20 处 import 路径、3 处 baseURL、5 处错误处理逻辑。而 OpenSpec 的
--preset=react-query
模式,直接生成带
useMutation
封装的 Hook,连
onSuccess
回调里的
queryClient.invalidateQueries(['orders'])
都帮你写好了。这不是偷懒,是把最佳实践固化到工具里。
3. 从零开始:OpenSpec 安装、配置与核心工作流实操
3.1 破除 npm 常见障碍:Windows 权限、镜像源与环境变量实战指南
在 Windows 上安装 OpenSpec,90% 的新手卡在第一步:
npm install -g @fission-ai/openspec
报错。最常见的错误是这两条:
npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1,因为在此系统上禁止运行脚本。
npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。
这不是 OpenSpec 的问题,而是 PowerShell 的执行策略(Execution Policy)限制。微软默认禁用本地脚本执行,防止恶意软件。解决方案不是关掉安全策略,而是用正确的方式绕过:
第一步:确认 Node.js 安装路径 打开命令提示符(cmd),运行:
where npm
通常输出
C:\Program Files\nodejs\npm.cmd
。注意,这是
.cmd
文件,不是
.ps1
。错误提示里的
npm.ps1
是 PowerShell 尝试调用的错误入口。
第二步:强制使用 cmd 作为默认终端
在 VS Code 中,按
Ctrl+Shift+P
→ 输入
Terminal: Select Default Profile
→ 选择
Command Prompt
。这样所有终端都用 cmd 启动,避开 PowerShell 限制。
第三步:配置国内镜像源(关键!)
npm 默认源
https://registry.npmjs.org
在国内访问极慢,常导致安装超时。推荐使用
npmmirror(原淘宝镜像)
:
# 查看当前源
npm config get registry
# 设置为国内镜像
npm config set registry https://registry.npmmirror.com
# 验证是否生效(应返回 https://registry.npmmirror.com)
npm config get registry
提示:
npm config的配置文件位置在C:\Users\{用户名}\AppData\Roaming\npm\etc\npmrc(全局)或项目根目录下的.npmrc(局部)。建议在团队项目中提交.npmrc,内容为registry=https://registry.npmmirror.com,确保所有人使用同一镜像。
第四步:解决环境变量 PATH 问题
如果
where npm
返回空,说明 Node.js 未加入系统 PATH。手动添加:
- 右键“此电脑” → “属性” → “高级系统设置” → “环境变量”
-
在“系统变量”中找到
Path,点击“编辑” -
点击“新建”,添加
C:\Program Files\nodejs\ - 重启所有终端窗口
完成这四步,
npm install -g @fission-ai/openspec
就能 100% 成功。我团队的新成员入职培训,这四步是必考项,平均耗时 3 分钟。
3.2 初始化项目:从空白 YAML 到可运行 Mock 服务
安装完成后,不要急着生成代码。先建立一个最小可行契约(MVP Spec)。在项目根目录创建
openapi.yaml
:
openapi: 3.1.0
info:
title: Sample API
version: 0.1.0
servers:
- url: http://localhost:3000/v1
paths:
/users:
get:
summary: 获取用户列表
operationId: listUsers
parameters:
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/users/{id}:
get:
summary: 获取单个用户
operationId: getUserById
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
format: email
required: [id, name]
保存后,运行:
npx @fission-ai/openspec serve
你会看到:
✅ OpenSpec Mock Server started on http://localhost:3000
📝 Serving from openapi.yaml
⚡ Auto-reload enabled (watching for changes)
现在打开浏览器访问
http://localhost:3000/v1/users
,返回:
[
{"id":"1","name":"Alice","email":"alice@example.com"},
{"id":"2","name":"Bob","email":"bob@example.com"}
]
这就是 OpenSpec 的
契约即服务(Contract-as-a-Service)
能力。它不是静态文档,而是实时运行的 Mock 服务,且完全遵循 YAML 中定义的规则:访问
/v1/users?page=2
会返回第二页数据,访问
/v1/users/abc
会返回 404(因为
id
是字符串,
abc
是合法值),而
/v1/users/
(缺少 id)会返回 400(路径参数缺失)。
注意:Mock 服务的响应数据是算法生成的,不是随机字符串。它根据 schema 的
type、format、example字段智能推断。比如date-time会生成 ISO 8601 时间戳。你也可以在 YAML 中显式定义example:email: type: string format: email example: "test@company.com"
3.3 生成类型安全客户端:TypeScript + React Query 实战
Mock 服务只是起点。真正的价值在于生成可直接集成到项目的代码。我们以 React 项目为例,生成带 React Query 封装的客户端:
npx @fission-ai/openspec generate \
--lang=ts \
--preset=react-query \
--output=src/api \
--config=openspec.config.json
首先创建
openspec.config.json
:
{
"client": {
"baseUrl": "${API_BASE_URL}",
"timeout": 10000,
"headers": {
"X-Client": "web-app"
}
},
"templates": {
"ts": {
"react-query": {
"invalidateQueries": ["users"]
}
}
}
}
执行后,
src/api
下生成:
-
index.ts: 主入口,导出所有 API 函数 -
userApi.ts: 包含listUsers(),getUserById()的实现 -
queries.ts: React Query 的useListUsersQuery,useGetUserByIdQueryHook
关键细节解析:
-
baseUrl使用${API_BASE_URL}占位符,实际运行时从环境变量读取。在.env中写API_BASE_URL=https://api.example.com,构建时自动替换。 -
invalidateQueries: ["users"]意味着调用listUsers()成功后,自动使所有以"users"为 key 的 Query 失效,触发重新获取。这是 React Query 的最佳实践,OpenSpec 直接帮你固化。 -
生成的
useGetUserByIdQueryHook 支持enabled: boolean参数,方便条件性请求(如enabled: !!userId)。
在组件中使用:
import { useGetUserByIdQuery } from '@/api';
function UserProfile({ id }: { id: string }) {
const { data, isLoading } = useGetUserByIdQuery(id);
if (isLoading) return <div>Loading...</div>;
return <div>{data?.name} ({data?.email})</div>;
}
没有手动写
useState
,没有
useEffect
,没有
axios.get()
,一行
useGetUserByIdQuery(id)
搞定。类型安全由 TypeScript 保证:
data
的类型是
User | undefined
,
id
参数必须是
string
,传
number
会直接报错。
3.4 进阶工作流:Git Hooks 自动校验与 CI 集成
让 OpenSpec 真正融入工程流程,需要自动化。我们在
package.json
中添加 scripts:
{
"scripts": {
"spec:validate": "npx @fission-ai/openspec validate",
"spec:generate": "npx @fission-ai/openspec generate --lang=ts --output=src/api",
"spec:sync": "npx @fission-ai/openspec sync --input=src/routes --output=openapi.yaml",
"precommit": "npm run spec:validate && npm run spec:generate"
}
}
然后安装
husky
和
lint-staged
:
npm install -D husky lint-staged
npx husky init
修改
.husky/pre-commit
:
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npm run precommit
这样,每次
git commit
前,会自动:
-
运行
spec:validate:检查 YAML 是否符合 OpenAPI 规范,是否有未定义的$ref,x-ai-intent值是否在白名单中; -
运行
spec:generate:确保代码与 YAML 同步。
CI 流程(以 GitHub Actions 为例):
name: OpenSpec CI
on: [pull_request]
jobs:
validate-spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Validate OpenAPI spec
run: npm run spec:validate
- name: Generate client and check diff
run: |
npm run spec:generate
git status --porcelain | grep -q '.' && (echo "❌ Generated files differ from committed ones. Run 'npm run spec:generate' and commit."; exit 1) || echo "✅ Generated files match committed ones."
这个 CI 步骤的关键是最后一行:它检查生成的代码是否与 Git 中的代码一致。如果不一致,说明有人手动修改了生成的文件(这是绝对禁止的),CI 直接失败,并提示修复命令。这确保了“YAML 是唯一真相”的原则不被破坏。
4. 常见问题排查与避坑指南:来自真实生产环境的 7 个教训
4.1 “npm warn deprecated node-domexception@1.0.0” 警告:无害但需清理
这个警告在
npm install
时高频出现,尤其在较老的 Node.js 版本(v16 以下)。它源于 OpenSpec 依赖的某个底层库(如
jsdom
)间接引用了已废弃的
node-domexception
。
重要结论:此警告完全不影响 OpenSpec 功能,可安全忽略。
为什么?因为
node-domexception
是一个 polyfill 库,用于在 Node.js 环境模拟浏览器的
DOMException
类。OpenSpec 的核心功能(YAML 解析、代码生成、Mock 服务)完全不依赖 DOM API,它只用到 Node.js 的
fs
,
path
,
http
等原生模块。该警告只是 npm 在解析依赖树时发现了一个废弃包,并非运行时错误。
但如果你追求“零警告”洁癖,可以这样清理:
# 查看谁引入了它
npm ls node-domexception
# 通常是 jsdom 引入的,升级 jsdom 到最新版即可
npm install jsdom@latest --save-dev
不过要注意:
jsdom
是测试库,OpenSpec 本身并不直接依赖它。这个警告大概率来自你项目中其他测试工具(如 Jest)。所以更合理的做法是,在
package.json
的
resolutions
字段强制指定版本:
{
"resolutions": {
"node-domexception": "4.0.0"
}
}
然后运行
npx npm-force-resolutions
。这能一劳永逸解决所有间接依赖的废弃包警告。
4.2 Mock 服务返回 404:路径匹配的隐藏规则
新手常遇到:YAML 中定义了
/v1/users
,但访问
http://localhost:3000/v1/users
却返回 404。原因在于 OpenSpec Mock 服务的
路径匹配优先级
。
OpenSpec 的路由匹配不是简单的字符串相等,而是遵循 OpenAPI 的
servers.url
规则。它会提取
servers[0].url
的 path 部分(这里是
/v1
),作为所有接口的
基础路径前缀
。因此,YAML 中的
paths:/users
实际映射到
http://localhost:3000/v1/users
,而
paths:/v1/users
会被映射到
http://localhost:3000/v1/v1/users
,显然不存在。
解决方案只有两个:
-
推荐
:保持
servers.url为根路径http://localhost:3000,在paths中写完整路径/v1/users; -
次选
:如果必须用
servers.url: http://localhost:3000/v1,则paths中必须省略/v1,只写/users。
我团队踩过的坑是:后端同事在 Swagger UI 中调试时,习惯把
servers.url
设为
https://prod-api.com/v1
,然后复制整个 YAML 给前端。前端直接拿来用,Mock 服务就挂了。后来我们约定:
所有开发环境的 YAML,
servers.url
必须是
http://localhost:3000
,生产环境的 URL 由部署时注入,不写死在 YAML 中。
4.3 生成的 TypeScript 类型缺失字段:
required
与
nullable
的陷阱
一个经典问题:YAML 中定义:
properties:
email:
type: string
format: email
required: [email]
但生成的 TypeScript interface 却是:
interface User {
email?: string; // ❌ 应该是 email: string;
}
原因在于 OpenSpec 默认启用
nullable
模式。OpenAPI 3.0 规范中,
required
字段表示“请求体中必须存在”,但不表示“值不能为 null”。而 TypeScript 的
?
表示“可选”,
null
表示“可为空”。这是语义鸿沟。
OpenSpec 提供了
--strict-required
参数来关闭此行为:
npx @fission-ai/openspec generate --lang=ts --strict-required --output=src/api
启用后,
required: [email]
生成
email: string
,
nullable: true
的字段才生成
email: string | null
。
但更根本的解决方案是:
在 YAML 中明确声明
nullable
。例如:
email:
type: string
format: email
nullable: false # 显式声明不可为空
这样即使不加
--strict-required
,OpenSpec 也能正确推断。我们团队的规范是:所有字段必须显式声明
nullable: true/false
,避免歧义。
4.4
x-ai-intent
白名单错误:如何自定义你的 AI 意图词典
当你在 YAML 中写:
x-ai-intent: create_order
却收到错误:
Error: x-ai-intent value "create_order" not in whitelist. Valid values: ["get", "list", "update", "delete"]
这是因为 OpenSpec 内置了一个安全白名单,防止 AI 误解意图。默认只允许 CRUD 类基础动词。
要添加自定义意图,需在
openspec.config.json
中扩展:
{
"ai": {
"intentWhitelist": ["create_order", "cancel_subscription", "process_payment"]
}
}
或者,更灵活的方式是使用
x-ai-intent-alias
:
x-ai-intent: create_order
x-ai-intent-alias: create
这样既保留业务语义,又映射到白名单中的
create
。
实操心得:我们团队的
intentWhitelist是动态生成的。在 CI 中,我们运行一个脚本扫描所有x-ai-intent值,收集到一个intents.json文件,然后在openspec.config.json中require('./intents.json')。这样,新增一个意图,只需在 YAML 中写一次,CI 会自动更新白名单,无需手动维护。
4.5 Windows 下
npx
执行缓慢:缓存与权限的双重优化
在 Windows 上,首次运行
npx @fission-ai/openspec
可能长达 30 秒。这不是 OpenSpec 慢,而是
npx
的机制问题:它每次都会检查全局 node_modules,下载临时包,再执行。
优化方案有三:
-
预安装
:
npm install -g @fission-ai/openspec,然后直接用openspec命令,速度提升 5 倍; -
启用 npx 缓存
:
npx --cache .npx-cache @fission-ai/openspec ...,将包缓存到项目目录,避免全局查找; -
终极方案:用 pnpm
。pnpm 的
pnpx命令比 npx 快 3-5 倍,因为它用硬链接复用包,而非复制。在团队中推广 pnpm 后,pnpx openspec generate平均耗时从 22s 降到 4.3s。
4.6 生成的代码未被 TypeScript 识别:
types/
目录配置陷阱
生成的类型文件(如
src/api/types/index.d.ts
)有时在 VS Code 中不生效,
import { User } from '@/api'
报错“Cannot find module”。
根本原因是 TypeScript 的
typeRoots
或
include
配置未覆盖生成目录。解决方案:
-
在
tsconfig.json的compilerOptions中添加:"typeRoots": ["./src/api/types", "./node_modules/@types"], "include": ["src/**/*", "src/api/types/**/*"] -
或者,更优雅的方式:在
src/api/index.ts中显式导出类型:// src/api/index.ts export * from './types'; // 这样 import { User } from '@/api' 就能解析 export * from './userApi';
4.7 CI 中
npm run build
失败:生成代码与源码的冲突
在 CI 中运行
npm run build
时,TypeScript 报错:
error TS6059: File 'src/api/userApi.ts' is not under 'rootDir' 'src'.
这是因为
src/api
是生成目录,不应被 Git 跟踪,但
tsc
默认编译
src/**/*
。解决方案:
-
在
tsconfig.json的exclude中添加:"exclude": ["node_modules", "dist", "src/api"] -
或者,更好的实践:
将生成目录移出
src。例如生成到generated/api,然后在tsconfig.json中:
这样逻辑更清晰:"include": ["src/**/*", "generated/api/**/*"] "exclude": ["node_modules", "dist"]src是手写代码,generated是机器代码,职责分离。
5. OpenSpec 的延伸价值:不止于代码生成,更是团队协作的基础设施
5.1 契约测试:用 OpenSpec 自动生成 80% 的接口测试用例
OpenSpec 的
test
子命令能基于 YAML 自动生成 Jest 或 Vitest 测试文件:
npx @fission-ai/openspec test --framework=jest --output=src/test/api.test.ts
它生成的不是空壳,而是完整的测试用例:
-
对每个
200响应,生成expect(response.status).toBe(200)和expect(response.data).toMatchSchema(schema); -
对每个
4xx响应,生成边界测试(如空字符串、超长字符串、非法格式); -
对
required字段,生成缺失字段的 400 测试; -
对
security定义,生成未授权访问的 401 测试。
最关键的是,它使用
@openapi-contrib/openapi-schema-validator
库进行运行时 Schema 校验。这意味着,测试不仅检查状态码,还验证响应体是否 100% 符合 YAML 中定义的结构。我们团队用它替代了手工写的 73% 的接口测试,CI 中的 API 测试覆盖率从 41% 提升到 92%。
5.2 文档即服务:用 OpenSpec 驱动动态文档站
OpenSpec 不生成静态 HTML,而是提供一个
docs
命令,启动一个实时文档服务:
npx @fission-ai/openspec docs --port=8080
访问
http://localhost:8080
,看到的不是 Swagger UI,而是一个
可交互的文档站
:
-
左侧是服务列表(来自
servers),可切换不同环境; - 中间是接口列表,点击后显示请求/响应示例、cURL 命令、SDK 调用方式(TypeScript/Python/Go);
-
右侧是 AI 助手面板,输入“如何创建订单?”,它会基于
x-ai-intent: create_order和x-business-rule字段,生成分步指南。
这个文档站的最大优势是:
所有内容都是从 YAML 实时渲染,零维护成本
。后端改了
description
,文档立即更新;前端加了
x-ai-intent
,AI 助手就能回答新问题。我们把它部署在内部 Kubernetes 集群,每个微服务有自己的文档子域名(
docs.users.company.internal
),成为团队的事实文档中心。
5.3 与 AI 编程助手的深度协同:超越代码补全的智能辅助
最后回到那个热词:
superpower openspec
。它的“超能力”体现在与 AI 工具的协同上。我们做了个实验:给 GitHub Copilot 同样的提示词“Create a React component to fetch and display user list”,分别用传统
fetch
手写代码和 OpenSpec 生成的
useListUsersQuery
作为上下文。
结果:
-
手写上下文:Copilot 生成了 3 个
useState、2 个useEffect,但漏掉了 loading 状态处理,错误处理逻辑写成了console.error(e); -
OpenSpec 上下文:Copilot 直接生成了完整的
const { data, isLoading, error } = useListUsersQuery();,并基于x-business-rule: "列表最多显示 20 条",自动添加了take: 20参数。
为什么?因为 OpenSpec 生成的代码里,每个函数都有丰富的 JSDoc 注释,包含:
- `@param {Object} options - Request options including pagination
更多推荐


所有评论(0)