开发手册|Java后端开发规范重点条目整理

Ps：部分熟知的开发规范未收录在本文中！暂无排版格式，等待后续添加……

一、编程规约

1.1 命名风格

代码中的命名严禁使用拼音与英文混合的方式
alibaba / taobao / youku / hangzhou 等国际通用的名称可视同英文

类名使用大驼峰的形式命名，例如 UpperCameCase
方法、参数与变量使用小驼峰的形式命名，例如 lowerCamelCase
常量命名全部大写且单词间使用下划线隔开，力求语义表达完整清楚，例如 MAX_STOCK_COUNT
杜绝完全不规范的缩写，避免词不达义
为了达到见名知意，命名时尽量使用完整的单词组合来表达其意

如果模块、接口、类、方法使用了设计模式，应在命名时体现出具体模式，有利于阅读者快速理解架构设计理念
public class OrderFactory / public class LoginProxy / public class ResourceObserver

接口类中的方法和属性不要加任何修饰符号（ public 也不要加，接口类中的访问修饰符默认就是 public ），保持代码的简洁性，并加上有效的 Javadoc（文档注释）。尽量不要在接口里定义变量，如果一定要定义变量，必须是与接口方法相关的，并且是整个应用的基础常量

各层命名规约：
Service / DAO 层方法命名规约如下。
获取单个对象的方法用 get 作为前缀
获取多个对象的方法用 list 作为前缀
获取统计值的方法用 count 作为前缀
插入的方法用 save / insert 作为前缀
删除的方法用 remove / delete 作为前缀

领域模型命名规约如下。
数据对象：xxxDO，xxx 为数据表名
数据传输对象：xxxDTO，xxx 为业务领域相关的名称
展示对象：xxxVo，xxx 一般为网页名称
POJO是 DO / DTO / BO / VO 的统称，禁止命名成 xxxPOJO

1.2 常量定义

不允许任何魔法值（即未经预先定义的常量）直接出现在代码中
long 或者 Long 初始赋值时，使用大写的 L，不能是小写的 l。小写 l 容易跟数字 1 混淆，造成误解
不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护

1.3 代码格式

if / for / while / switch / dp 等保留字与括号之间都必须加空格
任何二目、三目运算符的左右两边都需要加一个空格
注释的双斜线与注释内容之间有且仅有一个空格
单行字符数不超过 120 个，超出则需要换行，换行时遵循如下原则：
第二行相对第一行缩进 4 个空格，从第三行开始，不再持续缩进
运算符与下文一起换行
方法调用的点符号与下文一起换行
方法调用中的多个参数需要换行时，在逗号后进行
在括号前不要换行
方法参数在定义和传入时，多个参数逗号后边必须加空格
不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来，已提升可读性

1.4 OOP规约（面向对象编程 Object-Oriented Programming）

避免通过一个类的对象引用访问此类的静态变量或静态方法，造成无谓增加编译器解析成本，直接用类名来访问即可
所有的覆写方法，必须加 @Override 注解，可以准确判断是否覆盖成功
相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object
对外部正在调用或者二方库依赖的接口，不允许修改方法签名，以避免对接口调用方产生影响。若接口过时，必须加 @Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么
不能使用过时的类或方法
Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals，例如 “test”.equals(object)
所有相同类型的包装类对象之间值的比较，全部使用 equals 方法

关于基本数据类型与包装数据类型的使用标准如下：
所有的 POJO 类属性必须使用包装数据类型
RPC 方法的返回值和参数必须使用包装数据类型
所有的局部变量使用基本数据类型

在定义 DO / DTO / VO 等 POJO 类时，不要设定任何属性的默认值
当序列化类新增属性时，请不要修改 serialVersionUID 字段，以避免反序列失败；如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值
构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中
POJO 类必须写 toString 方法
当使用索引访问用 String 的 split 方法得到的数据时，需在最后一个分隔符后做有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险
当一个类有多个构造方法，或多个同名方法时，这些方法应该按顺序放置在一起便于阅读
类内方法定义的顺序是：公有方法或保护方法 > 私有方法 > getter / setter 方法
在 setter 方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在 getter / setter 方法中，不要增加业务逻辑，否则会增加排查问题的难度
在循环体内，字符串的连接方式使用 StringBuilder 的 append 方法进行扩展

final 可以声明类、成员变量、方法及本地变量，下列情况使用 final 关键字：
不允许被继承的类，如：String 类
不允许修改引用的域对象，如：POJO类的域变量
不允许被重写的方法，如 POJO 类的 setter 方法
不允许运行过程中重新赋值的局部变量
避免上下文重复使用一个变量，使用 final 描述可以强制重新定义 一个变量，方便更好地进行重构

慎用 Object 的 clone 方法来拷贝对象，对象的 clone 方法默认是浅拷贝，若想实现深拷贝，需要重写 clone 方法来实现属性对象的拷贝

类成员与方法访问控制从严：
如果不允许外部直接通过 new 来创建对象，那么构造方法必须限制为 private
工具类不允许有 public 或 default 构造方法
类非 static 成员变量并且与子类共享，必须限制为 protected
类非 static 成员变量并且仅在本类使用，必须限制为 private
类 static 成员变量如果仅在本类使用，必须限制为 private
若是 static 成员变量，必须考虑是否为 final
类成员方法只供类内部调用，必须限制为 private
类成员方法只对继承类公开，限制为 protected

每天更新一点，慢速更新中……