本文介绍在安装和初始化 OpenSpec 后的使用方法。

本文将通过一个完整的实战示例，演示如何使用 OpenSpec 规范驱动开发框架，配合 GitHub Copilot，从零开始创建一个基于 Spring Boot、MySQL、MyBatis、JDK 21 的后端 API 接口——用户管理模块（包含增删改查功能）。

一、OpenSpec 工作流：创建用户 API

阶段一：创建变更提案

前面已经完成了。

阶段二：实施开发

提案确认无误后，在 Copilot Chat 中输入：

/opsx-apply add-user-management-api

apply 过程中，会生成大量的代码，如下所示：

最后，会显示实现的任务，新增和更新的管家文件等等。

二、了解opsx:apply 过程

/opsx:apply add-user-management-api 这次主要完成了以下事项：

1. 变更识别与状态读取

确认使用变更 add-user-management-api。

读取 schema 与 apply 指令，识别为 spec-driven，总任务 17 个。

2. 上下文加载

按 apply 指令读取了 proposal、design、specs、tasks 四类上下文文件，作为实现依据。

3. 核心实现落地（任务 1.x-4.x）

完成数据库脚本与唯一索引：schema.sql

完成用户领域对象与请求/响应模型（含扩展字段）：

UserEntity.javaCreateUserRequest.javaUpdateUserRequest.javaPatchUserRequest.javaUserResponse.java

完成 Mapper 接口与 XML SQL（增删改查、分页、唯一冲突检查）：

UserMapper.javaUserMapper.xml

完成服务层（IUserService + UserServiceImpl）：

IUserService.javaUserServiceImpl.java

完成控制层六个 REST 端点：

UserController.java

完成统一响应、错误码、业务异常与全局异常处理：

Result.javaErrorCode.javaBusinessException.javaGlobalExceptionHandler.java

4. 工程配置调整

增加必要依赖（validation、mybatis、db 驱动、测试依赖）：pom.xml

增加 datasource 与 mybatis 配置：application.properties

增加 @MapperScan：OpenspecDemoApplication.java

补充 MyBatis 显式配置（解决 SqlSessionFactory 注入问题）：MyBatisConfig.java

5. 测试与联调（任务 5.1-5.3）

将原始 contextLoads 改为 CRUD/异常/分页契约集成测试：OpenspecDemoApplicationTests.java

处理并修复过程中出现的问题：

JDK 版本不匹配（改为 JDK 21 运行）MyBatis SqlSessionFactory 未注入（新增配置类）phone 正则转义错误（修正 DTO 校验表达式）

6. 文档与任务收尾（任务 5.4）

更新接口文档与示例：HELP.md

将 tasks 17 项全部打勾：tasks.md

7. 最终状态

openspec instructions apply --change "add-user-management-api" --json 显示：17/17 完成，state=all_done。

该变更已达到可归档状态。