CtrlK
BlogDocsLog inGet started
Tessl Logo

java-coding-standards

Spring Boot 服务的 Java 编码规范：命名、不可变性、Optional 使用、流（streams）、异常、泛型以及项目布局。

SKILL.md
Quality
Evals
Security

Java 编码规范 (Java Coding Standards)

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

何时激活 (When to Activate)

  • 在 Spring Boot 项目中编写或评审 Java 代码时
  • 强制执行命名、不可变性（immutability）或异常处理约定时
  • 使用 records、密封类（sealed classes）或模式匹配（pattern matching）（Java 17+）时
  • 评审 Optional、流（streams）或泛型（generics）的使用时
  • 规划包结构和项目布局时

核心原则 (Core Principles)

  • 清晰度优先于技巧性
  • 默认不可变；尽量减少共享的可变状态
  • 快速失败（Fail fast）并提供有意义的异常信息
  • 保持命名和包结构的一致性

命名 (Naming)

// ✅ 类/Records：大驼峰（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;

不可变性 (Immutability)

// ✅ 优先使用 records 和 final 字段
public record MarketDto(Long id, String name, MarketStatus status) {}

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

Optional 使用 (Optional Usage)

// ✅ find* 方法应返回 Optional
Optional<Market> market = marketRepository.findBySlug(slug);

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

流最佳实践 (Streams Best Practices)

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

// ❌ 避免复杂的嵌套流；为了清晰起见，优先使用循环

异常处理 (Exceptions)

  • 对领域错误使用非受检异常（unchecked exceptions）；通过上下文包装技术异常
  • 创建领域特定的异常（例如 MarketNotFoundException）
  • 避免捕获广义的 catch (Exception ex)，除非是在中心位置重新抛出或记录日志
throw new MarketNotFoundException(slug);

泛型与类型安全 (Generics and Type Safety)

  • 避免使用原始类型（raw types）；显式声明泛型参数
  • 对于可重用的工具类，优先使用有界泛型（bounded generics）
public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }

项目结构 (Project Structure - Maven/Gradle)

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

格式与风格 (Formatting and Style)

  • 一致地使用 2 或 4 个空格（遵循项目标准）
  • 每个文件仅包含一个公共顶级类型
  • 保持方法简短且聚焦；提取助手方法（helpers）
  • 成员排序：常量、字段、构造函数、公共方法、受保护方法、私有方法

应避免的代码异味 (Code Smells to Avoid)

  • 参数列表过长 → 使用 DTO/构建器（builders）
  • 层级嵌套过深 → 提前返回（early returns）
  • 魔法数字 → 命名常量
  • 静态可变状态 → 优先使用依赖注入（dependency injection）
  • 沉默的 catch 块 → 记录日志并处理或重新抛出

日志记录 (Logging)

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

空值处理 (Null Handling)

  • 仅在不可避免时接受 @Nullable；否则使用 @NonNull
  • 对输入使用 Bean 校验（Bean Validation，如 @NotNull, @NotBlank）

测试期望 (Testing Expectations)

  • 使用 JUnit 5 + AssertJ 进行流式断言
  • 使用 Mockito 进行 Mock；尽可能避免部分 Mock（partial mocks）
  • 优先使用确定性测试；严禁隐藏的 sleep 等待

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

Repository
xu-xiang/everything-claude-code-zh
Path

skills/java-coding-standards/SKILL.md

Commit

dfbf946

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill