Java Coding Standards

affaan-m/ECC/docs/zh-CN/skills/java-coding-standards

作者 affaan-mef648e01899ba3e8dc6371642deaaf64b4477775无许可证275K 个星标收录于 2026年10月9日更新于 2026年10月9日仓库4天前更新

Spring Boot服务的Java编码标准:命名、不可变性、Optional用法、流、异常、泛型和项目布局。

AI 生成的概览

面向 Spring Boot 服务的 Java 17+ 编码规范,涵盖命名、不可变性、Optional、流、异常与项目布局。

功能
该技能提供一套面向 Java 17 及以上、可读且可维护的 Spring Boot 服务的 Java 编码规范。它给出命名、不可变性、Optional 用法、流管道、异常处理、泛型与类型安全、项目与包布局、格式化、日志、空值处理和测试期望的约定与代码示例。它还列出应避免的代码坏味道,例如过长参数列表、深层嵌套、魔法数字和静默捕获块。它只产出指导内容,不产出代码或文件。
适用场景
在 Spring Boot 项目中编写或审查 Java 代码时使用,或在需要强制执行命名、不可变性或异常处理约定时使用。它也适用于审查 Optional、流或泛型的用法,以及决定包和项目布局。
运行要求
无需任何工具、软件包或凭据;它只是说明性内容,不附带脚本。它假定项目为 Java 17+ 的 Spring Boot 项目,并将 JUnit 5、AssertJ、Mockito 和 Bean Validation 作为约定提及。

Java 编码规范

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

何时激活

  • 在 Spring Boot 项目中编写或审查 Java 代码时
  • 强制执行命名、不可变性或异常处理约定时
  • 使用记录类、密封类或模式匹配(Java 17+)时
  • 审查 Optional、流或泛型的使用时
  • 构建包和项目布局时

核心原则

  • 清晰优于巧妙
  • 默认不可变;最小化共享可变状态
  • 快速失败并提供有意义的异常
  • 一致的命名和包结构

命名

java
// PASS: Classes/Records: PascalCasepublic class MarketService {}public record Money(BigDecimal amount, Currency currency) {}
// PASS: Methods/fields: camelCaseprivate final MarketRepository marketRepository;public Market findBySlug(String slug) {}
// PASS: Constants: UPPER_SNAKE_CASEprivate static final int MAX_PAGE_SIZE = 100;

不可变性

java
// PASS: Favor records and final fieldspublic record MarketDto(Long id, String name, MarketStatus status) {}
public class Market {  private final Long id;  private final String name;  // getters only, no setters}

Optional 使用

java
// PASS: Return Optional from find* methodsOptional<Market> market = marketRepository.findBySlug(slug);
// PASS: Map/flatMap instead of get()return market    .map(MarketResponse::from)    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

Streams 最佳实践

java
// PASS: Use streams for transformations, keep pipelines shortList<String> names = markets.stream()    .map(Market::name)    .filter(Objects::nonNull)    .toList();
// FAIL: Avoid complex nested streams; prefer loops for clarity

异常

  • 领域错误使用非受检异常;包装技术异常时提供上下文
  • 创建特定领域的异常(例如,MarketNotFoundException)
  • 避免宽泛的 catch (Exception ex),除非在中心位置重新抛出/记录
java
throw new MarketNotFoundException(slug);

泛型和类型安全

  • 避免原始类型;声明泛型参数
  • 对于可复用的工具类,优先使用有界泛型
java
public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }

项目结构 (Maven/Gradle)

src/main/java/com/example/app/  config/  controller/  service/  repository/  domain/  dto/  util/src/main/resources/  application.ymlsrc/test/java/... (mirrors main)

格式化和风格

  • 一致地使用 2 或 4 个空格(项目标准)
  • 每个文件一个公共顶级类型
  • 保持方法简短且专注;提取辅助方法
  • 成员顺序:常量、字段、构造函数、公共方法、受保护方法、私有方法

需要避免的代码坏味道

  • 长参数列表 → 使用 DTO/构建器
  • 深度嵌套 → 提前返回
  • 魔法数字 → 命名常量
  • 静态可变状态 → 优先使用依赖注入
  • 静默捕获块 → 记录日志并处理或重新抛出

日志记录

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

Null 处理

  • 仅在不可避免时接受 @Nullable;否则使用 @NonNull
  • 在输入上使用 Bean 验证(@NotNull, @NotBlank)

测试期望

  • 使用 JUnit 5 + AssertJ 进行流畅的断言
  • 使用 Mockito 进行模拟;尽可能避免部分模拟
  • 倾向于确定性测试;没有隐藏的休眠

记住:保持代码意图明确、类型安全且可观察。除非证明有必要,否则优先考虑可维护性而非微优化。

来源与署名

来源:affaan-m/ECC位于docs/zh-CN/skills/java-coding-standards提交ef648e0

许可证: 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架