java-dev

Java 開発 - Alibaba Coding Guidelines

概要

このスキルでは、Alibaba Java Coding Guidelines（Songshan Edition）に基づく包括的な Java 開発ガイダンスを提供します。命名規則、コーディング標準、並行処理、例外処理、データベース設計、セキュリティ、テスト、アーキテクチャ設計に関する業界のベストプラクティスに、すべての Java コードが従うようにします。

基本原則

Java コードを記述する際は、常に次の基本原則に従ってください。

1. コードの可読性：理解しやすく、保守しやすいコードを記述します
2. 一貫性：一貫した命名規則と書式規則に従います
3. 安全性を最優先：NPE、SQL インジェクション、並行処理の問題など、よくある落とし穴を防ぎます
4. パフォーマンスへの配慮：設計上の決定がパフォーマンスに与える影響を考慮します
5. テストカバレッジ：重要なコードに十分なユニットテストカバレッジを確保します

クイックリファレンス

命名規則

• クラス：UpperCamelCase（例：UserService、OrderController）
• メソッド／変数：lowerCamelCase（例：getUserById、userName）
• 定数：UPPER_SNAKE_CASE（例：MAX_COUNT、DEFAULT_SIZE）
• パッケージ：小文字を使用し、単語は1つが望ましい（例：com.company.module）

よくあるパターン

• 抽象クラス：Abstract* または Base* の接頭辞
• 例外クラス：*Exception の接尾辞
• テストクラス：*Test の接尾辞
• サービス実装：*Impl の接尾辞
• Boolean 型の変数：POJO クラスでは is 接頭辞を付けない
• DAO メソッド：get*（単一）、list*（複数）、count*、save*、remove*、update*

重要なルール

• ❌ コード内でマジックナンバーを直接使用しないでください
• ❌ 例外を処理せずに捕捉しないでください
• ❌ ラッパー型の比較に == を使用しないでください（equals() を使用してください）
• ❌ スレッドを直接作成しないでください（スレッドプールを使用してください）
• ❌ SQL クエリで SELECT * を使用しないでください
• ✅ SQL インジェクションを防ぐため、必ずプレースホルダー付きクエリを使用してください
• ✅ サイズが分かっている場合は、コレクションの初期容量を必ず指定してください
• ✅ finally ブロックでリソースを必ず閉じるか、try-with-resources を使用してください
• ✅ 外部入力を必ず検証してください

ワークフロー

1. コードを書く前に

詳細なガイドラインを確認してください。

• 命名規則について → naming-conventions.md を参照
• コーディング標準について → coding-standards.md を参照
• 並行処理について → concurrency.md を参照
• データベース設計について → database.md を参照
• セキュリティについて → security.md を参照
• テストについて → testing.md を参照
• デザインパターンについて → design.md を参照

2. コードを書く

記述しながら、次の項目を確認してください。

命名

• クラス名には UpperCamelCase を使用する
• メソッド名／変数名には lowerCamelCase を使用する
• 定数には UPPER_SNAKE_CASE を使用する
• 意味のある英語の名前を使用する（ピンインは使わない）

コード構造

• メソッドは80行未満にする
• クラス／メソッドごとに単一の責務を持たせる
• 適切なアクセス修飾子を使用する（デフォルトは private）
• オーバーライドしたメソッドには @Override を使用する

避けるべきよくある落とし穴

// ❌ Wrong: Magic numbers
if (status == 1) { ... }

// ✅ Correct: Named constants
private static final int STATUS_ACTIVE = 1;
if (status == STATUS_ACTIVE) { ... }

// ❌ Wrong: Comparing wrapper types with ==
Integer a = 128;
Integer b = 128;
if (a == b) { ... }  // May fail!

// ✅ Correct: Use equals()
if (a.equals(b)) { ... }

// ❌ Wrong: Empty catch block
try {
    doSomething();
} catch (Exception e) {
    // Silent failure
}

// ✅ Correct: Handle or rethrow
try {
    doSomething();
} catch (Exception e) {
    logger.error("Failed to do something", e);
    throw new BusinessException("Operation failed", e);
}

// ❌ Wrong: Creating threads directly
new Thread(() -> doWork()).start();

// ✅ Correct: Use thread pool
ExecutorService executor = new ThreadPoolExecutor(
    corePoolSize, maxPoolSize, keepAliveTime,
    TimeUnit.SECONDS, new LinkedBlockingQueue<>(),
    new ThreadFactoryBuilder().setNameFormat("worker-%d").build()
);
executor.submit(() -> doWork());

3. データベース操作

テーブル設計

• テーブル名：小文字とアンダースコアを使用する（例：user_order）
• 必須フィールド：id、create_time、update_time
• Boolean 型フィールド：is_* 接頭辞を使用する（例：is_deleted）
• ID には BIGINT UNSIGNED を使用する
• 金額には DECIMAL を使用する（FLOAT や DOUBLE は使用しない）

SQL のベストプラクティス

// ✅ Correct: Parameterized query
String sql = "SELECT id, user_name, email FROM user WHERE id = ?";
PreparedStatement ps = conn.prepareStatement(sql);
ps.setLong(1, userId);

// ✅ Correct: MyBatis parameter binding
@Select("SELECT * FROM user WHERE user_name = #{userName}")
User selectByUserName(@Param("userName") String userName);

// ❌ Wrong: String concatenation (SQL injection risk!)
String sql = "SELECT * FROM user WHERE user_name = '" + userName + "'";

4. 例外処理

例外の階層

• 具体的な例外型を使用する
• 復旧可能なエラーにはチェック例外を使用する
• プログラミングエラーには非チェック例外を使用する
• 例外メッセージには必ずコンテキストを含める

// ✅ Correct exception handling
public User getUserById(Long userId) {
    if (userId == null) {
        throw new IllegalArgumentException("userId cannot be null");
    }

    User user = userDao.selectById(userId);
    if (user == null) {
        throw new NotFoundException("User not found: " + userId);
    }

    return user;
}

// ✅ Correct logging with exception
try {
    processOrder(order);
} catch (Exception e) {
    logger.error("Failed to process order, orderId: {}", order.getId(), e);
    throw new BusinessException("订单处理失败", e);
}

5. 並行処理

スレッドセーフのルール

• Executors の代わりに ThreadPoolExecutor を使用する
• デバッグしやすいようにスレッドに名前を付ける
• 可視性の確保には volatile を、アトミック操作には AtomicXxx を使用する
• マルチスレッドコードでは SimpleDateFormat を避ける（DateTimeFormatter を使用する）
• ThreadLocal 変数をクリーンアップする

// ✅ Correct: Thread pool with proper configuration
ThreadPoolExecutor executor = new ThreadPoolExecutor(
    10,  // corePoolSize
    20,  // maximumPoolSize
    60L, // keepAliveTime
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(100),
    new ThreadFactoryBuilder().setNameFormat("order-processor-%d").build(),
    new ThreadPoolExecutor.CallerRunsPolicy()
);

// ✅ Correct: ThreadLocal cleanup
private static final ThreadLocal<User> USER_CONTEXT = new ThreadLocal<>();

public void processRequest() {
    try {
        USER_CONTEXT.set(getCurrentUser());
        // Process request
    } finally {
        USER_CONTEXT.remove();  // Critical: prevent memory leak
    }
}

6. セキュリティ

入力の検証

• すべての外部入力を検証します
• パラメーター化クエリを使用します（文字列連結は決して使用しません）
• XSS を防ぐために HTML 出力をサニタイズします
• CSRF 対策を実装します
• ログ内の機密データをマスキングします

// ✅ Correct: Input validation
public void createUser(UserCreateRequest request) {
    if (StringUtils.isBlank(request.getUserName())) {
        throw new ValidationException("用户名不能为空");
    }
    if (!ValidationUtils.isValidMobile(request.getMobile())) {
        throw new ValidationException("手机号格式不正确");
    }
    // Process...
}

// ✅ Correct: Sensitive data masking
logger.info("User login, mobile: {}", maskMobile(user.getMobile()));

7. 単体テスト

テスト基準

• テストクラスの命名規則：*Test
• テストメソッドの命名規則：test*
• カバレッジ目標：ステートメントカバレッジを最低 70% にします
• JUnit 5 と Mockito を使用します
• BCDE の原則（境界、正常系、設計、エラー）に従います

@ExtendWith(MockitoExtension.class)
public class UserServiceTest {

    @Mock
    private UserDao userDao;

    @InjectMocks
    private UserService userService;

    @Test
    @DisplayName("根据ID获取用户 - 正常情况")
    public void testGetUserById_Success() {
        // Given
        Long userId = 1L;
        User mockUser = new User();
        mockUser.setId(userId);
        mockUser.setUserName("test");
        when(userDao.selectById(userId)).thenReturn(mockUser);

        // When
        User result = userService.getUserById(userId);

        // Then
        assertNotNull(result);
        assertEquals(userId, result.getId());
        verify(userDao, times(1)).selectById(userId);
    }

    @Test
    @DisplayName("根据ID获取用户 - 参数为null")
    public void testGetUserById_NullParameter() {
        assertThrows(IllegalArgumentException.class, () -> {
            userService.getUserById(null);
        });
    }
}

コードレビューのチェックリスト

Java コードをレビューする際は、次の点を確認します。

命名規則とスタイル

• クラス名に UpperCamelCase を使用している
• メソッド名と変数名に lowerCamelCase を使用している
• 定数に UPPER_SNAKE_CASE を使用している
• コードにマジックナンバーがない
• 意味のある英語の名前を使用している（ピンインは使用しない）

コード品質

• メソッドが 80 行未満である
• 単一責任の原則に従っている
• 適切なアクセス修飾子を使用している
• 重複コードがない
• 例外を適切に処理している

安全性

• NPE のリスクがない（必要な箇所で null チェックを実施している）
• ラッパー型の比較に == ではなく equals() を使用している
• リソースを適切にクローズしている（try-with-resources または finally）
• 並行処理のコンテキストで使用する場合、スレッドセーフである
• 外部データの入力を検証している

データベース

• パラメーター化クエリを使用している（SQL インジェクションのリスクがない）
• 特定のカラムを選択している（SELECT * を使用していない）
• 適切なインデックスを定義している
• トランザクションの境界が適切である

パフォーマンス

• サイズが分かっている場合、コレクションの初期容量を指定している
• ループ内の文字列連結に StringBuilder を使用している
• 適切なデータ構造を選択している
• ループ内で不要なオブジェクトを生成していない

テスト

• 新しいコードに単体テストがある
• エッジケースを網羅している
• 例外ケースをテストしている
• 依存関係を適切にモックしている

リファレンスドキュメント

特定のトピックに関する詳細なガイドラインについては、次のリファレンスドキュメントを参照してください。

naming-conventions.md

クラス、メソッド、変数、パッケージ、ドメインモデルの包括的な命名規則です。

coding-standards.md

定数、フォーマット、OOP のルール、日付と時刻の処理、コレクション、制御文を含む詳細なコーディング規約です。

concurrency.md

スレッドプール、ロック、volatile、並行コレクション、一般的なパターンを網羅した包括的な並行処理ガイドラインです。

exception-logging.md

SLF4J を使用した例外処理のベストプラクティスとロギング基準です。

database.md

MySQL データベース設計ルール、インデックス戦略、SQL 最適化、ORM マッピング規則です。

security.md

入力検証、SQL インジェクション防止、XSS 対策、CSRF 防御、暗号化、機密データの取り扱いに関するセキュリティガイドラインです。

testing.md

単体テストの基準、フレームワーク（JUnit 5、Mockito）、カバレッジ要件、テストパターンです。

design.md

設計原則、レイヤードアーキテクチャ、ドメインモデル、デザインパターン、API 設計規則です。

一般的なシナリオ

シナリオ 1：新しいサービスクラスの作成

1. サービスの命名規則について naming-conventions.md を読みます
2. クラス構成について coding-standards.md を読みます
3. エラー処理について exception-logging.md を読みます
4. 上記のパターンに従って実装します
5. testing.md に従って単体テストを追加します

シナリオ 2：データベーステーブルの設計

1. テーブル設計ルールについて database.md を読みます
2. 必須フィールドとして id、create_time、update_time を設定します
3. 適切なデータ型を使用します（金額には DECIMAL、ID には BIGINT）
4. 適切なインデックスを追加します
5. 命名規則に従って対応する DO クラスを作成します

シナリオ 3：並行処理の実装

1. スレッドプールの設定については、concurrency.mdを参照します
2. 適切なパラメーターを指定してThreadPoolExecutorを使用します
3. デバッグしやすいようにスレッドに名前を付けます
4. ワーカースレッド内の例外を処理します
5. ThreadLocal 変数をクリーンアップします

シナリオ 4：セキュリティレビュー

1. セキュリティチェックリストについては、security.mdを参照します
2. 入力検証が実装されていることを確認します
3. SQL インジェクションの脆弱性がないか確認します
4. ログ内の機密データがマスキングされていることを確認します
5. 認証と認可を確認します

開発ワークフローとの統合

このスキルは開発プロセスにシームレスに統合できます。

1. 開発中：上記のクイックルールと、必要に応じて詳細なガイドラインを参照します
2. コードレビュー：チェックリストを使用して、準拠していることを確認します
3. リファクタリング：ガイドラインを適用して、既存のコードを改善します
4. オンボーディング：新しいチームメンバー向けのトレーニング資料として使用します

まとめ

このスキルにより、すべての Java コードが Alibaba の業界標準のコーディングガイドラインに準拠します。常に以下を優先してください。

• 巧妙さよりも可読性
• 利便性よりも安全性
• その場しのぎの修正よりも保守性
• 個人の好みよりも標準

迷った場合は、具体的なガイダンスについて詳細なリファレンスドキュメントを参照してください。