controller 规约

【获取用户】获取当前用户信息统一在Controller中获取
【规范】返回值统一Reply

service 规约

【规范】Reply对象不应该出现在在Service的返回值中
【规范】在service层，验证是抛异常，不能使用Reply。

命名规约

【规范】类名使用UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外： （ 领域模型的相关命名 ）DO / BO / DTO / VO 等。
正例： MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例： macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

【规范】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase 风格，必须遵从驼峰形式。
正例： localValue / getHttpMessage() / inputUserId

【规范】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

【规范】抽象类命名使用 Abstract 或 Base 开头 ； 异常类命名使用 Exception 结尾 ； 测试类命名以它要测试的类的名称开始，以 Test 结尾。枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

【规范】POJO 类中布尔类型的变量，都不要加 is ，否则部分框架解析会引起序列化错误。

【规范】各层命名规约：
A) Service / DAO 层方法命名规约
1 ） 获取单个对象的方法用 get 做前缀。
2 ） 获取多个对象的方法用 list 做前缀（习惯：getXXXList）。
3 ） 获取统计值的方法用 count 做前缀。
4 ） 插入的方法用 save（ 推荐 ） 或 insert 做前缀。
5 ） 删除的方法用 remove（ 推荐 ） 或 delete 做前缀。
6 ） 修改的方法用 update 做前缀(或modify)。
B) 领域模型命名规约
1 ） 数据对象： xxxDO ， xxx 即为数据表名。
2 ） 数据传输对象： xxxDTO ， xxx 为业务领域相关的名称。
3 ） 展示对象： xxxVO ， xxx 一般为网页名称。
4 ） POJO 是 DO / DTO / BO / VO 的统称，禁止命名成 xxxPOJO 。

常量规约

【规范】不允许任何魔法值（ 即未经定义的常量 ） 直接出现在代码中。
反例： String key =” Id # taobao _”+ tradeId；
cache . put(key , value);

格式规约

【风格】单行太长需换行

【风格】方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。

OOP规约

【效率】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。

【规范】所有的覆写方法，必须加@ Override 注解。

【规范】对外暴露的接口签名，原则上不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。

【规范】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。

正例： “ test “ .equals(object);
反例： object.equals( “ test “ );

【规范】所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。(注意空指针)
说明：对于 Integer var =?在-128 至 127 之间的赋值， Integer 对象是在IntegerCache . cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。

【规范】关于基本数据类型与包装数据类型的使用标准如下：

• 所有的 POJO 类属性必须使用包装数据类型。
• RPC 方法的返回值和参数必须使用包装数据类型。
• 所有的局部变量【推荐】使用基本数据类型。

【强制】序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败 ； 如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。

【规范】构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。

【规范】使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
说明：
String str = “a,b,c,,”;
String[] ary = str.split(“,”);

预期大于 3，结果是 3

System.out.println(ary.length);

【规范】当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读。

【风格】类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter方法。

【效率】final 可提高程序响应效率，声明成 final 的情况：

• 不需要重新赋值的变量，包括类属性、局部变量。
• 对象参数前加 final ，表示不允许修改引用的指向。
• 类方法确定不允许被重写。
  -例子：final boolean existed = (file.open(fileName, “w”) != null) && (…) || (…);

集合处理

【强制】关于 hashCode 和 equals 的处理，遵循如下规则：

• 只要重写 equals ，就必须重写 hashCode 。
• 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。
• 如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals 。

【强制】不要在 foreach 循环里进行元素的 remove / add 操作。 remove 元素请使用 Iterator方式，如果并发操作，需要对 Iterator 对象加锁。
反例：

List<String> a = new ArrayList<String>();
a.add("1");
a.add("2");
for (String temp ： a) {
if("1".equals(temp)){
a.remove(temp);
}
}

说明：以上代码的执行结果肯定会出乎大家的意料，那么试一下把“1”换成“2”，会是同样的结果吗？(java.util.ConcurrentModificationException)
正例：

Iterator<String> it = a.iterator();
while(it.hasNext()){
String temp = it.next();
if(删除元素的条件){
it.remove();
}
}

【规范】集合初始化时，尽量指定集合初始值大小。
说明： ArrayList 尽量使用 ArrayList(int initialCapacity) 初始化。

【规范】使用 entrySet 遍历 Map 类集合 KV，而不是 keySet 方式进行遍历。
说明：keySet 其实是遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出 key 所对应的 value。而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效 率更高。如果是 JDK8，使用 Map.foreach 方法。

Map<String, String> map = new HashMap<String, String>();
map.put("1", "@@");
map.put("2", "##");

/**
* JDK8推荐使用
*/
map.forEach((K, V) -> {
System.out.println("Key ： " + K);
System.out.println("Value ： " + V);
});

/**
* foreach推荐使用
*/
for (Map.Entry<String, String> entry ： map.entrySet()) {
System.out.println("Key ： " + entry.getKey());
System.out.println("Value ： " + entry.getValue());
}

/**
* 不推荐使用
*/
for (String key ： map.keySet()) {
System.out.println("Key ： " + key);
System.out.println("Value ： " + map.get(key));
}

【强制】高度注意 Map 类集合 K/V 能不能存储 null 值的情况，如下表格：

并发处理

【规范】获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
说明：资源驱动类、工具类、单例工厂类都需要注意。

【规范】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
正例：
public class TimerTaskThread extends Thread { public TimerTaskThread(){
super.setName(“TimerTaskThread”); … }

【规范】线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
说明：使用线程池的好处是减少在创建和销毁线程上所花的时间以及系统资源的开销，解决资 源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者 “过度切换”的问题。

【规范】线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样 的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。 说明：Executors 返回的线程池对象的弊端如下：
1)FixedThreadPool 和 SingleThreadPool：
允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。
2)CachedThreadPool 和 ScheduledThreadPool：
允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。

【效率】高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁;能 锁区块，就不要锁整个方法体;能用对象锁，就不要用类锁。

【强制】对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造 成死锁。
说明：线程一需要对表 A、B、C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序 也必须是 A、B、C，否则可能出现死锁。

【规范】并发修改同一记录时，避免更新丢失，要么在应用层加锁，要么在缓存加锁，要么在 数据库层使用乐观锁，使用 version 作为更新依据。
说明：如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次 数不得小于 3 次。

【规范】多线程并行处理定时任务时，Timer 运行多个 TimeTask 时，只要其中之一捕获抛出的异常，其它任务便会自动终止运行，使用ScheduledExecutorService 则没有这个问题。

【规范】HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在 开发过程中注意规避此风险。

控制语句

【规范】在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程 序将继续执行到哪一个 case 为止;在一个 switch 块内，都必须包含一个 default 语句并且 放在最后，即使它什么代码也没有。

【规范】在 if/else/for/while/do 语句中必须使用大括号，即使只有一行代码，避免使用 下面的形式：if (condition) statements;

【规范】推荐尽量少用 else， if-else 的方式可以改写成：

if(condition){
...
return obj; }

接着写 else 的业务逻辑代码;
说明：如果非得使用if()…else if()…else…方式表达逻辑，【强制】请勿超过3层，
超过请使用状态设计模式 或者 卫语句。
卫语句示例：

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 Alibaba Java Coding Guidelines.”);
return;
}

【规范】除常用方法(如 getXxx/isXxx)等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
说明：很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么 样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢?

正例：

伪代码如下：

boolean existed = (file.open(fileName, "w") != null) && (...) || (...); if (existed) {
... }

反例：

if ((file.open(fileName, "w") != null) && (...) || (...)) { ...
}

【规范】方法中需要进行参数校验的场景：

• 调用频次低的方法。
• 执行时间开销很大的方法，参数校验时间几乎可以忽略不计，但如果因为参数错误导致
  中间执行回退，或者错误，那得不偿失。
• 需要极高稳定性和可用性的方法。
• 对外提供的开放接口，不管是RPC/API/HTTP接口。
• 敏感权限入口。

【规范】方法中不需要参数校验的场景：

• 极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参
  数检查。
• 底层的方法调用频度都比较高，一般不校验。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一 台服务器中，所以 DAO 的参数校验，可以省略。
• 被声明成private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参 数已经做过检查或者肯定不会有问题，此时可以不校验参数。

单元测试

【强制】好的单元测试必须遵守 AIR 原则。

说明：单元测试在线上运行时，感觉像空气(AIR)一样并不存在，但在测试质量的保障上，却是非常关键的。好的单元测试宏观上来说，具有自动化、独立性、可重复执行的特点。

• A：Automatic(自动化)
• I：Independent(独立性)
• R：Repeatable(可重复)

【强制】单元测试应该是全自动执行的，并且非交互式的。测试框架通常是定期执行的，执行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元测 试中不准使用 System.out 来进行人肉验证，必须使用 assert 来验证。

【强制】保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间 决不能互相调用，也不能依赖执行的先后次序。
反例：method2 需要依赖 method1 的执行，将执行结果做为 method2 的输入。

【强制】对于单元测试，要保证测试粒度足够小，有助于精确定位问题。单测粒度至多是类级别，一般是方法级别。
说明：只有测试粒度小才能在出错时尽快定位到出错位置。单测不负责检查跨类或者跨系统的 交互逻辑，那是集成测试的领域。

【强制】核心业务、核心应用、核心模块的增量代码确保单元测试通过。
说明：新增代码及时补充单元测试，如果新增代码影响了原有单元测试，请及时修正。

【推荐】单元测试的基本目标：语句覆盖率达到 70%;核心模块的语句覆盖率和分支覆盖率都 要达到 100%
说明：在工程规约的应用分层中提到的 DAO 层，Manager 层，可重用度高的 Service，都应该 进行单元测试。

【推荐】编写单元测试代码遵守 BCDE 原则，以保证被测试模块的交付质量。
B：Border，边界值测试，包括循环边界、特殊取值、特殊时间点、数据顺序等。
C：Correct，正确的输入，并得到预期的结果。
D：Design，与设计文档相结合，来编写单元测试。
E：Error，强制错误信息输入(如：非法数据、异常流程、非业务允许输入等)，并得 到预期的结果。

【推荐】和数据库相关的单元测试，可以设定自动回滚机制，不给数据库造成脏数据。或者 对单元测试产生的数据有明确的前后缀标识。
正例：在 RDC 内部单元测试中，使用 RDC_UNIT_TEST_的前缀标识数据。

【推荐】在设计评审阶段，开发人员需要和测试人员一起确定单元测试范围，单元测试最好 覆盖所有测试用例(UC)。

【推荐】单元测试作为一种质量保障手段，不建议项目发布后补充单元测试用例，建议在项 目提测前完成单元测试。

【参考】不要对单元测试存在如下误解：

• 那是测试同学干的事情。本文是开发手册，凡是本文内容都是与开发同学强相关的。
• 单元测试代码是多余的。汽车的整体功能与各单元部件的测试正常与否是强相关的。
• 单元测试代码不需要维护。一年半载后，那么单元测试几乎处于废弃状态。
• 单元测试与线上故障没有辩证关系。好的单元测试能够最大限度地规避线上故障。

ORM规约

【规范】POJO 类的 boolean 属性不能加 is，而数据库字段必须加 is_，要求在 resultMap 中 进行字段与属性之间的映射。
说明：参见定义 POJO 类以及数据库字段定义规定，在 sql.xml 增加映射，是必须的。

【安全】配置XML文件时注意SQL注入问题。

【规范】不允许直接拿 HashMap 与 Hashtable 作为查询结果集的输出。

【强制】更新数据表记录时，必须同时更新记录对应的 gmt_modified 字段值为当前时间。

【规范】不要写一个大而全的数据更新接口，传入为 POJO 类，不管是不是自己的目标更新字 段，都进行 update table set c1=value1,c2=value2,c3=value3; 这是不对的。执行 SQL 时，尽量不要更新无改动的字段，一是易出错;二是效率低;三是 binlog 增加存储。

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

工程规约

【说明】图中默认上层依赖于下层，箭头关系表示可直接依赖，如：开放接口层可以依赖于Web 层，也可以直接依赖于 Service 层，依此类推。

• 开放接口层：可直接封装 Service接口暴露成 RPC 接口;通过 Web 封装成 http 接口;网关控 制层等。
• 终端显示层：各个端的模板渲染并执行显示层。当前主要是 velocity 渲染，JS 渲染，JSP 渲 染，移动端展示层等。
• Web 层：主要是对访问控制进行转发，各类基本参数校验，或者不复用的业务简单处理等。(Controller)
• Service 层：相对具体的业务逻辑服务层。
• Manager 层：通用业务处理层，它有如下特征：
  1) 对第三方平台封装的层，预处理返回结果及转化异常信息;
  2) 对Service层通用能力的下沉，如缓存方案、中间件通用处理;
  3) 与DAO层交互，对DAO的业务通用能力的封装。
• DAO 层：数据访问层，与底层 MySQL、Oracle、Hbase 进行数据交互。
• 外部接口或第三方平台：包括其它部门 RPC 开放接口，基础平台，其它公司的 HTTP 接口。

【规范】(分层异常处理规约)在 DAO 层，产生的异常类型有很多，无法用细粒度的异常进行catch，使用catch(Exception e)方式，并throw new DAOException(e)，不需要打印日志，因为日志在 Manager/Service 层一定需要捕获并打到日志文件中去，如果同台服务器再打日志，浪费性能和存储。在 Service 层出现异常时，必须记录出错日志到磁盘，尽可能带 上参数信息，相当于保护案发现场。如果 Manager 层与 Service 同机部署，日志方式与 DAO 层处理一致，如果是单独部署，则采用与 Service 一致的处理方式。Web 层绝不应该继续往上抛异常，因为已经处于顶层，如果意识到这个异常将导致页面无法正常渲染，那么就应该直接跳转到友好错误页面，加上用户容易理解的错误提示信息。开放接口层要将异常处理成错误码 和错误信息方式返回。

【规范】分层领域模型规约：

• DO(Data Object)：与数据库表结构一一对应，通过 DAO 层向上传输数据源对象。(Entity)
• DTO(Data Transfer Object)：数据传输对象，Service 和 Manager 向外传输的对象。
• BO(Business Object)：业务对象。可以由 Service 层输出的封装业务逻辑的对象。
• QUERY：数据查询对象，各层接收上层的查询请求。注：超过 2 个参数的查询封装，禁止 使用 Map 类来传输。
• VO(View Object)：显示层对象，通常是 Web 向模板渲染引擎层传输的对象。

服务器规约

【效率】高并发服务器建议调小 TCP 协议的 time_wait 超时时间。

说明：操作系统默认 240 秒后，才会关闭处于 time_wait 状态的连接，在高并发访问下，服务器端会因为处于 time_wait 的连接数太多，可能无法建立新的连接，所以需要在服务器上 调小此等待值。
正例：在 linux 服务器上请通过变更/etc/sysctl.conf 文件去修改该缺省值(秒)：
net.ipv4.tcp_fin_timeout = 30

【效率】调大服务器所支持的最大文件句柄数(File Descriptor，简写为fd)。

说明：主流操作系统的设计是将 TCP/UDP 连接采用与文件一样的方式去管理，即一个连接对 应于一个 fd。主流的 linux 服务器默认所支持最大 fd 数量为 1024，当并发连接数很大时很 容易因为 fd 不足而出现“open too many files”错误，导致新的连接无法建立。 建议将 linux 服务器所支持的最大句柄数调高数倍(与服务器的内存数量相关)。

【规范】给 JVM 设置-XX：+HeapDumpOnOutOfMemoryError 参数，让 JVM 碰到 OOM 场景时输出 dump 信息。

说明：OOM 的发生是有概率的，甚至有规律地相隔数月才出现一例，出现时的现场信息对查错 非常有价值。

【规范】服务器内部重定向使用 forward;外部重定向地址使用 URL 拼装工具类来生成，否则 会带来 URL 维护不一致的问题和潜在的安全风险。

安全规约

【安全】隶属于用户个人的页面或者功能必须进行权限控制校验。

说明：防止没有做水平权限校验就可随意访问、操作别人的数据，比如查看、修改别人的订单。

【安全】用户敏感数据禁止直接展示，必须对展示数据脱敏。

说明：查看个人手机号码会显示成：158****9119，隐藏中间 4 位，防止隐私泄露。

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

【安全】用户请求传入的任何参数必须做有效性验证。

说明：忽略参数校验可能导致：

• page size 过大导致内存溢出
• 恶意 order by 导致数据库慢查询
• 任意重定向
• SQL 注入
• 反序列化注入
• 正则输入源串拒绝服务 ReDoS
  说明：Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题， 但是如果攻击人员使用的是特殊构造的字符串来验证，有可能导致死循环的效果。

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

【安全】表单、AJAX 提交必须执行 CSRF 安全过滤。

说明：CSRF(Cross-site request forgery)跨站请求伪造是一类常见编程漏洞。对于存在 CSRF 漏洞的应用/网站，攻击者可以事先构造好 URL，只要受害者用户一访问，后台便在用户 不知情情况下对数据库中用户参数进行相应修改。

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

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

【安全】发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过 滤等风控策略。

其它规约

【效率】在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。 说明：不要在方法体内定义：Pattern pattern = Pattern.compile(规则);

【规范】获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime();
说明：如果想获取更加精确的纳秒级时间值，用 System.nanoTime()。在 JDK8 中，针对统计 时间等场景，推荐使用Instant 类。

【规范】对于“明确停止使用的代码和配置”，如方法、变量、类、配置文件、动态配置属性等要坚决从程序中清理出去，避免造成过多垃圾。