# Java Coding Standards

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

- **Type:** Skill
- **Install:** `agentstack add skill-xu-xiang-everything-claude-code-zh-java-coding-standards`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xu-xiang](https://agentstack.voostack.com/s/xu-xiang)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [xu-xiang](https://github.com/xu-xiang)
- **Source:** https://github.com/xu-xiang/everything-claude-code-zh/tree/main/docs/ja-JP/skills/java-coding-standards
- **Website:** https://oneskill.one

## Install

```sh
agentstack add skill-xu-xiang-everything-claude-code-zh-java-coding-standards
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Java 编码规范

适用于 Spring Boot 服务中易读且可维护的 Java (17+) 代码标准。

## 核心原则

- 清晰度优先于巧妙性
- 默认不可变；最小化共享的可变状态
- 抛出有意义的异常以实现早期失败（Fail fast）
- 一致的命名与包结构

## 命名

```java
// ✅ 类/记录（Record）: 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;
```

## 不可变性

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

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

## Optional 的使用

```java
// ✅ find* 方法返回 Optional
Optional market = marketRepository.findBySlug(slug);

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

## 流（Stream）最佳实践

```java
// ✅ 使用流进行转换，保持流水线（Pipeline）简洁
List names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

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

## 异常

- 对于领域错误（Domain errors）使用非检查异常（Unchecked Exceptions）；使用上下文包装技术异常
- 创建领域特定的异常（例如：`MarketNotFoundException`）
- 避免捕获过于宽泛的 `catch (Exception ex)`（除非在中心位置重新抛出或记录日志）

```java
throw new MarketNotFoundException(slug);
```

## 泛型与类型安全

- 避免使用原始类型（Raw types）；声明泛型参数
- 优先在可重用的工具类中使用受限泛型（Bounded Generics）

```java
public  Map indexById(Collection items) { ... }
```

## 项目结构 (Maven/Gradle)

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

## 格式与样式

- 始终一致地使用 2 或 4 个空格（遵循项目标准）
- 每个文件仅包含一个 public 顶级类型
- 保持方法短小且专注；提取助手方法（Helper methods）
- 成员顺序：常量、字段、构造函数、public 方法、protected、private

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

- 过长的参数列表 -> 使用 DTO 或建造者模式（Builder）
- 过深的嵌套 -> 使用早期返回（Early Return）
- 魔术数字 -> 使用命名常量
- 静态可变状态 -> 优先使用依赖注入（Dependency Injection）
- 沉默的 catch 块 -> 记录日志并采取行动，或者重新抛出

## 日志记录

```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 校验（Bean Validation，如 `@NotNull`、`@NotBlank`）

## 测试预期

- JUnit 5 + AssertJ 实现流式断言（Fluent Assertions）
- 使用 Mockito 进行打桩；尽可能避免使用部分打桩（Partial mocks）
- 优先选择确定性测试；严禁隐藏的 `sleep`

**记住**：保持代码的意图清晰、类型安全且可观测。除非证明确有必要，否则应优先优化可维护性而非微小的性能优化。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xu-xiang](https://github.com/xu-xiang)
- **Source:** [xu-xiang/everything-claude-code-zh](https://github.com/xu-xiang/everything-claude-code-zh)
- **License:** MIT
- **Homepage:** https://oneskill.one

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xu-xiang-everything-claude-code-zh-java-coding-standards
- Seller: https://agentstack.voostack.com/s/xu-xiang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.