Java Conventions

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: 部署上线

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

Java Conventions — 注释模板与检查清单

注释检查清单（提交前）

• 是否新增/修改了类或方法？若是：类注释与方法注释必须同步更新。
• 方法是否包含非简单 CRUD 的业务逻辑？若是：按逻辑块补充注释（意图、边界、异常路径）。
• Controller/Service/ServiceImpl/Mapper 是否均保持注释一致（职责描述、入参出参、异常/返回约定）？
• 注释是否与当前实现一致（不保留过期说明）？

常用 JavaDoc 模板

Controller

/**
 * XXX 接口控制器。
 *
 * 职责：
 * - 接收 HTTP 请求并完成参数校验
 * - 调用应用/服务层完成业务编排
 * - 组装并返回统一响应
 */

Service / ServiceImpl

/**
 * XXX 领域服务。
 *
 * 职责：
 * - 承载跨聚合/跨实体的业务规则编排
 * - 保持领域逻辑内聚，避免将业务下沉为 CRUD 拼接
 */

Mapper

/**
 * XXX 数据访问层。
 *
 * 约束：
 * - 仅负责数据库读写与对象映射
 * - 不在 Mapper 内堆叠业务规则
 */

方法（通用）

/**
 * 执行 XXX 业务动作。
 *
 * @param xxx 业务参数含义说明
 * @return 返回值含义说明
 * @throws IllegalArgumentException 参数不合法时抛出
 */

逻辑块注释示例（非简单 CRUD）

public Result handle(Command cmd) {
  // 1) 参数校验与默认值处理

  // 2) 领域规则校验（状态机/幂等/权限等）

  // 3) 状态变更与持久化（事务边界）

  // 4) 事件发布/异步触发（若有）
  return Result.ok();
}