JAVA开发规范

java开发编程

提交的代码必须符合阿里巴巴的代码检查工具，代码检查有违反规约不能上测试、生产环境

命名规约

1. 【强制】类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外：DO / BO /DTO / VO / AO

正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
BO 业务对象，封装对象、复杂对象 ，里面可能包含多个类；
DTO 传输对象，前端调用时传输 ；
VO 表现对象，前端界面展示。

1. 【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格,必须遵从 驼峰形式。

正例: localValue / getHttpMessage() / inputUserId

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

2. 【强制】各种功能类的命名

1. 【强制】包名统一使用小写

2. 【强制】禁止中英文混写

3. 【强制】Controller类中的方法，下面提供通用的方法名

1. 【强制】Controller类api路径格式

1)类上使用@RestController注解
2)方法上分别使用@GetMapping，@PostMapping，@DeleteMapping,@PutMapping注解

   比如对会员进行增删该查

3)api组成
  业务模块关键字/业务关键字

• 业务模块关键字

店铺 shop 商品 goods 会员 member 促销 promotion 订单 order 系统 system 楼层 floor

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

常亮定义

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

2. 【推荐】不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护。 说明：大而全的常量类，不利于理解和维护。
   正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 ConfigConsts 下。

OOP 规约

1. 【强制】所有的覆写方法，必须加@Override 注解。 说明：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错。

2. 【强制】接口过时或废弃必须加@Deprecated 注解

3. 【强制】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。 正例："test".equals(object); 反例：object.equals("test");

4. 【强制】所有的相同类型的包装类(Integer 等)对象之间值的比较，全部使用 equals 方法比较。

控制语句

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

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

3. 【推荐】表达异常的分支时，少用 if-else 方式，这种方式可以改写成： if (condition) { ... return obj; } // 接着写 else 的业务逻辑代码; 说明：如果非得使用 if()...else if()...else...方式表达逻辑，请勿超过 3 层。

注释规约

1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/** 内容 */格式，不得使用// xxx 方式。 说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

2. 【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 说明：对子类的实现要求，或者调用注意事项，请一并说明。

3. 【强制】所有的类都必须添加创建者、创建日期、版本。

版本号（外部开发使用vfX.Y.Z ）说明，vf：表示外部人员

X主版本号：全盘重构时增加；重大功能或方向改变时增加；大范围不兼容之前的接口时增加。
Y次版本号：增加新的业务功能或大的修改，可以按照期数增加。
Z修订号：增加新的接口、BUG修复或小的优化时增加；在接口不变的情况下，增加接口的非必填属性时增加；增强和扩展接口功能时增加。

示例：外服开发人员，第三期的版本号为：vf1.3.0，若有小问题修复则vf1.3.1

1. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

2. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

3. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。 说明：代码与注释更新不同步， 就失去了注释的意义。

4. 【强制】TODO 需求注明添加TODO的人员

异常处理

1. 【强制】Java 类库中定义的一类 RuntimeException 可以通过预先检查进行规避，而不应该通过 catch 来处理，比如：IndexOutOfBoundsException，NullPointerException 等等。 说明：无法通过预检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过 catch NumberFormatException 来实现。 正例：if (obj != null) {...} 反例：try { obj.method() } catch (NullPointerException e) {...}

2. 【强制】异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。

3. 【强制】对大段代码进行 try-catch，这是不负责任的表现。catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。

4. 【强制】捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

5. 【强制】有 try 块放到了事务代码中，catch 异常后，如果需要回滚事务，一定要注意手动回滚事务。

6. 【强制】finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。 说明：如果 JDK7 及以上，可以使用 try-with-resources 方式。

7. 【强制】不能在 finally 块中使用 return，finally 块中的 return 返回后方法结束执行，不会再执行 try 块中的 return 语句。

8. 【推荐】方法的返回值可以为 null，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回 null 值。调用方需要进行 null 判断防止 NPE 问题。 说明：本手册明确防止 NPE 是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null 的情况。

9. 【推荐】防止 NPE，是程序员的基本修养，注意 NPE 产生的场景： 1）返回类型为基本数据类型，return 包装数据类型的对象时，自动拆箱有可能产生 NPE。 反例：public int f() { return Integer 对象}， 如果为 null，自动解箱抛 NPE。 2） 数据库的查询结果可能为 null。 3） 集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null。 4） 远程调用返回对象时，一律要求进行空指针判断，防止 NPE。 5） 对于 Session 中获取的数据，建议 NPE 检查，避免空指针。 6） 级联调用 obj.getA().getB().getC()；一连串调用，易产生 NPE。 正例：使用 JDK8 的 Optional 类来防止 NPE 问题

10. 【推荐】定义时区分 unchecked / checked 异常，避免直接抛出 new RuntimeException()，更不允许抛出 Exception 或者 Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException / ServiceException 等。

11. 【参考】在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http/api 开放接口必须使用“错误码”；而应用内部推荐异常抛出；跨应用间 RPC 调用优先考虑使用 Result 方式，封装 isSuccess()方法、“错误码”、“错误简短信息”。 说明：关于 RPC 方法返回方式使用 Result 方式的理由： 1）使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。 2）如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输 的性能损耗也是问题。

12. 【参考】避免出现重复的代码（Don’t Repeat Yourself），即 DRY 原则。 说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是组件化。 正例：一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取： private boolean checkParam(DTO dto) {...}

数据库数据处理

1. 所有的更新和保存操作都需要更新数据库字段updater和update_time，所有保存都需要写入creater和create_time