Alibaba Java Development Guidelines Skill (嵩山版)#

在任何 Java 代码的编写、修改、审查场景中， 必须 严格遵守本规范。 规约等级：【强制】>【推荐】>【参考】

适用范围#

本 skill 在以下场景中自动激活并强制执行：

• 编写新的 Java 类 / 接口 / 枚举
• 修改已有的 Java 代码
• 代码审查 / Code Review
• 重构代码
• 生成 SQL / MyBatis XML 映射
• 设计数据库表结构
• 编写单元测试
• 定义 API 接口（前后端交互）

---

核心工作流程#

Step 1: 规则匹配#

根据当前代码任务，定位适用的规约分类：

场景定位规约定义类名/方法名/变量名references/naming.md — 命名风格定义常量references/constants.md — 常量定义编写/格式化代码references/code-format.md — 代码格式编写类/接口/对象references/oop.md — OOP 规约处理日期时间references/date-time.md — 日期时间使用集合（List/Map/Set）references/collections.md — 集合处理编写并发/多线程代码references/concurrency.md — 并发处理编写条件/循环逻辑references/control-flow.md — 控制语句编写注释references/comments.md — 注释规约设计 REST API / 前后端交互references/api-contract.md — 前后端规约正则 / BeanUtils / Velocity 等references/others.md — 其他异常处理 / 错误码references/exceptions.md — 异常日志日志打印references/logging.md — 日志规约编写单元测试references/unit-test.md — 单元测试安全检查 / 输入校验references/security.md — 安全规约建表 / 索引references/mysql-ddl.md — MySQL 建表规约索引设计references/mysql-index.md — MySQL 索引规约编写 SQLreferences/mysql-sql.md — MySQL SQL 语句MyBatis / ORM 映射references/orm.md — ORM 映射项目分层 / 依赖references/project-structure.md — 工程结构系统设计references/design.md — 设计规约

Step 2: 读取对应规约文件#

在生成/修改代码之前， 必须 读取对应 reference 文件，逐条对照【强制】规则。

Step 3: 生成/修改代码#

按照规约要求编写代码，注意：

• 【强制】规则 必须遵守，无例外
• 【推荐】规则 应尽量遵守
• 【参考】规则 可酌情采纳

Step 4: 自查清单#

代码生成后，逐项对照以下通用自查（适用于所有 Java 代码任务）：

命名

• 类名 UpperCamelCase，方法/变量 lowerCamelCase
• 常量全大写 + 下划线分隔
• 包名全小写，单数形式
• 无拼音、无下划线开头/结尾、无歧视性词语
• POJO 布尔变量不加 is 前缀
• 枚举类带 Enum 后缀，成员全大写

代码格式

• 4 空格缩进，无 Tab
• 单行 ≤ 120 字符
• 关键词与括号间有空格，运算符左右有空格
• UTF-8 编码，Unix 换行符

OOP

• 覆写方法加了 @Override
• equals 用常量/确定值调用，整型包装类用 equals 比较
• 浮点数用 BigDecimal 比较， BigDecimal 用 compareTo
• POJO 属性用包装类型，不设默认值
• POJO 有 toString
• 构造方法无业务逻辑

集合

• 覆写 equals 时覆写了 hashCode
• isEmpty() 判空而非 size()==0
• Collectors.toMap() 使用了 mergeFunction
• foreach 中无 remove/add 操作
• 集合初始化指定大小

并发

• 线程通过线程池创建，不用 Executors
• SimpleDateFormat 非 static 或用 ThreadLocal
• ThreadLocal 在 finally 中 remove()
• 锁在 try 外获取， finally 中释放

控制语句

• switch 有 default，每个 case 有 break/return
• if/else/for/while 使用大括号
• 三目运算符注意自动拆箱 NPE

异常日志

• 不用 catch 预检可规避的 RuntimeException
• 异常不捕获后抛弃，要处理或上抛
• finally 中不使用 return
• RPC/二方包用 Throwable 拦截
• 日志用 SLF4J，占位符拼接，有级别开关
• 生产环境无 System.out / e.printStackTrace()

MySQL

• 不用 SELECT *
• 主键 bigint unsigned 自增，必备字段 id, create_time, update_time
• 小数用 decimal，不用 float/double
• 无外键、无存储过程
• MyBatis 用 #{} 不用 ${}

安全

• SQL 参数绑定，无字符串拼接
• 用户输入参数校验
• 敏感数据脱敏
• CSRF 防护

---

快速规则速查#

命名速查#

text

类名:       UpperCamelCase   (例外: DO/DTO/VO/BO/AO/PO/UID)
方法/变量:  lowerCamelCase
常量:       ALL_UPPER_CASE
包名:       alllowercase.singular
数组:       int[] array      (不是 String args[])
枚举:       XxxEnum.SOME_VALUE
抽象类:     AbstractXxx / BaseXxx
异常类:     XxxException
测试类:     XxxTest
Service:    XxxService (接口) / XxxServiceImpl (实现)

代码格式速查#

text

缩进:       4 空格，禁止 Tab
行宽:       ≤ 120 字符
空格:       if/for/while + 空格 + (
           运算符左右各一空格
           注释 // 后一空格
括号:       左大括号前空格，不换行
编码:       UTF-8，Unix 换行

常见陷阱速查#

陷阱正确做法Integer a == Integer b``a.equals(b)``float a == float b``Math.abs(a-b) < epsilon 或 BigDecimal``BigDecimal(double)``new BigDecimal("0.1") 或 BigDecimal.valueOf(0.1)``BigDecimal.equals()``BigDecimal.compareTo()``new Date().getTime()``System.currentTimeMillis()``SimpleDateFormat staticThreadLocal<DateFormat> 或 DateTimeFormatter``Executors.newFixedThreadPool()``new ThreadPoolExecutor(...)``foreach 中 list.remove()``iterator.remove()``catch(Exception e) { }处理异常或上抛finally { return x; }不在 finally 中 returnSELECT *明确列出字段MyBatis ${param}``#{param}魔法值直接写定义为常量POJO boolean isDeleted``Boolean deleted (POJO 不用 is 前缀)long a = 2l``long a = 2L (大写 L)

---

参考文件#

完整规约来源: D:\ai\Java开发手册（嵩山版）.md

文件内容references/naming.md命名风格（19 条）references/constants.md常量定义（5 条）references/code-format.md代码格式（13 条）references/oop.mdOOP 规约（26 条）references/date-time.md日期时间（7 条）references/collections.md集合处理（21 条）references/concurrency.md并发处理（19 条）references/control-flow.md控制语句（14 条）references/comments.md注释规约（12 条）references/api-contract.md前后端规约（14 条）references/others.md其他（8 条）references/exceptions.md异常处理（13 条）+ 错误码（13 条）references/logging.md日志规约（13 条）references/unit-test.md单元测试（16 条）references/security.md安全规约（9 条）references/mysql-ddl.mdMySQL 建表规约（15 条）references/mysql-index.mdMySQL 索引规约（11 条）references/mysql-sql.mdMySQL SQL 语句（13 条）references/orm.mdORM 映射（10 条）references/project-structure.md工程结构（20 条）references/design.md设计规约（19 条）

---

版本#

版本日期作者变更1.0.02026-04-29endcy初始版本，基于嵩山版（1.7.0）完整规约