AI编程-- Spec Coding 模板

Java 项目 Spec Coding 模板

这是一个 Java 项目 Spec Coding 模板，

用于 AI编程，适合 Spring Boot、Dubbo、微服务、单体服务、后台管理系统、任务系统等大部分 Java 项目。

让AI开发时，按这个模板写好 Spec 的Md 文档，让 AI能够更清晰地理解需求，写对代码。

Spec: <功能名称>

1. 背景与目标

背景

描述当前系统/业务现状，以及为什么需要做这个功能。

问题

当前存在什么问题、限制或机会？

目标

• <目标 1>
• <目标 2>
• <目标 3>

非目标

本次明确不做的内容：

• <非目标 1>
• <非目标 2>

2. 需求说明

使用场景

描述谁在什么情况下使用该功能。

用户故事

• 作为 <角色>，我希望 <能力>，以便 <价值>。

功能需求

• <需求 1>
• <需求 2>
• <需求 3>

业务规则

规则	说明
<规则名称>	<规则说明>

边界条件

• <边界条件 1>
• <边界条件 2>

3. 总体设计

方案概述

简要描述实现思路。

涉及模块

模块	职责
controller / api	对外暴露接口
service	编排业务逻辑
domain	核心业务模型
repository / mapper / dao	数据访问
job / listener / consumer	异步或事件处理

流程图

flowchart TD A["接收请求"] --> B["参数校验"] B --> C["执行业务逻辑"] C --> D["读写数据"] D --> E["返回结果"]

4. 接口设计

接口类型

• REST API / RPC / Dubbo / gRPC / Message Consumer / Scheduled Job

接口定义

<ReturnType> <methodName>(<RequestDTO> request);

或 REST：

POST /api/<resource>/<action>

请求参数

字段	类型	必填	说明
id	Long	是	主键 ID
name	String	否	名称

响应参数

字段	类型	说明
code	String	响应码
message	String	响应信息
data	Object	响应数据

错误码

错误码	场景	处理方式
INVALID_PARAM	参数非法	返回参数错误
NOT_FOUND	数据不存在	返回空或业务异常
OPERATION_FAILED	操作失败	返回失败原因

5. 数据设计

涉及数据表

表名	说明
<table_name>	<说明>

新增字段

表

字段

类型

是否为空

默认值

说明

varchar(64)

是

null

<说明>

索引设计

表

索引

字段

类型

说明

idx_xxx

xxx_id

普通索引

查询优化

数据迁移

是否需要数据迁移：是 / 否

如需要，说明：

• 迁移范围：
• 迁移脚本：
• 回滚方式：

6. 业务逻辑设计

主流程

1. 校验请求参数。
2. 校验权限或数据归属。
3. 查询必要数据。
4. 执行业务规则判断。
5. 写入或更新数据。
6. 返回处理结果。

校验逻辑

• 参数校验：
• 权限校验：
• 状态校验：
• 幂等校验：

状态流转

当前状态	操作	目标状态	条件
INIT	submit	SUBMITTED	参数合法

幂等设计

说明是否需要防重复提交、重复消费、重复执行。

可选方案：

• 唯一索引
• 幂等表
• 业务唯一 key
• 分布式锁
• 消息去重

7. 异步与事件设计

是否涉及异步处理：是 / 否

异步场景

• <场景 1>
• <场景 2>

事件 / 消息

事件	触发时机	消费方	说明
	<触发时机>	<消费者>	<说明>

失败处理

• 是否重试：
• 最大重试次数：
• 死信队列：
• 补偿机制：

8. 非功能需求

性能

• 单次请求预期耗时：
• 最大 QPS：
• 最大数据量：
• 是否需要分页：
• 是否需要缓存：

安全

• 是否需要鉴权：
• 是否涉及敏感数据：
• 是否需要脱敏：
• 是否需要操作审计：

可靠性

• 是否允许部分失败：
• 是否需要事务：
• 是否需要补偿：
• 是否需要降级：

可观测性

• 日志：
• 指标：
• 链路追踪：
• 告警：

9. 代码设计约束

DTO / VO / Entity

• Request DTO 使用包装类型，避免 nullable 字段使用 Java primitive。
• DTO、VO、Entity 职责分离。
• 不在 Entity 中承载复杂业务逻辑，除非项目采用 DDD 风格。

Service

• Service 负责业务编排。
• 避免超大方法。
• 避免在循环中查询数据库。
• 长耗时逻辑优先考虑异步化。

Repository / DAO

• 查询条件尽量下推到 SQL。
• 避免查询宽泛数据后在 Java 内存中过滤。
• 注意索引命中和分页性能。

常量与枚举

• 避免 magic value。
• 状态、类型、错误码使用枚举或常量集中管理。

10. 测试方案

单元测试

• 正常流程
• 参数为空
• 参数非法
• 数据不存在
• 状态不允许
• 权限不足
• 幂等重复请求
• 异常分支

集成测试

• 数据库读写正确
• 事务行为正确
• 外部接口调用正确
• 消息发送/消费正确
• 缓存读写正确

回归测试

• 旧接口兼容
• 旧数据兼容
• 核心业务流程不受影响

11. 发布方案

发布步骤

1. 合并代码。
2. 执行数据库脚本。
3. 发布应用。
4. 验证核心接口。
5. 观察日志和监控。

配置变更

配置项	默认值	说明
<config.key>		<说明>

灰度策略

• 是否灰度：
• 灰度范围：
• 放量方式：

回滚方案

• 代码回滚：
• 配置回滚：
• 数据回滚：
• 消息补偿：

12. 风险与应对

风险	影响	应对方案
<风险 1>	<影响>	<应对>

13. 决策记录

决策	备选方案	选择原因
<决策>	<备选方案>	<原因>

14. 待确认问题

• <问题 1>
• <问题 2>
• <问题 3>

这个模板的核心是：先讲清楚 为什么做、做什么、不做什么，再讲 接口、数据、业务流程、异常、测试、发布回滚。大部分 Java 后端功能都可以用它开工。