【免费】阿里规约（嵩山版）.docx资源-CSDN文库

java

阿里规约

需积分: 0 120 浏览量 2020-08-14 18:03:19 上传评论收藏 98KB DOCX 举报

资源推荐

资源详情

资源评论

前言

《开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结，经历了多次

大规模一线实战的检验及不断完善，公开到业界后，众多社区开发者踊跃参与，共同打磨

完善，系统化地整理成册，当前的版本是嵩山版。现代软件行业的高速发展对开发者的综

合素质要求越来越高，因为不仅是编程知识点，其它维度的知识点也会影响到软件的最终

交付质量。比如：五花八门的错误码人为地增加排查问题的难度；数据库的表结构和索引

设计缺陷带来的系统架构缺陷或性能风险；工程结构混乱导致后续项目维护艰难；没有鉴

权的漏洞代码易被黑客攻击等等。所以本手册以 开发者为中

心视角，划分为编程规约、异常日志、单元测试、安全规约、数据库、工程结构、

设计规约七个维度，再根据内容特征，细分成若干二级子目录。另外，依据约束力强弱及

故障敏感性，规约依次分为【强制】、【推荐】、【参考】三大类。在延伸信息中，“说

明”对规约做了适当扩展和解释；“正例”提倡什么样的编码和实现方式；“反例”说明需要提

防的雷区，以及真实的错误案例。

手册的愿景是码出高效，码出质量。现代软件架构的复杂性需要协同开发完成，如何

高效地协同呢？无规矩不成方圆，无规范难以协同，比如，制订交通法规表面上是要限制

行车权，实际上是保障公众的人身安全，试想如果没有限速，没有红绿灯，谁还敢上路行

驶？对软件来说，适当的规范和标准绝不是消灭代码内容的创造性、优雅性，而是限制过

度个性化，以一种普遍认可的统一方式一起做事，提升协作效率，降低沟通成本。代码的

字里行间流淌的是软件系统的血液，质量的提升是尽可能少踩坑，杜绝踩重复的坑，切实

提升系统稳定性，码出质量。

我们已经在 杭州云栖大会上发布了配套的 开发规约 插件，下载量达到

万人次，阿里云效也集成了代码规约扫描引擎。次年，发布 万字的配套详解图书

《码出高效》，本书秉持“图胜于表，表胜于言”的理念，深入浅出地将计算机基础、面向

对象思想、探源、数据结构与集合、并发与多线程、单元测试等知识客观、立体地呈

现出来。紧扣学以致用、学以精进的目标，结合阿里巴巴实践经验和故障案例，与底层源

码解析融会贯通，娓娓道来。《码出高效》和《 开发手册》稿费所得收入均捐赠公益

事情，希望用技术情怀帮助更多的人

一、编程规约

(一) 命名风格

【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结

束。

反例：

【强制】所有编程相关的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文

的方式。

说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，纯拼音命名方式更要避免采

 开发手册（嵩山版）

用。

正例：  ! " "#"$%&$ "等国际通用的名称，可视同英文。

反例：'$()  * +打折,%(%-./01+评分,)%-2+福娃,某变量 3

【强制】代码和注释中都要避免使用任何语言的种族歧视性词语。

正例：日本人 印度人  !#4 244! 5)

反例：6./78'94!#42$44

:【强制】类名使用 8;;)<<4风格，但以下情形例外：=.=>==9=

(=8等。

正例：? )!< 584)=@>=A)!>!;85;>()  * 

反例：- )!! 584) @> A)!><(8(>9()  * 

B【强制】方法名、参数名、成员变量、局部变量都统一使用  2)<<4风格。

正例：  !"%@C;44%01;"84)5

【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名

字长。

正例：9A>=<D<=8/><9<@A(6>

反例：9A<=8/>A(6>

【强制】抽象类命名使用 94)!或 .4开头；异常类命名使用 E!;* 结尾；测试

类命名以它要测试的类的名称开始，以 >4结尾。

F【强制】类型与中括号紧挨相连来表示数组。

正例：定义整形数组 +,)) 。

反例：在 参数中，使用 )%)%4+,来定义。

G【强制】(==类中的任何布尔类型的变量，都不要加 4前缀，否则部分框架解析会引

起序列化错误。

说明：在本文 规约中的建表约定第一条，表达是与否的变量采用 4EEE的命名方式，所以，

需要在H)4";I设置从 4EEE到 EEE的映射关系。

反例：定义为基本数据类型 . 45的属性，它的方法也是 4501，框架在反向解析的

时候，“误以为”对应的属性名称是 55，导致属性获取不到，进而抛出异常。

【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名

统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

正例：应用工具类包名为 ! #"";"*、类名为 44%8*4（此规则参考 4;)%的

框架结构）

【强制】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相

同的命名，使可理解性降低。

说明：子类、父类成员变量名相同，即使是 ;"!类型的变量也能够通过编译，另外，局部变量在同

 开发手册（嵩山版）

一方法内的不同代码块中同名也是合法的，这些情况都要避免。对于非 4C)%C)的参数名称也要

避免与成员变量名称相同。

反例：

;"!!44< -"4%/J;"!4 !#K非 4C)%C)的参数名称，不允许与本类成员变

量同名 ;"! 5%0)%1J-0! 5* 1JL 3K

M- )03KHKNN1J在同一方法体中，不允许与其它代码块中的  命名相同

L 3BGFKMMM!44 E54< -"4%/J不允许与父类的

成员变量名称相同 ;"!4 !#KM

【强制】杜绝完全不规范的缩写，避免望文不知义。

反例：94)!<44O缩写”成 94<44；! 5* O缩写”成 ! 5；?"!* 缩写”成 ?"，此类

随意缩写严重降低了代码的可阅读性。

【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整

的单词组合来表达。

正例：对某个对象引用的  *字段进行原子更新的类名为 9 !6-)!?58;5)。

反例：常见的方法内变量为 K的定义方式。

:【推荐】在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度。

正例：4)>2 )#""4>6/9>>@69<=8/>

反例：4)59""=-P )#4/<=8/>>6/9>>@69

B【推荐】如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。

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

正例：

;"!!44=)5)?! )K;"!!44 %() EK;"!!4464 ")!=4))K

【推荐】接口类中的方法和属性不要加任何修饰符号（;"!也不要加），保持代码的

简洁性，并加上有效的 5 !注释。尽量不要在接口里定义变量，如果一定要定义变量，

确定与接口方法相关，并且是整个应用的基础常量。

正例：接口方法签名  5! 01K

接口基础常量 )%<=(9/Q3RRK

反例：接口方法定义 ;"!4)! 5-01K

说明：DF中接口允许有默认实现，那么这个 5-"方法，是对所有实现类都有价值的默认实现。

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

）【强制】对于 )!和 9=类，基于 =9的理念，暴露出来的服务一定是接口，内部的实现类

用 ;的后缀与接口区别。

正例：<!$)!;实现 <!$)!接口。

）【推荐】如果是形容能力的接口名称，取对应的形容词为接口名（通常是–的形容词）。

正例：94)!>)4 )实现 >)4接口。

F【参考】枚举类名带上 "后缀，枚举成员名称需要全大写，单词间用下划线隔开。

说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例：枚举名字为 () !44"4"的成员名称：8<<8/D/=P/69=/。

 开发手册（嵩山版）

G【参考】各层命名规约：

91)!9=层方法命名规约

）获取单个对象的方法用 %做前缀。

）获取多个对象的方法用 4做前缀，复数结尾，如：4=!4。

）获取统计值的方法用 ! "做前缀。

:）插入的方法用 44)做前缀。

B）删除的方法用 ) 5做前缀。

）修改的方法用 ";5做前缀。

.1领域模型命名规约

）数据对象：EEE=，EEE即为数据表名。

）数据传输对象：EEE>=，EEE为业务领域相关的名称。

）展示对象：EEE=，EEE一般为网页名称。

:） (==是 =>=.==的统称，禁止命名成 EEE(==。

(二) 常量定义

【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。

反例：

本例中，开发者 9定义了缓存的 #，然后开发者 .使用缓存时少了下划线，即 #是R5S  RN)55，导致出

现故障 )%#3R5S  RN)55K!!$;"0#T"1K

【强制】在  %或者  %赋值时，数值后使用大写字母 ，不能是小写字母 ，小写容

易跟数字混淆，造成误解。

说明： %3K写的是数字的 ，还是  %型的 ？

【推荐】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

说明：大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解，也不利于维

护。

正例：缓存相关常量放在类 <!$< 44下；系统配置相关常量放在类 4< L%< 44下。

:【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常

量、包内共享常量、类内共享常量。

）跨应用共享常量：放置在二方库中，通常是 !)中的 ! 4目录下。

）应用内共享常量：放置在一方库中，通常是子模块中的 ! 4目录下。

反例：易懂变量也要统一定义成应用内共享常量，两位工程师在两个类中分别定义了“QU的变量：

类 9中：;"!4*!L)%Q3R4RK

类 .中：;"!4*!L)%Q3RRK

9QV"40.Q1，预期是 )"，但实际返回为 -4，导致线上问题。

）子工程内部共享常量：即在当前子工程的 ! 4目录下。

:）包内共享常量：即在当前包下单独的 ! 4目录下。

B）类内共享常量：直接在类内部 ;)4*!L定义。

B【推荐】如果变量值仅在一个固定范围内变化用 "类型来定义。

说明：如果存在名称之外的延伸属性应使用 "类型，下面正例中的数字就是延伸信息，表示一年

中的第几个季节。

 开发手册（嵩山版）

正例：

;"!"4 "J(6/701T8601T98>8/01TP/>60:1K;)4VK4 "04V1J

$44V34VKM;"!%V01J)")4VKMM

(三) 代码格式

【强制】如果是大括号内为空，则简洁地写成JM即可，大括号中间无需换行和空格；如

果是非空代码块则：

）左大括号前不换行。

）左大括号后换行。

）右大括号前换行。

:）右大括号后还有 4等代码则不换行；表示终止的右大括号后必须换行。

【强制】左小括号和右边相邻字符之间不出现空格；右小括号和左边相邻字符之间也不

出现空格；而左大括号前需要加空格。详见第 B条下方正例提示。

反例：-0空格 33空格1

【强制】-- )2$42!$5 等保留字与括号之间都必须加空格。

:【强制】任何二目、三目运算符的左右两边都需要加一个空格。

说明：包括赋值运算符3、逻辑运算符WW、加减乘除符号等。

B【强制】采用 :个空格缩进，禁止使用 >字符。

说明：如果使用 >缩进，必须设置 个 >为 :个空格。9设置 >为 :个空格时，请勿勾选

84!$)!)；而在 !;4中，必须勾选 4)4;!4- )4。

正例：（涉及 XB点）

;"!4*! 50)%+,)%41J缩进 :个空格 )%43R$ RK运算符的左右必须有一个空格 

Y%3K关键词 -与括号之间必须有一个空格，括号内的 -与左括号，与右括号不需要空格 -0Y%331J

4 ";)041KM左大括号前加空格且不换行；左大括号后换行 -0Y%331J

4 ";)0R2 )5R1K右大括号前换行，右大括号后有 4，不用换行 M4J

4 ";)0R #R1K在右大括号后直接结束，则必须换行 MM

【强制】注释的双斜线与注释内容之间有且仅有一个空格。

正例：

这是示例注释，请注意在双斜线之后有一个空格 )%! )%32)%01K

【强制】在进行类型强制转换时，右括号与强制转换值之间不需要任何空格隔开。

正例：

5 "L)435K4! 5301L)4NK

F【强制】单行字符数限制不超过 个，超出需要换行，换行时遵循如下原则：

）第二行相对第一行缩进 :个空格，从第三行开始，不再继续缩进，参考示例。

）运算符与下文一起换行。

）方法调用的点符号与下文一起换行。

:）方法调用中的多个参数需要换行时，在逗号后进行。

B）在括号前不要换行，见反例。

正例：

 开发手册（嵩山版）

剩余49页未读，继续阅读

评论收藏

内容反馈

小木偶MO

粉丝: 5
资源: 3

阿里规约（嵩山版）.docx

阿里规约（嵩山版）.pdf

阿里巴巴规约

阿里规约终极版.pdf

阿里代码规约.pdf

阿里规约手册V1.6（泰山版）.rar

阿里巴巴开发规范.docx

Java开发手册（嵩山版）.docx

阿里巴巴JAVA开发规范word文档

阿里规约手册转载-官方版仅供学习请支持正版

阿里巴巴规约17年-完整版

阿里规约开发手册，嵩山版、华山版

阿里规约-Java开发手册 v-1.7.0（嵩山版）.rar

eclipse阿里规约

工程&代码规约-阿里巴巴.pdf

阿里巴巴开发代码规约

阿里规约性插件

阿里巴巴开发手册嵩山版.rar

阿里Java开发编程规范word版

阿里Java开发手册泰山版 v1.6.0

java阿里开发手册-新

阿里Java开发手册word版--终极版.doc

java开发手册word版本.docx

Java开发手册 嵩山版 华山版 泰山版 2020年 08月 版本

阿里Java开发手册个人加注Word版（同步手册2018.5.20版）

阿里巴巴1.4代码书写规范word版本

基于spring boot的小区物业管理系统源码+论文+答辩ppt

STM32CubeMX安装包(版本:6.9.0) 附带 Java安装包(版本:371) - -2023年7月14日

java-面试指北PDF版本（最新）

最新Java JDK 8安装版（Windows 64位）

自主研发的软著申请代码文档整理输出工具

最新资源

Java开发手册嵩山版华山版泰山版 2020年 08月版本