Java开发手册黄山版新增规约摘录

Posted 2022-03-28 码农UP2U

早期文章

HDFS 在 HA 模式集群下 JournalNode 节点的作用

大数据 | HDFS 元数据持久化笔记

大数据 | Java 操作 HDFS 常用 API

大数据 | HDFS 常用操作命令

        在 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 的文章：

Redis | Redis 的安装

Redis | Redis 的帮助命令

Redis | Redis 命令分类

Redis | Redis 通用命令

Redis | Redis 字符串相关命令

Redis | Redis 列表相关命令

Redis | Redis 集合相关命令

Redis | Redis 有序集合相关命令

Redis | Redis 哈希相关命令

Redis | 源码阅读 —— 字符串

Redis | 源码阅读 —— 链表

Redis | Redis Pub/Sub相关命令

Redis | 管道 —— PipeLine

Redis | SpringBoot整合Redis

Redis | Redis 的事务一

Redis | Redis 的事务二

Redis | 基础数据类型应用场景

Redis | 事务源码阅读

Redis | 事务源码阅读 —— watch

Redis | 慢查询

Redis | 给接口添加缓存

Redis | Redis 也会算距离

新增16条设计规约！阿里巴巴Java开发手册（详尽版）开放下载！

《阿里巴巴Java开发手册》是阿里内部Java工程师所遵循的开发规范，涵盖编程规约、单元测试规约、异常日志规约、MySQL规约、工程规约、安全规约等，这是近万名阿里Java技术精英的经验总结，并经历了多次大规模一线实战检验及完善。这是阿里回馈给Java社区的一份礼物，希望能够帮助企业开发团队在Java开发上更高效、容错、有协作性，提高代码质量，降低项目维护成本。

 

2018年6月5日，《阿里巴巴Java开发手册》再次刷新代码规范认知，我们新增了16条设计规约！

 

点此免费下载《阿里巴巴Java开发手册》（详尽版）！

 

 

 

 

为何要新增设计规约？

 

脍炙人口的唐诗“两个黄鹂鸣翠柳，一行白鹭上青天”，清爽直接，简明易懂。可读性好的代码也是让人陶醉的，那么如何写出可读性的代码？

 

代码的可读性是指代码让人容易阅读、理解、调试、可预料的程度。提高代码的可读性可以为代码阅读者节约时间和精力，提升团队协作效率。熟悉和遵守《阿里巴巴JAVA开发手册》的编程风格，那只是“标”，而代码可读性的“本”可以追溯到软件设计阶段。试想一下如果发型师没有设计好，不用指望能剪出一个“可读性”比较好的你。

 

设计是一种梦想和追求，谁都喜欢有气质的女神，谁都会欣赏有设计感的代码。你可能会问，什么是设计感？就像烧饭这件事，村姑和御厨都会烧，都能吃饱，但是菜品的美感、口感，有本质的区别。代码到艺术层面上，能够体现出来非常好的扩展性、解耦性。代码就象积木一样，换一个搭法，也是OK的，结构清晰，不用担心拔出萝卜带出泥。

 

 

 

何为16条？

 

设计规约是根据阿里巴巴实际项目架构经验提炼而成，共16条。设计规约主要从UML图和架构设计原则来规定比较基础的软件设计理念，并且明确了超过什么样的阈值需要以什么样的方式来呈现设计思维。根据阿里巴巴内部的反馈声音来看，对于数据底层结构、状态图、以及敏捷开发相关的三条，共鸣感最强，那么详细点评一下：

 

 

数据底层结构

 

底层数据结构属于大厦的地基工程，如果地基不稳，那么上层去修正难度是相当大的，甚至是无法修正。所以设计规约提倡，存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。有缺陷的底层数据结构容易导致系统风险高，可扩展性差，重构成本因历史数据迁移、系统平滑过渡也会陡然增加，所以，存储方案和数据结构需要认真地进行设计和评审，生产环境提交执行后，需要进行double check。评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发展、表或字段之间的辩证关系、字段名称、字段类型、索引等；数据结构变更（如在原有表中新增字段）也需要进行评审通过后上线。

 

状态图

 

业务对象状态相关的编码错误是引起线上故障的一个重要导火索。多一个状态，少一个状态，如果没有历史设计文档沉淀，那么都是灾难性的。如果某个业务对象的状态超过3个，使用状态图来表达并且明确状态变化的各个触发条件。状态图的核心是对象状态，首先明确对象有多少种状态，然后明确两两状态之间是否存在直接转换关系，再明确触发状态转换的条件是什么。淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。

 

 

敏捷开发

 

敏捷开发是当下流行的一种开发模式，相比传统软件生产流程，更加快速地交付。但是，敏捷开发适合于信任度好、理解力强、技术水平相对一致的创业型团队。但是在很多公司敏捷成为一个抓进度的拔苗助长式的借口。所以避免如下误解：敏捷开发 = 讲故事 + 编码 + 发布。敏捷开发是快速交付迭代可用的系统，省略多余的设计方案，摒弃传统的审批流程，但核心关键点上的必要设计和文档沉淀是需要的。

 

写在最后

 

我们相信技术之心生生不息，也相信好的规约值得被传播和应用。

本次新增的不单是16条新的设计规约，还是千万阿里人的技术之心。

我们也期待大家的意见，持续完善，

那么说说大家眼里的软件设计中遇到的坑吧。

 

---------

本文作者：孤尽?