snailclimb Java 编码规范
将这个 skill 视为 Java 17+ / Spring Boot 项目的简明工作卡。SKILL.md 只保留流程和路由，具体规则按需加载 references/ 下的参考文件。
使用原则
- 仓库内规则优先于本 skill。若
AGENTS.md、CLAUDE.md、本地格式化配置或相邻代码与本 skill 冲突，优先遵循仓库约定；只有当冲突会影响结果时，再明确指出。 - 不要为了满足本 skill 而大规模重构无关代码。优先贴近现有模式，除非当前实现已经带来真实的正确性、安全性、事务或可维护性风险。
- 规则要尽量具体、可检查。维护本 skill 时，始终追问一句：删掉这条后，AI 是否更容易犯真实错误？
- 禁止项要配上推荐替代方案。例如：不要用字段注入；优先使用构造器注入，通常配合 Lombok
@RequiredArgsConstructor。 - 机械性规则尽量交给工具。优先依赖 formatter、Checkstyle、Spotless、测试、CI 或 hooks，不要只靠自然语言约束格式。
工作流程
编写或重构代码时
- 先看项目上下文：构建文件、本地说明文件、formatter/lint 配置、包结构以及相似类的现有写法。
- 只加载当前改动真正需要的参考文件，按下方“参考路由”选择。
- 控制改动面，尽量只改行为相关部分，不顺手做无关清理。
- 把逻辑放到正确层级： Controller 负责路由、认证边界、校验注解和响应转换； Service 负责业务编排； Manager 负责事务和 DAO 组合； DAO/Mapper 负责持久化。
- 用最小但有效的命令验证：优先跑定向测试、模块编译、formatter 或静态检查；如果没跑，要说明原因。
代码评审时
- 先看 bug 和风险，不要先盯风格细节。
- 按严重程度排序问题，并尽量给出文件/行号引用。
- 每个问题都说明：违反了什么规则、为什么重要、推荐怎么修。
- 风格问题只有在会带来维护成本，或与仓库工具链冲突时才提。
- 如果没有发现问题，要明确说明，同时补充剩余的测试或验证缺口。
回答规范类问题时
优先按这个结构回答：规则、原因、示例、以及仓库内是否存在本地覆盖约定。
参考路由
| 需求 | 加载文件 |
|---|---|
| Java 格式、导入、括号、缩进、换行、switch、注解、修饰符、Javadoc、命名 | references/google-style.md |
| 项目结构、JavaBean 后缀、Optional、Stream、泛型、不可变性、现代 Java 特性 | references/code-style.md |
模块化目录、Controller/Service/Manager/DAO 分层、URL 规范、@Transactional、设计模式、统一响应 |
references/architecture.md |
| 异常、日志、性能、线程池、远程调用、安全、测试、数据库设计 | references/best-practices.md |
核心默认规则
- 格式：2 空格缩进，不用 Tab，100 列限制，K&R 大括号风格，不用通配符导入，修饰符顺序标准化，可见 API 在有必要时补 Javadoc。
- 命名：类使用
UpperCamelCase，方法/字段使用lowerCamelCase，常量使用UPPER_SNAKE_CASE，包名全小写且不用下划线，项目名全小写并使用中划线。 - API 边界：不要直接暴露
Entity。请求用Form，返回用VO，跨层传输用DTO，内部业务对象用BO。BO不应出现在 Controller API 中。 - 布尔字段：优先使用
xxxFlag/xxx_flag，避免isXxx字段，以免序列化和 RPC 映射歧义。 - 参数数量：单个方法参数尽量不超过 5 个；超过时优先封装为请求对象或值对象。
- URL 风格：默认跟随仓库现有约定。若仓库没有明确约定，本 skill 默认偏向非 RESTful 的
GET/POST /module/submodule/action，并且把路由注解写在方法上，便于搜索。 - 文档注解：遵循仓库当前使用的 Swagger/OpenAPI 体系。若项目使用 Swagger
@ApiOperation，需要沿用既有 author 习惯；若项目使用 springdoc，则跟随本地@Operation写法。
分层默认规则
- Controller：不写业务逻辑，不做数据组装，不直接访问 DB/缓存/MQ。只有在请求边界层，且项目采用请求线程上下文时，才在这里获取当前用户。
- Service：负责业务编排和校验；大 Service 按 use case 拆分。
- Manager：默认把
@Transactional(rollbackFor = Exception.class)放在这里，负责 DAO 组合和第三方平台细节封装，并尽量缩小事务范围。 - DAO/Mapper：只做持久化。对于采用这套约定的 MyBatis-Plus 项目，优先 XML mapper SQL，避免 Wrapper 查询构造器，常量通过参数传入，业务逻辑不要写进 XML。
没有本地覆盖时不要做的事
- 不要在数据库事务里调用外部 HTTP、LLM、S3、MQ、邮件或其他慢速远程接口。事务前准备数据，必要时在提交后触发副作用。
- 不要依赖同类内部调用触发
@Transactional；应把事务方法移动到另一个 Spring Bean，通常是 Manager，或使用仓库既有代理方案。 - 不要创建静态异常实例，否则堆栈信息会失真。
- 不要写空的
catch (Exception e) {}；要么处理、要么带上下文包装、要么明确说明为何可以忽略。 - 不要在同一层既记录日志又继续抛出同一个异常，除非该层就是最终处理层。
- 不要把 N+1 数据库调用或远程调用藏进 Stream 或循环里；应先批量查，再在内存中组装。
- 不要硬编码密钥、Token、供应商 base URL；使用配置与仓库既有的 URL 校验/客户端工厂。
- 不要在生产路径使用
Executors.newFixedThreadPool()或newCachedThreadPool()；要显式创建带边界队列、线程名、监控和关闭逻辑的ThreadPoolExecutorBean。
评审检查清单
架构与 API：
- Controller / Service / Manager / DAO 职责是否清晰分离。
- 请求/响应边界是否使用 Form / VO / DTO 和统一响应包装。
- 是否遵循本地 URL 与 Swagger/OpenAPI 规范。
事务与持久化：
- 需要事务的方法是否正确使用
rollbackFor = Exception.class。 - 事务内是否混入远程调用、大循环或慢操作。
- DAO/Mapper 是否保持持久化职责，没有出现 N+1 访问。
数据模型与 Java 风格：
- JavaBean 后缀与布尔
flag规则是否正确。 - 方法是否足够短、可读，参数数量是否控制在 5 个以内。
- Optional、Stream、record、switch expression 是否在提升可读性时才使用。
异常、日志与安全：
- 领域异常是否包含足够上下文，且不是静态实例。
- 日志是否使用 SLF4J，保留堆栈，避免重复记录，并对敏感数据做脱敏。
- 外部 URL、密钥和用户输入是否走本地安全工具或约束。
测试与验证：
- 关键分支、边界和异常路径是否有聚焦测试覆盖。
- 是否运行了最小但有意义的编译/测试/lint 命令；若未运行，是否说明原因。
Skill 维护规则
维护这个 skill 时，遵循与优秀 CLAUDE.md / AGENTS.md 相同的原则：
- 让
SKILL.md只承担路由和执行层角色；长示例和细则放入references/。 - 只有当某条规则长期有效、足够通用、并且确实能减少重复错误时，才把它固化进来。
- 删除模糊规则，例如“写出干净代码”，除非它包含明确检查点或替代方案。
- 如果某条规则本可以由 formatter、linter、hook、测试或 CI 强制执行，优先记录工具和验证命令，而不是只写成文字说明。
- 对 skill 做了较大修改后，用
skill-creator的验证流程再检查一遍。