【java代码规范】

公司的代码规范,做个备注

愿景：不需要通过看注释了解代码

不要求我们用多好的技术，码出多高的水准，我们要做的是看到代码就像见到美女一样，能吸收眼球认真的看下去，看到别人的代码就感觉像是自己写的一样，再者我们搞规范要求大家，不是想让大家古板死守、遵守规范，相反是想当大家通过约束来掌握技术的精髓、用更优雅的方式去实现代码之美，规范是死的，人是活的，我们的规范要我们与时俱近，走在技术的前沿！

编程规约

1.命名风格

1.1通用性

• 禁止下划线或美元符号（_$）开始和结束
• 严禁使用拼音与英文混合和中文
• 杜绝不规范的缩写，缩写要有统用性

1.2项目

• 全部小写，可以用"-"拼接

1.3包

• 包用使用小写，单语意，单数，禁止使用复数

1.4类

• 驼峰式命名(类首字母要大小，其它小写)，单词明确，排除D0/BO/VO/AO/DTO等惯用词
• 抽象类、接口类、实现类中要提现出特征如：抽象类--Abstract/Base开始接口类--I/Interface开始实现类--Impl结束异常类--Exception结束测试类--Test结束工具类--Utils结束参数命名时同时参照这样的规则
• 枚举类名后要 加上Enum后缀，成员要全部大写、或者首字母大写，单词间用“_"分割

1.5常量

• 不允许任何魔法值（未定位直接在程序中出现的变量/常量）
• 常量全部大写，单词间用”_"分割，力求词义明确，不嫌长度
• 在Long或者long赋值时，不允许使用小写l
• 按常量功能进行归类，分开维护

1.6方法

• 获取单个对象的方法用 get/load 做前缀。
• 获取多个对象的方法用 list 做前后缀
• 获取统计值的方法用 count 做前缀
• 插入的方法用 save/insert 做前缀
• 删除的方法用 remove/delete 做前缀
• 修改的方法用 update 做前缀

1.7其它

• pojo中的布尔变量不要加isXX,部分框架会引起序列化错误
• 如果模块、接口、类、方法使用了设计模式时，命名时要提现出来，例：xxxFactory、xxxProxy
• 接口类方法中不需要加任何的修饰词，保持代码整洁

2.代码格式（统一使用IEDA开发工具，严谨个性化配置）

2.1大括号内为空，则简洁地写成{}即可

2.2大括号内不为空

• 左大括号前不换后换
• 右大括号前换行后看着换
• 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行

2.4if/for/while/switch/do 等保留字与括号之间都必须加空格。

2.5任何二目、三目运算符的左右两边都需要加一个空格

2.6注释的双斜线与注释内容之间有且仅有一个空格

2.7在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开

2.8单行字符数限制不超过 120 个，超出需要换行

• 运算符与下文一起换行
• 方法调用的点符号与下文一起换行
• 方法调用中的多个参数需要换行时，在逗号后进行。
• 在括号前不要换行

参照以下正例：

3.OOP 规约

3.1jdk中的注解

• 重写的方法必须加上@Override
• 不用的方法需要加上@Deprecated

3.2类和方法

• 相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object
• 不能使用过时的类或方法
• Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals
• 构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中
• 有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起
• 类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter方法
• 在getter/setter 方法中，不要增加业务逻辑，增加排查问题的难度

3.3关键字

    注意final使用

• 不允许被继承的类
• 不允许修改引用的域对象
• 不允许被覆写的方法
• 不允许运行过程中重新赋值的局部变量
• 避免上下文重复使用一个变量，使用 final 关键字可以强制重新定义一个变量，方便更好地进行重构

3.5jdk中的基础类

• 慎用 Object 的 clone 方法来拷贝对象，推荐使用hutool的工具类

3.6基本类型包装类

• 所有整型包装类对象之间值的比较，全部使用 equals 方法比较
• 浮点数之间的等值判断，基本数据类型不能用==来比较，包装数据类型不能用 equals来判断
• BigDecimal 的等值比较应使用 compareTo()方法，而不是 equals()方法
• 禁止使用构造方法 BigDecimal(double)的方式把 double 值转化为 BigDecimal 对象
• 所有的局部变量尽量使用基本数据类型
• 类成员与方法访问控制从严，注意关键字使用

3.7POJO

• 定义数据对象 DO 类时，属性类型要与数据库字段类型相匹配
• 所有的 POJO 类属性必须使用包装数据类型
• 不要设定任何属性默认值
• 禁止在 POJO 类中，同时存在对应属性 xxx 的 isXxx()和 getXxx()方法

4.日期时间

4.1日期格式化时，传入 pattern 中表示年份统一使用小写的 y，注意格式：yyyy-MM-dd HH:mm:ss

• 大Y与小y：大Y表示当本周的年份，小y则是天为准
• 大M与小m：大M表示月份，小m表示分钟
• 大H与小h：大H表示24小时，小h表示12小时

4.2注意日期包使用，统一使用jdk

4.3禁止程序中写死一年365天

5.集合处理

• 5.1判断所有集合内部的元素是否为空，使用 isEmpty()方法，而不是 size()==0 的方式
• 5.2在使用 java.util.stream.Collectors 类的 toMap()方法转为 Map 集合时，一定要注意当 value 为 null 时会抛 NPE 异常
• 5.3ArrayList 的 subList 结果不可强转成 ArrayList
• 5.4使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常
• 5.5不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator方式，如果并发操作，需要对 Iterator 对象加锁

6.控制语句

•  6.1switch 块内，每个 case 要么通过 continue/break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止，都必须包含一个 default
• 6.2当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null判断
• 6.3在 if/else/for/while/do 语句中必须使用大括号
• 6.4在高并发场景中，避免使用”等于”判断作为中断或退出的条件。
• 6.5表达异常的分支时，少用 if-else 方式，如果避免不了请勿超过三层

7.注释规约

• 7.1类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用// xxx 方式。
• 7.2所有接口中方法必须得有注释，除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
• 7.3所有的类都必须添加创建者和创建日期
• 7.4方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐
• 7.5所有的枚举类型字段必须要有注释，说明每个数据项的用途
• 7.6代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改
• 7.7不留僵尸代码，不加注释说明，见到一律删除

8.前后端规约

8.1RESTFUL规则

• PUT 适用于更新
• GET 适用于查询
• POST 适用于添加
• PATCH 适用于单个属性修改
• DELETE 适用于删除

8.2所有请求需要约定RequestId,进行防重验证

9.异常日志

9.1异常处理

• 根据业务进行划分
• 常用异常不应该去捕获，业务上应该规避，比如：NullPointerException，IndexOutOfBoundsException 等等
• 返回类型为基本数据类型，return 包装数据类型的对象时，自动拆箱有可能产生 NPE
• 数据库的查询结果可能为 null
• 集合里的元素即使 isNotEmpty，取出的数据元素也可能为 null
• 远程调用返回对象时，一律要求进行空指针判断，防止 NPE
• 对于 Session 中获取的数据，建议进行 NPE 检查，避免空指针
• 级联调用getA().getB().getC()；一连串调用，易产生 NP
• 所有业务异常要向上抛
• 捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类
• 异常捕获后不要用来做流程控制，条件控制
• catch 时要分清哪些是稳定代码些是非稳定代码，杜绝大面积段try-catch
• finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。
• 使用 JDK8 的 Optional 类来防止 NPE 问题

9.2日志规范

• 禁止直接使用 System.out 或 System.err 输出日志或使用e.printStackTrace()打印异常堆栈。
• 在日志输出时，字符串变量之间的拼接使用占位符的方式
• 日志打印时禁止直接用 JSON 工具将对象转换成 String

10.错误码

这块还在整理中，收集我们目前项目中使用的类型完善成我们统一的格式，要做到不管什么项目，都能适用，就像是说明书一样，出现错误码，查说明就知道是什么原因


目前代碼中常見的要遵循的規範

常見代碼規範：
1.類注釋 方法注釋   單行注釋
/**
 * 類的描述
 *
 * @author    作者名稱
 * @date      日期時間
 */
/**
 * 方法描述  (也可寫明方法步驟)
 *
 * @param param1    入參描述1
 * @param param2    入參描述2
 * @param param3    入參描述3
 * @return 返回參數
 * @author    作者名稱
 * @date      日期時間
 */

單行注釋  用 //

2.單行注釋之前要空一行編碼

3.不准在controller做大多的邏輯校驗     controller層只是做為接收前端參數   轉發的作用   哪怕生成的代碼也要挪動到service層的實體類中編碼

4.controller層中的 mapping必須遵守restful風格的編碼

5.方法內代碼不能超過80行  多餘部分要拆分    最好是按照 一個方法只處理一個事情去拆分

6.事務的註解必須帶上  

@Transactional(rollbackFor = Exception.class)

7.代碼中盡量不使用  try  catch       因為維護比較麻煩   還容易異常被自己吃掉

8.我們代碼中使用了很多枚舉        注意枚舉的值比較以及地址比較 

ActivityResultStatus.Refuse == ActivityResultStatus.getEnum(status)

9.代碼中不能使用updateByid作為更新     

10.注釋的代碼要馬上刪除   不能提交一些僵尸代碼到遠程分支

11.不允許在一個sevice中調用多個mapper或者Dao   service要調用別的類服務   必須通過service調用   不能調用別的持久層

12.返回給前端參數不能使用數據庫持久的entity類  要封裝成對應的VO返回給到前端