Java 项目 Spec Coding 模板这是一个 Java 项目 Spec Coding 模板用于 AI编程适合 Spring Boot、Dubbo、微服务、单体服务、后台管理系统、任务系统等大部分 Java 项目。让AI开发时按这个模板写好 Spec 的Md 文档让 AI能够更清晰地理解需求写对代码。Spec: 功能名称1. 背景与目标背景描述当前系统/业务现状以及为什么需要做这个功能。问题当前存在什么问题、限制或机会目标目标 1目标 2目标 3非目标本次明确不做的内容非目标 1非目标 22. 需求说明使用场景描述谁在什么情况下使用该功能。用户故事作为 角色我希望 能力以便 价值。功能需求需求 1需求 2需求 3业务规则规则说明规则名称规则说明边界条件边界条件 1边界条件 23. 总体设计方案概述简要描述实现思路。涉及模块模块职责controller / api对外暴露接口service编排业务逻辑domain核心业务模型repository / mapper / dao数据访问job / listener / consumer异步或事件处理流程图接收请求参数校验执行业务逻辑读写数据返回结果4. 接口设计接口类型REST API / RPC / Dubbo / gRPC / Message Consumer / Scheduled Job接口定义ReturnType methodName(RequestDTO request);或 RESTPOST /api/resource/action请求参数字段类型必填说明idLong是主键 IDnameString否名称响应参数字段类型说明codeString响应码messageString响应信息dataObject响应数据错误码错误码场景处理方式INVALID_PARAM参数非法返回参数错误NOT_FOUND数据不存在返回空或业务异常OPERATION_FAILED操作失败返回失败原因5. 数据设计涉及数据表表名说明table_name说明新增字段表字段类型是否为空默认值说明varchar(64)是null说明索引设计表索引字段类型说明idx_xxxxxx_id普通索引查询优化数据迁移是否需要数据迁移是 / 否如需要说明迁移范围迁移脚本回滚方式6. 业务逻辑设计主流程校验请求参数。校验权限或数据归属。查询必要数据。执行业务规则判断。写入或更新数据。返回处理结果。校验逻辑参数校验权限校验状态校验幂等校验状态流转当前状态操作目标状态条件INITsubmitSUBMITTED参数合法幂等设计说明是否需要防重复提交、重复消费、重复执行。可选方案唯一索引幂等表业务唯一 key分布式锁消息去重7. 异步与事件设计是否涉及异步处理是 / 否异步场景场景 1场景 2事件 / 消息事件触发时机消费方说明触发时机消费者说明失败处理是否重试最大重试次数死信队列补偿机制8. 非功能需求性能单次请求预期耗时最大 QPS最大数据量是否需要分页是否需要缓存安全是否需要鉴权是否涉及敏感数据是否需要脱敏是否需要操作审计可靠性是否允许部分失败是否需要事务是否需要补偿是否需要降级可观测性日志指标链路追踪告警9. 代码设计约束DTO / VO / EntityRequest DTO 使用包装类型避免 nullable 字段使用 Java primitive。DTO、VO、Entity 职责分离。不在 Entity 中承载复杂业务逻辑除非项目采用 DDD 风格。ServiceService 负责业务编排。避免超大方法。避免在循环中查询数据库。长耗时逻辑优先考虑异步化。Repository / DAO查询条件尽量下推到 SQL。避免查询宽泛数据后在 Java 内存中过滤。注意索引命中和分页性能。常量与枚举避免 magic value。状态、类型、错误码使用枚举或常量集中管理。10. 测试方案单元测试正常流程参数为空参数非法数据不存在状态不允许权限不足幂等重复请求异常分支集成测试数据库读写正确事务行为正确外部接口调用正确消息发送/消费正确缓存读写正确回归测试旧接口兼容旧数据兼容核心业务流程不受影响11. 发布方案发布步骤合并代码。执行数据库脚本。发布应用。验证核心接口。观察日志和监控。配置变更配置项默认值说明config.key说明灰度策略是否灰度灰度范围放量方式回滚方案代码回滚配置回滚数据回滚消息补偿12. 风险与应对风险影响应对方案风险 1影响应对13. 决策记录决策备选方案选择原因决策备选方案原因14. 待确认问题问题 1问题 2问题 3这个模板的核心是先讲清楚为什么做、做什么、不做什么再讲接口、数据、业务流程、异常、测试、发布回滚。大部分 Java 后端功能都可以用它开工。