Java编码规范

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在命名、不可变性、依赖注入、响应式代码、异常、项目布局、日志记录、配置和测试方面的具体示例。

命名

// PASS：类/记录：帕斯卡命名法
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// PASS：方法/字段：驼峰命名法
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

// PASS：常量：大写蛇形命名法
private static final int MAX_PAGE_SIZE = 100;

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

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

不可变性

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

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

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

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

Optional使用

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

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

// PASS：使用map/flatMap代替get()
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

流式处理最佳实践

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

// FAIL：避免复杂嵌套流；为清晰起见优先使用循环

依赖注入

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

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

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

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

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

// FAIL：[SPRING] 使用@Autowired进行字段注入
@Autowired
private MarketRepository marketRepository; // 应使用构造器注入

// FAIL：[QUARKUS] 需要拦截或懒初始化时使用@Singleton
@Singleton // 不可代理——应改用@ApplicationScoped
public class MarketService {}

响应式模式 [QUARKUS]

// PASS：从响应式端点返回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));
}

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

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

// FAIL：对共享的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 bean、Producers
  resource/            # JAX-RS资源（非"controller"）
  service/
  repository/          # PanacheRepository实现（如未使用活跃记录）
  domain/              # JPA/Panache实体、MongoDB实体
  dto/
  util/
  mapper/              # MapStruct映射器（如使用）
src/main/resources/
  application.properties   # Quarkus约定（通过quarkus-config-yaml支持YAML）
  import.sql               # Hibernate开发/测试自动导入
src/test/java/...（与main镜像）

格式和风格

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

应避免的代码坏味

• 长参数列表 → 使用DTO/构建器
• 深层嵌套 → 提前返回
• 魔术数字 → 命名常量
• 静态可变状态 → 优先依赖注入
• 静默捕获块 → 记录日志并处理或重新抛出
• [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注入，作用域限定于声明类

null处理

• 仅在不可避免时接受@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用于模拟；尽可能避免部分模拟
• 优先确定性测试；不要使用隐藏的sleep

[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;
}

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