Java 项目 Spec Coding 模板

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

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

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

Spec: <功能名称>

1. 背景与目标

背景

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

问题

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

目标

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

2. 需求说明

使用场景

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

用户故事

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

功能需求

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

业务规则

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

边界条件

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

3. 总体设计

方案概述

简要描述实现思路。

涉及模块

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

流程图

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. 测试方案（非必需）

单元测试

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

集成测试

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

回归测试

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

10. 发布方案 (非必需)

发布步骤

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

配置变更

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

灰度策略

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

回滚方案

• 代码回滚：
• 配置回滚：
• 数据回滚：

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