前 言
《Java 开发手册》是阿里巴巴集团技术团队的集½智慧结晶和经验总结，经历了多次大规模
一线实战的检验及不断完善，公开到业界后，众多社区开发者踊跃参与，共同打磨完善，系统化地
整理成册。现代½件行业的高速发展对开发者的综合素质要求越来越高，因为不仅是编程知识点，
其它维度的知识点也会½响到½件的最终交付质量。比如：数据库的表结构和索引设计缺陷可½带
来½件上的架构缺陷或性½风险；工程结构混乱导致后续维护艰难；没有鉴权的漏洞代码易被黑客
攻击等等。所以本手册以
Java
开发者为中心视角，划分为编程规约、异常日志、单元测试、安全规
约、MySQL 数据库、工程结构、设计规约七个维度，再根据内容特征，细分成若干二级子目½。
另外，依据约束力强弱及故障敏感性，规约依次分为强制、推荐、参考三大类。在延伸信息中，
“说明”对规约做了适½扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要
提防的雷区，以及真实的错误案例。
手册的愿景是码出高效，码出质量。现代½件架构的复杂性需要协同开发完成，如½高效地协
同呢？无规矩不成方圆，无规范难以协同，比如，制订交通法规表面上是要限制行½权，实际上是
保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行驶？对½件来说，适½的规
范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过度个性化，以一种普遍认可的统一方
式一起做事，提升协½效率，降½沟通成本。代码的字里行间流淌的是½件系统的血液，质量的提
升是½可½少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。
我们已经在
2017
杭州云栖大会上发布了配套的
Java
开发规约
IDE
插件，阿里云效也集成了
代码规约扫描引擎。次年，发布
36
万字的配套详解图书《码出高效》，本书秉持“图胜于表，表胜
于言”的理念，深入浅出地将计算机基础、面向对象思想、JVM 探源、数据结构与集合、并发与多
线程、单元测试等知识客观、立½地呈现出来。紧扣学以致用、学以精进的目标，结合阿里巴巴实
践经验和故障案例，与底层源码解析融会贯通，娓娓道来。此书所得收入均捐赠公益事情，希望用
技术情怀帮助更多的人。
目½
前言
一、编程规约
................................................................................................................................................... 1
(一)
(二)
(三)
(四)
(五)
(六)
(七)
(八)
(九)
(一)
(二)
½名风格
...................................................................................................................................... 1
常量定义
...................................................................................................................................... 4
代码格式
...................................................................................................................................... 5
OOP
规约
.................................................................................................................................... 7
集合处理
....................................................................................................................................11
并发处理
....................................................................................................................................14
控制语句
....................................................................................................................................18
注释规约
....................................................................................................................................21
其它
............................................................................................................................................22
异常处理
....................................................................................................................................24
日志规约
....................................................................................................................................26
二、异常日志
.................................................................................................................................................24
三、单元测试
.................................................................................................................................................28
四、安全规约
.................................................................................................................................................30
五、MySQL 数据库
.......................................................................................................................................31
(一)
(二)
(三)
(四)
(一)
(二)
(三)
建表规约
....................................................................................................................................31
索引规约
....................................................................................................................................32
SQL
语句
....................................................................................................................................34
ORM
映射
..................................................................................................................................35
应用分层
....................................................................................................................................37
二方库依赖
................................................................................................................................38
服务器
........................................................................................................................................39
六、工程结构
.................................................................................................................................................37
七、设计规约
.................................................................................................................................................41
附
1：版本历史 ..............................................................................................................................................43
附
2：专有名词解释 ......................................................................................................................................44
（注：浏览时请½用
PDF
左侧导航栏）
Java
开发手册
版本号
1.5.0
制定团队
阿里巴巴与
Java
社区开发者
更新日期
2019.06.19
备注
华山版，新增
21
条，修改描述
112
处
一、 编程规约
(一)
½名风格
1.
【强制】代码中的½名均不½以下划线或美元符号开始，也不½以下划线或美元符号结束。
反例：_name
/ __name / $name / name_ / name$ / name__
2.
【强制】代码中的½名严禁½用拼音与英文混合的方式，更不允许直接½用中文的方式。
说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，纯拼音½名方式更要避免采用。
正例：renminbi
/ alibaba / taobao / youku / hangzhou
等½际通用的名称，可视同英文。
反例：DaZhePromotion
[打折] / getPingfenByName() [评分] / int
某变量
= 3
3.
【强制】类名½用
UpperCamelCase
风格，½以下情½例外：DO
/ BO / DTO / VO / AO
/ PO / UID
等。
正例：JavaServerlessPlatform
/ UserDO / XmlService / TcpUdpDeal / TaPromotion
反例：javaserverlessplatform
/ UserDo / XMLService / TCPUDPDeal / TAPromotion
4.
【强制】方法名、参数名、成员变量、局部变量½统一½用
lowerCamelCase
风格，必须遵
从驼峰½式。
正例：
localValue / getHttpMessage() / inputUserId
5.
【强制】常量½名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字
长。
正例：MAX_STOCK_COUNT
/ CACHE_EXPIRED_TIME
反例：MAX_COUNT
/ EXPIRED_TIME
6.
【强制】½象类½名½用
Abstract
或
Base
开头；异常类½名½用
Exception
结尾；测试类
½名以它要测试的类的名称开始，以
Test
结尾。
7.
【强制】类型与中括号紧挨相连来表示数组。
正例：定义整½数组
int[] arrayDemo;
反例：在
main
参数中，½用
String args[]来定义。
8.
【强制】POJO
类中布尔类型变量½不要加
is
前缀，否则部分框架解析会引起序列化错误。
说明：在本文
MySQL
规约中的建表约定第一条，表达是与否的值采用
is_xxx
的½名方式，所以，需要在
<resultMap>设½从 is_xxx
到
xxx
的映射关系。
反例：定义为基本数据类型
Boolean isDeleted
的属性，它的方法也是
isDeleted()，RPC
框架在反向解
析的时候，“误以为”对应的属性名称是
deleted，导致属性获取不到，进而抛出异常。
1/44
Java
开发手册
9.
【强制】包名统一½用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一½
用单数½式，½是类名如果有复数含义，类名可以½用复数½式。
正例：应用工具类包名为
com.alibaba.ai.util、类名为 MessageUtils（此规则参考 spring
的框架结构）
10.
【强制】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的½
名，½可读性降½。
说明：子类、父类成员变量名相同，即½是
public
类型的变量也是½够通过编译，而局部变量在同一方法
内的不同代码块中同名也是合法的，½是要避免½用。对于非
setter/getter
的参数名称也要避免与成员
变量名称相同。
反例：
public class
ConfusingName
{
public int
age;
//
非
setter/getter
的参数名称，不允许与本类成员变量同名
public void
getData(String
alibaba)
{
if(condition)
{
final int
money
=
531;
// ...
}
for
(int
i
=
0;
i
<
10;
i++)
{
//
在同一方法½中，不允许与其它代码块中的
money
½名相同
final int
money
=
615;
// ...
}
}
}
class
Son
extends
ConfusingName
{
//
不允许与父类的成员变量名称相同
public int
age;
}
11.
【强制】杜绝完全不规范的缩写，避免望文不知义。
反例：AbstractClass“缩写”½名成
AbsClass；condition“缩写”½名成 condi，此类随意缩写严重
降½了代码的可阅读性。
12.
【推荐】为了达到代码自解释的目标，任½自定义编程元素在½名时，½用½量完整的单词
组合来表达其意。
正例：在
JDK
中，表达原子更新的类名为：AtomicReferenceFieldUpdater。
反例：int
a
的随意½名方式。
13.
【推荐】在常量与变量的½名时，表示类型的名词放在词尾，以提升辨识度。
正例：startTime
/ workQueue / nameList / TERMINATED_THREAD_COUNT
反例：startedAt
/ QueueOfWork / listName / COUNT_TERMINATED_THREAD
14.
【推荐】如果模块、接口、类、方法½用了设计模式，在½名时需½现出具½模式。
说明：将设计模式½现在名字中，有利于阅读者快速理解架构设计理念。
2/44
京公网安备 11010802033920号
Copyright © 2005-2024 EEWORLD.com.cn, Inc. All rights reserved
评论