Java 编码规范
适用于 Spring Boot 服务中可读、可维护的 Java (17+) 代码的规范。
何时激活
- 在 Spring Boot 项目中编写或审查 Java 代码时
- 强制执行命名、不可变性或异常处理约定时
- 使用记录类、密封类或模式匹配（Java 17+）时
- 审查 Optional、流或泛型的使用时
- 构建包和项目布局时
核心原则
- 清晰优于巧妙
- 默认不可变；最小化共享可变状态
- 快速失败并提供有意义的异常
- 一致的命名和包结构
命名
// PASS: Classes/Records: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}
// PASS: Methods/fields: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}
// PASS: Constants: UPPER_SNAKE_CASE
private static final int MAX_PAGE_SIZE = 100;不可变性
// PASS: Favor records and final fields
public record MarketDto(Long id, String name, MarketStatus status) {}
public class Market {
private final Long id;
private final String name;
// getters only, no setters
}Optional 使用
// PASS: Return Optional from find* methods
Optional<Market> market = marketRepository.findBySlug(slug);
// PASS: Map/flatMap instead of get()
return market
.map(MarketResponse::from)
.orElseThrow(() -> new EntityNotFoundException("Market not found"));Streams 最佳实践
// PASS: Use streams for transformations, keep pipelines short
List<String> names = markets.stream()
.map(Market::name)
.filter(Objects::nonNull)
.toList();
// FAIL: Avoid complex nested streams; prefer loops for clarity异常
- 领域错误使用非受检异常；包装技术异常时提供上下文
- 创建特定领域的异常（例如，
MarketNotFoundException） - 避免宽泛的
catch (Exception ex)，除非在中心位置重新抛出/记录
throw new MarketNotFoundException(slug);泛型和类型安全
- 避免原始类型；声明泛型参数
- 对于可复用的工具类，优先使用有界泛型
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.yml
src/test/java/... (mirrors main)格式化和风格
- 一致地使用 2 或 4 个空格（项目标准）
- 每个文件一个公共顶级类型
- 保持方法简短且专注；提取辅助方法
- 成员顺序：常量、字段、构造函数、公共方法、受保护方法、私有方法
需要避免的代码坏味道
- 长参数列表 → 使用 DTO/构建器
- 深度嵌套 → 提前返回
- 魔法数字 → 命名常量
- 静态可变状态 → 优先使用依赖注入
- 静默捕获块 → 记录日志并处理或重新抛出
日志记录
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 进行模拟；尽可能避免部分模拟
- 倾向于确定性测试；没有隐藏的休眠
记住：保持代码意图明确、类型安全且可观察。除非证明有必要，否则优先考虑可维护性而非微优化。