java-coding-standards

Java 编码规范

适用于 Spring Boot 和 Quarkus 服务中可读、可维护的 Java (17+) 代码规范。

使用时机

• 在 Spring Boot 或 Quarkus 项目中编写或审查 Java 代码时
• 强制执行命名、不可变性或异常处理约定时
• 使用记录类、密封类或模式匹配（Java 17+）时
• 审查 Optional、流或泛型的使用时
• 组织包和项目布局时
• [QUARKUS]：处理 CDI 作用域、Panache 实体或响应式管道时

工作原理

框架检测

在应用规范之前，从构建文件中确定框架：

• 构建文件包含 quarkus → 应用 [QUARKUS] 约定
• 构建文件包含 spring-boot → 应用 [SPRING] 约定
• 两者均未检测到 → 仅应用共享约定

核心原则

• 清晰优于巧妙
• 默认不可变；最小化共享可变状态
• 快速失败，提供有意义的异常
• 一致的命名和包结构
• [QUARKUS]：优先构建时处理而非运行时处理；尽可能避免运行时反射

示例

以下各节展示了具体的 Spring Boot、Quarkus 和共享 Java 示例，涵盖命名、不可变性、依赖注入、响应式代码、异常、项目布局、日志、配置和测试。

命名

// 通过：类/记录：PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// 通过：方法/字段：camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

// 通过：常量：UPPER_SNAKE_CASE
private static final int MAX_PAGE_SIZE = 100;

// 通过：[QUARKUS] JAX-RS 资源命名为 *Resource，而非 *Controller
public class MarketResource {}

// 通过：[SPRING] REST 控制器命名为 *Controller
public class MarketController {}

不可变性

// 通过：优先使用记录类和 final 字段
public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market {
  private final Long id;
  private final String name;
  // 仅提供 getter，无 setter
}

// 通过：[QUARKUS] Panache 活动记录实体使用 public 字段（Quarkus 约定）
@Entity
public class Market extends PanacheEntity {
  public String name;
  public MarketStatus status;
  // Panache 在构建时生成访问器；此处 public 字段是惯用写法
}

// 通过：[QUARKUS] Panache MongoDB 实体
@MongoEntity(collection = "markets")
public class Market extends PanacheMongoEntity {
  public String name;
  public MarketStatus status;
}

Optional 使用

// 通过：从 find* 方法返回 Optional
// [SPRING]
Optional<Market> market = marketRepository.findBySlug(slug);

// [QUARKUS] Panache
Optional<Market> market = Market.find("slug", slug).firstResultOptional();

// 通过：使用 map/flatMap 而非 get()
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

流最佳实践

// 通过：使用流进行转换，保持管道简短
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// 失败：避免复杂的嵌套流；优先使用循环以提高清晰度

依赖注入

// 通过：[SPRING] 构造器注入（优先于字段上的 @Autowired）
@Service
public class MarketService {
  private final MarketRepository marketRepository;

  public MarketService(MarketRepository marketRepository) {
    this.marketRepository = marketRepository;
  }
}

// 通过：[QUARKUS] 构造器注入
@ApplicationScoped
public class MarketService {
  private final MarketRepository marketRepository;

  @Inject
  public MarketService(MarketRepository marketRepository) {
    this.marketRepository = marketRepository;
  }
}

// 通过：[QUARKUS] 包私有字段注入（在 Quarkus 中可接受——避免代理问题）
@ApplicationScoped
public class MarketService {
  @Inject
  MarketRepository marketRepository;
}

// 失败：[SPRING] 使用 @Autowired 的字段注入
@Autowired
private MarketRepository marketRepository; // 应使用构造器注入

// 失败：[QUARKUS] 在需要拦截或延迟初始化时使用 @Singleton
@Singleton // 不可代理——应使用 @ApplicationScoped
public class MarketService {}

响应式模式 [QUARKUS]

// 通过：从响应式端点返回 Uni/Multi
@GET
@Path("/{slug}")
public Uni<Market> findBySlug(@PathParam("slug") String slug) {
  return Market.find("slug", slug)
      .<Market>firstResult()
      .onItem().ifNull().failWith(() -> new MarketNotFoundException(slug));
}

// 通过：非阻塞管道组合
public Uni<OrderConfirmation> placeOrder(OrderRequest req) {
  return validateOrder(req)
      .chain(valid -> persistOrder(valid))
      .chain(order -> notifyFulfillment(order));
}

// 失败：在 Uni/Multi 管道中进行阻塞调用
public Uni<Market> find(String slug) {
  Market m = Market.find("slug", slug).firstResult(); // 阻塞——破坏事件循环
  return Uni.createFrom().item(m);
}

// 失败：多次订阅共享的 Uni
Uni<Market> shared = fetchMarket(slug);
shared.subscribe().with(m -> log(m));
shared.subscribe().with(m -> cache(m)); // 重复订阅——应使用 Uni.memoize()

异常

• 对领域错误使用非检查异常；用上下文包装技术异常
• 创建领域特定异常（例如 MarketNotFoundException）
• 避免宽泛的 catch (Exception ex)，除非是重新抛出或集中记录

throw new MarketNotFoundException(slug);

集中式异常处理

// [SPRING]
@RestControllerAdvice
public class GlobalExceptionHandler {
  @ExceptionHandler(MarketNotFoundException.class)
  public ResponseEntity<ErrorResponse> handle(MarketNotFoundException ex) {
    return ResponseEntity.status(404).body(ErrorResponse.from(ex));
  }
}

// [QUARKUS] 选项 A：ExceptionMapper
@Provider
public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> {
  @Override
  public Response toResponse(MarketNotFoundException ex) {
    return Response.status(404).entity(ErrorResponse.from(ex)).build();
  }
}

// [QUARKUS] 选项 B：@ServerExceptionMapper（RESTEasy Reactive）
@ServerExceptionMapper
public RestResponse<ErrorResponse> handle(MarketNotFoundException ex) {
  return RestResponse.status(Status.NOT_FOUND, ErrorResponse.from(ex));
}

泛型和类型安全

• 避免原始类型；声明泛型参数
• 对可重用工具优先使用有界泛型

public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }

项目结构

[SPRING] Maven/Gradle

src/main/java/com/example/app/
  config/
  controller/
  service/
  repository/
  domain/
  dto/
  util/
src/main/resources/
  application.yml
src/test/java/... (与 main 镜像)

[QUARKUS] Maven/Gradle

src/main/java/com/example/app/
  config/              # @ConfigMapping、@ConfigProperty beans、Producers
  resource/            # JAX-RS 资源（非 "controller"）
  service/
  repository/          # PanacheRepository 实现（如果不使用活动记录）
  domain/              # JPA/Panache 实体、MongoDB 实体
  dto/
  util/
  mapper/              # MapStruct 映射器（如果使用）
src/main/resources/
  application.properties   # Quarkus 约定（YAML 支持需 quarkus-config-yaml）
  import.sql               # Hibernate 自动导入，用于开发/测试
src/test/java/... (与 main 镜像)

格式和风格

• 一致使用 2 或 4 个空格（项目标准）
• 每个文件一个公共顶层类型
• 保持方法简短且专注；提取辅助方法
• 成员顺序：常量、字段、构造器、公共方法、受保护、私有

应避免的代码坏味

• 长参数列表 → 使用 DTO/构建器
• 深层嵌套 → 提前返回
• 魔法数字 → 命名常量
• 静态可变状态 → 优先依赖注入
• 静默的 catch 块 → 记录并处理或重新抛出
• [QUARKUS]：本应使用 @ApplicationScoped 却用了 @Singleton——破坏代理和拦截
• [QUARKUS]：混合使用 quarkus-resteasy-reactive 和 quarkus-resteasy（经典）——选择其中一个栈
• [QUARKUS]：在同一有界上下文中同时使用 Panache 活动记录和仓库模式——选择其一

日志

// [SPRING] SLF4J
private static final Logger log = LoggerFactory.getLogger(MarketService.class);
log.info("fetch_market slug={}", slug);
log.error("failed_fetch_market slug={}", slug, ex);

// [QUARKUS] JBoss Logging（默认，构建时零成本）
private static final Logger log = Logger.getLogger(MarketService.class);
log.infof("fetch_market slug=%s", slug);
log.errorf(ex, "failed_fetch_market slug=%s", slug);

// [QUARKUS] 替代方案：使用 @Inject 简化日志
@Inject
Logger log; // CDI 注入，作用域为声明类

空值处理

• 仅在不可避免时接受 @Nullable；否则使用 @NonNull
• 对输入使用 Bean Validation（@NotNull、@NotBlank）
• [QUARKUS]：在 @BeanParam、@RestForm 和请求体参数上应用 @Valid

配置

// [SPRING] @ConfigurationProperties
@ConfigurationProperties(prefix = "market")
public record MarketProperties(int maxPageSize, Duration cacheTtl) {}

// [QUARKUS] @ConfigMapping（类型安全，构建时验证）
@ConfigMapping(prefix = "market")
public interface MarketConfig {
  int maxPageSize();
  Duration cacheTtl();
}

// [QUARKUS] 使用 @ConfigProperty 的简单值
@ConfigProperty(name = "market.max-page-size", defaultValue = "100")
int maxPageSize;

测试期望

共享

• JUnit 5 + AssertJ 用于流畅断言
• Mockito 用于模拟；尽可能避免部分模拟
• 优先确定性测试；无隐藏休眠

[SPRING]

• @WebMvcTest 用于控制器切片，@DataJpaTest 用于仓库切片
• @SpringBootTest 保留用于完整集成测试
• @MockBean 用于替换 Spring 上下文中的 bean

[QUARKUS]

• 普通 JUnit 5 + Mockito 用于单元测试（无 @QuarkusTest）
• @QuarkusTest 保留用于 CDI 集成测试
• @InjectMock 用于替换集成测试中的 CDI bean
• Dev Services 用于数据库/Kafka/Redis——在 Dev Services 足够时避免手动 Testcontainers 设置
• @QuarkusTestResource 用于自定义外部服务生命周期

// [SPRING] 控制器测试
@WebMvcTest(MarketController.class)
class MarketControllerTest {
  @Autowired MockMvc mockMvc;
  @MockBean MarketService marketService;
}

// [QUARKUS] 集成测试
@QuarkusTest
class MarketResourceTest {
  @InjectMock
  MarketService marketService;

  @Test
  void should_return_404_when_market_not_found() {
    given().when().get("/markets/unknown").then().statusCode(404);
  }
}

// [QUARKUS] 单元测试（无 CDI，无 @QuarkusTest）
@ExtendWith(MockitoExtension.class)
class MarketServiceTest {
  @Mock MarketRepository marketRepository;
  @InjectMocks MarketService marketService;
}

记住：保持代码有意图、有类型、可观察。优先考虑可维护性而非微优化，除非证明有必要。