Java Code Style Skill

将个人经验、团队约定与业界规范沉淀为可执行的 Java 代码风格工作流。

Skill Goal

在 Java 后端场景中完成以下任务：

1. 产出可落地的代码风格规范（不是口号式原则）。
2. 对现有代码进行结构化风格审查（分级、可追踪、可修复）。
3. 在不改变业务语义的前提下提供最小改动的重构建议。
4. 统一团队在命名、异常、日志、边界分层、并发与数据库访问上的实践。

Baseline Reference

优先参考以下资料作为基础规范源：

• references/阿里巴巴Java开发规范（嵩山版）.md

在引用规则时，尽量给出“章节 + 页码段”定位，避免泛化描述。

已知目录主干（来自手册）：

• 编程规约（命名、常量、格式、OOP、日期时间、集合、并发、控制语句、注释、前后端、其他）
• 异常日志（错误码、异常处理、日志规约）
• 单元测试
• 安全规约
• MySQL 数据库（建表、索引、SQL、ORM）
• 工程结构（应用分层、二方库依赖、服务器）
• 设计规约

Operating Mode

默认按以下模式工作：

1. 先识别任务类型：规范制定 / 代码审查 / 代码改写。
2. 再识别技术上下文：JDK 版本、Spring Boot 版本、ORM、日志框架、构建工具。
3. 再应用规则：强制项优先于推荐项。
4. 最后输出可执行结果：问题清单、改写建议、统一模板。

Required Inputs

在信息不足时，先补齐最小上下文：

• Java 与 Spring Boot 版本（例如 JDK 17 + Spring Boot 3.x）。
• 架构风格（分层/DDD/Clean Architecture）。
• 团队禁用项（如字段注入、通配符导入、System.out.println）。
• 当前目标（写新代码 / 审查旧代码 / 统一历史代码）。

若用户未提供，先按“通用企业级后端默认值”执行，并在输出中明确假设。

Rule Hierarchy

将规则分成三层：

• L1 强制（Blocking）：违反后必须修改。
• L2 推荐（Important）：建议修改，影响可维护性与协作效率。
• L3 参考（Nice-to-have）：优化项，可在时间允许时处理。

将手册中的【强制 / 推荐 / 参考】映射到上述等级，并保持一致。

Style Dimensions

审查或制定规范时，至少覆盖以下维度：

1) 命名与语义

• 统一类名、方法名、变量名风格。
• 禁止歧义缩写与混乱命名。
• 保证命名可表达业务含义与边界语义。

2) 常量与魔法值

• 抽离魔法值。
• 常量命名语义完整。
• 明确常量作用域（类内/模块内/跨模块）。

3) 代码结构与可读性

• 方法复杂度不设硬性上限，但必须保证可读性与可维护性。
• 强制使用卫语句（early return）减少分支金字塔。
• 工具类保持单一职责，优先复用成熟生态工具（如 Apache Commons Lang3、Commons Collections4、Guava），避免重复造轮子。
• 简单循环场景优先使用 for / while，禁止使用 stream().forEach(...)。
• 禁止在 Stream 管道中编写复杂业务逻辑或超长 lambda/匿名内部类；复杂逻辑先抽离为具名方法。
• Service 按 DDD 语义拆分，避免“万能服务类”。

4) OOP 与分层边界

• 严格区分 DTO / VO / DO / Entity / Command / Query。
• 实体类优先使用 Lombok 减少样板 getter/setter 代码。
• Service/DAO 默认采用接口 + Impl 模式。
• 保留 Manager 层，用于第三方适配、通用能力下沉与多 DAO 组合复用。
• 禁止跨层泄漏（Controller 直接拼 SQL、Repository 承担业务编排等）。
• 保持接口契约清晰，避免“万能服务类”。

5) 集合与并发

• 明确集合类型选择依据。
• 并发问题优先通过业务流程拆解降低冲突，再考虑锁策略。
• 优先减少分布式锁使用，避免将锁作为默认方案。
• JDK >= 21 时，优先评估虚拟线程方案。
• 明确并发访问场景与线程安全策略，避免无边界并发、隐式共享可变状态。

6) 控制流与防御性编程

• 强制卫语句，减少深层嵌套。
• 判空统一优先使用 Objects.isNull / Objects.nonNull。
• 相等判断统一优先使用 Objects.equals。
• 字符串判空/非空统一优先使用 StringUtils.isEmpty / StringUtils.isNotEmpty。
• 集合判空/非空统一优先使用 CollectionUtils.isEmpty / CollectionUtils.isNotEmpty。
• if 判断中禁止直接使用逻辑非 !，布尔判断优先使用 BooleanUtils.isFalse / BooleanUtils.isTrue。
• Optional 与 null 不做过度限制，按上下文选择。
• 对集合型返回（如 DB/RPC 查询 List），无数据或参数不合法时默认返回空列表。
• 在系统边界进行输入校验。

7) 异常、错误码、日志

• 业务异常体系主要用于 Controller 内部调用链（Manager/Service/Repository）。
• 端点 Controller 与 RPC 返回以 Result 结构为主，统一承载 success/errorCode/errorMessage。
• RuntimeException 可直接使用，不强制必须自定义业务异常。
• 项目存在错误码规范时遵循现有规范；不存在时按通用规范与项目经验建立。
• 日志避免“无意义、无上下文”输出；敏感信息与日志级别策略按具体项目场景定义。

8) 数据库与 ORM

• 以 MyBatis Plus 为主，兼容 MyBatis Flex、Jimmer 等 ORM 选型。
• SQL 可读、可维护、可索引命中。
• ORM 映射避免 N+1 与隐式全表扫描风险。
• 更新语句必须维护 update_time。
• SQL 风格不做硬编码约束，优先询问项目/团队偏好后统一（如关键字大小写、别名习惯、分页写法）。
• 索引设计与查询模式一致。

9) 缓存与一致性

• Redis 操作强制优先使用 Redisson；仅在无法满足需求时才可评估其他框架。
• 涉及本地缓存或分布式缓存时，必须建立 XXXCacheManager 作为统一入口。
• 所有缓存 get/set/refresh 等操作必须通过 XXXCacheManager，禁止业务代码直接操作缓存客户端。
• 缓存 Key 规范、TTL 策略与一致性策略必须集中定义并可审查；缓存刷新策略不设统一硬规则，按具体项目约定执行。

10) 测试与可验证性

• 关键业务规则必须可单元测试。
• 复杂分支必须有边界场景用例。
• 风格改写不改变行为，需有回归验证建议。

11) 工程结构与设计一致性

• 目录结构与架构分层一致。
• 模块职责边界清晰。
• 避免循环依赖与跨模块隐式耦合。

Output Contracts

A. 规范制定输出模板

按如下结构输出：

1. 适用范围（技术栈、模块范围、执行阶段）
2. 规则分级表（L1/L2/L3）
3. 禁止项清单（可直接放进团队 code review）
4. 示例对照（Bad / Good）
5. 落地机制（审查节奏、自动化检查建议）

默认附带以下固定禁止项 Top 10：

1. 禁止在 if 条件中直接使用逻辑非 !，统一使用 BooleanUtils.isFalse/isTrue。
2. 禁止手写 obj == null / obj != null 判空链式判断，统一使用 Objects.isNull/nonNull。
3. 禁止使用存在空指针风险的相等判断（如 a.equals(b)），统一使用 Objects.equals(a, b)。
4. 禁止手写字符串判空表达式（如 str == null || str.length() == 0），统一使用 StringUtils.isEmpty/isNotEmpty。
5. 禁止手写集合判空表达式（如 list == null || list.isEmpty()），统一使用 CollectionUtils.isEmpty/isNotEmpty。
6. 禁止在简单遍历场景使用 stream().forEach(...)，统一使用 for/while。
7. 禁止在 Stream 管道中编写复杂业务逻辑、超长 lambda 或庞大匿名内部类。
8. 禁止跨层职责泄漏（如 Controller 直接拼 SQL、Repository 承担业务编排）。
9. 禁止在更新链路遗漏 update_time 维护。
10. 禁止输出无意义、无上下文日志。

B. 代码审查输出模板

按如下格式输出：

• Summary：总体结论（通过 / 需整改）
• Findings：
• CRITICAL：阻断问题（必须改）
• MAJOR：重要问题（建议尽快改）
• MINOR：优化问题
• 每条问题必须包含：

1. 位置（文件/类/方法）
2. 问题说明
3. 违反规则
4. 修改建议（尽量给出示例）

C. 改写建议输出模板

• 先给“最小变更方案”（优先）。
• 再给“增强方案”（可选）。
• 标注潜在影响面（接口、事务、SQL、并发语义）。

Refactor Guardrails

执行代码风格重构时，遵循以下护栏：

1. 保持业务语义不变。
2. 保持对外契约不变（除非用户明确要求）。
3. 单次改动聚焦一种问题，避免混合重构。
4. 不引入与任务无关的新抽象。
5. 避免“顺手大改”。

Conflict Resolution Policy

当“个人习惯、团队约定、手册规则”冲突时，按以下优先级处理：

1. 项目既有强约束（lint、框架约束、历史兼容要求）
2. 团队明确约定
3. 手册强制项
4. 个人风格偏好

输出时明确说明冲突点与取舍理由。

Default Java/Spring Backend Defaults

当用户未给团队规则时，使用以下默认基线：

• Controller 层只做协议转换与参数校验，对外以 Result 结构返回。
• Service 层承载业务编排，按 DDD 进行职责拆分。
• 保留 Manager 层用于第三方适配、通用能力下沉和多 DAO 组合复用。
• Repository/Mapper 层只处理持久化。
• 事务边界不做硬性限制，可根据场景位于 Service/Manager/定时任务。
• ORM 默认 MyBatis Plus，兼容 MyBatis Flex/Jimmer。
• 更新语句默认维护 update_time。
• JDK >= 21 时优先评估虚拟线程。
• 优先构造器注入，避免隐藏依赖。

Trigger Examples

以下用户表达应触发本技能：

• “帮我做一份 Java 后端代码规范。”
• “这段 Spring Boot 代码风格不统一，帮我审查。”
• “把我的编码习惯沉淀成团队 SKILL。”
• “给我一套 Java 异常和日志规范模板。”
• “按阿里规范 + 团队经验，给出可执行检查表。”

Non-Goals

以下内容不作为默认目标，除非用户显式要求：

• 大规模架构迁移
• 业务逻辑重写
• 与风格无关的性能专项优化
• 与风格无关的基础设施改造

Additional Resources

Reference Files

• references/阿里巴巴Java开发规范（嵩山版）.md：原始规范全文（转换版）
• references/rules-mapping.md：本 Skill 的 L1/L2/L3 映射与规则索引

Example Files

• examples/review-output-template.md：标准化审查报告模板
• examples/refactor-before-after.md：常见风格改写对照（Bad/Good）

Quick Checklist

交付前至少检查：

• 是否明确适用范围。
• 是否给出分级规则。
• 是否给出可执行禁止项。
• 是否包含 Bad/Good 示例。
• 是否给出落地与审查机制。
• 是否区分“必须改”与“可优化”。

Collaboration Questions for Tailoring

每轮优化优先询问并固化以下偏好：

1. 命名与分层：DO/DTO/VO/Entity/Command/Query 边界、Service 接口化、Manager 职责。
2. 代码结构：是否强制卫语句、工具类复用策略、DDD 拆分粒度。
3. 空值策略：Optional 使用边界、null 语义、空列表返回约定。
4. 异常体系：业务异常与 RuntimeException 的边界、Result 使用场景。
5. 错误码：沿用项目规范或新建规范的原则。
6. 日志规范：上下文字段、级别约束、敏感信息处理策略。
7. ORM/SQL：技术选型、update_time 约束、SQL 风格约束强度。
8. 并发与事务：事务边界、锁策略优先级、虚拟线程采用条件。

在后续版本中，根据真实审查案例持续补充例外规则与反例库。