alibaba-java-manual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

阿里巴巴 Java 开发手册（黄山版）

Alibaba Java Development Manual (Huangshan Edition)

码出高效，码出质量。本 Skill 只描述什么情况下需要什么规范及对应参考文档；规约正文（含说明/正例/反例）见
references/
目录各文件。

Code efficiently, code with quality. This Skill only describes which convention is needed in which situation and the corresponding reference document; the full convention text, including explanations, positive examples, and negative examples, is available in each file in the
references/
directory.

何时激活此 Skill

When to Activate This Skill

编写或审查 Java 代码时（命名、格式、OOP、集合、并发、控制语句、注释）
处理异常、日志、错误码时
编写单元测试、评估测试覆盖率时
做安全审计、权限校验、敏感数据脱敏时
设计 MySQL 表结构、索引、编写 SQL、使用 ORM 时
规划工程分层、二方库依赖、服务器配置时
进行系统设计、用例/状态/时序/类/活动图选型时
制定项目编码规范、团队开发标准、Code Review 时

When writing or reviewing Java code, including naming, formatting, OOP, collections, concurrency, control statements, and comments
When handling exceptions, logs, and error codes
When writing unit tests or evaluating test coverage
When conducting security audits, permission checks, or sensitive data masking
When designing MySQL schemas and indexes, writing SQL, or using an ORM
When planning application layers, second-party library dependencies, or server configurations
When conducting system design or selecting use case, state, sequence, class, or activity diagrams
When defining project coding standards, team development standards, or conducting a Code Review

规约等级

Convention Levels

等级	标识	含义
强制	【强制】	必须遵守，违反将导致故障或严重问题
推荐	【推荐】	建议遵守，提升质量与可维护性
参考	【参考】	可选遵守，按实际情况灵活处理

Level	Indicator	Meaning
Mandatory	【Mandatory】	Must be followed; violations may cause failures or serious problems
Recommended	【Recommended】	Recommended to improve quality and maintainability
Reference	【Reference】	Optional; apply flexibly according to the actual situation

场景速查：什么情况查什么规范

Scenario Quick Reference: Which Convention to Consult

按场景定位需要遵守的规约及对应参考文档。审查/编写代码时对照下表，命中即去对应
references/
文件查阅正例反例。

Locate the conventions that should be followed and their corresponding reference documents according to the scenario. When reviewing or writing code, compare against the table below; whenever an item applies, consult the corresponding
references/
file for positive and negative examples.

1. 命名

1. Naming

场景	规约要点	参考文档
给类/接口命名	UpperCamelCase；DO/PO/DTO/BO/VO/UID 例外	01 § 命名风格
给方法/变量/参数命名	lowerCamelCase	01 § 命名风格
给常量命名	全大写+下划线，语义完整不嫌长（MAX_STOCK_COUNT）	01 § 命名风格
命名是否可用下划线/美元符开头结尾	禁止	01 § 命名风格
命名是否可拼音英文混用/纯中文	禁止；国际通用名（taobao/hangzhou）可视同英文	01 § 命名风格
命名是否可用歧视性词语	禁止（blackList→blockList，slave→secondary）	01 § 命名风格
布尔变量是否加 is 前缀	POJO 禁止加 is（防框架序列化错误）	01 § 命名风格
抽象类/异常类/测试类命名	抽象类 Abstract/Base 开头；异常 Exception 结尾；测试 Test 结尾	01 § 命名风格
数组定义方式	`int[] arrayDemo` （类型紧挨中括号）	01 § 命名风格
包名规范	全小写、点分隔单数、单词	01 § 命名风格
Service/DAO 接口与实现命名	实现类用 Impl 后缀与接口区分	01 § 命名风格
枚举类与成员命名	类名带 Enum 后缀；成员全大写下划线	01 § 命名风格
各层方法命名	get/list/count/save·insert/remove·delete/update 前缀	01 § 命名风格
领域模型命名	xxxDO/xxxDTO/xxxVO；禁止 xxxPOJO	01 § 命名风格

Scenario	Convention Summary	Reference Document
Naming a class/interface	UpperCamelCase; DO/PO/DTO/BO/VO/UID are exceptions	01 § Naming Style
Naming a method/variable/parameter	lowerCamelCase	01 § Naming Style
Naming a constant	Uppercase letters plus underscores; keep the meaning complete even if the name is long, such as MAX_STOCK_COUNT	01 § Naming Style
Whether underscores/dollar signs may appear at the beginning or end	Prohibited	01 § Naming Style
Whether Pinyin may be mixed with English or Chinese may be used alone	Prohibited; internationally recognized names such as taobao/hangzhou may be treated as English	01 § Naming Style
Whether discriminatory terms may be used	Prohibited, such as blackList→blockList and slave→secondary	01 § Naming Style
Whether Boolean variables should have an is prefix	Prohibited in POJOs to prevent framework serialization errors	01 § Naming Style
Naming abstract classes, exception classes, and test classes	Abstract classes start with Abstract/Base; exception classes end with Exception; test classes end with Test	01 § Naming Style
Array declaration style	`int[] arrayDemo` , with the type immediately adjacent to the brackets	01 § Naming Style
Package naming conventions	Lowercase, dot-separated, singular words	01 § Naming Style
Naming Service/DAO interfaces and implementations	Use the Impl suffix for implementation classes to distinguish them from interfaces	01 § Naming Style
Naming enum classes and members	Class names end with Enum; member names use uppercase letters and underscores	01 § Naming Style
Method naming at each layer	Use the get/list/count/save·insert/remove·delete/update prefixes	01 § Naming Style
Domain model naming	Use xxxDO/xxxDTO/xxxVO; xxxPOJO is prohibited	01 § Naming Style

2. 常量

2. Constants

场景	规约要点	参考文档
代码中出现未定义的字面量	禁止魔法值，必须预定义常量	01 § 常量定义
long 赋值后缀	大写 L，禁止小写 l	01 § 常量定义
浮点数后缀	统一大写 D/F	01 § 常量定义
常量类组织	按功能归类分开维护，禁止一个大而全常量类	01 § 常量定义
固定范围取值变量	优先用 enum	01 § 常量定义

Scenario	Convention Summary	Reference Document
An undefined literal appears in code	Magic values are prohibited; constants must be predefined	01 § Constant Definitions
long assignment suffix	Use uppercase L; lowercase l is prohibited	01 § Constant Definitions
Floating-point suffix	Use uppercase D/F consistently	01 § Constant Definitions
Organizing constant classes	Maintain separate classes by function; a single catch-all constant class is prohibited	01 § Constant Definitions
Variables with a fixed value range	Prefer an enum	01 § Constant Definitions

3. 代码格式

3. Code Formatting

场景	规约要点	参考文档
大括号/缩进/空格/换行	非空块左括号前不换行后换行；4 空格缩进禁 Tab	01 § 代码格式
运算符/关键词空格	二目三目运算符两边加空格；if/for/while 与括号间加空格	01 § 代码格式
单行长度	不超 120 字符，超长按规则换行	01 § 代码格式
方法行数	单方法不超 80 行	01 § 代码格式
文件编码/换行符	UTF-8；Unix 换行	01 § 代码格式
方法参数逗号后	必须加空格	01 § 代码格式

Scenario	Convention Summary	Reference Document
Braces/indentation/spaces/line breaks	For non-empty blocks, do not insert a line break before the opening brace and insert one after it; use four spaces for indentation; Tab is prohibited	01 § Code Formatting
Spaces around operators and keywords	Add spaces on both sides of binary and ternary operators; add a space between if/for/while and its parentheses	01 § Code Formatting
Single-line length	Must not exceed 120 characters; wrap long lines according to the rules	01 § Code Formatting
Method length	A method must not exceed 80 lines	01 § Code Formatting
File encoding/line endings	UTF-8; Unix line endings	01 § Code Formatting
After commas in method parameters	A space is required	01 § Code Formatting

4. OOP

场景	规约要点	参考文档
覆写父类方法	必须 @Override	01 § OOP 规约
equals 调用	常量或确定有值对象调 equals；推荐 Objects#equals	01 § OOP 规约
整型包装类比较	用 equals 不用 ==	01 § OOP 规约
浮点数等值判断	禁 == 与 equals；用误差范围或 BigDecimal	01 § OOP 规约
BigDecimal 比较	用 compareTo 不用 equals	01 § OOP 规约
BigDecimal 构造	禁 BigDecimal(double)；用 String 构造或 valueOf	01 § OOP 规约
DO 属性类型与字段类型	必须匹配（bigint→Long）	01 § OOP 规约
POJO/局部变量基本类型 vs 包装类型	POJO 与 RPC 必须包装类型；局部变量推荐基本类型	01 § OOP 规约
POJO 默认值/toString/serialVersionUID	不设默认值；必须 toString；新增属性不改 serialVersionUID	01 § OOP 规约
POJO 是否同时有 isXxx/getXxx	禁止并存	01 § OOP 规约
构造方法是否含业务逻辑	禁止，放 init 方法	01 § OOP 规约
循环内字符串拼接	用 StringBuilder.append	01 § OOP 规约
访问控制从严	工具类无私有构造；成员最小可见性	01 § OOP 规约

Scenario	Convention Summary	Reference Document
Overriding a parent class method	@Override is required	01 § OOP Conventions
Calling equals	Call equals on constants or objects guaranteed to have a value; Objects#equals is recommended	01 § OOP Conventions
Comparing wrapper integer types	Use equals instead of ==	01 § OOP Conventions
Testing floating-point equality	Both == and equals are prohibited; use a tolerance range or BigDecimal	01 § OOP Conventions
Comparing BigDecimal values	Use compareTo instead of equals	01 § OOP Conventions
Constructing BigDecimal	BigDecimal(double) is prohibited; use a String constructor or valueOf	01 § OOP Conventions
DO property type and field type	Must match, such as bigint→Long	01 § OOP Conventions
Primitive versus wrapper types for POJOs and local variables	POJOs and RPC parameters must use wrapper types; primitive types are recommended for local variables	01 § OOP Conventions
POJO default values/toString/serialVersionUID	Do not set default values; toString is required; do not change serialVersionUID when adding properties	01 § OOP Conventions
Whether a POJO may contain both isXxx and getXxx	They must not coexist	01 § OOP Conventions
Business logic in constructors	Prohibited; use an init method instead	01 § OOP Conventions
String concatenation inside a loop	Use StringBuilder.append	01 § OOP Conventions
Strict access control	Utility classes require a private constructor; members should have the minimum possible visibility	01 § OOP Conventions

5. 日期时间

5. Date and Time

场景	规约要点	参考文档
日期格式化年份	小写 y（禁 YYYY 跨年）	01 § 日期时间
月/分/时大小写	月=M，分=m，24时=H，12时=h	01 § 日期时间
取毫秒数	System.currentTimeMillis()，禁 new Date().getTime()	01 § 日期时间
java.sql.Date/Time/Timestamp	禁止使用	01 § 日期时间
硬编码一年 365 天	禁止，用 LocalDate.lengthOfYear()	01 § 日期时间

Scenario	Convention Summary	Reference Document
Year in date formatting	Use lowercase y; YYYY is prohibited because it may cross year boundaries	01 § Date and Time
Case for month/minute/hour	Month=M, minute=m, 24-hour=H, 12-hour=h	01 § Date and Time
Obtaining milliseconds	Use System.currentTimeMillis(); new Date().getTime() is prohibited	01 § Date and Time
java.sql.Date/Time/Timestamp	Prohibited	01 § Date and Time
Hard-coding 365 days per year	Prohibited; use LocalDate.lengthOfYear()	01 § Date and Time

6. 集合

6. Collections

场景	规约要点	参考文档
覆写 equals 是否覆写 hashCode	必须同时覆写	01 § 集合处理
判集合是否空	isEmpty()，禁 size()==0	01 § 集合处理
Stream toMap 重复 key	必须传 mergeFunction	01 § 集合处理
Stream toMap value 为 null	会抛 NPE，注意防范	01 § 集合处理
subList 强转 ArrayList	禁止	01 § 集合处理
集合转数组	toArray(new T[0])	01 § 集合处理
Arrays.asList 修改	禁 add/remove/clear	01 § 集合处理
foreach 中 remove/add	禁止，用 Iterator	01 § 集合处理
集合初始化容量	指定初始大小（HashMap 默认 16）	01 § 集合处理
遍历 Map	entrySet 或 forEach	01 § 集合处理
ConcurrentHashMap 存 null	禁止（抛 NPE）	01 § 集合处理

Scenario	Convention Summary	Reference Document
Overriding equals without overriding hashCode	hashCode must also be overridden	01 § Collection Handling
Checking whether a collection is empty	Use isEmpty(); size()==0 is prohibited	01 § Collection Handling
Stream toMap with duplicate keys	A mergeFunction must be provided	01 § Collection Handling
Stream toMap with a null value	It throws an NPE; guard against this case	01 § Collection Handling
Casting subList to ArrayList	Prohibited	01 § Collection Handling
Converting a collection to an array	Use toArray(new T[0])	01 § Collection Handling
Modifying the result of Arrays.asList	add/remove/clear are prohibited	01 § Collection Handling
Calling remove/add inside foreach	Prohibited; use an Iterator	01 § Collection Handling
Initial capacity of a collection	Specify an initial size, such as the default HashMap size of 16	01 § Collection Handling
Iterating over a Map	Use entrySet or forEach	01 § Collection Handling
Storing null in ConcurrentHashMap	Prohibited because it throws an NPE	01 § Collection Handling

7. 并发

7. Concurrency

场景	规约要点	参考文档
单例线程安全	必须保证	01 § 并发处理
创建线程命名	指定有意义线程名	01 § 并发处理
显式 new Thread	禁止，必须用线程池	01 § 并发处理
线程池创建方式	用 ThreadPoolExecutor，禁 Executors（OOM 风险）	01 § 并发处理
SimpleDateFormat 线程安全	线程不安全，禁 static 或加锁；JDK8 用 DateTimeFormatter	01 § 并发处理
ThreadLocal 回收	线程池场景必须 try-finally remove	01 § 并发处理
锁的性能	无锁优先；锁区块尽量小；对象锁优于类锁	01 § 并发处理
多资源加锁顺序	必须一致，防死锁	01 § 并发处理
lock 与 try 块位置	lock 在 try 之外	01 § 并发处理
tryLock 释放前	必须判断是否持锁	01 § 并发处理
并发更新防丢失	加锁或乐观锁（version）	01 § 并发处理
资金敏感信息锁策略	悲观锁	01 § 并发处理
多线程随机数	用 ThreadLocalRandom	01 § 并发处理
双重检查锁	目标属性须 volatile	01 § 并发处理

Scenario	Convention Summary	Reference Document
Thread safety of singletons	Must be guaranteed	01 § Concurrency Handling
Naming newly created threads	Specify a meaningful thread name	01 § Concurrency Handling
Explicitly creating a Thread with new Thread	Prohibited; use a thread pool	01 § Concurrency Handling
Creating a thread pool	Use ThreadPoolExecutor; Executors is prohibited because of OOM risks	01 § Concurrency Handling
Thread safety of SimpleDateFormat	It is not thread-safe; do not define it as static without locking; use DateTimeFormatter on JDK8	01 § Concurrency Handling
Cleaning up ThreadLocal	In thread-pool scenarios, remove it in a try-finally block	01 § Concurrency Handling
Lock performance	Prefer lock-free approaches; keep lock blocks as small as possible; prefer object locks over class locks	01 § Concurrency Handling
Lock ordering for multiple resources	The order must be consistent to prevent deadlocks	01 § Concurrency Handling
Position of lock relative to try	Place the lock outside the try block	01 § Concurrency Handling
Before releasing a tryLock	Check whether the lock is still held	01 § Concurrency Handling
Preventing lost updates during concurrent updates	Use locking or optimistic locking with a version	01 § Concurrency Handling
Locking strategy for financially sensitive information	Use pessimistic locking	01 § Concurrency Handling
Random numbers in multiple threads	Use ThreadLocalRandom	01 § Concurrency Handling
Double-checked locking	The target property must be volatile	01 § Concurrency Handling

8. 控制语句

8. Control Statements

场景	规约要点	参考文档
switch 缺 break/default	必须终止或注释说明；必须含 default	01 § 控制语句
switch 入参 String 为 null	必须先判空	01 § 控制语句
if/else/for/while 大括号	必须用大括号	01 § 控制语句
三目运算符 NPE	注意自动拆箱	01 § 控制语句
高并发等值判断退出	禁用等于，用区间判断	01 § 控制语句
if-else 层级	不超 3 层；用卫语句/策略/状态模式	01 § 控制语句
批量接口入参保护	必须做	01 § 控制语句
参数校验时机	低频/高开销/高可用/开放接口/敏感入口须校验	01 § 控制语句

Scenario	Convention Summary	Reference Document
switch without break/default	Each branch must terminate or include an explanatory comment; default is required	01 § Control Statements
switch argument is a null String	Check for null first	01 § Control Statements
Braces for if/else/for/while	Braces are required	01 § Control Statements
NPE caused by a ternary operator	Watch for automatic unboxing	01 § Control Statements
Equality-based termination under high concurrency	Prohibited; use range comparison	01 § Control Statements
if-else nesting depth	Must not exceed three levels; use guard clauses, the Strategy pattern, or the State pattern	01 § Control Statements
Input protection for batch APIs	Required	01 § Control Statements
Timing of parameter validation	Low-frequency, high-cost, high-availability, open-interface, and sensitive entry-point parameters must be validated	01 § Control Statements

9. 注释

9. Comments

场景	规约要点	参考文档
类/属性/方法注释	Javadoc `/** */` ，禁 `//`	01 § 注释规约
抽象方法注释	必须说明做什么、实现要求	01 § 注释规约
创建者与创建日期	所有类必须加	01 § 注释规约
枚举字段注释	必须有	01 § 注释规约
TODO/FIXME	注明标记人、时间、预计处理时间	01 § 注释规约
注释掉代码	上方说明原因或直接删除	01 § 注释规约

Scenario	Convention Summary	Reference Document
Class/field/method comments	Use Javadoc `/** */` ; `//` is prohibited	01 § Comment Conventions
Abstract method comments	Must explain what the method does and what implementations are required to do	01 § Comment Conventions
Creator and creation date	Required for every class	01 § Comment Conventions
Enum field comments	Required	01 § Comment Conventions
TODO/FIXME	Include the marker owner, time, and expected resolution time	01 § Comment Conventions
Commented-out code	Explain the reason above it or delete it	01 § Comment Conventions

10. 前后端

10. Frontend and Backend

场景	规约要点	参考文档
API 协议/路径/方法	生产 HTTPS；路径名词复数小写下划线；禁后缀	01 § 前后端规约
列表接口空返回	返回空数组[]/{}，禁 null	01 § 前后端规约
错误响应体	含 HTTP 状态码+errorCode+errorMessage+用户提示	01 § 前后端规约
JSON key 命名	lowerCamelCase	01 § 前后端规约
超大整数返回前端	用 String，禁 Long（精度丢失）	01 § 前后端规约
URL 参数长度	不超 2048 字节	01 § 前后端规约
时间格式	yyyy-MM-dd HH:mm:ss，GMT	01 § 前后端规约
翻页越界	前端<1 返首页；后端>总页数返末页	01 § 前后端规约

Scenario	Convention Summary	Reference Document
API protocol/path/method	Use HTTPS in production; path nouns should be plural, lowercase, and underscore-separated; suffixes are prohibited	01 § Frontend and Backend Conventions
Empty response from a list API	Return an empty array/object such as []/{}; null is prohibited	01 § Frontend and Backend Conventions
Error response body	Include the HTTP status code, errorCode, errorMessage, and a user-facing message	01 § Frontend and Backend Conventions
JSON key naming	lowerCamelCase	01 § Frontend and Backend Conventions
Returning very large integers to the frontend	Use String; Long is prohibited because it may lose precision	01 § Frontend and Backend Conventions
URL parameter length	Must not exceed 2048 bytes	01 § Frontend and Backend Conventions
Time format	yyyy-MM-dd HH:mm:ss, GMT	01 § Frontend and Backend Conventions
Pagination out of bounds	If the frontend value is less than 1, return the first page; if the backend value exceeds the total number of pages, return the last page	01 § Frontend and Backend Conventions

11. 异常

11. Exceptions

场景	规约要点	参考文档
可预检查的 RuntimeException	预检查规避，禁 catch（如 NPE）	02 § 异常处理
异常做流程控制	禁止	02 § 异常处理
捕获后不处理	禁止抛弃，须处理或向上抛	02 § 异常处理
事务中 catch 后回滚	必须手动回滚	02 § 异常处理
finally 关闭资源	必须；JDK7 用 try-with-resources	02 § 异常处理
finally 中 return	禁止	02 § 异常处理
RPC/二方包/动态类异常	用 Throwable 拦截（NoSuchMethodError）	02 § 异常处理
防 NPE 场景	拆箱/DB结果/集合元素/远程调用/Session/级联调用	02 § 异常处理
自定义异常	有业务含义，禁直接抛 RuntimeException/Exception/Throwable	02 § 异常处理
跨应用 RPC 返回	优先 Result+isSuccess()	02 § 异常处理

Scenario	Convention Summary	Reference Document
Pre-checkable RuntimeException	Prevent it in advance; catching it, such as catching NPE, is prohibited	02 § Exception Handling
Using exceptions for flow control	Prohibited	02 § Exception Handling
Catching an exception without handling it	Discarding it is prohibited; handle it or rethrow it	02 § Exception Handling
Rolling back after catching an exception in a transaction	A manual rollback is required	02 § Exception Handling
Closing resources in finally	Required; use try-with-resources on JDK7	02 § Exception Handling
Returning from finally	Prohibited	02 § Exception Handling
RPC/second-party package/dynamic class exceptions	Catch Throwable, such as NoSuchMethodError	02 § Exception Handling
NPE prevention scenarios	Unboxing, database results, collection elements, remote calls, Session access, and chained calls	02 § Exception Handling
Custom exceptions	Must have business meaning; directly throwing RuntimeException/Exception/Throwable is prohibited	02 § Exception Handling
Cross-application RPC return value	Prefer Result+isSuccess()	02 § Exception Handling

12. 日志

12. Logging

场景	规约要点	参考文档
日志 API 选择	用 SLF4J 门面，禁直接用 Log4j/Logback	02 § 日志规约
日志保存期限	至少 15 天；敏感操作相关不少于 6 个月	02 § 日志规约
字符串拼接	用占位符 `{}`	02 § 日志规约
trace/debug/info 输出前	必须日志级别开关判断	02 § 日志规约
重复打印	additivity=false	02 § 日志规约
System.out/printStackTrace	生产环境禁止	02 § 日志规约
异常日志内容	案发现场+堆栈信息	02 § 日志规约
日志输出对象	禁直接 JSON 工具转 String，用 toString	02 § 日志规约
敏感信息日志	脱敏	02 § 日志规约

Scenario	Convention Summary	Reference Document
Selecting a logging API	Use the SLF4J facade; calling Log4j/Logback directly is prohibited	02 § Logging Conventions
Log retention period	At least 15 days; at least six months for sensitive operations	02 § Logging Conventions
String concatenation	Use the `{}` placeholder	02 § Logging Conventions
Before outputting trace/debug/info logs	A log-level switch check is required	02 § Logging Conventions
Duplicate logging	Set additivity=false	02 § Logging Conventions
System.out/printStackTrace	Prohibited in production environments	02 § Logging Conventions
Exception log content	Include the incident context and stack trace	02 § Logging Conventions
Objects written to logs	Do not convert them to strings with a JSON tool; use toString	02 § Logging Conventions
Sensitive information in logs	Mask the data	02 § Logging Conventions

13. 错误码

13. Error Codes

场景	规约要点	参考文档
错误码格式	字符串 5 位 = 来源(A/B/C)+4位数字	02 § 错误码
全部正常	返回 00000	02 § 错误码
错误码是否含版本/等级	不体现	02 § 错误码
错误码直接给用户	禁止	02 § 错误码
第三方错误码转义	C→B，带原错误码	02 § 错误码
错误码完整列表	175 条	08 § 错误码列表

Scenario	Convention Summary	Reference Document
Error code format	A five-character string consisting of a source letter A/B/C and four digits	02 § Error Codes
Completely successful result	Return 00000	02 § Error Codes
Whether an error code includes a version or level	It must not	02 § Error Codes
Returning an error code directly to the user	Prohibited	02 § Error Codes
Translating a third-party error code	Convert C to B and retain the original error code	02 § Error Codes
Complete error code list	175 entries	08 § Error Code List

14. 单元测试

14. Unit Testing

场景	规约要点	参考文档
测试基本原则	AIR（自动化/独立/可重复）	03 单元测试
测试验证方式	用 assert，禁 System.out 人肉验证	03 单元测试
测试独立性	用例间禁互相调用/依赖顺序	03 单元测试
测试粒度	类级，一般方法级	03 单元测试
测试目录	src/test/java	03 单元测试
覆盖率目标	语句覆盖 70%；核心模块语句+分支 100%	03 单元测试
测试用例设计	BCDE（边界/正确/设计/错误）	03 单元测试
DB 相关测试	程序准备数据/自动回滚/前后缀标识	03 单元测试

Scenario	Convention Summary	Reference Document
Basic testing principles	AIR: Automated, Independent, Repeatable	03 Unit Testing
Test verification method	Use assertions; manual verification with System.out is prohibited	03 Unit Testing
Test independence	Test cases must not call one another or depend on execution order	03 Unit Testing
Test granularity	Generally class-level, with method-level tests where appropriate	03 Unit Testing
Test directory	src/test/java	03 Unit Testing
Coverage target	70% statement coverage; 100% statement and branch coverage for core modules	03 Unit Testing
Test case design	BCDE: Boundary, Correct, Design, Error	03 Unit Testing
DB-related tests	Prepare data in the program, roll back automatically, and use prefix/suffix identifiers	03 Unit Testing

15. 安全

15. Security

场景	规约要点	参考文档
用户页面/功能权限	必须校验（防水平越权）	04 安全规约
敏感数据展示	必须脱敏（手机 139****1219）	04 安全规约
SQL 参数	参数绑定，禁字符串拼接（防注入）	04 安全规约
请求参数校验	必须有效性验证（防 OOM/慢查询/SSRF/注入）	04 安全规约
HTML 输出用户数据	必须过滤转义（防 XSS）	04 安全规约
表单/AJAX 提交	必须 CSRF 校验	04 安全规约
URL 外部重定向	必须白名单过滤	04 安全规约
短信/邮件/支付等平台资源	防重放（数量/频率/验证码）	04 安全规约
文件上传	校验大小与类型	04 安全规约
配置文件密码	必须加密	04 安全规约

Scenario	Convention Summary	Reference Document
User page/function permissions	Validation is required to prevent horizontal privilege escalation	04 Security Conventions
Displaying sensitive data	Masking is required, such as 139****1219 for a phone number	04 Security Conventions
SQL parameters	Use parameter binding; string concatenation is prohibited to prevent injection	04 Security Conventions
Request parameter validation	Validate parameters for validity to prevent OOM, slow queries, SSRF, and injection	04 Security Conventions
Rendering user data in HTML	Filter and escape it to prevent XSS	04 Security Conventions
Form/AJAX submission	CSRF validation is required	04 Security Conventions
External URL redirection	Apply whitelist filtering	04 Security Conventions
Platform resources such as SMS, email, and payments	Prevent replay attacks through quantity/frequency limits and verification codes	04 Security Conventions
File uploads	Validate the file size and type	04 Security Conventions
Passwords in configuration files	Encryption is required	04 Security Conventions

16. 建表

16. Table Design

场景	规约要点	参考文档
是否字段命名	is_xxx，unsigned tinyint	05 § 建表规约
表名/字段名	小写或数字，禁大写、禁数字开头、禁两下划线间仅数字	05 § 建表规约
表名复数	禁止	05 § 建表规约
保留字	禁用（desc/range/match 等）	05 § 建表规约
索引命名	pk_/uk_/idx_	05 § 建表规约
小数类型	decimal，禁 float/double	05 § 建表规约
varchar 长度	不超 5000，超则 text 独立表	05 § 建表规约
必备字段	id/create_time/update_time	05 § 建表规约
物理删除	禁止，用逻辑删除	05 § 建表规约
分库分表时机	单表超 500 万行或 2GB	05 § 建表规约

Scenario	Convention Summary	Reference Document
Boolean field naming	is_xxx with unsigned tinyint	05 § Table Design Conventions
Table/field names	Use lowercase letters or numbers; uppercase letters, leading numbers, and numbers between two underscores are prohibited	05 § Table Design Conventions
Plural table names	Prohibited	05 § Table Design Conventions
Reserved words	Prohibited, such as desc/range/match	05 § Table Design Conventions
Index naming	pk_/uk_/idx_	05 § Table Design Conventions
Decimal type	Use decimal; float/double are prohibited	05 § Table Design Conventions
varchar length	Must not exceed 5000; use text in a separate table if it exceeds the limit	05 § Table Design Conventions
Required fields	id/create_time/update_time	05 § Table Design Conventions
Physical deletion	Prohibited; use logical deletion	05 § Table Design Conventions
When to partition databases or tables	A single table exceeds five million rows or 2 GB	05 § Table Design Conventions

17. 索引

17. Indexes

场景	规约要点	参考文档
唯一业务字段	必须建唯一索引（含组合字段）	05 § 索引规约
join 表数量	不超 3 表	05 § 索引规约
varchar 索引	必须指定索引长度	05 § 索引规约
左模糊/全模糊查询	禁止，走搜索引擎	05 § 索引规约
order by 利用索引	排序字段放组合索引最后	05 § 索引规约
覆盖索引	利用避免回表	05 § 索引规约
组合索引字段顺序	区分度最高最左；等号条件列前置	05 § 索引规约

Scenario	Convention Summary	Reference Document
Unique business field	A unique index is required, including for composite fields	05 § Index Conventions
Number of tables in a join	Must not exceed three	05 § Index Conventions
varchar index	The index length must be specified	05 § Index Conventions
Left-fuzzy or fully fuzzy queries	Prohibited; use a search engine	05 § Index Conventions
Using an index for order by	Place the sorting field last in a composite index	05 § Index Conventions
Covering index	Use it to avoid table lookups	05 § Index Conventions
Composite index field order	Place the column with the highest cardinality leftmost; place equality-condition columns first	05 § Index Conventions

18. SQL 语句

18. SQL Statements

场景	规约要点	参考文档
统计行数	count(*)，禁 count(列名)/count(常量)	05 § SQL 语句
判 NULL	ISNULL()	05 § SQL 语句
sum() 的 NPE	用 IFNULL(SUM(col),0)	05 § SQL 语句
分页 count 为 0	直接返回	05 § SQL 语句
外键与级联	禁止，应用层解决	05 § SQL 语句
存储过程	禁止	05 § SQL 语句
数据订正	先 select 确认再 update/delete	05 § SQL 语句
多表列名	必须加表别名限定	05 § SQL 语句
in 集合数量	控制 1000 以内	05 § SQL 语句

Scenario	Convention Summary	Reference Document
Counting rows	Use count(*); count(column)/count(constant) is prohibited	05 § SQL Statements
Checking for NULL	Use ISNULL()	05 § SQL Statements
NPE from sum()	Use IFNULL(SUM(col),0)	05 § SQL Statements
Pagination count is zero	Return immediately	05 § SQL Statements
Foreign keys and cascades	Prohibited; handle them in the application layer	05 § SQL Statements
Stored procedures	Prohibited	05 § SQL Statements
Correcting data	Run select to verify the records before update/delete	05 § SQL Statements
Column names from multiple tables	Qualify them with table aliases	05 § SQL Statements
Size of an IN collection	Keep it within 1,000 items	05 § SQL Statements

19. ORM 映射

19. ORM Mapping

场景	规约要点	参考文档
查询字段	禁 select *，明确写明字段	05 § ORM 映射
resultMap	必须定义，禁 resultClass；布尔 is_→xxx 映射	05 § ORM 映射
参数占位符	#{}，禁 ${}（注入风险）	05 § ORM 映射
queryForList(start,size)	不推荐（OOM 风险）	05 § ORM 映射
结果集载体	禁直接用 HashMap/Hashtable 接收	05 § ORM 映射
更新记录	必须同时更新 update_time	05 § ORM 映射
大而全更新接口	禁止，只更新改动字段	05 § ORM 映射

Scenario	Convention Summary	Reference Document
Query fields	select * is prohibited; list the fields explicitly	05 § ORM Mapping
resultMap	Must be defined; resultClass is prohibited; map is_ to xxx for Boolean fields	05 § ORM Mapping
Parameter placeholders	Use #{}; ${} is prohibited because of injection risks	05 § ORM Mapping
queryForList(start,size)	Not recommended because of OOM risks	05 § ORM Mapping
Result set container	Directly receiving results in HashMap/Hashtable is prohibited	05 § ORM Mapping
Updating records	update_time must be updated at the same time	05 § ORM Mapping
Update interface that modifies every field	Prohibited; update only the fields that changed	05 § ORM Mapping

20. 工程分层

20. Application Layering

场景	规约要点	参考文档
分层结构	开放API/终端显示/Web/Service/Manager/DAO	06 § 应用分层
分层异常处理	DAO 不打日志；Service 记盘；Web 不上抛跳错误页；开放接口返错误码	06 § 应用分层
领域模型	DO/DTO/BO/Query/VO 各层职责	06 § 应用分层
查询参数封装	超 2 参数用 Query，禁 Map	06 § 应用分层

Scenario	Convention Summary	Reference Document
Layered structure	Open API/Terminal Display/Web/Service/Manager/DAO	06 § Application Layering
Exception handling by layer	DAO does not log; Service writes logs; Web does not rethrow or jump directly to an error page; Open API returns an error code	06 § Application Layering
Domain models	Responsibilities of DO/DTO/BO/Query/VO at each layer	06 § Application Layering
Query parameter encapsulation	Use a Query object for more than two parameters; Map is prohibited	06 § Application Layering

21. 二方库依赖

21. Second-Party Library Dependencies

场景	规约要点	参考文档
GAV 命名	GroupId 最多 4 级；ArtifactId 产品线-模块名	06 § 二方库依赖
版本号	主.次.修订；起始 1.0.0	06 § 二方库依赖
线上依赖 SNAPSHOT	禁止	06 § 二方库依赖
同 GAV 不同 Version	禁止	06 § 二方库依赖
统一版本变量	依赖群定义统一版本变量	06 § 二方库依赖
pom 依赖管理	依赖放 dependencies，版本仲裁放 dependencyManagement	06 § 二方库依赖
接口返回值用枚举	禁止	06 § 二方库依赖

Scenario	Convention Summary	Reference Document
GAV naming	GroupId may contain at most four levels; ArtifactId uses product-line-module-name	06 § Second-Party Library Dependencies
Version number	Use major.minor.patch and start with 1.0.0	06 § Second-Party Library Dependencies
SNAPSHOT dependency in production	Prohibited	06 § Second-Party Library Dependencies
Same GAV with different versions	Prohibited	06 § Second-Party Library Dependencies
Unified version variables	Define unified version variables in the dependency group	06 § Second-Party Library Dependencies
pom dependency management	Put dependencies in dependencies and perform version arbitration in dependencyManagement	06 § Second-Party Library Dependencies
Using an enum as an interface return value	Prohibited	06 § Second-Party Library Dependencies

22. 服务器

22. Servers

场景	规约要点	参考文档
远程调用超时	必须设置	06 § 服务器
高并发 time_wait	调小 tcp_fin_timeout	06 § 服务器
文件句柄数	调大 fd	06 § 服务器
OOM dump	-XX:+HeapDumpOnOutOfMemoryError	06 § 服务器
Xms/Xmx	生产环境设为相同	06 § 服务器

Scenario	Convention Summary	Reference Document
Remote call timeout	Must be configured	06 § Servers
High-concurrency time_wait	Reduce tcp_fin_timeout	06 § Servers
File descriptor count	Increase fd	06 § Servers
OOM dump	-XX:+HeapDumpOnOutOfMemoryError	06 § Servers
Xms/Xmx	Set them to the same value in production environments	06 § Servers

23. 系统设计

23. System Design

场景	规约要点	参考文档
存储方案/数据结构设计	评审通过并沉淀文档	07 设计规约
用例图选用	User>1 类且 UseCase>5	07 设计规约
状态图选用	业务对象状态>3	07 设计规约
时序图选用	调用链涉及对象>3	07 设计规约
类图选用	模型类>5 且依赖复杂	07 设计规约
活动图选用	>2 对象协作且流程复杂	07 设计规约
弱依赖识别	必须设计降级/应急预案	07 设计规约
设计原则	单一职责/聚合优于继承/依赖倒置/开闭/DRY	07 设计规约
敏捷开发误区	≠讲故事+编码+发布	07 设计规约
无障碍设计	tab 聚焦/验证码多方式/自定义控件交互	07 设计规约

Scenario	Convention Summary	Reference Document
Storage solution/data structure design	Review and approval are required, followed by documentation	07 Design Conventions
Selecting a use case diagram	User>1 and UseCase>5	07 Design Conventions
Selecting a state diagram	Business object states>3	07 Design Conventions
Selecting a sequence diagram	Objects involved in the call chain>3	07 Design Conventions
Selecting a class diagram	Model classes>5 with complex dependencies	07 Design Conventions
Selecting an activity diagram	More than two collaborating objects with a complex process	07 Design Conventions
Identifying weak dependencies	A degradation strategy and contingency plan must be designed	07 Design Conventions
Design principles	Single responsibility, composition over inheritance, dependency inversion, open/closed principle, and DRY	07 Design Conventions
Agile development misconception	Agile is not equivalent to telling stories, writing code, and releasing	07 Design Conventions
Accessibility design	Tab focus, multiple CAPTCHA methods, and custom control interactions	07 Design Conventions

反模式红线（出现即停）

Anti-Pattern Red Lines (Stop Immediately When Found)

反模式	违反规约	参考
变量名拼音英文混用/中文	命名	01 § 命名风格
代码出现魔法值	常量	01 § 常量定义
用 Tab 缩进 / 单行超 120	格式	01 § 代码格式
`param.equals("test")`	OOP	01 § OOP 规约
Integer 用 == 比较	OOP	01 § OOP 规约
`new BigDecimal(0.1)`	OOP	01 § OOP 规约
POJO 布尔加 is 前缀	OOP	01 § OOP 规约
`new Date().getTime()`	日期	01 § 日期时间
foreach 里 remove/add	集合	01 § 集合处理
`Executors.newXxx` 建线程池	并发	01 § 并发处理
SimpleDateFormat 定义为 static 不加锁	并发	01 § 并发处理
finally 里 return	异常	02 § 异常处理
catch NPE 而非预检查	异常	02 § 异常处理
直接用 Log4j API	日志	02 § 日志规约
生产环境 System.out/printStackTrace	日志	02 § 日志规约
SQL 字符串拼接参数	安全	04 安全规约
select * 查询	ORM	05 § ORM 映射
用 ${} 传参	ORM	05 § ORM 映射
物理删除	建表	05 § 建表规约
用外键/级联/存储过程	SQL	05 § SQL 语句
线上依赖 SNAPSHOT	依赖	06 § 二方库依赖

Anti-Pattern	Violated Convention	Reference
Variable names mix Pinyin with English or use Chinese	Naming	01 § Naming Style
Magic values appear in code	Constants	01 § Constant Definitions
Tab indentation or a line longer than 120 characters	Formatting	01 § Code Formatting
`param.equals("test")`	OOP	01 § OOP Conventions
Comparing an Integer with ==	OOP	01 § OOP Conventions
`new BigDecimal(0.1)`	OOP	01 § OOP Conventions
Adding an is prefix to a POJO Boolean field	OOP	01 § OOP Conventions
`new Date().getTime()`	Date and time	01 § Date and Time
Calling remove/add inside foreach	Collections	01 § Collection Handling
Creating a thread pool with Executors.newXxx	Concurrency	01 § Concurrency Handling
Defining SimpleDateFormat as static without locking	Concurrency	01 § Concurrency Handling
Returning from finally	Exceptions	02 § Exception Handling
Catching NPE instead of checking in advance	Exceptions	02 § Exception Handling
Calling the Log4j API directly	Logging	02 § Logging Conventions
Using System.out/printStackTrace in production	Logging	02 § Logging Conventions
Concatenating SQL parameters as strings	Security	04 Security Conventions
Using a select * query	ORM	05 § ORM Mapping
Passing parameters with ${}	ORM	05 § ORM Mapping
Physical deletion	Table design	05 § Table Design Conventions
Using foreign keys, cascades, or stored procedures	SQL	05 § SQL Statements
Using a SNAPSHOT dependency in production	Dependencies	06 § Second-Party Library Dependencies

参考文档索引

Reference Document Index

详细规约正文（含说明、正例、反例、完整条目）存放于

references/

文件	内容	子章节
01-coding-conventions.md	一、编程规约	命名风格/常量定义/代码格式/OOP 规约/日期时间/集合处理/并发处理/控制语句/注释规约/前后端规约/其他
02-exception-logging.md	二、异常日志	错误码/异常处理/日志规约
03-unit-testing.md	三、单元测试	AIR/BCDE/覆盖率/数据准备
04-security.md	四、安全规约	权限/脱敏/注入/XSS/CSRF/上传/加密
05-mysql-database.md	五、MySQL 数据库	建表规约/索引规约/SQL 语句/ORM 映射
06-engineering-structure.md	六、工程结构	应用分层/二方库依赖/服务器
07-design-conventions.md	七、设计规约	存储评审/各类图选型/设计原则
08-appendix.md	附录	前言/版本历史/专有名词解释/错误码列表(175条)

来源：阿里巴巴集团技术团队 · 全球 Java 社区开发者
版本：1.7.1 黄山版（2022.02.03）
愿景：码出高效，码出质量

The full convention text, including explanations, positive examples, negative examples, and complete entries, is stored in the

references/

directory:

File	Content	Subchapters
01-coding-conventions.md	I. Programming Conventions	Naming Style/Constant Definitions/Code Formatting/OOP Conventions/Date and Time/Collection Handling/Concurrency Handling/Control Statements/Comment Conventions/Frontend and Backend Conventions/Other
02-exception-logging.md	II. Exceptions and Logging	Error Codes/Exception Handling/Logging Conventions
03-unit-testing.md	III. Unit Testing	AIR/BCDE/Coverage/Data Preparation
04-security.md	IV. Security Conventions	Permissions/Masking/Injection/XSS/CSRF/Uploads/Encryption
05-mysql-database.md	V. MySQL Databases	Table Design Conventions/Index Conventions/SQL Statements/ORM Mapping
06-engineering-structure.md	VI. Engineering Structure	Application Layering/Second-Party Library Dependencies/Servers
07-design-conventions.md	VII. Design Conventions	Storage Review/Diagram Selection/Design Principles
08-appendix.md	Appendix	Preface/Version History/Glossary of Proper Nouns/Error Code List (175 entries)

Source: Alibaba Group Technical Team · Global Java Community Developers
Version: 1.7.1 Huangshan Edition (2022.02.03)
Vision: Code efficiently, code with quality