本文档详细阐述了Java编程中的一系列规范和最佳实践，包括命名规约、常量定义、OOP原则、集合处理、并发处理、控制语句、异常日志处理、服务器配置以及安全措施。强调了代码一致性、可读性、健壮性和安全性的重要性，旨在提高代码质量，降低维护成本。
Java编码风格规范
一、概述
1、目的：
- 让项目中所有的文档都看起来像一个人写的,增加可读性,减少项目组中因为换人而带来的损失。指导JAVA开发岗位的具体工作。
2、阅读人员：
- 所有Java开发人员
二、编程规约
1、命名规约
- 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
- 反例：_name / _name / $Object / name / name$ /Object$
- 代码中的命名**严禁使用拼音与英文混合的方式，更不允许直接使用中文**的方式
- 正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使**纯拼音命名方式也要避免采用**。
- 反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3
- 正例：alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文
。
- 类名使用 UpperCamelCase风格，必须**遵从驼峰形式**，但以下情形例外：（领域模型的相关命名）DO / BO / DTO / VO等
- 反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
- 正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
- 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase风格，必须**遵从驼峰形式**。
- 正例：localValue / getHttpMessage() / inputUserId
- 常量命名**全部大写，单词间用下划线隔开**，力求语义表达完整清楚，不要嫌名字长。
- 反例：MAX_COUNT
- 正例：MAX_STOCK_COUNT
- 抽象类命名使用 Abstract或 Base开头；异常类命名使用 Exception结尾；测试类命名以它要测试的类的名称开始，以 Test结尾。
- POJO类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。
- 反例：定义为基本数据类型 boolean isSuccess；的属性，它的方法也是 isSuccess()，RPC框架在反向解析的时候，“以为”对应的属性名称是 success，导致属性获取不到，进而抛出异常。
- 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
- 正例：应用工具类包名为 com.alibaba.open.util、类名为 MessageUtils
- 杜绝完全不规范的缩写，避免望文不知义
- 反例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。
- 如果使用到了设计模式，建议在类名中体现出具体模式。
- 说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计思想。
- 正例：public class OrderFactory; public class LoginProxy; public class ResourceObserver;
- 枚举类名建议带上 Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
- 说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。
- 正例：枚举名字：DealStatusEnum，成员名称：SUCCESS / UNKOWN_REASON。
2、常量定义
- long或者 Long初始赋值时，必须使用大写的 L，不能是小写的 l，小写容易跟数字1混淆，造成误解。
- 说明：Long a = 2l; 写的是数字的 21，还是 Long型的 2?
3、OOP规约
-
避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。
-
所有的覆写方法，必须加@Override注解。
- 反例：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的0，加@Override可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错。
-
避免使用可变参数，可利用数组代替
- 反例：public User getUsers(String type, Integer… ids)
- 正例：public User getUsers(String type, Integer[] ids)
-
对外暴露的接口签名，原则上不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@Deprecated注解，并清晰地说明采用的新接口或者新服务是什么。
-
不能使用过时的类或方法。
- 说明：java.net.URLDecoder 中的方法 decode(StringencodeStr) 这个方法已经过时，应该使用双参数 decode(String source, String encode)。接口提供方既然明确是过时接口，那么有义务同时提供新的接口；作为调用方来说，有义务去考证过时方法的新实现是什么。
-
Object的 equals方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。
- 反例：object.equals(“test”);
- 正例：
- java.util.Objects.equals(“test”, object);
- “test”.equals(object);
-
所有的相同类型的包装类对象之间值的比较，全部使用 equals方法比较。
- 说明对于 Integer var=?在-128至 127之间的赋值，Integer对象是在IntegerCache.cache产生，会复用已有对象，这个区间内的 Integer值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals方法进行判断。
-
关于基本数据类型与包装数据类型的使用标准如下：
- 所有的 POJO类属性必须使用包装数据类型。
- RPC方法的返回值和参数必须使用包装数据类型。
- 所有的**局部变量使用基本数据类型。**
-
定义 DO/DTO/VO等 POJO类时，不要设定任何属性默认值。
- 反例：POJO类的 gmtCreate默认值为 new Date();但是这个属性在数据提取时并没有置入具体值，在更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。
-
每个**Serializable类确保serialVersionUID字段不会改变**，且尽量不重复。
-
构造方法里面禁止加入任何业务逻辑，如果有**初始化逻辑，请放在 init方法中**。
-
当一个类有**多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起**，便于阅读
-
类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter方法。
-
Setter方法中，参数名称与类成员变量名称一致，this.成员名=参数名。在getter/setter方法中，尽量不要增加业务逻辑，增加排查问题的难度。
-
循环体内，字符串的联接方式，使用 StringBuilder的 append方法进行扩展。
-
说明：反编译出的字节码文件显示每次循环都会 new出一个 StringBuilder对象，然后进行append操作，最后通过 toString方法返回 String对象，造成内存资源浪费。
-
反例：
//反例 String str = "start"; for(int i=0; i<100; i++){ str = str + "hello"; }
-
-
final可提高程序响应效率，声明成 final的情况：
- 不需要重新赋值的变量，包括类属性、局部变量。
- 对象参数前加 final，表示不允许修改引用的指向。
- 类方法确定不允许被重写。
-
慎用 Object的 clone方法来拷贝对象。
- 说明：对象的 clone方法默认是浅拷贝，若想实现**深拷贝需要重写 clone方法实现属性对象的拷贝。**
4、集合处理
-
关于 hashCode和 equals的处理，遵循如下规则：
- 只要重写 equals，就必须重写 hashCode。
- 因为 Set存储的是不重复的对象，依据 hashCode和 equals进行判断，所以 Set存储的对象必须重写这两个方法。
- 如果**自定义对象做为 Map的键**，那么必须重写 hashCode和 equals。
- 正例：String重写了 hashCode和 equals方法，所以我们可以非常愉快地使用 String对象作为 key来使用
-
使用**集合转数组的方法，必须使用集合的 toArray(T[] array)**，传入的是类型完全一样的数组，大小就是 list.size()。
-
说明：使用 toArray带参方法，入参分配的数组空间不够大时，toArray方法内部将重新分配内存空间，并返回新数组地址；如果数组元素大于实际所需，下标为[ list.size() ]的数组元素将被置为 null，其它数组元素保持原值，因此最好将方法**入参数组大小定义与集合元素个数一致。**
-
正例：
//正例 List<String> list = new ArrayList<String>(2); list.add("guan"); list.add("bao"); String[] array = new String[list.size()]; array = list.toArray(array);
-
-
不要在 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); } } -
正例：
Iterator<String> it = a.iterator(); while(it.hasNext()){ String temp = it.next(); if(删除元素的条件){ it.remove(); } }
-
-
Comparator要**满足自反性，传递性，对称性**。
- 自反性：x，y的比较结果和 y，x的比较结果相反。
- 传递性：x>y,y>z,则 x>z。
- 对称性：x=y,则 x,z比较结果和 y，z比较结果相同。、
-
集合初始化时，尽量指定集合初始值大小。
- 说明：ArrayList尽量使用 ArrayList(int initialCapacity) 初始化。
-
合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。
- 说明：**稳定性指集合每次遍历的元素次序是一定的。有序性是指遍历的结果是按某种比较规则依次排列的。**如：ArrayList是 order/unsort；HashMap是 unorder/unsort；TreeSet是order/sort。
-
利用 Set元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List的contains方法进行遍历、对比、去重操作。
5、并发处理
-
获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
- 说明：资源驱动类、工具类、单例工厂类都需要注意。
-
创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
-
正例：
public class TimerTaskThread extends Thread { public TimerTaskThread(){ super.setName("TimerTaskThread"); ... } }
-
-
线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
- 说明：使用线程池的**好处是减少在创建和销毁线程上所花的时间以及系统资源的开销，解决资源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题**。
-
SimpleDateFormat 是线程不安全的类，一般不要定义为 static变量，如果定义为static，必须加锁，或者使用 DateUtils工具类。
-
高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。
-
对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。
- 说明：线程一需要对表 A、B、C依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是 A、B、C，否则可能出现死锁。
-
并发修改同一记录时，避免更新丢失，要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version作为更新依据。
- 说明：如果每次访问**冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于 3次。**
-
避免 Random实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed 导致的性能下降。
- 说明：Random实例包括 java.util.Random 的实例或者 Math.random()实例。
- 正例：在 JDK7之后，可以直接使用 API ThreadLocalRandom，在 JDK7之前，可以做到每个线程一个实例。
-
volatile解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但是如果多写，同样无法解决线程安全问题。
-
HashMap在容量不够进行 resize时由于高并发可能出现死链，导致 CPU飙升，在开发过程中注意规避此风险。
6、控制语句
- 在一个 switch块内，每个 case要么通过 break/return等来终止，要么注释说明程序将继续执行到哪一个 case为止；在一个 switch块内，都必须包含一个 default语句并且放在最后，即使它什么代码也没有。
- 在 if/else/for/while/do语句中必须使用大括号，即使只有一行代码。
- 反例：if (condition) statements;
- 循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的 try-catch操作（这个 try-catch是否可以移至循环体外）。
- 接口入参保护，这种场景常见的是用于做批量操作的接口。
- 方法中需要进行参数校验的场景：
- 调用频次低的方法。
- 执行时间开销很大的方法，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
- 需要极高稳定性和可用性的方法
- 对外提供的开放接口，不管是 RPC/API/HTTP接口。
- 敏感权限入口。
- 方法中不需要参数校验的场景：
- 极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参数检查。
- 底层的方法调用频度都比较高，一般不校验。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO层与 Service层都在同一个应用中，部署在同一台服务器中，所以 DAO的参数校验，可以省略。
- 被声明成 private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题的方法，此时可以不校验参数。
7、注释规约
- 类、类属性、类方法的注释必须使用 Javadoc规范，*使用/内容/格式，不得使用//xxx方式。
- 说明：在 IDE编辑窗口中，Javadoc方式会提示相关注释，生成 Javadoc可以正确输出相应注释；在 IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
- 所有的抽象方法（包括接口中的方法）必须要用 Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
- 对子类的实现要求，或者调用注意事项，请一并说明。
- **方法内部单行注释，在被注释语句上方另起一行，使用//注释。*方法内部多行注释使用/ */注释，注意与代码对齐。
- 所有的枚举类型字段必须要有注释，说明每个数据项的用途。
- 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。
- 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
- 说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
- 注释掉的代码尽量要配合说明，而不是简单的注释掉。
- 说明：代码被注释掉有两种可能性：
- 后续会恢复此段代码逻辑。
- 永久不用。
- 前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。
- 说明：代码被注释掉有两种可能性：
- 对于注释的要求：
- 能够**准确反应设计思想和代码逻辑**；
- 能够**描述业务含义，使别的程序员能够迅速了解到代码背后的信息**。
- 说明：完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
- **好的命名、代码结构是自解释的，注释力求精简准确、表达到位。**避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
- 特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
- **待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]），表示需要实现，但目前还未实现的功能。**这实际上是一个 Javadoc的标签，目前的 Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc标签）。
- 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]），在注释中用 FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。
三、异常日志
1、异常处理
-
不要捕获 Java类库中定义的继承自 RuntimeException的运行时异常类，如：IndexOutOfBoundsException / NullPointerException，这类异常由程序员预检查来规避，保证程序健壮性。
- 反例：try { obj.method() } catch(NullPointerException e){…}
- 正例：if(obj != null) {…}
-
异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。
-
对大段代码进行 try-catch，这是不负责任的表现。catch时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch尽可能进行区分异常类型，再做对应的异常处理。
-
捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。
-
有 try块放到了事务代码中，catch异常后，如果需要回滚事务，一定要注意手动回滚事务。
-
finally块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。
-
不能在 finally块中使用 return，finally块中的 return返回后方法结束执行，不会再执行 try块中的 return语句。
-
捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。
- 说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。
-
方法的返回值可以为 null，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回 null值。调用方需要进行 null判断防止 NPE问题。
- 本规约明确防止 NPE是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败，运行时异常等场景返回 null的情况。
-
防止 NPE，是程序员的基本修养，注意 NPE产生的场景：
-
返回类型为包装数据类型，有可能是 null，返回 int值时注意判空。
-
反例：
//反例 public int f(){ return Integer对象 };如果为 null，自动解箱抛 NPE。
-
-
数据库的查询结果可能为 null。
-
集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null。
-
远程调用返回对象，一律要求进行 NPE判断。
-
对于 Session中获取的数据，建议 NPE检查，避免空指针。
-
级联调用 obj.getA().getB().getC()；一连串调用，易产生 NPE。
-
-
在代码中使用“抛异常”还是“返回错误码”，对于**公司外的 http/api开放接口必须使用“错误码”；而应用内部推荐异常抛出**；跨应用间 RPC调用优先考虑使用 Result方式，封装 isSuccess、“错误码”、“错误简短信息”。
- 说明：关于 RPC方法返回方式使用 Result方式的理由：
- 使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。
- 如果不加栈信息，只是 new自定义异常，加入自己的理解的 error message，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。
- 说明：关于 RPC方法返回方式使用 Result方式的理由：
-
定义时区分 unchecked/checked 异常，避免直接使用 RuntimeException抛出，更不允许抛出 Exception或者 Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException / ServiceException等。
-
避免出现重复的代码（Don’t Repeat Yourself），即 DRY原则。
- 说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是共用模块。
2、日志规约
-
应用中不可直接使用日志系统（Log4j、Logback）中的 API，而应依赖使用日志框架SLF4J中的 API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。
-
正例：
//正例 import org.slf4j.Logger; import org.slf4j.LoggerFactory; private static final Logger logger = LoggerFactory.getLogger(Abc.class);
-
-
日志文件推荐至少保存 15天，因为有些异常具备以“周”为频次发生的特点。
-
对 trace/debug/info级别的日志输出，必须使用条件输出形式或者使用占位符的方式。
-
说明：
logger.debug("Processing trade with id: " + id + " symbol: " + symbol);如果日志级别是 warn，上述日志不会打印，但是会执行字符串拼接操作，如果 symbol是对象，会执行 toString()方法，浪费了系统资源，执行了上述操作，最终日志却没有打印。
-
正例：
//正例 //（条件） if (logger.isDebugEnabled()) { logger.debug("Processing trade with id: " + id + " symbol: " + symbol); } //（占位符） logger.debug("Processing trade with id: {} symbol : {} ", id, symbol);
-
-
异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么往上抛。
- 正例：logger.error(各类参数或者对象 toString + “_” + e.getMessage(), e);
-
可以使用 warn日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适从。注意日志输出的级别，error级别只记录系统逻辑出错、异常等重要的错误信息。如非必要，请不要在此场景打出 error级别。
-
谨慎地记录日志。生产环境禁止输出 debug日志；有选择地输出 info日志；如果使用 warn来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志。
- 说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。
四、服务器规约
- 高并发服务器建议调小 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不足而出现“opentoomanyfiles”错误，导致新的连接无法建立。 建议将 linux服务器所支持的最大句柄数调高数倍（与服务器的内存数量相关）。
- 给 JVM设置-XX:+HeapDumpOnOutOfMemoryError参数，让 JVM碰到 OOM场景时输出dump信息。
- 说明：OOM的发生是有概率的，甚至有规律地相隔数月才出现一例，出现时的现场信息对查错非常有价值。
- 服务器内部重定向使用 forward；外部重定向地址使用 URL拼装工具类来生成，否则会带来 URL维护不一致的问题和潜在的安全风险。
五、安全规约
- 隶属于用户个人的页面或者功能必须进行权限控制校验。
- 说明：防止没有做水平权限校验就可随意访问、操作别人的数据，比如查看、修改别人的订单。
- 用户敏感数据禁止直接展示，必须对展示数据脱敏。
- 说明：查看个人手机号码会显示成:158****9119，隐藏中间 4位，防止隐私泄露。
- 用户输入的 SQL参数严格使用参数绑定或者 METADATA字段值限定，防止 SQL注入，禁止字符串拼接 SQL访问数据库。
- 用户请求传入的任何参数必须做有效性验证。
- 禁止向 HTML页面输出未经安全过滤或未正确转义的用户数据。
- 表单、AJAX提交必须执行 CSRF安全过滤。
- 说明：CSRF(Cross-site request forgery)跨站请求伪造是一类常见编程漏洞。对于存在CSRF漏洞的应用/网站，攻击者可以事先构造好 URL，只要受害者用户一访问，后台便在用户不知情情况下对数据库中用户参数进行相应修改。
- 在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制，如数量限制、疲劳度控制、验证码校验，避免被滥刷、资损。
- 说明：如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并造成短信平台资源浪费
- 发贴、评论、发送即时消息等用户生成内容的场景**必须实现防刷、文本内容违禁词过滤等风控策略**。
扫一扫
739
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
