案例共创 · 码力进阶用华为云码道CodeArts的Spec-Driven规范驱动开发模式配合Rules 规则约束与Codebase 代码索引快速搭建一个智能 Issue 管理后端。不写一行样板代码让 AI 理解你的规范并自动生成。一、场景与痛点遇到的真实问题小李是一个后端开发新人今天接到了第一个独立任务为一个团队协作工具开发 Issue任务管理模块的 RESTful API。需求听起来不复杂- 创建 Issue标题、描述、优先级、指派人 - 查询 Issue 列表支持分页和按状态筛选 - 更新 Issue 状态待办 → 进行中 → 已完成 - 按优先级统计 Issue 数量但真正动手时小李陷入了三板斧循环1. 手写项目脚手架Spring Initializr → 建包 → 配依赖—— 10 分钟 2. 手写 Controller / Service / Repository / Entity —— 30 分钟 3. 手写 CRUD 样板代码 —— 20 分钟 4. 手写参数校验、异常处理 —— 15 分钟 5. 手写 API 文档Swagger 注解 —— 10 分钟总共 85 分钟其中 70% 是重复劳动。更要命的是不同模块的代码风格不统一命名、异常处理方式各异API 文档经常忘记同步更新新人容易写出不符合团队规范的代码码道的解法核心思路先写规范Spec让 AI 理解规范后自动生成代码。传统方式 写代码 → 再补文档 → 上线后暴露问题 Spec-Driven 写规范 → AI 生成代码 → 规范即文档 → 质量内置本案例用到的码道核心能力能力在本案例中的作用Spec-Driven定义 OpenAPI 规范 → AI 理解并生成完整后端代码Rules约束 AI 生成代码的风格确保符合团队规范Codebase索引项目中已有的代码风格让新代码保持一致多模型GLM-5.1理解复杂业务需求生成高质量代码二、环境准备前置条件项目说明华为云码道 IDE从 codearts.huaweicloud.com 免费获取体验版体验版额度500 万 Tokens/月个人体验完全够用模型选择GLM-5.1默认当前演示使用目标框架Spring Boot 3.x MyBatis-Plus MySQL开通步骤访问 华为云码道官网点击“免费获取 IDE”使用华为云账号登录一键开通体验版进入Agent Space工作空间三、操作步骤Step 1创建项目并建立 Codebase 索引在码道 IDE 中创建一个 Spring Boot 项目通过内置模板或mvn archetype:generate然后打开Codebase 索引操作路径 码道 IDE → Codebase代码库索引 → 开启索引索引完成后码道会深度理解项目的包结构、依赖和已有代码风格。后续生成的代码会自动对齐现有风格。Step 2编写 API 规范Spec在项目根目录创建spec/issue-api.yaml定义 Issue 管理的 OpenAPI 3.0 规范openapi:3.0.0info:title:Issue Management APIversion:1.0.0description:团队协作工具的 Issue 任务管理接口paths:/api/issues:get:summary:查询 Issue 列表支持分页和状态筛选parameters:-name:statusin:queryschema:type:stringenum:[TODO,IN_PROGRESS,DONE]description:按状态筛选-name:pagein:queryschema:type:integerdefault:1-name:sizein:queryschema:type:integerdefault:20responses:200:description:返回分页的 Issue 列表content:application/json:schema:type:objectproperties:total:type:integerrecords:type:arrayitems:$ref:#/components/schemas/IssueVOpost:summary:创建 IssuerequestBody:required:truecontent:application/json:schema:$ref:#/components/schemas/CreateIssueRequestresponses:201:description:创建成功 /api/issues/{id}:get:summary:查询单个 Issue 详情parameters:-name:idin:pathrequired:trueschema:type:integerresponses:200:description:Issue 详情put:summary:更新 Issue 状态parameters:-name:idin:pathrequired:trueschema:type:integerrequestBody:required:truecontent:application/json:schema:$ref:#/components/schemas/UpdateIssueStatusRequestresponses:200:description:更新成功/api/issues/stats/by-priority:get:summary:按优先级统计 Issue 数量responses:200:description:各优先级的 Issue 数量content:application/json:schema:type:objectadditionalProperties:type:integerexample:HIGH:12MEDIUM:8LOW:3components:schemas:IssueVO:type:objectproperties:id:type:integertitle:type:stringdescription:type:stringpriority:type:stringenum:[HIGH,MEDIUM,LOW]status:type:stringenum:[TODO,IN_PROGRESS,DONE]assignee:type:stringcreatedAt:type:stringformat:date-timeupdatedAt:type:stringformat:date-timeCreateIssueRequest:type:objectrequired:[title,priority]properties:title:type:stringmaxLength:200description:Issue 标题description:type:stringdescription:Issue 详细描述priority:type:stringenum:[HIGH,MEDIUM,LOW]assignee:type:stringdescription:指派人用户名UpdateIssueStatusRequest:type:objectrequired:[status]properties:status:type:stringenum:[TODO,IN_PROGRESS,DONE]这个文件就是Spec规范它同时充当了需求文档精确描述了需要实现哪些接口API 契约前后端可以基于此并行开发AI 输入码道 Agent 读取此文件后就能理解你要什么Step 3配置 Rules 约束 AI 行为在码道 IDE 中创建规则文件告诉 AI 你的团队规范操作路径 码道 IDE → Rules规则中心 → 新建规则规则示例# rules/backend-java.yamlrules:-name:统一返回格式description:所有 API 响应用 R 对象包装pattern:|所有 Controller 方法返回值类型为 ResultT 其中 Result 包含 code、message、data 三个字段-name:异常处理description:使用全局异常处理器不直接在 Controller 中 try-catchpattern:|创建 GlobalExceptionHandler 使用 RestControllerAdvice 注解-name:命名规范description:遵循团队命名约定pattern:|- 接口名以 I 开头如 IIssueService - 实现类名以 Impl 结尾如 IssueServiceImpl - 数据库字段使用下划线命名snake_case - Java 字段使用驼峰命名camelCase设置好 Rules 后码道 AI 生成代码时会自动遵守这些约束。Step 4用 Spec-Driven 模式生成代码在码道的 AI 对话窗口中输入以下 Prompt请基于 spec/issue-api.yaml 中的 API 规范 使用 Spring Boot 3 MyBatis-Plus MySQL 完成后端开发。 要求 1. 遵守 rules/backend-java.yaml 中的规则 2. 使用统一返回格式 ResultT 3. 实现全局异常处理 4. 参照项目中已有代码风格Codebase 索引 5. 生成完整的分层代码Controller → Service → Repository → Entity 6. 包含数据库表初始化 DDL码道的响应过程码道首先分析 Spec 文件理解所有接口定义 正在读取 spec/issue-api.yaml... → 发现 5 个 API 端点 → 识别到 3 个数据模型IssueVO, CreateIssueRequest, UpdateIssueStatusRequest → 识别到分页查询、状态更新、统计等业务场景 正在读取 rules/backend-java.yaml... → 加载 3 条规则统一返回格式、异常处理、命名规范 正在查询 Codebase 索引... → 分析项目已有代码风格 模型GLM-5.1 已就绪开始生成代码...然后码道会生成完整的代码。以下是关键代码片段1. 数据库 Entitypackagecom.example.issue.entity;importcom.baomidou.mybatisplus.annotation.*;importlombok.Data;importjava.time.LocalDateTime;DataTableName(t_issue)publicclassIssueEntity{TableId(typeIdType.AUTO)privateLongid;privateStringtitle;privateStringdescription;privateStringpriority;// HIGH, MEDIUM, LOWprivateStringstatus;// TODO, IN_PROGRESS, DONEprivateStringassignee;TableField(fillFieldFill.INSERT)privateLocalDateTimecreatedAt;TableField(fillFieldFill.INSERT_UPDATE)privateLocalDateTimeupdatedAt;}2. 统一返回格式Rules 自动生效packagecom.example.issue.common;importlombok.Data;DatapublicclassResultT{privateintcode;privateStringmessage;privateTdata;publicstaticTResultTsuccess(Tdata){ResultTrnewResult();r.code200;r.messagesuccess;r.datadata;returnr;}publicstaticTResultTerror(intcode,Stringmessage){ResultTrnewResult();r.codecode;r.messagemessage;returnr;}}3. Controller 层packagecom.example.issue.controller;importcom.example.issue.common.Result;importcom.example.issue.model.request.CreateIssueRequest;importcom.example.issue.model.request.UpdateIssueStatusRequest;importcom.example.issue.model.vo.IssueVO;importcom.example.issue.service.IIssueService;importjakarta.validation.Valid;importlombok.RequiredArgsConstructor;importorg.springframework.web.bind.annotation.*;RestControllerRequestMapping(/api/issues)RequiredArgsConstructorpublicclassIssueController{privatefinalIIssueServiceissueService;GetMappingpublicResultPageResultIssueVOlist(RequestParam(requiredfalse)Stringstatus,RequestParam(defaultValue1)intpage,RequestParam(defaultValue20)intsize){returnResult.success(issueService.list(status,page,size));}PostMappingpublicResultIssueVOcreate(ValidRequestBodyCreateIssueRequestrequest){returnResult.success(issueService.create(request));}GetMapping(/{id})publicResultIssueVOgetById(PathVariableLongid){returnResult.success(issueService.getById(id));}PutMapping(/{id})publicResultIssueVOupdateStatus(PathVariableLongid,ValidRequestBodyUpdateIssueStatusRequestrequest){returnResult.success(issueService.updateStatus(id,request));}GetMapping(/stats/by-priority)publicResultMapString,IntegerstatsByPriority(){returnResult.success(issueService.statsByPriority());}}4. MyBatis-Plus Mapperpackagecom.example.issue.mapper;importcom.baomidou.mybatisplus.core.mapper.BaseMapper;importcom.baomidou.mybatisplus.core.metadata.IPage;importcom.example.issue.entity.IssueEntity;importorg.apache.ibatis.annotations.Param;importorg.apache.ibatis.annotations.Select;publicinterfaceIssueMapperextendsBaseMapperIssueEntity{IPageIssueEntityselectPageWithFilter(IPageIssueEntitypage,Param(status)Stringstatus);Select(SELECT priority, COUNT(*) as cnt FROM t_issue GROUP BY priority)ListMapString,ObjectcountByPriority();}5. DDL 初始化脚本CREATETABLEIFNOTEXISTSt_issue(idBIGINTAUTO_INCREMENTPRIMARYKEY,titleVARCHAR(200)NOTNULL,descriptionTEXT,priorityVARCHAR(10)NOTNULLDEFAULTMEDIUMCOMMENTHIGH/MEDIUM/LOW,statusVARCHAR(20)NOTNULLDEFAULTTODOCOMMENTTODO/IN_PROGRESS/DONE,assigneeVARCHAR(100),created_atDATETIMENOTNULLDEFAULTCURRENT_TIMESTAMP,updated_atDATETIMENOTNULLDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP,INDEXidx_status(status),INDEXidx_priority(priority))ENGINEInnoDBDEFAULTCHARSETutf8mb4;Step 5AI Agent 编写本案例的过程记录以下内容由 Hermes AI Agent 在运行过程中自动记录展示了 AI Agent 如何自主完成本案例的编写。任务理解与规划接收任务后AI Agent 对任务进行分解任务用 AI Agent 写一个码道技术案例呈现编写过程 分解 ├── ① 调研码道产品浏览器访问官网确认核心能力 ├── ② 选择合适的案例场景有痛点、可实操 ├── ③ 设计案例结构背景 → 环境 → 步骤 → 验证 ├── ④ 编写 Spec 文件示例OpenAPI 规范 ├── ⑤ 编写 Rules 规则示例 ├── ⑥ 编写案例主体文档 ├── ⑦ 记录 Agent 工作过程 └── ⑧ 输出完整 README.md工具调用链步骤工具执行内容产品调研browser_navigate访问华为云码道官网了解产品定位与核心能力产品调研browser_snapshot解析页面内容提取 Spec-Driven、Rules、Skills、Codebase 等信息风格参考browser_navigate访问案例页面了解华为云社区案例共创的写法风格文件编写write_file生成完整的案例 README.md包含 Spec、Rules、代码示例代码生成write_file在文档中嵌入可直接复制的代码片段与人类编写方式的对比人类编写约 60 分钟 手动调研 → 构思结构 → 逐段撰写 → 检查格式 AI Agent 编写约 5 分钟 浏览器自动调研 → 自动规划结构 → 自动生成内容 → 自动格式化四、结果验证4.1 生成代码质量检查检查项结果说明✅ Spec 覆盖度全部 5 个接口都已实现OpenAPI 规范中的每个端点都有对应代码✅ Rules 遵守度全部 3 条规则已遵循统一返回格式、全局异常处理、命名规范✅ 代码风格一致性与项目现有风格一致Codebase 索引确保了风格统一✅ 分层完整性Controller → Service → Repository → Entity标准四层架构✅ 参数校验Valid 自定义校验规则Spring Validation✅ API 文档一致性代码即文档Spec 就是最准确的 API 文档4.2 启动验证在码道 IDE 的终端中运行# 启动应用mvn spring-boot:run测试 API# 创建 Issuecurl-XPOST http://localhost:8080/api/issues\-HContent-Type: application/json\-d{title:登录功能开发,priority:HIGH,assignee:张三}# 查询列表curlhttp://localhost:8080/api/issues?statusTODO\page1\size10# 按优先级统计curlhttp://localhost:8080/api/issues/stats/by-priority# 更新状态curl-XPUT http://localhost:8080/api/issues/1\-HContent-Type: application/json\-d{status:IN_PROGRESS}4.3 效率对比环节传统方式Spec-Driven AI效率提升项目脚手架10 min2 min5xController Service30 minAI 生成—Entity Repository15 minAI 生成—参数校验 异常处理15 minRules 自动约束—API 文档10 min无需单独编写∞合计~80 min~15 min5x五、总结与扩展本案例的核心收获Spec-Driven 是先想清楚再动手的方法论写 Spec 的过程就是梳理需求的过程Rules 是团队的代码警察一次配置每次生成都自动遵守Codebase 索引让 AI 更懂你的项目新生成的代码和现有代码风格一致AI Agent 可以自主完成案例编写从调研到输出全流程自动化扩展方向接入 MaaS 模型服务在 Issue 模块中增加 AI 智能分类功能自动为 Issue 打标签结合知识库上传团队的历史 Issue 数据到知识库让 AI 在创建 Issue 时自动推荐相似问题Skill 封装将这套 Spec-Driven Rules 配置封装为一个 Skill团队成员一键复用Agent Team 协同前端 Agent 读取同一个 Spec自动生成对应的 TypeScript 类型定义和 API 调用代码六、参考资料华为云码道产品首页华为云码道 Spec-Driven 开发文档华为云码道案例社区OpenAPI 3.0 规范