java-dev

Java 開発規約

参考資料：Google Java Style Guide、阿里巴巴 Java 開発手冊

---

ツールチェーン

# Maven
mvn clean compile                    # 编译
mvn test                             # 运行测试
mvn verify                           # 运行所有检查

# Gradle
./gradlew build                      # 构建
./gradlew test                       # 运行测试

---

命名規約

種類	ルール	例
パッケージ名	すべて小文字、ドメイン名を逆順にする	com.example.project
クラス名	アッパーキャメルケース、名詞／名詞句	UserService, HttpClient
メソッド名	ローワーキャメルケース、動詞で始める	findById, isValid
定数	すべて大文字、アンダースコアで区切る	MAX_RETRY_COUNT
真偽値を返すメソッド	is/has/can の接頭辞を付ける	isActive(), hasPermission()

---

クラスメンバーの順序

public class Example {
    // 1. 静态常量
    public static final String CONSTANT = "value";

    // 2. 静态变量
    private static Logger logger = LoggerFactory.getLogger(Example.class);

    // 3. 实例变量
    private Long id;

    // 4. 构造函数
    public Example() { }

    // 5. 静态方法
    public static Example create() { return new Example(); }

    // 6. 实例方法（公共 → 私有）
    public void doSomething() { }
    private void helperMethod() { }

    // 7. getter/setter（或使用 Lombok）
}

---

DTO/VO クラスの規約

ルール	説明
❌ getter/setter の手書きを禁止	DTO、VO、Request、Response クラスでは、すべて Lombok を使用します
✅ @Data を使用	通常の DTO
✅ @Value を使用	不変 DTO
✅ @Builder を使用	フィールドが多い場合は併用します
⚠️ Entity クラスでの @Data の使用は慎重に	JPA Entity の equals/hashCode は Hibernate プロキシに影響します

// ❌ 手写 getter/setter
public class UserDTO {
    private Long id;
    private String name;
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    // ... 大量样板代码
}

// ✅ 使用 Lombok
@Data
public class UserDTO {
    private Long id;
    private String name;
}

---

一括クエリの規約

ルール	説明
❌ IN 句のパラメーター数が 500 を超えることを禁止	SQL の解析コストが大きく、実行計画が不安定になります
✅ 超える場合は分割してクエリを実行	1 回あたり 500 件とし、結果を統合します
✅ 共通のユーティリティメソッドにまとめる	各所で分割処理を手書きするのを防ぎます

// ❌ 1700 个 ID 一次查询
List<User> users = userRepository.findByIdIn(allIds); // IN 子句过长

// ✅ 分批查询工具方法
public static <T, R> List<R> batchQuery(List<T> params, int batchSize,
                                         Function<List<T>, List<R>> queryFn) {
    List<R> result = new ArrayList<>();
    for (int i = 0; i < params.size(); i += batchSize) {
        List<T> batch = params.subList(i, Math.min(i + batchSize, params.size()));
        result.addAll(queryFn.apply(batch));
    }
    return result;
}

// 使用
List<User> users = batchQuery(allIds, 500, ids -> userRepository.findByIdIn(ids));

---

N+1 クエリの防止

ルール	説明
❌ ループ内での Repository/Mapper 呼び出しを禁止	stream/forEach/for 内で、反復のたびにクエリが実行されます
✅ ループの外で一括クエリを実行し、結果を Map に変換	クエリ回数を N から 1（または distinct 数）に減らします

// ❌ N+1：循环内逐行查询 count
records.forEach(record -> {
    long count = deviceRepo.countByDeviceId(record.getDeviceId()); // 每条触发一次查询
    record.setDeviceCount(count);
});

// ✅ 循环外批量查询 + Map 查找
List<String> deviceIds = records.stream()
    .map(Record::getDeviceId).distinct().collect(Collectors.toList());
Map<String, Long> countMap = deviceRepo.countByDeviceIdIn(deviceIds).stream()
    .collect(Collectors.toMap(CountDTO::getDeviceId, CountDTO::getCount));
records.forEach(r -> r.setDeviceCount(countMap.getOrDefault(r.getDeviceId(), 0L)));

よくある N+1 の状況と修正パターン：

状況	ループ内（❌）	ループ外（✅）
count	repo.countByXxx(id)	repo.countByXxxIn(ids) → Map<id, count>
findById	repo.findById(id)	repo.findByIdIn(ids) → Map<id, entity>
exists	repo.existsByXxx(id)	repo.findXxxIn(ids) → Set<id> + set.contains()

---

並行処理の安全性に関する規約

ルール	説明
❌ read-modify-write を禁止	残高を読み取ってから書き戻すと、並行処理時に更新が失われます
❌ フォールバックのない check-then-act を禁止	先に確認してから操作すると、並行処理時に条件が無効になります
✅ 原子的な更新 SQL を使用	UPDATE SET balance = balance + :delta WHERE id = :id
✅ または楽観ロックを使用	@Version フィールドと再試行の仕組みを組み合わせます
✅ 最終防衛策として一意インデックスを使用	重複挿入を防ぐ最後の防衛策です

// ❌ read-modify-write 竞态条件
PointsAccount account = accountRepo.findById(id);
account.setBalance(account.getBalance() + points); // 并发时丢失更新
accountRepo.save(account);

// ✅ 方案一：原子更新 SQL
@Modifying
@Query("UPDATE PointsAccount SET balance = balance + :points WHERE id = :id")
int addBalance(@Param("id") Long id, @Param("points") int points);

// ✅ 方案二：乐观锁
@Version
private Long version; // Entity 中添加版本字段

// ❌ check-then-act 无兜底（并发下可能重复结算）
if (!rewardRepo.existsByTenantIdAndPeriod(tenantId, period)) {
    rewardRepo.save(new RankingReward(...));
}

// ✅ 唯一索引兜底 + 异常捕获
// DDL: UNIQUE INDEX uk_tenant_period (tenant_id, ranking_type, period, rank_position)
try {
    rewardRepo.save(new RankingReward(...));
} catch (DataIntegrityViolationException e) {
    log.warn("重复结算已被唯一索引拦截: tenantId={}, period={}", tenantId, period);
}

---

例外処理

// ✅ 好：捕获具体异常，添加上下文
try {
    user = userRepository.findById(id);
} catch (DataAccessException e) {
    throw new ServiceException("Failed to find user: " + id, e);
}

// ✅ 好：资源自动关闭
try (InputStream is = new FileInputStream(file)) {
    // 使用资源
}

// ❌ 差：捕获过宽
catch (Exception e) { e.printStackTrace(); }

---

null 値の処理

// ✅ 使用 Optional
public Optional<User> findById(Long id) {
    return userRepository.findById(id);
}

// ✅ 参数校验
public void updateUser(User user) {
    Objects.requireNonNull(user, "user must not be null");
}

// ✅ 安全的空值处理
String name = Optional.ofNullable(user)
    .map(User::getName)
    .orElse("Unknown");

---

並行プログラミング

// ✅ 使用 ExecutorService
ExecutorService executor = Executors.newFixedThreadPool(10);
Future<Result> future = executor.submit(() -> doWork());

// ✅ 使用 CompletableFuture
CompletableFuture<User> future = CompletableFuture
    .supplyAsync(() -> findUser(id))
    .thenApply(user -> enrichUser(user));

// ❌ 差：直接创建线程
new Thread(() -> doWork()).start();

---

テスト規約（JUnit 5）

class UserServiceTest {
    @Test
    @DisplayName("根据 ID 查找用户 - 用户存在时返回用户")
    void findById_whenUserExists_returnsUser() {
        // given
        when(userRepository.findById(1L)).thenReturn(Optional.of(expected));

        // when
        Optional<User> result = userService.findById(1L);

        // then
        assertThat(result).isPresent();
        assertThat(result.get().getName()).isEqualTo("test");
    }
}

---

Spring Boot 規約

// ✅ 构造函数注入
@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;
    private final EmailService emailService;
}

// ✅ REST Controller
@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    public ResponseEntity<UserDto> findById(@PathVariable Long id) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
}

認証フィルターのフォールバック原則

ルール	説明
✅ optional-auth パスで無効／期限切れ／不完全な token に遭遇した場合は、匿名アクセスにフォールバック	401/403 を返してはいけません
❌ 一部の認証情報しか持たないユーザーの体験を、匿名ユーザーより悪くすることを禁止	例：公開インターフェースで一時 token に対して 403 を返す

循環依存の防止（Spring Boot 3.x）

Spring Boot 3.x では、デフォルトでコンストラクターの循環依存が禁止されています。大規模な Service から子 Service を切り出す場合は、依存の方向を必ず確認してください。

対処方法	優先度	適用場面
共通メソッドを独立したユーティリティクラスに切り出す	✅ 第一選択	純粋なユーティリティメソッド（例：resolveTenantIds）
@Lazy フィールドインジェクション	⚠️ 緊急対応	双方向の呼び出しが本当に必要な場合
Function<> コールバック	⚠️ 代替案	柔軟ですが、複雑さが増します

// ❌ 拆分后子服务回调父服务 → 循环依赖
@RequiredArgsConstructor
public class ReportInvoiceService {
    private final ReportService reportService; // 启动失败！
}

// ✅ 提取公共方法到独立类
@Component
public class TenantHelper {
    public List<Long> resolveTenantIds(Long tenantId) { ... }
}

詳細は refactor-safety skill の「落とし穴 #5」を参照してください

ページネーションパラメーターの規約（Spring Data JPA）

Spring Data JPA のページインデックスは 0 から始まります。ページネーションパラメーターをリファクタリングする際は、フロントエンドとバックエンドでインデックスの基準が一致していることを必ず確認してください。

ルール	説明
スタック全体で 0-based に統一	フロントエンド、Controller、Service、JPA のすべてで 0-based インデックスを使用します
Controller のデフォルト値は必ず 0 にする	@RequestParam(defaultValue = "0") int page
Service では page をそのまま使用	PageRequest.of(page, size) を使用し、page - 1 は行わないでください

// ❌ 错误：前端传 page=0，Controller 默认值 1，Service 内部 -1
@GetMapping("/list")
public Page<Product> list(@RequestParam(defaultValue = "1") int page) {
    return service.list(page);  // Service 内部 PageRequest.of(page - 1, size)
}
// 问题：前端传 page=0 → Service 计算 page - 1 = -1 → 异常

// ✅ 正确：全栈统一 0-based
@GetMapping("/list")
public Page<Product> list(@RequestParam(defaultValue = "0") int page) {
    return service.list(page);  // Service 内部 PageRequest.of(page, size)
}

リファクタリングのチェックリスト：

• フロントエンドの呼び出しで page: 0（1 ページ目）を渡す
• Controller のデフォルト値が 0
• Service で PageRequest.of(page, size) を使用する（1 を減算しない）
• page=0 と page=1 のどちらでもデータが正常に返されることをテストする

---

入力検証の規約

ルール	説明
❌ @RequestBody に @Valid を付けないことを禁止	すべてのリクエストボディを検証する必要があります
✅ DTO フィールドに制約アノテーションを付ける	@NotBlank、@Size、@Pattern など
✅ 数値フィールドに範囲制約を付ける	@Min、@Max、@Positive など
✅ ページネーションパラメーターに上限を設ける	大量のクエリを防ぐため、size に必ず @Max(100) を付けます
✅ enum／状態フィールドを許可リストで検証する	カスタムバリデーターまたは @Pattern

よく使う DTO フィールド検証の早見表：

フィールドの種類	必須アノテーション	説明
数量 quantity	@NotNull @Min(1)	0 または負数を防止します（負数は逆方向の操作を引き起こす可能性があります）
金額 amount/price	@NotNull @Positive	または @DecimalMin("0.01")
ページネーション size	@Min(1) @Max(100)	size=999999 によってデータベースに過度な負荷がかかるのを防ぎます
ページネーション page	@Min(1)	ページ番号は 1 から始まります
パーセンテージ rate	@Min(0) @Max(100)	業務上の定義に応じた範囲を指定します

// ❌ 无校验，任意输入直接进入业务逻辑
@PostMapping("/ship")
public Result ship(@RequestBody ShippingRequest request) { ... }

// ✅ 完整校验
@PostMapping("/ship")
public Result ship(@RequestBody @Valid ShippingRequest request) { ... }

public record ShippingRequest(
    @NotNull Long orderId,
    @NotBlank @Size(max = 500) String shippingInfo,
    @Pattern(regexp = "pending|shipped|delivered") String giftStatus
) {}

// ❌ quantity 只有 @NotNull，负数会导致 Redis DECRBY 反向加库存
public record CreateOrderRequest(
    @NotNull Integer quantity  // 可提交 0 或负数
) {}

// ✅ 数量必须 >= 1
public record CreateOrderRequest(
    @NotNull @Min(1) Integer quantity
) {}

// ❌ 分页无上限，用户可传 size=999999
@GetMapping("/orders")
public Result list(@RequestParam int page, @RequestParam int size) { ... }

// ✅ 分页参数加约束
@GetMapping("/orders")
public Result list(@RequestParam @Min(1) int page,
                   @RequestParam @Min(1) @Max(100) int size) { ... }

---

パフォーマンス最適化

落とし穴	解決策
N+1 クエリ	「N+1 クエリの防止」の章を参照してください
ループ内での文字列連結	StringBuilder を使用します
ボクシング／アンボクシングの頻発	プリミティブ型のストリームを使用します
コレクションの初期容量を指定しない	new ArrayList<>(size)

第三方 API HTTP 客户端选型

规则	说明
❌ 避免 RestTemplate 默认客户端调用国内平台 API	默认 HttpURLConnection 的 POST 请求与微信/支付宝等 CDN 存在兼容性问题（已知触发 412/403）
✅ 优先用 java.net.http.HttpClient（JDK 11+）	现代 HTTP 客户端，无 CDN 兼容性问题
✅ 或配置 HttpComponentsClientHttpRequestFactory	让 RestTemplate 底层走 Apache HttpClient

诊断特征：HTTP 错误 + body 为空 + response headers 极简（只有 Connection/Content-Length）= CDN 层拦截，不是 API 本身的响应。同一 API 的 GET 正常但 POST 异常时，优先怀疑 HTTP 客户端兼容性。

---

Native SQL 规范

别名避免 MySQL 保留字

@Query(nativeQuery = true) 中的列别名如果是 MySQL 保留字，会导致语法错误。

高频踩坑保留字：year_month, order, status, key, value, name, type, date, time, rank, range, rows, column, user, role, group

规则	说明
✅ 使用短别名或缩写	ym, ord_status, cnt
✅ 或用反引号转义	`year_month`
❌ 禁止直接用保留字做别名	as year_month、as order、as rank

// ❌ year_month 是 MySQL 保留字（INTERVAL YEAR_MONTH）
@Query(value = """
    SELECT DATE_FORMAT(o.order_date, '%Y-%m') as year_month,
           COUNT(*) as cnt
    FROM orders o
    GROUP BY year_month
    """, nativeQuery = true)

// ✅ 改用非保留字别名
@Query(value = """
    SELECT DATE_FORMAT(o.order_date, '%Y-%m') as ym,
           COUNT(*) as cnt
    FROM orders o
    GROUP BY ym
    """, nativeQuery = true)

---

日志规范

// ✅ 参数化日志
log.debug("Finding user by id: {}", userId);
log.info("User {} logged in successfully", username);
log.error("Failed to process order {}", orderId, exception);

// ❌ 差：字符串拼接
log.debug("Finding user by id: " + userId);

---

详细参考

文件	内容
references/java-style.md	命名约定、异常处理、Spring Boot、测试规范
references/collections.md	不可变集合（Guava）、字符串分割
references/concurrency.md	线程池配置、CompletableFuture 超时
references/concurrency-db-patterns.md	Get-Or-Create 并发、N+1 防范、原子更新、Redis+DB 一致性
references/code-patterns.md	卫语句、枚举优化、策略工厂模式
references/date-time.md	日期加减、账期计算、禁止月末对齐
references/http-client.md	第三方 API HTTP 客户端选型、CDN 兼容性问题

---

📋 本回复遵循：java-dev - [具体章节]