java-conventions

name	java-conventions
description	统一 Java 项目编码规范与注释规范（SLF4J+Lombok 日志、Bean Lombok 注解选择、判空 Objects/Optional、工具类优先级 Spring→Apache Commons→Hutool→Guava、复杂逻辑用设计模式/简单逻辑不拆分、Controller/Service/ServiceImpl/Mapper 注释一致性）。当需要“按 Java 规范重构/Review/补全注释/统一日志/统一工具类使用/补全 JavaDoc”时使用。

Java Conventions

用于在 Java 项目中统一编码习惯与注释要求，帮助你在不引入过度设计的前提下保证一致性与可维护性。

使用流程

• 先判断改动范围：仅改动当前涉及的类/方法，不做无关格式化。
• 先统一基础规范：日志、判空、工具类选择、Bean 注解策略。
• 再做注释检查：对象注释、方法注释、逻辑块注释（非简单 CRUD）。
• 最后验证：编译 + 测试通过后再提交。

编码规范

日志规范（必选）

• 统一使用 SLF4J，并结合 Lombok 注解（例如 @Slf4j）。
• 禁止 System.out.println、printStackTrace()。
• 日志内容避免敏感信息与大对象全量输出。

示例：

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 吞异常”的方式掩盖空指针问题；应在边界处校验输入。

示例：

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。

输出要求（用于 Review/改造时的交付）

• 列出：已调整的规范点（日志/判空/工具类/注释）。
• 附带：受影响文件清单与验证方式（编译/测试）。

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。