Java开发手册黄山版新增规约摘录
共 2815字，需浏览 6分钟
·
2022-04-07 15:29
早期文章
在 2020 年 8 月 3 日 推出的《Java 开发手册嵩山版》后历经了 18 个月阿里又推出了《Java 开发手册黄山版》。想必每个 Java 程序员应该都会关注阿里推出的《Java 开发手册》，个人觉得这份开发手册短小精干，非常实用。在整个手册中可以逐步地学到知识（手册背不下来，只能逐步的吸收，并尽量付诸实践），也可以从知识的表面理解一些更深层的思想。其实之前我做 PHP 的时候，就对这份手册非常的喜欢。因此手册有更新，我把更新的规约摘录在这里，方便阅读，方便学习。
按照《手册》中《附1》来看，黄山版比嵩山版新增了 11 条规约，修改了描述 22 处，具体如下：
1）新增 11 条新规约。比如，浮点数的后缀统一为大写；枚举的属性字段必须是私 有且不可变；配置文件中的密码需要加密等。2）新增描述中的正反例 2 条。比如，多个构造方法次序、NoSuchMethodError 处 理；新增扩展说明 5 条。比如，父集合元素的增加或删除异常等。3）修改描述 22 处。比如，魔法值的示例代码、ScheduledThreadPool 问题等。4）修正嵩山版中部分代码格式错误和描述错误。
《Java 开发手册》（黄山版）
以上部分引自《Java 开发手册》（黄山版），截图如下：
本文整理了新增的 11 条规约，这里都列举出来，具体内容如下：
一、编程规约
（二）常量定义（P3）
3.【强制】浮点数类型的数值后缀统一为大写的 D 或 F。
正例：public static final double HEIGHT = 175.5D;
public static final float WEIGHT = 150.3F;
(十一) 其他（ p23）
6.【强制】枚举 enum（括号内）的属性字段必须是私有且不可变
二、异常日志
(三) 日志规约（ p28）
14.【推荐】为了保护用户隐私，日志文件中的用户敏感信息需要进行脱敏处理。
说明：日志排查问题时，推荐使用订单号、UUID 之类的唯一编号进行查询。
四、安全规约（p31）
9.【强制】对于文件上传功能，需要对于文件大小、类型进行严格检查和控制。
说明：攻击者可以利用上传漏洞，上传恶意文件到服务器，并且远程执行，达到控制网站服务器的目的。
10.【强制】配置文件中的密码需要加密。
五、MySQL 数据库
(一) 建表规约（p32）
10.【强制】在数据库中不能使用物理删除操作，要使用逻辑删除。
说明：逻辑删除在数据删除后可以追溯到行为操作。不过会使得一些情况下的唯一主键变得不唯一，需要根据情况来酌情解决。
六、工程结构
(二) 二方库依赖（p38）
6.【强制】二方库定制包的命名方式，在规定的版本号之后加“-英文说明[序号]”，英文说明可以是部门简称、业务名称，序号直接紧跟在英文说明之后，表示此定制包的顺序号。
说明：fastjson 给 SCM 定制的版本号：1.0.0-SCM1。注：请尽可能在应用端来解决类冲突和加载问题，避免随意发布此类定制包。
(三) 服务器（p39）
1.【强制】调用远程操作必须有超时设置。
说明：类似于 HttpClient 的超时设置需要自己明确去设置 Timeout。根据经验表明，无数次的故障都是因为没有设置超时时间。
2.【推荐】客户端设置远程接口方法的具体超时时间（单位 ms），超时设置生效顺序一般为：1）客户端 Special Method；2）客户端接口级别；3）服务端 Special Method；4）服务端接口级别。
7.【推荐】了解每个服务大致的平均耗时，可以通过独立配置线程池，将较慢的服务与主线程池隔离开，免得不同服务的线程同归于尽。
七、设计规约（p40）
7.【强制】系统设计时要准确识别出弱依赖，并针对性地设计降级和应急预案，保证核心系统正常可用。
说明：系统依赖的第三方服务被降级或屏蔽后，依然不会影响主干流程继续进行，仅影响信息展示、或消息通知等非关键功能，那么这些服务称为弱依赖。
正例：当系统弱依赖于多个外部服务时，如果下游服务耗时过长，则会严重影响当前调用者，必须采取相应降级措施，比如，当调用链路中某个下游服务调用的平均响应时间或错误率超过阈值时，系统自动进行降级或熔断操作，屏蔽弱依赖负面影响，保护当前系统主干功能可用。
反例：某个疫情相关的二维码出错：“服务器开了点小差，请稍后重试”，不可用时长持续很久，引起社会高度关注，原因可能为调用的外部依赖服务 RT 过高而导致系统假死，而在显示端没有做降级预案，只能直接抛错给用户。
我在每个分类后都增加了具体的页码，大家可以自行查阅。
从上面的列举可以看出，黄山版《手册》中“编程规约”增加了 2 条，“异常日志”增加了 1 条，“安全规约”增加了 2 条，“MySQL 数据库”规约增加了 1 条，“工程结构”增加了 4 条，“设计规约”增加了 1 条，一共刚好 11 条规约。11 条规约当中强制的 8 条，推荐的 3 条。摘录的不多不少。
废话不多说了，觉得有用就点赞、关注、在看吧！！
回复【java开发手册】获取《Java开发手册》黄山版。
公众号内回复 【mongo】 下载 SpringBoot 整合操作 MongoDB 的文档。
公众号内回复 【cisp知识整理】 下载 CISP 读书笔记。
之前整理的关于 Redis 的文章：