AI编程-- Spec Coding 模板

乐之者v2026-06-28 10:06

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 异步或事件处理

流程图

#mermaid-svg-ShGIaSZclguVwsbu{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ShGIaSZclguVwsbu .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ShGIaSZclguVwsbu .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ShGIaSZclguVwsbu .error-icon{fill:#552222;}#mermaid-svg-ShGIaSZclguVwsbu .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ShGIaSZclguVwsbu .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ShGIaSZclguVwsbu .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ShGIaSZclguVwsbu .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ShGIaSZclguVwsbu .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ShGIaSZclguVwsbu .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ShGIaSZclguVwsbu .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ShGIaSZclguVwsbu .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ShGIaSZclguVwsbu .marker.cross{stroke:#333333;}#mermaid-svg-ShGIaSZclguVwsbu svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ShGIaSZclguVwsbu p{margin:0;}#mermaid-svg-ShGIaSZclguVwsbu .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ShGIaSZclguVwsbu .cluster-label text{fill:#333;}#mermaid-svg-ShGIaSZclguVwsbu .cluster-label span{color:#333;}#mermaid-svg-ShGIaSZclguVwsbu .cluster-label span p{background-color:transparent;}#mermaid-svg-ShGIaSZclguVwsbu .label text,#mermaid-svg-ShGIaSZclguVwsbu span{fill:#333;color:#333;}#mermaid-svg-ShGIaSZclguVwsbu .node rect,#mermaid-svg-ShGIaSZclguVwsbu .node circle,#mermaid-svg-ShGIaSZclguVwsbu .node ellipse,#mermaid-svg-ShGIaSZclguVwsbu .node polygon,#mermaid-svg-ShGIaSZclguVwsbu .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ShGIaSZclguVwsbu .rough-node .label text,#mermaid-svg-ShGIaSZclguVwsbu .node .label text,#mermaid-svg-ShGIaSZclguVwsbu .image-shape .label,#mermaid-svg-ShGIaSZclguVwsbu .icon-shape .label{text-anchor:middle;}#mermaid-svg-ShGIaSZclguVwsbu .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ShGIaSZclguVwsbu .rough-node .label,#mermaid-svg-ShGIaSZclguVwsbu .node .label,#mermaid-svg-ShGIaSZclguVwsbu .image-shape .label,#mermaid-svg-ShGIaSZclguVwsbu .icon-shape .label{text-align:center;}#mermaid-svg-ShGIaSZclguVwsbu .node.clickable{cursor:pointer;}#mermaid-svg-ShGIaSZclguVwsbu .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ShGIaSZclguVwsbu .arrowheadPath{fill:#333333;}#mermaid-svg-ShGIaSZclguVwsbu .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ShGIaSZclguVwsbu .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ShGIaSZclguVwsbu .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ShGIaSZclguVwsbu .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ShGIaSZclguVwsbu .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ShGIaSZclguVwsbu .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ShGIaSZclguVwsbu .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ShGIaSZclguVwsbu .cluster text{fill:#333;}#mermaid-svg-ShGIaSZclguVwsbu .cluster span{color:#333;}#mermaid-svg-ShGIaSZclguVwsbu div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ShGIaSZclguVwsbu .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ShGIaSZclguVwsbu rect.text{fill:none;stroke-width:0;}#mermaid-svg-ShGIaSZclguVwsbu .icon-shape,#mermaid-svg-ShGIaSZclguVwsbu .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ShGIaSZclguVwsbu .icon-shape p,#mermaid-svg-ShGIaSZclguVwsbu .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ShGIaSZclguVwsbu .icon-shape .label rect,#mermaid-svg-ShGIaSZclguVwsbu .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ShGIaSZclguVwsbu .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ShGIaSZclguVwsbu .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ShGIaSZclguVwsbu :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 接收请求
参数校验
执行业务逻辑
读写数据
返回结果

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 后端功能都可以用它开工。

热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04飞书长连接_事件订阅（接收消息，审批任务状态变更）05Trae国际版与国内版深度测评：AI原生IDE的双生花06【AI】2026 年具身智能模型和世界模型总结07GitHub 镜像站点08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析092026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）102026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？