Java 开发规范

参考来源: Google Java Style Guide、阿里巴巴 Java 开发手册

---

工具链

# Maven
mvn clean compile                    # 编译
mvn test                             # 运行测试
mvn verify                           # 运行所有检查

# Gradle
./gradlew build                      # 构建
./gradlew test                       # 运行测试

---

命名约定

类型	规则	示例
包名	全小写，域名反转	com.example.project
类名	大驼峰，名词/名词短语	UserService, HttpClient
方法名	小驼峰，动词开头	findById, isValid
常量	全大写下划线分隔	MAX_RETRY_COUNT
布尔返回值	is/has/can 前缀	isActive(), hasPermission()

---

类成员顺序

public class Example {
    // 1. 静态常量
    public static final String CONSTANT = "value";

    // 2. 静态变量
    private static Logger logger = LoggerFactory.getLogger(Example.class);

    // 3. 实例变量
    private Long id;

    // 4. 构造函数
    public Example() { }

    // 5. 静态方法
    public static Example create() { return new Example(); }

    // 6. 实例方法（公共 → 私有）
    public void doSomething() { }
    private void helperMethod() { }

    // 7. getter/setter（或使用 Lombok）
}

---

DTO/VO 类规范

规则	说明
❌ 禁止手写 getter/setter	DTO、VO、Request、Response 类一律使用 Lombok
✅ 使用 @Data	普通 DTO
✅ 使用 @Value	不可变 DTO
✅ 使用 @Builder	字段较多时配合使用
⚠️ Entity 类慎用 @Data	JPA Entity 的 equals/hashCode 会影响 Hibernate 代理

// ❌ 手写 getter/setter
public class UserDTO {
    private Long id;
    private String name;
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    // ... 大量样板代码
}

// ✅ 使用 Lombok
@Data
public class UserDTO {
    private Long id;
    private String name;
}

---

批量查询规范

规则	说明
❌ 禁止 IN 子句超过 500 个参数	SQL 解析开销大，执行计划不稳定
✅ 超过时分批查询	每批 500，合并结果
✅ 封装通用工具方法	避免每处手写分批逻辑

// ❌ 1700 个 ID 一次查询
List<User> users = userRepository.findByIdIn(allIds); // IN 子句过长