ataopro-alibaba-java-coding-guidelines

Alibaba Java開発規約

このスキルはAlibaba Java開発規約（略称：Alibaba開発規約）に基づいており、Javaコード規約のチェック、開発の指導、コードレビューに使用します。

トリガーとなるシナリオ

ユーザーが以下の意図を示した場合、このスキルが自動的に有効になります。

1. コード規約のチェック

• 「コード規約をチェックして」
• 「Javaコードをチェックして」
• 「コードレビュー」
• 「コードがAlibaba規約に準拠しているか確認して」
• 「コードに問題がないかチェックして」
• 「このコードをレビューして」

2. 開発規約の指定

• 「Alibaba開発規約を使用して」
• 「Alibaba規約に従って開発して」
• 「Alibaba開発マニュアルに従って」
• 「Alibaba開発規約に準拠して」
• 「Alibaba開発規約」
• 「規約に沿って書いて」

3. 改善提案

• 「Javaコードを最適化して」
• 「コードの改善案」
• 「規約に準拠したJavaコードの書き方」
• 「このコードをどう改善すればよいか」

---

主要規則のクイックリファレンス

1. 命名規則【必須】

規則	正例	反例
クラス名	UserDO, CacheServiceImpl, OrderDTO	userDo, User_Do
メソッド名／変数名	getUserById, localValue, inputUserId	get_user_by_id
定数	MAX_STOCK_COUNT, DEFAULT_TIMEOUT	MAX_COUNT, maxStockCount
ブール変数	deleted, active, isValid（booleanのみ）	isDeleted（POJO内）
パッケージ名	com.alibaba.open.util	com.Alibaba.Open.util

重要な規則：

• アンダースコアまたはドル記号で始まる／終わる名前は禁止
• ピンインと英語の混在は禁止
• 抽象クラス名は Abstract または Base で始める
• 例外クラス名は Exception で終える
• テストクラス名は Test で終える

2. 定数の定義【必須】

// ❌ 反例 - 魔法值
String key = "Id#taobao_" + tradeId;
cache.put(key, value);

// ✅ 正例
private static final String KEY_PREFIX = "Id#taobao_";
String key = KEY_PREFIX + tradeId;

// ❌ 反例 - 小写l易混淆
Long a = 2l;

// ✅ 正例
Long a = 2L;

3. OOP規約【必須】

equalsの呼び出し順序

// ❌ 反例 - 可能抛NPE
object.equals("test");

// ✅ 正例 - 推荐
"test".equals(object);
Objects.equals(object, "test");

ラッパークラスの比較

// ✅ 正例 - 使用equals
Integer a = 128;
Integer b = 128;
a.equals(b);  // true

// ❌ 反例 - == 比较
a == b;  // false (超出-128~127范围)

POJOクラスの規約

// ❌ 反例 - 使用基本类型
public class User {
    private int id;        // 基本类型
    private boolean isActive; // is前缀
    private Date gmtCreate = new Date(); // 默认值
}

// ✅ 正例
public class User {
    private Long id;           // 包装类型
    private Boolean active;    // 无is前缀
    private Date gmtCreate;    // 无默认值
}

アクセス制御は厳格に

// 工具类
public final class StringUtils {
    private StringUtils() {}  // 私有构造
}

// 方法可见性
private void internalMethod() {}     // 仅内部使用
protected void hookMethod() {}       // 供子类调用
public void publicApi() {}           // 对外暴露

4. コレクションの処理【必須】

hashCodeとequals

// ❌ 反例 - 只重写equals
@Override
public boolean equals(Object o) { ... }

// ✅ 正例 - 配对重写
@Override
public boolean equals(Object o) { ... }
@Override
public int hashCode() { ... }

subListをキャストしない

// ❌ 反例
ArrayList list = subList; // ClassCastException

// ✅ 正例
List list = subList;

Arrays.asList()は変更不可

// ❌ 反例
String[] str = {"a", "b"};
List list = Arrays.asList(str);
list.add("c"); // UnsupportedOperationException

// ✅ 正例 - 需要可修改列表
List<String> list = new ArrayList<>(Arrays.asList(str));

foreach内でremoveしない

// ❌ 反例 - ConcurrentModificationException
for (String item : list) {
    list.remove(item);
}

// ✅ 正例
Iterator<String> it = list.iterator();
while (it.hasNext()) {
    if (condition) {
        it.remove();
    }
}

// ✅ JDK8+ 推荐
list.removeIf(item -> condition);

Mapの走査

// ❌ 反例 - keySet遍历两次
for (String key : map.keySet()) {
    Object value = map.get(key);
}

// ✅ 正例 - entrySet一次遍历
for (Map.Entry<String, Object> entry : map.entrySet()) {
    String key = entry.getKey();
    Object value = entry.getValue();
}

// ✅ JDK8+ 推荐
map.forEach((k, v) -> { ... });

5. 並行処理【必須】

スレッドプールの作成

// ❌ 反例 - 可能导致OOM
ExecutorService executor = Executors.newFixedThreadPool(10);
ExecutorService executor = Executors.newCachedThreadPool();

// ✅ 正例
ExecutorService executor = new ThreadPoolExecutor(
    10,                          // corePoolSize
    50,                          // maximumPoolSize
    60L, TimeUnit.SECONDS,       // keepAliveTime
    new LinkedBlockingQueue<>(100), // workQueue
    new ThreadFactory() {
        @Override
        public Thread newThread(Runnable r) {
            Thread t = new Thread(r);
            t.setName("custom-pool-" + t.getId());
            return t;
        }
    },
    new ThreadPoolExecutor.AbortPolicy()
);

SimpleDateFormatはスレッドセーフではない

// ❌ 反例 - 线程不安全
private static final DateFormat DF = new SimpleDateFormat("yyyy-MM-dd");

// ✅ 方案1: ThreadLocal
private static final ThreadLocal<DateFormat> DF = 
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

// ✅ 方案2: JDK8+ 推荐
private static final DateTimeFormatter DTF = 
    DateTimeFormatter.ofPattern("yyyy-MM-dd");
LocalDate date = LocalDate.parse("2024-01-01", DTF);

マルチスレッドでのRandom

// ❌ 反例 - 线程竞争
Random random = new Random();
int randomValue = random.nextInt(100);

// ✅ 正例
int randomValue = ThreadLocalRandom.current().nextInt(100);

6. 制御文【必須】

// ❌ 反例 - 无大括号
if (condition)
    doSomething();

// ✅ 正例
if (condition) {
    doSomething();
}

// ❌ 反例 - switch无default
switch (status) {
    case 1: doThing(); break;
    case 2: doOther(); break;
}

// ✅ 正例 - 必须有default
switch (status) {
    case 1: doThing(); break;
    case 2: doOther(); break;
    default: logger.warn("Unknown status: {}", status);
}

7. コメント規約【必須】

/**
 * 根据用户ID获取用户信息
 *
 * @param userId 用户ID，不能为空
 * @return 用户信息，如果不存在返回null
 * @throws IllegalArgumentException if userId is null
 */
public UserDO getUserById(Long userId) {
    // 单行注释
    if (userId == null) {
        throw new IllegalArgumentException("userId不能为空");
    }
    // TODO(zhangsan: 2024-01-01) 等需求确认后实现缓存
    // FIXME(张三: 2024-01-15) 高并发下有性能问题，需要优化
    return userDAO.selectById(userId);
}

8. MySQL規約【必須】

規則	説明
主キーの命名	id または {表名}_id
インデックスの命名	idx_フィールド名, uniq_フィールド名
ブールフィールド	is_xxx / xxx_status
時刻フィールド	gmt_create, gmt_modified
削除フラグ	is_deleted（0/1）

-- ✅ 正例
CREATE TABLE user (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE,
    status TINYINT DEFAULT 0 COMMENT '0-正常 1-禁用',
    gmt_create DATETIME DEFAULT CURRENT_TIMESTAMP,
    gmt_modified DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    is_deleted TINYINT DEFAULT 0
);

CREATE INDEX idx_username ON user(username);
CREATE UNIQ INDEX uniq_phone ON user(phone);

9. 例外処理【必須】

// ❌ 反例
try {
    doSomething();
} catch (Exception e) {
    // 捕获所有异常
}

// ❌ 反例 - 吞掉异常
try {
    doSomething();
} catch (Exception e) {
    // 什么都不做
}

// ✅ 正例
try {
    doSomething();
} catch (SpecificException e) {
    logger.error("业务错误描述", e);
    throw new BusinessException("用户友好的错误信息");
}

// ✅ 正例 - try-with-resources
try (Connection conn = dataSource.getConnection()) {
    // 自动关闭
}

10. ログ規約【必須】

// ❌ 反例
logger.info("用户登录: " + userId);
logger.debug("debug info");
logger.error(e.getMessage()); // 丢失堆栈

// ✅ 正例 - 包含上下文
logger.info("用户登录成功, userId={}, ip={}", userId, ip);
logger.warn("库存不足, skuId={}, available={}", skuId, available);
logger.error("调用下游服务失败, service=order, error={}", e.getMessage(), e);

// 正确的日志级别
logger.error("系统异常", e);           // ERROR: 影响功能
logger.warn("业务校验失败", e);        // WARN: 需关注但不影响
logger.info("订单创建成功, orderId={}", orderId); // INFO: 关键节点
logger.debug("请求参数: {}", params);  // DEBUG: 调试信息

---

コードフォーマット規約

インデントとスペース

// ✅ 缩进4个空格，运算符左右各一空格，关键词与括号间有空格
public static void main(String[] args) {
    String say = "hello";
    int flag = 0;
    
    if (flag == 0) {
        System.out.println(say);
    } else if (flag == 1) {
        System.out.println("world");
    } else {
        System.out.println("ok");
    }
}

// ✅ 方法参数逗号后有空格
method("a", "b", "c");

改行規則

// ✅ 超120字符换行，缩进4空格
StringBuffer sb = new StringBuffer();
sb.append("zi").append("xin")...
   .append("huang")...
   .append("huang")...
   .append("huang");

// ✅ 多参数换行
method(args1, args2, args3, 
       args4, args5);

---

クイックチェックリスト

コードをコミットする前に、各項目を確認してください。

基本規約

• 命名が規約に準拠している（クラス名、メソッド名、定数など）
• パッケージ名がすべて小文字で、複数形ではない
• アンダースコア／ドル記号で始まる名前、または終わる名前がない

コード品質

• マジックナンバーを使わず、定数を定義している
• equals/hashCodeをペアでオーバーライドしている
• equalsの呼び出し順序が正しい
• ラッパークラスの比較にequalsを使用している
• POJOのプロパティにラッパー型を使用し、デフォルト値を設定していない

コレクション操作

• subListを正しく使用している
• Arrays.asListは変更不可である
• foreach内で正しくremoveしている
• Mapの走査にentrySetを使用している

並行処理の安全性

• スレッドプールを正しく作成している
• SimpleDateFormatがスレッドセーフになるようにしている
• RandomにThreadLocalRandomを使用している
• マルチスレッドで共有リソースをロックしている

制御文

• switchにdefaultがある
• if/whileに波括弧がある
• 多重ネストを避けている（ガード節を使用する）

コメントとログ

• クラス／メソッドにJavadocコメントがある
• ログにコンテキスト情報がある
• 例外を正しく処理している

---

関連ツール

IDEプラグイン

• IDEA: Alibaba Java Coding Guidelines
• Eclipse: Alibaba Java Coding Guidelines

Mavenプラグイン

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <configuration>
        <configLocation>checkstyle.xml</configLocation>
    </configuration>
</plugin>


<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
</plugin>

CheckStyleルール

Alibaba規約に基づくcheckstyle.xmlの設定を参照してください。

• キャメルケースの命名
• 波括弧の改行規則
• 4スペースのインデント

---

関連リソース

• Alibaba Java開発規約: https://developer.aliyun.com/article/1589859
• Alibaba Java Coding Guidelinesプラグイン: https://plugins.jetbrains.com/plugin/10032-alibaba-java-coding-guidelines
• GitHubリポジトリ: https://github.com/ataopro/ataopro-alibaba-java-coding-guidelines

---

更新履歴

v1.1.0 (2026-02-20)

• コードフォーマット規約の詳しい説明を追加
• MySQLテーブル作成規約の例を追加
• 例外処理のベストプラクティスを追加
• ログ規約の例を追加
• クイックチェックリストを拡充

v1.0.0 (2026-02-20)

• 初版
• Alibaba Java開発規約に基づいて編集
• 主要規約の10章を収録

---

著作権表示: 本スキルの内容はAlibaba Java開発規約をもとに編集したものであり、学習および参考目的に限り使用できます。 作者: ataopro バージョン: 1.1.0 ライセンス: MIT