《阿里巴巴 Java 开发手册》读书笔记

偶然看到阿里巴巴竟然出书了？？？趁着满减活动（节约节约....）我赶忙买来准备看看，刚拿到的时候掂量了好多下，总以为商家给我少发了一本书，结果打开才知道..原来这本书这么小....

编码规范的重要性

别人都说咱们是搬砖的码农，但咱们知道本身是追求个性的艺术家。也许咱们不会过多在乎本身的外表和穿着，但在咱们不羁的外表下，骨子里追求着代码的美、系统的美、设计的美，代码规范其实就是一个对程序美的定义。—— 引自 序

若是有一天在咱们的项目中看到了这样的代码：

或者是这样的代码：

这样美不美呢？或许看着是还挺美的，可是若是须要修改，是否是人傻啦？

那这样的代码呢？

做为一个对本身有必定要求的程序猿，是否是第一反应就是：

• 重写！
• 原做者是谁？锤他！

规范不一，就会像下图中的小鸭和小鸡对话同样，语言不通，一脸囧相。鸡同鸭讲也偏偏形容了人与人之间沟通的痛点，自说自话，没法达成一致意见。再举一个生活中的例子，交通规则靠左行驶仍是靠右行驶，二者孰好孰坏并不重要，重要的是必需要在统一的方向上通行，表面上限制了自由，但其实是保障了公众的人身安全。试想，若是没有规定靠右行驶，那样的路况确定拥堵不堪，险象环生。一样，过度自由随意、天马行空的代码会严重的伤害系统的健康，影响到可扩展性以及可维护性。

• 总结：代码规范很重要！

关于编码规范的三大圣战

众所周知，互联网公司的优点在于效率，它是企业核心竞争力。体如今产品开发领域，就是够沟通效率和研发效率。对于沟通效率的重要性，能够从程序猿三大 “编码理念之争” 提及：

• 缩进采用空格键，仍是 Tab 键
• if 单行语句须要大括号仍是不须要大括号
• 左大括号不换行，仍是单独另起一行

在美剧《硅谷》中，有这样的一个经典镜头：

• 程序媛：Kid? 咱们彷佛好久没有一块儿睡了。
• 程序猿：如今？不可能！我永远不会和使用空格来缩进的人睡在一块儿！

• 程序媛：（疯狂敲 space 气走了程序猿）
• 程序猿：（甩了一句）一个 Tab 能够代替 8个 空格！
  以后程序猿就由于视图一步跨下八个阶梯而摔了....

Tab 键和空格键的争议确实存在，而且在知乎上讨论得火热：写代码时，缩进使用 tab 仍是空格？

• 总结：使用 4 个空格好，在《阿里巴巴 Java 开发手册》中也明确支持了这样的作法。下面也引用一张图来调侃一下。

if 单语句是否须要换行，也是争论不休的话题。相对来讲，写过格式缩进类编程语言的开发者， 更加习惯于不加大括号。《手册》中明确 if/for 单行语句必须加大括号，由于单行语句的写法，容易在添加逻辑时引发视觉上的错误判断。此外，if 不加大括号还会有局部变量做用域的问题。

左大括号是否单独另起一行？由于 Go 语言的强制不换行，在这点上，“编程理念之争” 的硝烟味彷佛没有那么浓。若是必定要给一个理由，那么换行的代码能够增长一行，对于按代码行数考核工做量的公司员工，确定倾向于左大括号前换行。《手册》明确左大括号不换行！

• 总结： 其实，不少编程方式客观上没有对错之分，一致性很重要，可读性很重要，团队沟通效率很重要。

---

第1章：编程规约

这一章是对传统意义上的代码规范，包括变量命名、代码风格、控制语句、代码注释等基本的变成习惯，以及从高并发场景中提炼出来的集合处理技巧与并发多线程的注意事项。

1.1 命名风格

第一条：【强制】代码中的命名均不能如下划线或美圆符号开始，也不能如下划线或美圆符号结束。

• 反例：_name / $name / name_ / name$

尽管 $ 能够做为标识符使用，然而咱们应该尽可能避免对其使用。

• 缘由： $ 一般在编译器生成的标识符名称中使用，若是咱们也使用这个符号，可能会有一些意想不到的错误发生....
• 意想不到的错误示例：

package test;

public class User$VIP {
    public static void main(String[] args) {
        User user = new User();
        User.VIP vip = user.new VIP();
        vip.print();
    }
}

class User{
    class VIP{
        void print(){
            System.out.println("成员类");
        }
    }
}

仔细阅读如下，彷佛并无什么问题，代码也比较简单，但正在咱们编译的时候，IDEA提示咱们：

定义了重复的代码？归根到底，都是 $ 惹的祸！由于 $ 被编译器所使用，在源文件（.java 文件）编译成字节码（.class 文件）后，会称为顶层类型与嵌套类型之间的链接符。例如，若是存在一个顶层类 A，在其内声明了一个成员类 B，那么编译以后就会产生两个 class 文件，分别为 A.class 与 A$B.class。

就本程序来讲，会生成 3 个 class 文件（若是能够编译的话），分别是 User$VIP.class（顶层类）、User.class 与 User$VIP.class（User 类的成员类，也就是类 VIP）。因为试图存在两个 User$VIP.class 因此才会报错！

第三至第六条：【强制】

• 类名使用 UpperCamelCase 风格，方法名、参数名、成员变量、局部变量都赞成使用 lowerCamelCase 风格，必须听从驼峰形式。

• 变量命名所有大写，单词兼用下划线隔开，力求予以表达完整清楚，不要嫌名字太长。

  正例：MAX_STOCK_COUNT / PRIZE_NUMBER_EVERYDAY
  反例：MAX_COUNT / PRIZE_NUMBER

• 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类名开始，以 Test 结尾。

第八条：【强制】 POJO 类中布尔类型的变量都不要加 is 前缀，不然部分框架解析会引发序列化错误。

反例：定义为基本数据类型 Boolen isDeleted; 的属性，它的方法名称也是 isDeleted() ，RPC 框架在反向解析的时候，“误觉得” 对应的属性名称是 deleted ，致使属性获取不到抛出异常。

第十二条：【推荐】 若是模块、类、方法使用了设计模式，应在命名时体现出具体模式

• 说明： 将设计模式体如今名字中，有利于阅读者快速理解架构设计理念。

  正例：
  public class OrderFactory;
public class LoginProxy;
public class ResourceObserver;

第十三条：【推荐】 接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的间接性，并加上有效的 Javadoc 注释。尽可能不要在接口里定义变量，若是必定要定义变量，必须是与接口方法相关的，而且是整个应用的基础变量。

正例：
接口方法签名： void commit();
接口基础变量： String COMPANY = "alibaba";
反例：
接口定义方法： public abstract void commit();

• 说明： 若是 JDK8 中接口容许有默认实现，那么这个 default 方法，是对全部实现类都有价值的默认实现。

第十四条：接口和实现类的命名规则

• 1）：【强制】 对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务必定是接口，内部的实现类用 Impl 后缀与接口区别。

正例： CacheServiceImpl 实现 CacheServcie 接口

• 2）：【推荐】 若是是形容能力的接口名称，取对应的形容词为接口名（一般是 -able 的形式）。

  正例： AbstractTranslator 实现 Translatable。

1.2 常量定义

第二条：【强制】 long 或者 Long 初始赋值时，使用大写的 L，不能是小写的 l。小写的 l 容易跟数字 1 混淆，形成误解。

• 说明： Long a = 2l; 写得是数字的 21 仍是 Long 型的 2？

第三条：【推荐】 不要使用一个常量类维护全部变量，要按常量功能进行归类，分开维护。

• 说明： 大而全的变量类，非得使用查找功能才能定位到修改的常量，不利于理解和维护。

  正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在 ConfigConsts 下。

1.3 代码格式

public static void main(String[] args){
    // 注释的双斜线与注释内容之间有且仅有一个空格
    // 缩进 4 个空格
    String say = "hello";
    // 运算符的左右必须有 1 个空格
    int flag = 0;
    // 关键字 if 与括号之间必须有 1 个空格，括号内的 f与左括号、
    // 0 与右括号之间不须要空格
    if (flag == 0) {
        System.out.println(say);
    }
    // 左大括号前加空格且不换行；左大括号后换行
    if (flag == 1) {
        System.out.println("world");
    // 右大括号前换行，右大括号后有 else，不用换行
    } else {
        System.out.println("ok");
    // 在右大括号后直接结束，则必须换行
    }
}

第八条：【强制】 方法参数在定义和传入时，多个参数逗号后边必须加空格。

正例：下例中实参的“one”，后边必需要有一个空格。
method("one", "two", "three");

1.4 OOP 规约

第二条：【强制】 全部的复写方法，必须加 @Override 注解。

• 说明： getObject() 与 get0bject() 的问题。一个是字母 O,一个是数字 0，
  加 @Override 注解能够准确判断是否覆盖成功。另外，若是在抽象类中对方法签名进行修改，其实现类会立刻编译报错。

第七条：【强制】 全部相同类型的包装类对象之间值得比较，所有使用 equals 方法

• 说明： 对于 Intergre var = ? 在 -128~127 范围内的赋值， Integer 对象是在 IntegerCache.cache 中产生的，会复用已有的对象，这个区间内的 Integer 值能够直接使用 == 进行判断，可是这个区间以外的全部数据，都会在堆上产生，并不会复用已有对象。这是一个大坑，推荐使用 equals 方法进行判断。

第十二条：【强制】 POJO 类必须写 toString 方法。在使用 IDE 中的工具 source>generate toString 时，若是继承了另外一个 POJO 类，注意在前面加一下 super.toString。

• 说明： 在方法执行抛出异常时，能够直接调用 POJO 的 toString() 方法打印其属性值，便于排查问题。

1.5 集合处理

第七条：【强制】 不要在 foreach 循环里进行元素的 remove / add 操做。remove 元素请使用 Iterator 方式，若是并发操做，须要对 Iterator 对象加锁。

// 正例
Iterator<String> iterator = list.iterator();
while (iterator.hasNext()) {
    String item = iterator.next();
    if (删除元素的条件) {
        iterator.remove();
    }
}
// 反例
List<String> list = new ArrayList<>();
list.add("1");
list.add("2");
for (String item : list) {
    // 若是把 1 改成 2 再试一下看看是否相同
    if ("1".equals(item)) {
        list.remove(item);
    }
}

第十一条：【推荐】 高度注意 Map 类集合 K/V 能不能存储 null 值得状况

1.6 并发处理

第三条：【强制】 线程资源必须经过线程池提供，不容许在应用中自行显式建立线程。

• 说明： 使用线程池的好处是减小在建立和销毁线程上所消耗的时间以及系统资源，解决资源不足的问题。若是不适用线程池，有可能形成系统建立大量同类线程而致使消耗完内存或者 “过渡切换” 的问题。

1.7 控制语句

第二条：【强制】 在 if / else / for / while / do 语句中，必须使用大括号。即便只有一行代码，也应该避免采用单行的编码方式：if (condition) statements;

第三条：【强制】 在高并发场景中，避免使用 “等于” 判断做为终端或退出的条件

• 说明： 若是并发控制没有处理好，容易产生等值判断被 “击穿” 的状况，应使用大于或小于的区间判断条件来代替。

反例：判断剩余奖品数量等于 0 时，终止发放奖品，但由于并发处理错误致使奖品数量瞬间变成了负数，这样的话，活动没法终止。

第四条：【推荐】 在表达异常的分支时，尽可能少用 if-else 方式

• 说明： 若是不得不使用 if()...else if()...else... 方式表达逻辑，【强制】 避免后续代码维护困难，请勿超过 3 层。

// 正例：超过 3 层的 if-else 逻辑判断代码可使用卫语句、策略模式
// 状态模式等来实现，其中卫语句实例以下：
public void today() {
    if (isBusy()) {
        System.out.println("change time,");
        return;
    }

    if (isFree()) {
        System.out.println("go to travel.");
        return;
    }
    System.out.println("stay at home to learn Java");
    return;
}

1.8 注释规约

第一条：【强制】 类、类属性、类方法的注释必须使用 Javadoc 规范，使用 /**内容*/ 格式，不得使用 //xxx 方式

第二条：【强制】 全部的抽象方法（包括接口中的方法）必需要用 Javadoc 注释，除了返回值、参数、异常说明外，还必须指出该方法作什么事情，实现什么功能。

• 说明： 对子类的实现要求，或者调用注意事项，请一并说明。

第三条：【强制】 全部的类都必须添加建立者和建立日期。

1.9 其余

第三条：【强制】 后台输送给网页的变量必须加$!{var}——中间是感叹号

• 说明： 若是 var=null 或者不存在，那么 ${var} 会直接显示在页面上。

第四条：【强制】 注意 Math.random() 这个方法返回的是 double 类型，取值的范围 0≤x＜1（可以取到零值，注意除零异常），若是向获取整数类型的随机数，不要将 x 放大 10 的若干倍而后取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法。

第六条：【推荐】 不要在视图模板中加入任何复杂的逻辑。

• 说明： 根据 MVC 理论，视图的职责是展现，不要抢模型和控制器的工做。

---

第4章：安全规约

“安全生产，责任重于泰山。” 这句话一样适用于软件生产，本章主要说明编程中须要注意的比较基础的安全准则。

第一条：【强制】 隶属于用户我的的页面或者功能必须进行权限控制校验

• 说明： 放置皆有作水平权限校验就能够随意访问、修改、删除别人的数据，好比查看他人的私信内容、修改他人的订单。

第二条：【强制】 用户敏感数据禁止直接展现，必须对展现数据进行脱敏。

• 说明： 我的手机号码会显示为 158****9119，隐藏中间 4 位，防止我的隐私泄露。

第三条：【强制】 用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定，防止 SQL 注入，禁止字符串拼接 SQL 访问数据库。

第四条：【强制】 用户请求传入的任何参数必须作有效性验证

• 说明： 忽略参数校验可能致使以下状况。
  1）page size 过大致使内存溢出
  2）恶意 order by 致使数据库慢查询
  3）任意重定向
  4）SQL 注入
  5）反序列化注入
  6）正则输入源串拒绝服务 ReDoS
  Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，可是若是攻击人员使用的是特殊构造的字符串来验证，则有可能致使死循环。

第五条：【强制】 禁止向 HTML 页面输出未经安全过滤或未正确转义的用户数据。

第六条：【强制】 表单、AJAX 提交必须执行 CSRF 安全过滤

第七条：【强制】 在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制，如数量限制、疲劳度控制、验证码校验，避免被滥刷、资损。

• 说明：如注册时发送验证码到手机，若是没有限制次数和频率，那么能够利用此功能骚扰到其它用户，并形成短信平台资源浪费。

---

第5章：MySQL 数据库

5.1 建表规约

第二条：【强制】 表名、字段名必须使用小写字母或数字 ， 禁止出现数字开头，禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，由于没法进行预发布，因此字段名称须要慎重考虑。

• 说明： MySQL 在 Windows 下不区分大小写，但在 Linux 下默认区分大小写。所以，数据库名、代表、字段名都不容许出现任何大写字母，避免节外生枝。

  正例： getter _ admin ， task _ config ， level 3_ name
  反例： GetterAdmin ， taskConfig ， level 3 name

第四条：【强制】禁用保留字，如 desc 、 range 、 match 、 delayed 等，请参考 MySQL 官方保留字。

第五条： 【强制】主键索引名为 pk_ 字段名；惟一索引名为 uk _字段名 ； 普通索引名则为 idx _字段名。

• 说明： pk_ 即 primary key；uk _ 即 unique key；idx _ 即 index 的简称。

第六条：【强制】小数类型为 decimal ，禁止使用 float 和 double 。

• 说明：float 和 double 在存储的时候，存在精度损失的问题，极可能在值的比较时，获得不正确的结果。若是存储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数分开存储。

第八条：【强制】 varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，若是存储长度大于此值，定义字段类型为 text ，独立出来一张表，用主键来对应，避免影响其它字段索引效率。

第九条：【强制】表必备三字段： id , gmt _ create , gmt _ modified

• 说明：其中 id 必为主键，类型为 unsigned bigint 、单表时自增、步长为 1。 gmt _ create ,gmt _ modified 的类型均为 date _ time 类型。

第十条： 【推荐】表的命名最好是加上“业务名称_表的做用”。

正例： tiger _ task / tiger _ reader / mpp _ config

第十五条：【参考】合适的字符存储长度，不但节约数据库表空间、节约索引存储，更重要的是提高检索速度。

正例：以下表，其中无符号值能够避免误存负数，且扩大了表示范围。

对象	年龄区间	类型	表示范围
人	150 岁以内	unsigned tinyint	无符号值：0 到 255
龟	数百岁	unsigned smallint	无符号值：0 到 65535
恐龙化石	数千万年	unsigned int	无符号值：0 到约 42.9 亿
太阳	约 50 亿年	unsigned bigint	无符号值：0 到约 10 的 19 次方

5.2 索引规约

第五条： 【推荐】若是有 order by 的场景，请注意利用索引的有序性。 order by 最后的字段是组合索引的一部分，而且放在索引组合顺序的最后，避免出现 file _ sort 的状况，影响查询性能。

正例： where a =? and b =? order by c; 索引： a _ b _ c
反例：索引中有范围查找，那么索引有序性没法利用，如： WHERE a >10 ORDER BY b; 索引 a _ b 没法排序。

第九条： 【推荐】建组合索引的时候，区分度最高的在最左边。

正例：若是 where a =? and b =? ， a 列的几乎接近于惟一值，那么只须要单建 idx _ a 索引便可。

• 说明： 存在非等号和等号混合判断条件时，在建索引时，请把等号条件的列前置。如： where a >? and b = ? 那么即便 a 的区分度更高，也必须把 b 放在索引的最前列。

5.3 SQL 语句

第一条：【强制】不要使用 count( 列名 ) 或 count( 常量 ) 来替代 count( * ) ， count( * ) 是 SQL 92 定义的标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。

• 说明： count( * ) 会统计值为 NULL 的行，而 count( 列名 ) 不会统计此列为 NULL 值的行。

第六条： 【强制】不得使用外键与级联，一切外键概念必须在应用层解决。

• 说明： （ 概念解释 ） 学生表中的 student _ id 是主键，那么成绩表中的 student _ id 则为外键。若是更新学生表中的 student _ id ，同时触发成绩表中的 student _ id 更新，则为级联更新。外键与级联更新适用于单机低并发，不适合分布式、高并发集群 ； 级联更新是强阻塞，存在数据库更新风暴的风险 ； 外键影响数据库的插入速度。

第八条： 【强制】数据订正时，删除和修改记录时，要先 select ，避免出现误删除，确认无误才能执行更新语句。

5.4 ORM 映射

整个规约对本身来讲都挺有用的，由于正好涉及到这方面，幸亏感受脸不怎么疼。

第一条：【强制】在表查询中，一概不要使用 * 做为查询的字段列表，须要哪些字段必须明确写明。

• 说明： 1 ） 增长查询分析器解析成本。2 ） 增减字段容易与 resultMap 配置不一致。

第二条：【强制】 POJO 类的 布尔 属性不能加 is ，而数据库字段必须加 is _，要求在 resultMap 中进行字段与属性之间的映射。

• 说明： 参见定义 POJO 类以及数据库字段定义规定，在 中 增长映射，是必须的。在 MyBatis Generator 生成的代码中，须要进行对应的修改。

第三条：【强制】不要用 resultClass 当返回参数，即便全部类属性名与数据库字段一一对应，也须要定义 ； 反过来，每个表也必然有一个与之对应。

• 说明： 配置映射关系，使字段与 DO 类解耦，方便维护。

第七条：【强制】更新数据表记录时，必须同时更新记录对应的 gmt _ modified 字段值为当前时间。

第九条：【参考】@ Transactional 事务不要滥用。事务会影响数据库的 QPS ，另外使用事务的地方须要考虑各方面的回滚方案，包括缓存回滚、搜索引擎回滚、消息补偿、统计修正等。

---

总结

浏览了一遍，仍是学习到了不少东西吧，上面也仅仅只是总结了对我本身比较收益，现阶段我能吸取能实际感觉获得的规约，若是想要 PDF 版的能够在这里下载：戳这里

欢迎转载，转载请注明出处！
简书ID：@我没有三颗心脏
github：wmyskxz 欢迎关注公众微信号：wmyskxz_javaweb 分享本身的Java Web学习之路以及各类Java学习资料