2021-11-07编码设计规约

2021-11-07编码设计规约

编码设计规约

• 编码规约缘起
• 代码格式与命名风格
• 如何定义常量
• 注释规约
• 前后端设计与规约

编码规约缘起

熵增定律：只要我们没有外力干预代码规范，我们的代码总有一天无可救药
编码规约存在的意义：
减少代码的维护成本
改善可读性
提高团队的开发合作效率
锻炼出更加严谨的思维
身心愉快

代码格式与命名风格

命名体现代码元素特征
抽象类命名使用Abstract或base开头
异常类命名使用Exception结尾
测试类命名以它要测试的类名开始，以Test结尾
类型与中括号紧挨相连来定义数组
枚举类名带上Enum后缀，枚举成员名称需要全大写，单词间用下画线隔开
命名最好望文知义
某些不规范的缩写会导致理解成本增加，比如 condition 缩写成condi
主流的编程语言基本上以英语为基础，此处望文知义的 '文’指的是英文
某业务代码中，曾经出现过 DaZePromotion

如何定义常量

常量复用层次：
跨应用共享常量：放置在SDK中
应用内共享常量：放置在一方库中
子工程内部共享常量：即在当前子工程的constant 目录下
包内共享常量：即在当前包下单独的constant 目录下
类内共享常量：直接在类内部private static final 定义
常量定义设计与规约
常量命名应该全部大写，单词间用下画线隔开，力求语义表达完整清楚，不要嫌名字长
如：
最大库存数量命名：MAX_STOCK_COUNT
缓存失效时间命名：CACHE_EXPIRED_TIME
用户注册错误：USER_REGISTER_ERROR

注释规约

误区：
没啥用，反正不影响编译
为了怕老板说我没有注释
增加代码行数
对简单单词的傻瓜翻译
作用
提高代码可读性
使程序调理清晰
为方便后期代码维护
方便程序员间的交流沟通
生成帮助文档
警示作用，防止踩坑

前后端设计与规约

前后端联合开发的纠结点
接口名称和风格
如果空集合，返回null还是空集合
json组装格式
后台异常的失败提示
错误信息与用户提示透出
前后端交互的API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体
Java与JS对数字类型变量处理方式不同。如果数字太大或者有精度要求，最好使用String类型

@Test
public void test_1(){
    float a = 0.5F - 0.25F;
    float b = 0.25F - 0.0F;
    System.out.println(a == b ? "true" : "false");
    Float c = Float.valueOf(a);
    Float d = Float.valueOf(b);
    System.out.println(c.equals(d) ? "true" : "false");
}
@Test
public void test_2(){
    float a = 1.0F - 0.9F;
    float b = 0.9F - 0.8F;
    System.out.println(a == b ? "true" : "false");
    Float c = Float.valueOf(a);
    Float d = Float.valueOf(b);
    System.out.println(c == d ? "true" : "false");
}

test_1方法输出true true; test_2方法输出false false
科学计数法
表示极大数、极小数、浮点数范围
Float：⽐特数为32，有效数字为7位（⼗进制），数值范围为-3.4E+38 和3.4E+38
Double：⽐特数为64，有效数字为16（⼗进制），数值范围为-1.7E-308和1.7E+308
浮点数


**【强制】**对于需要使用超大整数的场景，服务端一律使用 String 字符串类型返回，禁止使用Long 类型。
说明：Java 服务端如果直接返回 Long 整型数据给前端，JS 会自动转换为 Number 类型（注：此类型为双精度浮点数，表示原理与取值范围等同于 Java 中的 Double）。Long 类型能表示的最大值是 2 的 63 次方-1，在取值范围之内，超过 2 的 53 次方 (9007199254740992)的数值转化为 JS 的 Number 时，有些数值会有精度损失。
扩展说明，在 Long 取值范围内，任何 2 的指数次整数都是绝对不会存在精度损失的，所以说精度损失是一个概率问题。若浮点数尾数位与指数位空间不限，则可以精确表示任何整数，但很不幸，双精度浮点数的尾数位只有 52 位。
反例：通常在订单号或交易号大于等于 16 位，大概率会出现前后端单据不一致的情况，比如，“orderId”: 362909601374617692，前端拿到的值却是: 362909601374617660。
【强制】 HTTP 请求通过 URL 传递参数时，不能超过 2048 字节。
说明：不同浏览器对于 URL 的最大长度限制略有不同，并且对超出最大长度的处理逻辑也有差异，2048字节是取所有浏览器的最小值。
【强制】 HTTP 请求通过 body 传递内容时，必须控制长度，超出最大长度后，后端解析会出错。
说明：nginx 默认限制是 1MB，tomcat 默认限制为 2MB，当确实有业务需要传较大内容时，可以通过调大服务器端的限制。
【强制】 服务器内部重定向必须使用 forward；外部重定向地址必须使用 URL 统一代理模块生成，否则会因线上采用 HTTPS 协议而导致浏览器提示“不安全”，并且还会带来 URL 维护不一致的问题。