java-conventions

# Java Conventions 用于在 Java 项目中统一编码习惯与注释要求，帮助你在不引入过度设计的前提下保证一致性与可维护性。 ## 使用流程 - 先判断改动范围：仅改动当前涉及的类/方法，不做无关格式化。 - 先统一基础规范：日志、判空、工具类选择、Bean 注解策略。 - 再做注释检查：对象注释、方法注释、逻辑块注释（非简单 CRUD）。 - 最后验证：编译 + 测试通过后再提交。 ## 编码规范 ### 日志规范（必选） - 统一使用 SLF4J，并结合 Lombok 注解（例如 `@Slf4j`）。 - 禁止 `System.out.println`、`printStackTrace()`。 - 日志内容避免敏感信息与大对象全量输出。 示例： ```java import lombok.extern.slf4j.Slf4j; @Slf4j public class UserService { public void handle(String userId) { log.info("handle userId={}", userId); } } ``` ### Bean/Lombok 注解（按场景选择） - 领域/DTO/VO/BO 等：按需要选 `@Getter`/`@Setter`/`@Builder`/`@Data`。 - 需要可控 equals/hashCode/toString 时：优先显式选择 Lombok 注解组合，避免一把梭。 - 当对象被序列化/日志输出频繁时：注意 `toString` 的敏感字段与大字段。 ### 判空与防御式编程 - 判空优先使用 JDK 工具：`Objects.requireNonNull`、`Objects.nonNull`、`Optional`。 - 不要用“全局 try/catch 吞异常”的方式掩盖空指针问题；应在边界处校验输入。 示例： ```java import java.util.Objects; public void updateName(String name) { Objects.requireNonNull(name, "name must not be null"); } ``` ### 工具类优先级（字符串 / 集合等） - 优先级：Spring → Apache Commons → Hutool → Guava。 - 在已有依赖满足的前提下，避免为了一个小工具方法引入新依赖。 - 当同类工具同时存在时，统一团队选择，避免到处混用。 ## 设计与拆分 - 复杂逻辑：优先通过设计模式（策略、模板方法、责任链等）提升可扩展性与可测试性。 - 简单逻辑：避免过度设计与过度拆分，保持可读性优先。 - 领域建模：业务规则尽量收敛到领域对象/领域服务，避免贫血模型堆在 ServiceImpl。 ## 注释规范 ### 规则（必选） - 创建或更新任何对象/方法时，进行注释检查并补全/完善对象注释与方法注释。 - 若方法逻辑不是最简单的 CRUD，需要按逻辑块补充注释说明关键意图与边界条件。 - Controller、Service、ServiceImpl、Mapper 均需要注释，保持注释与代码一致（不写过期注释）。 ### 建议模板 - 类：说明职责边界、输入输出、关键约束。 - 方法：说明做什么、关键参数含义、异常/返回约定。 更完整的注释模板与检查清单见 [references/api_reference.md](references/api_reference.md)。 ## 输出要求（用于 Review/改造时的交付） - 列出：已调整的规范点（日志/判空/工具类/注释）。 - 附带：受影响文件清单与验证方式（编译/测试）。 ## 常见陷阱 (Gotchas) 1. **版本兼容性**：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异 2. **配置文件格式**：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查 3. **环境变量**：确保所有必要的环境变量已正确设置，敏感信息不要硬编码 4. **依赖冲突**：多版本共存时注意依赖冲突，使用 lock 文件锁定版本 5. **性能陷阱**：大数据量场景下注意性能优化，避免 N+1 查询等常见问题 ## 使用流程 ### Step 1: 环境准备 确保开发环境已安装必要的依赖和工具。 ### Step 2: 配置初始化 根据项目需求进行基础配置。 ### Step 3: 核心功能使用 按照示例代码实现核心功能。 ### Step 4: 测试验证 运行测试确保功能正常。 ### Step 5: 部署上线 完成开发后进行部署和监控。