Spring Boot 3.5 后端骨架 + 全栈 AGENTS.md
把一套经过生产验证的后端基础设施复制到新项目，并可为「前后端同仓」的项目生成一份同时约束前后端的 AGENTS.md。只含基础设施，不含业务模块。
触发条件
满足任一即加载本 skill：
- 新建 / 搭建 Spring Boot 后端服务、脚手架、微服务工程
- 复制、复用或评审既有后端骨架
- 为前后端同仓项目生成 / 补强根级
AGENTS.md - 排查 Spring Boot 启动失败、依赖冲突、JPA / QueryDSL、Flyway、Sa-Token 鉴权问题
- 设计或评审后端分层结构、统一响应、异常体系、数据库表与索引
技术栈偏好（本骨架固定）
| 维度 | 采用 | 不要用 |
|---|---|---|
| 构建 | Gradle Kotlin DSL（8.14.x） | Maven |
| JDK | Java 21（虚拟线程） | Java 17 及以下 |
| Web | Spring Boot 3.5 Web MVC | WebFlux（除非明确要求） |
| 持久化 | Spring Data JPA + QueryDSL | MyBatis / MyBatis-Plus |
| 迁移 | Flyway，时间戳版本号 | V1/V2 递增整数、Liquibase |
| 鉴权 | Sa-Token | Spring Security / 手写 JWT |
| 缓存 / 锁 | Redis（Redisson 按需） | 自造锁 |
| 配置 | 单份 application.yml + 环境变量 |
application-dev/test/prod.yml 多 profile |
| 接口文档 | springdoc-openapi | 手写 YAML |
| 数据库 | PostgreSQL；分布式库见 reference | MySQL 默认 |
> 若用户明确要求使用上表「不要用」中的方案，以用户为准，但需在产出中说明与骨架默认的差异点。
产出
产出 A —— 后端骨架：可 ./gradlew bootRun 启动的服务，具备：
- 统一响应
R<T>、分页PageResult<T>/ 游标CursorPage<T> - 全局异常
GlobalExceptionHandler+BizException+ErrorCode - Sa-Token 登录鉴权、角色加载、用户/角色表
- JPA：雪花主键、审计字段、乐观锁、逻辑删除、QueryDSL
- Flyway 时间戳迁移 +
ddl-auto=validate+ 分布式建表/索引范式 - Jackson Long→String、CORS、TraceId、MDC 透传、虚拟线程异步池
产出 B —— 全栈 AGENTS.md：合并「后端 Java 规范」与「前端工程规范」的根级 AGENTS.md。前端部分必须先调用 frontend-agents-md skill 按其四段式产出后再合并，见 references/skeleton.md 步骤 11。
不产出：任何具体业务模块（视频、脚本、AI、直播等）；AI SDK / OSS / 支付等重依赖默认不引入。
核心红线（违反即错）
| 编号 | 规则 |
|---|---|
| RL-01 | Controller 必须返回 R<T>，禁止裸对象 / Map |
| RL-02 | Controller 禁止写业务逻辑，只做校验、鉴权、调 Service、包装响应 |
| RL-03 | common 禁止 import 任何 module.*（鉴权层的 StpInterfaceImpl 为唯一例外） |
| RL-04 | 实体必须继承 BaseEntity，禁止自建 id / 审计字段 |
| RL-05 | 必须构造器注入（@RequiredArgsConstructor + private final），禁止字段 @Autowired |
| RL-06 | 表结构只通过新增 Flyway 时间戳脚本变更，禁止修改历史脚本 |
| RL-07 | 分布式库：禁止外键；主键 BIGINT 雪花、禁自增；唯一键必须含分片键 |
| RL-08 | 只保留单份 application.yml，参数用 ${ENV:default}；禁止多 profile、禁止密钥写默认值 |
| RL-09 | 业务失败必须抛 BizException，禁止吞异常或用 null 表示失败 |
| RL-10 | 多用户数据必须做归属校验（userId 过滤 / admin 豁免），禁止只按 id 查 |
| RL-11 | 软删除统一 deleted（0/1），查询必须带 deleted = 0 |
| RL-12 | 异步 / 定时任务用 LocalUserContext / TraceContext 显式传上下文，禁止跨线程读 Sa-Token |
| RL-13 | 日志用 @Slf4j 占位符，禁止 System.out / printStackTrace |
| RL-14 | 生成全栈 AGENTS.md 时前端规则必须来自 frontend-agents-md 探测，禁止臆造 |
步骤导航
详细实现与完整代码模板见 references/skeleton.md：
- 建工程 + Gradle 依赖
- 单份配置（
application.yml）+ 环境变量 - 目录骨架
common/response：统一响应common/exception：异常体系common/jpa+common/entity：JPA 基础设施module/auth+common/security：Sa-Token 鉴权与用户common/config+common/filter+common/util：Web 基础设施- Flyway 时间戳迁移 + 分布式建表 / 索引范式
- 启动自检
- 生成全栈
AGENTS.md（结合frontend-agents-md）
参考文件（按需加载）
| 文件 | 何时加载 |
|---|---|
references/skeleton.md |
实际搭建骨架、需要完整代码模板与建表 SQL 时 |
references/testing.md |
编写单元 / Web / 持久层 / 集成测试时 |
references/deployment.md |
打 Docker 镜像、配 JVM 参数、整理环境变量清单时 |
references/troubleshooting.md |
启动失败、依赖冲突、JPA / QueryDSL / Flyway / 鉴权报错排查时 |
frontend-agents-md skill |
生成全栈 AGENTS.md 的前端部分时（必须调用） |
反模式（不要做）
- ❌ 在
common里 importmodule.*的业务类 - ❌ Controller 返回裸对象 /
Map - ❌ 用
ordinal()存枚举、用null表示失败 - ❌ 改历史 Flyway 脚本；用递增整数当迁移版本号
- ❌ 用外键约束、数据库自增主键、唯一索引不带分片键
- ❌ 默认全量引入 AI / OSS / Redisson 等重依赖
- ❌ 把密钥写进
application.yml默认值 - ❌ 拆
application-dev.yml/application-prod.yml多份 profile - ❌ 在生成全栈
AGENTS.md时臆造前端技术栈
