🚀 OpenSpec 基础教程🚀 OpenSpec 基础教程 📖 一、为什么需要 OpenSpec？ ⚠️ 传统

🚀 OpenSpec 基础教程

OpenSpec 是 Fission-AI **开源的规范驱动开发（Spec-Driven Development, SDD）**工具，专为 AI 辅助编程设计。

本教程面向 Vue3 + Spring Cloud 技术栈，覆盖新项目启动 (Greenfield) 和 老项目改造 (Brownfield) 两种核心场景，旨在解决微服务架构下 AI 编程的“黑盒”难题。

📖 一、为什么需要 OpenSpec？

⚠️ 传统 AI 编程在微服务中的痛点

微服务的复杂性让“氛围编程”（Vibe Coding）极易翻车：

🚫 服务边界模糊：AI 不知道接口归属，常在错误的 Service 中生成代码。
🚫 约定丢失：接口字段、状态码、错误格式仅存在于某次对话上下文，无法持久化。
🚫 跨服务影响不可见：修改 user-service 返回结构，AI 往往忽略 order-service 的 Feign 客户端同步更新。
🚫 网关配置遗漏：新增微服务后，AI 经常忘记更新 Gateway 的路由转发规则。

💡 OpenSpec 的解法：规范先行

在每次编码变更前，强制生成一套可执行的规范文件，遵循以下闭环：

tongyi-mermaid-2026-02-26-204440

提案 Proposal->评审 Review->实现 Apply->归档 Archive

核心理念：规范文件中明确记录涉及哪些微服务、接口契约细节、前端组件变更点及 Feign 同步策略。让 AI 照着规范干活，而不是凭猜测。

🛠️ 二、快速安装

1. 前提条件

Node.js: v20.19.0 或更高版本（OpenSpec CLI 基于 Node 构建，与后端 Java 环境无关）。

node --version

2. 安装 CLI

推荐使用 npm 或 pnpm 全局安装：

# 1. 设置淘宝镜像为默认源
npm config set registry https://registry.npmmirror.com
# 2. 验证配置是否生效
npm config get registry
# 3. 使用 npm
npm install -g @fission-ai/openspec@latest

# 4. 或使用 pnpm
pnpm add -g @fission-ai/openspec@latest

3. 验证安装

openspec --version

🧠 三、核心概念

3.1 Specs（规范）—— 项目的“活文档”

按微服务和前端模块组织，存放在 openspec/specs/ 目录，是 AI 的唯一真理源。

openspec/specs/
├── gateway/
│   └── spec.md          # 路由规则、跨域配置、鉴权过滤器逻辑
├── user-service/
│   └── spec.md          # 接口契约、数据库表结构、Feign 定义
├── order-service/
│   └── spec.md          # 业务状态机、接口列表
└── frontend/
    ├── spec.md          # 模块划分、路由结构、全局状态约定
    └── components/
        └── spec.md      # 核心组件复用规范

3.2 Changes（变更）—— 独立工作空间

每次任务生成的独立沙箱，位于 openspec/changes/：

openspec/changes/add-order-payment/
├── proposal.md      # 做什么：需求描述
├── design.md        # 怎么做：架构设计、依赖分析
├── tasks.md         # 执行清单：按服务/前端拆解的具体步骤
└── specs/           # 本次变更产生的规范增量 (Delta)

3.3 AGENTS.md —— 给 AI 的项目说明书

初始化时自动生成，用于告知 AI 项目的宏观架构：

微服务列表及其职责边界
通信协议（OpenFeign / RestTemplate）
前端技术栈细节（Vue3 + Pinia + Router）
基础设施（Nacos, MySQL, Redis 等）

🔄 四、工作流路径选择

根据任务复杂度选择合适的工作流：

路径类型	命令序列	适用场景
⚡ 快速路径	`/opsx:propose` → `/opsx:apply` → `/opsx:archive`	单服务改动、小功能迭代、Bug 修复
🛡️ 完整路径	`/opsx:new` → `/opsx:ff` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`	跨服务改动、新增微服务、核心重构

💡 重要提示：涉及多个微服务的改动，必须使用完整路径。design.md 会显式列出服务间依赖，verify 阶段会自动检查各服务改动的一致性。

🌱 五、场景一：新项目启动 (Greenfield)

5.1 标准项目结构

典型的 Vue3 + Spring Cloud Monorepo 布局：

my-platform/
├── gateway/                  # Spring Cloud Gateway
├── common/                   # 公共模块 (DTO, Utils, Feign Interfaces)
├── user-service/             # 用户微服务
├── order-service/            # 订单微服务
├── frontend/                 # Vue3 前端 (Vite)
│   ├── src/
│   │   ├── api/              # Axios 封装
│   │   ├── stores/           # Pinia 状态管理
│   │   ├── views/            # 页面视图
│   │   └── components/       # 通用组件
│   └── ...
├── docker-compose.yml
└── pom.xml                   # 父工程

5.2 初始化 OpenSpec

建议在 Monorepo 根目录 初始化，以便统一管理所有服务规范：

cd my-platform
openspec init

初始化后将生成 openspec/ 目录及根目录下的 AGENTS.md。

5.3 完善 AGENTS.md (关键步骤)

初始化后，请务必花费 5 分钟补充 AGENTS.md 中的架构信息，这直接决定 AI 生成代码的质量：

# 项目架构说明

## 技术栈
- **后端**: Spring Boot 3.x + Spring Cloud 2023.x + MyBatis-Plus
- **注册中心**: Nacos
- **网关**: Spring Cloud Gateway
- **通信**: OpenFeign
- **数据库**: MySQL 8.0 (库隔离)
- **前端**: Vue3 + TS + Vite + Pinia + Element Plus

## 微服务清单
- `gateway` (8080): 统一入口，JWT 鉴权
- `user-service` (8081): 用户认证、权限
- `order-service` (8082): 订单核心业务

## 开发约定
- **响应格式**: `{ code, message, data }`
- **路径前缀**: `/api/{service-name}/v1/`
- **前端风格**: Composition API (`<script setup>`) + TypeScript

5.4 实战：实现用户注册登录

Step 1: 提案 (Propose)

输入指令：

/opsx:propose 实现用户注册和登录功能：
1. user-service 提供注册/登录接口 (JWT)
2. gateway 配置路由及 JWT 过滤器
3. Vue3 前端实现登录/注册页，Token 存入 Pinia

Step 2: 评审任务清单 (Review Tasks)

AI 生成的 tasks.md 将自动拆分任务，请仔细核对：

## ✅ user-service Tasks
- [ ] 创建 `users` 表 (id, username, password_hash, ...)
- [ ] 实现 `POST /api/user/v1/auth/register`
- [ ] 实现 `POST /api/user/v1/auth/login` (返回 JWT)
- [ ] 密码 BCrypt 加密 & JSR-303 参数校验

## ✅ gateway Tasks
- [ ] 配置路由: `/api/user/**` -> `lb://user-service`
- [ ] 实现 JWT 全局过滤器 (放行 /login, /register)

## ✅ frontend Tasks (Vue3)
- [ ] 新增路由 `/login`, `/register`
- [ ] 创建 `useAuthStore` (Pinia) 管理 Token
- [ ] 实现 LoginView/RegisterView (Element Plus)
- [ ] Axios 拦截器：自动注入 Header & 401 跳转

Step 3: 执行与归档

确认无误后执行：

/opsx:apply
# 测试通过后
/opsx:archive

🏗️ 六、场景二：老项目接入 (Brownfield)

针对已运行 1-2 年、缺乏文档的存量 Spring Cloud 项目。

6.1 无侵入初始化

cd my-platform
openspec init

仅新增 openspec/ 和 AGENTS.md，不触碰现有代码。

6.2 策略选择

🅰️ 方案 A：按需建档 (推荐大型项目)

不要试图一次性文档化所有服务。改哪里，建哪里。

/opsx:propose 我需要给订单服务新增退款功能。
请先扫描 order-service 现有代码，梳理状态机和接口，
生成 specs/order-service/spec.md，暂不写代码。

建议优先级：核心业务服务 > 网关/Common > 基础设施

🅱️ 方案 B：快速全量建档 (适合中小型项目)

/opsx:new 扫描以下模块并生成规范文档（不写代码）：
- gateway: 路由与鉴权
- user-service: 用户接口与表结构
- order-service: 订单状态机
- frontend/src: 路由与 Store 结构

6.3 实战：跨服务新增“商品收藏”功能

涉及新建 favor-service 并联动现有系统。

指令示例：

/opsx:new 新增商品收藏微服务 favor-service：
1. 新建 Spring Boot 模块并注册 Nacos
2. 提供收藏/取消/查询接口
3. Gateway 新增路由
4. order-service 通过 Feign 调用获取收藏状态
5. Vue3 商品详情页增加收藏按钮

生成的 design.md 亮点：

服务依赖图：清晰标注 favor-service 被谁调用。
Feign 契约：自动定义 FavorFeignClient 接口。
全量 Task 列表：涵盖从 DB 建表到前端 UI 的所有步骤，杜绝遗漏。

🎨 七、Vue3 前端专项场景

7.1 模块化开发 (路由 + 状态 + API)

利用 OpenSpec 确保新模块符合项目规范：

/opsx:propose 新增用户个人中心模块：
- 功能：基本信息、修改密码、地址管理
- 规范：Element Plus 组件，Composition API，Pinia 状态管理

AI 将自动生成包含路由配置、Store 定义、API 封装及 View 组件的完整 Task 列表。

7.2 遗留代码重构

针对 Vue2 Options API 迁移：

/opsx:propose 将 src/views/order/ 下页面迁移至 Vue3 Composition API：
- 提取公共逻辑至 src/composables/useOrder.ts
- 状态迁移至 Pinia，移除 Vuex 依赖
- 保持模板与样式不变

7.3 固化 Axios 规范

在 specs/frontend/spec.md 中明确约定，防止 AI 生成风格不一致的代码：

## API 调用约定
- **位置**: 所有调用必须在 `src/api/` 目录下，禁止组件内直连 axios。
- **统一处理**: `src/utils/request.ts` 处理拦截器。
- **错误处理**: `code !== 200` 时统一 `ElMessage.error`；`401` 自动登出。

☁️ 八、Spring Cloud 后端专项场景

8.1 新增微服务 Checklist

/opsx:new 新建消息通知微服务 notify-service：
- 支持站内信/邮件/短信
- 提供 Feign 接口供内部调用
- 异步消费 RocketMQ
- 仅对内暴露，Gateway 不配置公网路由

8.2 高风险：接口变更影响面分析

修改接口时，必须使用完整路径以触发影响面分析：

/opsx:new 修改 user-service 的用户详情接口，新增 roles 字段。
注意：order-service 和 frontend 均依赖此接口，需同步更新。

AI 生成的 Impact Analysis：

User Service: Controller, Service, VO 更新。
Common Module: 共享 DTO 更新。
Order Service: Feign Client 及调用处检查。
Frontend: TypeScript 类型定义及页面展示更新。

8.3 数据库迁移规范

/opsx:propose 为 orders 表新增 cancel_reason 字段：
- 使用 Flyway 管理，命名规范 V{Version}_{Desc}.sql
- 同步更新 Entity 和 VO

🤝 九、多服务协作最佳实践

9.1 Feign 双向检查机制

在 tasks.md 中显式列出 Feign 消费者，防止“改了提供者，忘了消费者”。

Example: UserFeignClient 被 order-service 和 notify-service 使用，变更时需同步检查这两处。

9.2 接口契约先行 (Contract First)

前后端并行开发时，先在 specs/ 中固化 JSON 结构。

前端基于 Spec 进行 Mock 开发。
后端基于 Spec 进行实现。
减少联调时的字段扯皮。

9.3 全局错误码字典

在 specs/common/spec.md 维护统一错误码表，避免各服务自定义冲突：

Code	含义	处理策略
401	未登录	前端跳转登录
403	无权限	前端提示无权
20001	订单不存在	业务级错误

📟 十、常用 CLI 命令速查

# 初始化
openspec init

# 查看进行中的变更
openspec list

# 查看变更详情
openspec show <change-name>

# 校验规范格式
openspec validate <change-name>

# 交互式仪表盘
openspec view

# 切换配置模式 (推荐跨服务时使用)
openspec config profile

Slash Commands (对话指令)

命令	说明	推荐场景
`/opsx:propose`	快速提案	单服务小功能
`/opsx:new`	完整任务启动 (含影响分析)	跨服务变更、新增服务
`/opsx:apply`	执行代码生成	评审通过后
`/opsx:verify`	验证实现与规范一致性	跨服务变更后必用
`/opsx:sync`	同步规范与代码现状	修复规范漂移
`/opsx:archive`	归档并更新 Specs	功能完成
`/opsx:onboard`	生成新人入职上下文	团队成员变动

🚧 十一、避坑指南 (FAQ)

❌ 问题 1：AI 改了接口，忘了更新 Feign Client

现象: 编译报错或运行时 500。
对策:
1. 提案时显式声明：“注意 order-service 也调用了此接口”。
2. 在 spec.md 中维护 Feign 消费者列表。
3. 执行后务必运行 /opsx:verify。

❌ 问题 2：Vue3 代码风格混乱 (Options vs Composition)

现象: 新生成组件使用了 data() 而非 <script setup>。
对策: 在 AGENTS.md 和 specs/frontend/spec.md 中强制约束：“禁止使用 Options API，必须使用 Composition API + TS”。

❌ 问题 3：Gateway 路由遗漏

现象: 服务启动了，但外部访问 404。
对策: 将“更新 Gateway 路由”列为 tasks.md 的必检项。在 AGENTS.md 中强调 Gateway 的依赖规则。

❌ 问题 4：规范与代码漂移

现象: 几个月后，Spec 里的接口列表与实际代码不符。
对策:
1. 定期运行 /opsx:sync 扫描差异。
2. 团队红线: 涉及接口变更的 PR，必须同步提交 spec.md 的更新。

❌ 问题 5：新服务忘记配置 Nacos

现象: 服务启动后未在注册中心发现。
对策: 在 AGENTS.md 中内置 New Service Checklist (pom 依赖, bootstrap.yml, @EnableDiscoveryClient 等)。

❌ 问题 6：前后端类型不同步

现象: 后端改名，前端 TS 类型未变，导致 undefined。
对策: 在 spec.md 中同时维护 Java DTO 和 TS Interface 对照表，变更时同步更新。

❌ 问题 7：MVP 阶段觉得流程繁琐

建议:
- 微服务 ≤ 2: 可暂时跳过复杂流程，快速迭代。
- 微服务 ≥ 3: 立即引入。此时隐性依赖复杂度呈指数上升，OpenSpec 的收益远超成本。

🧠 十二、模型选择建议

为了获得最佳效果，建议根据阶段切换 AI 模型：

🏗️ 规划阶段 (propose / new): 需要强推理能力，分析跨服务依赖。
- 推荐: Claude Opus 4.6, o3
💻 实现阶段 (apply): 需要高精度代码生成。
- 推荐: Claude Sonnet 4.6, GPT-4o

在 Claude Code 中临时切换示例:

claude --model claude-opus-4-6

📝 总结

场景	推荐路径	核心价值
新项目 / 小功能	`init` → `propose` → `apply`	快速启动，规范落地
跨服务复杂功能	`new` → `verify` → `archive`	显性化隐性依赖，防止漏改
老项目改造	`init` → 按需建档 → `new`	渐进式重构，降低风险
Sprint 结束	`bulk-archive`	保持文档鲜活

核心原则：Spring Cloud 的难点在于服务间的隐性依赖（Feign、Gateway、共享 DTO）。OpenSpec 的最大价值就是将这些依赖转化为显性的、可审查的规范文件，让 AI 在写第一行代码前，就已经看清了全局影响面。

🔗 参考资源