《孤尽班T31-06-项目编码规约》

《孤尽班T31-05-项目编码规约》

孤尽训练营---------

孤尽大佬亲自解读《alibaba Java 开发手册》

• 阿里巴巴编码规约-编程规约
• 编程规约
• 命名规范
• 常量定义
• 代码格式
• OOP规约
• 集合处理
• 并发处理
• 控制语句

---

T31项目第12天

项目编码规约

1.编码规约

1.1 熵增定律

每件事物如果不维护都是朝着更坏的方向进展，就好比一间房间，如果不定期清扫和维护，过一段时间房间会变得脏乱不堪。

1.2编码规约的作用

• 代码更加简约
• 代码维护工作量减轻
• 代码管理更方便

1.3编码的规约要求

以下为讲解版本（来自孤尽大佬）
命名风格和业务描述
主要体现在以下6点方面：
1.望文知意：
例如：service 和 controller 和 dao，pojo 层的类命名应该以业务名称（实体类）+层级名称来命名，每个层级文件存在在固定的目录下
2.抽象类命名 前缀带有 Abstract 或Base开头
例如：AbstractAddress
3.异常类使用Exception结尾（NullpointException）
4.测试类名以测试类名+Test（UserTest）
5.枚举类名以Enum后缀，枚举成员名称需要全大写，单词间使用下划线连接
6.类名命名应该以业务对应的英文来命名，如果是组合的英文，每个英文之间使用下划线隔开
例如：User_Adress

以下为详细版本（来自手册）：
[强制] 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

反例: _name /__name / $name / name_ / name$ / name__

[强制] 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

建议: 使用正确的英语拼写和语法， 尽量不要使用纯拼音命名。
正例:

alibaba / taobao / youku / hangzhou

等国际通用的名称，可视同英文。
反例: DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3
[强制] 类名使用UpperCamelCase风格，但以下情形例外：DO / BO / DTO / VO / AO / PO等。

正例: MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例: macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
[强制] 方法名、参数名、成员变量、局部变量 统一使用lowerCamelCase风格，必须遵从驼峰形式。
正例: localValue / getHttpMessage() / inputUserId
[强制] 常量 命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
正例: MAX_STOCK_COUNT
反例: MAX_COUNT // 意义不完整
[强制] 抽象类 命名使用Abstract或Base开头；异常类 命名使用Exception结尾；测试类命名以它要测试的类名开始，以Test结尾。

复习——分层领域模型规约：

DO（ Data Object）：与数据库表结构一一对应，通过DAO层向上传输数据源对象。
DTO（ Data Transfer Object）：数据传输对象，Service或Manager向外传输的对象。
BO（ Business Object）：业务对象。
由Service层输出的封装业务逻辑的对象。
AO（ Application Object）：应用对象。
在Web层与Service层之间抽象的复用对象模型，极为贴近展示层，复用度不高。
VO（ View Object）：显示层对象，通常是Web向模板渲染引擎层传输的对象。
POJO（ Plain Ordinary Java Object）：在本手册中， POJO专指只有setter/getter/toString的简单类，包括DO/DTO/BO/VO等。

[强制] 抽象类 类型与中括号紧挨相连来定义数组。

正例: int[] arrayDemo;
反例: String args[];
[强制] POJO类中布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误。

反例: 定义为基本数据类型Boolean isDeleted;的属性，它的方法也是isDeleted()，RPC 框架在反向解析的时候，“误以为”对应的属性名称是deleted，导致属性获取不到，进而抛出异常。
[强制] 包名 统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

正例: 应用工具类包名为com.alibaba.ai.util、类名为MessageUtils（此规则参考spring的框架结构）
[强制] 杜绝完全不规范的缩写，避免望文不知义。

反例: AbstractClass“缩写”命名成AbsClass；condition “缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。
[推荐] 为了达到代码自解释的目标，任何定义编程元素在命名时使用尽量完整单词 组合来表达其意。

正例: 从远程仓库拉取代码的类命名为 PullCodeFromPullCodeFrom。
变量 int a; 的随意命名方式。
不怕长，就怕说不清楚、不知所云。
[推荐] 如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。

说明: 将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。
正例:

public class OrderFactory; 
public class LoginProxy; 
public class ResourceObserver;

[推荐] 接口类中的方法和属性 不要加任何修饰符号（public也不要加），保持代码的简洁性，并加上有效的Javadoc注释。

尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
正例: 接口方法签名void f();， 接口基础常量String COMPANY = "alibaba";
反例: 接口方法定义public abstract void f();
说明: JDK8中接口允许有默认实现，那么这个default方法，是对所有实现类都有价值的默认实现。

接口和实现类的命名有两套规则：

[强制] 对于Service和DAO类，基于SOA的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别。
正例: CacheServiceImpl实现CacheService接口。
[推荐] 如果是形容能力的接口名称，取对应的形容词为接口名(通常是–able的形式)
正例: AbstractTranslator实现 Translatable。
[参考] 枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。
正例：枚举名字为ProcessStatusEnum的成员名称：SUCCESS / UNKNOWN_REASON。
[推荐] 各层命名规约：

1. Service/DAO层方法命名规约:
   获取单个对象的方法用get作前缀。
   获取多个对象的方法用list作前缀。
   获取统计值的方法用count作前缀。
   插入的方法用save/insert作前缀。
   删除的方法用remove/delete作前缀。
   修改的方法用update作前缀。

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

1.4 java常量规约

常量复用层级：
跨应用共享常量：放置在SDK中
应用内共享常量：放置在一方库中
子工程内部共享常量：当前子工程的constant目录中
包内共享常量：当前包下单独的constant目录下
类内共享常量：直接在类内部private static final 定义
补充：常量的命名字母应该全部大写，单词间使用下划线隔开，保证语义表达清楚；
举例：
例如：
MAX_CONNECTION 最大连接数
TreeMap类中常量

2.注释规约

2.1注释的作用

1.提高代码的可读性
2.使程序条理清晰
3.后期维护方便
4.减少程序的沟通障碍（沟通效率）
5.生成帮助文档（协作效率）
6.警示作用，防止出错

2.2注释的内容分类

注释根据说明内容分为以下3类：
1.附加说明：说明此段代码为什么这么写，用途是什么
2.部分与整体：此段代码与整体业务之间的关联关系
2.风险提示：此段代码可能存在一些问题，未测试，提示其他协作人员

3.前后端的设计规约

3.1前后端设计要素

1.接口名称和风格统一
2.前后端交互的对象属性值统一
3.json组装格式（阿里巴巴开发手册-嵩山版）

//Javabean对象转换成String类型的JSON字符串
JSONObject.toJSONString(Javabean对象)
 
//String类型的JSON字符串转换成Javabean对象
JSONObject.toJavaObject(JSON字符串,Javabean.class)
 
//Json字符串转换成JSONObject对象
JSONObject.parseObject(JSON字符串)
 
//JSON字符串转换成Javabean对象
JSONObject.parseObject(JSON字符串,Javabean.class)

//获取jsonObject中某个字段
jsonObject.getString("字段名字");
 
Refund r = new Refund();
String jsonStr = JSONObject.toJSONString(r);
 
 
String jsonStr = "{\"msg\":\"ZhangSan\"}";
Refund r = JSONObject.toJavaObject(jsonStr,Refund.class);
 
 
JSONObject jsonObject = JSONObject.parseObject(jsonStr);
 
Stirng msg= jsonObject.getString("msg");

Refund r = JSONObject.parseObject(jsonStr,Refund.class)

4.后台异常的失败提示（后端和前端统一异常处理方式）
5.错误信息和用户提示透出
例如：后端返回前端的信息中包含后端处理的状态值，前端根据状态值抛出不同的信息 ，status 200 成功，400 失败等
6.前后端交互的API：协议，域名，请求方式，请求方法，请求内容，状态码，响应体

4.前后端对数值类型处理

4.1 java和js对数字类型的处理方式

1.java的可用于设计数字比较大数值和极小值 类型 Long Float Double
2.JS中处理数值类型的类型 Numbr，等同与java中double，属于双精度类型

4.2 科学计数法

double 和 float使用科学计数法来保存数据

4代表 410^11的数值
8代表 810^10的数值
6代表6*10^9
…

4.3 浮点数值表示

第一位数：表示数字符号，正负，+ -
指数位数：当前指数的整数部分，例如 2.12 *2^1 中的2
有效数值：当前指数的小数部分，例如 2.12 *2^1 中的0.12
float数值的科学计数法的转换方法：Float > int > StringBit

4.4 浮点数的计算

计算题：1F-0.9F=0.100000024F，为什么不等于0.1F
解题思路：

总结：只要存在有效数值部分，都有可能存在精度问题，因为每种数值类型保存的有效数值部分的精度不同，当出现转换的数值精度超过了当前数值类型的有效数值的精度范围时，系统会自动舍弃精度范围之外额数字，保留精度范围之内的数值，就会出现精度问题。

4.5 java 和 js之间精度问题处理（Long）

JAVA中对于数值比较大的类型禁止使用Long类型
解决思路：后端传给前端的类型中Long，为64位，要保证数据一致，必须转为二进制传输，因为前端会将后端的数值类型转换为Number类型，等同于java双精度类型Double，最大支持 253次方数据，超过 253的数值保留精确度，java中定义该数值类型应该使用String来表示

参考:20211106 T-31 编码规约