| 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)
- 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
- 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
- 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
- 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
- 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题
使用流程
Step 1: 环境准备
确保开发环境已安装必要的依赖和工具。
Step 2: 配置初始化
根据项目需求进行基础配置。
Step 3: 核心功能使用
按照示例代码实现核心功能。
Step 4: 测试验证
运行测试确保功能正常。
Step 5: 部署上线
完成开发后进行部署和监控。
