java-code-style

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），无数据或参数不合法时默认返回空列表。
• 在系统边界进行输入校验。