Alibaba Java Standard

阿里巴巴Java开发手册合规指南

概述

本指南全面遵循《阿里巴巴Java开发手册》，涵盖核心编码规范、最佳实践及易错点。包含命名规范、注释要求、依赖注入、异常处理、API返回格式、数据库字段命名的标准化解决方案。代码审查清单和自动化检测规则请参考 code-review.md；Spring/Spring Boot 等框架专属合规要求请参考 framework-compliance.md。

核心合规规则

1. 命名规范

基础命名规则

• 类名：使用大驼峰命名法（PascalCase），例如：UserController、OrderService
• 方法/变量名：使用小驼峰命名法（camelCase），例如：getUserById、userName
• 常量：使用大写+下划线分隔，例如：MAX_RETRY_TIMES、DEFAULT_PAGE_SIZE
• 数据库字段/Java属性：统一使用驼峰命名（禁止下划线），例如：userId（而非 user_id）
• 前端组件/函数：使用英文命名（与后端映射保持一致），例如：UserList.vue、getUserList()

禁用命名方式

• 禁止单字符命名（循环变量 i/j/k 除外）
• 禁止标识符中包含中文字符
• 禁止使用保留字（如 new、class、int）作为标识符
• 禁止名称首尾出现下划线（如 _userName、userName_）

2. 注释要求

强制注释规则

• 所有代码文件整体注释率 ≥ 20%
• 所有注释必须使用中文（禁止中英混用或纯英文）
• 所有方法必须包含完整的Javadoc注释（包含 @param、@return、@throws）
• 类级注释必须包含作者、创建日期、功能描述
• 核心业务逻辑行必须添加行注释（//）说明用途

注释格式标准

/**
 * 类级Javadoc注释（标准格式）
 * 
 * @author [开发者姓名]
 * @date 年-月-日
 * @description [类的详细功能描述]
 */
public class StandardClass {

    /**
     * 方法级Javadoc注释（标准格式）
     * 
     * @param param1 [参数1说明，包含数据类型和业务含义]
     * @param param2 [参数2说明]
     * @return [返回值说明，包含数据类型和业务含义]
     * @throws BusinessException [异常场景说明]
     */
    public String standardMethod(String param1, Integer param2) throws BusinessException {
        // 行注释：解释核心业务逻辑（保证注释率≥20%）
        String result = param1 + param2;
        return result;
    }
}