阿里巴巴代码规范

一、命名风格

1.类名

UpperCamleCase

2.方法名、参数名、成员变量、局部变量

lowerCamleCase

3.常量名

全部大写，单词间下划线隔开

MAX_STOCK_COUNT

4.抽象类命名

Abstract或Base开头

5.异常类命名

xxxException

6.测试类命名

xxxTest

7.数组

定义整形数组 int[] arrayDemo

8.POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。

9.包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xJ4nAQla-1654337319922)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505182314181.png)]

10.避免不规范缩写

反例：AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function 缩写”成 Fu，此类随意缩写严重降低了代码的可阅读性。

11.在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度

startTime

workQueue

nameList

12.如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。

public class OrderFactory

public class LoginProxy

public class ResourceObserver

13.接口类中的方法和属性不要加任何修饰符号**（public 也不要加）**，保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，确定与接口方法相关，并且是整个应用的基础常量。

方法：void commit();

常量：String COMPANY="alibaba";

14.对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用Impl 的后缀与接口区别。

用CacheServiceImpl实现CacheService

15.Service/DAO 层方法命名规约

1）获取单个对象的方法用 get 做前缀。

2）获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects。

3）获取统计值的方法用 count 做前缀。

4）插入的方法用 save/insert 做前缀。

5）删除的方法用 remove/delete 做前缀。

6）修改的方法用 update 做前缀。

二、常量定义

1.不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 SystemConfigConsts 下。

三、代码格式

1.if/for/while/switch/do 等保留字与括号之间都必须加空格。

2.任何二目、三目运算符的左右两边都需要加一个空格。

a = b a && b

3.采用 4 个空格缩进，禁止使用 Tab 字符。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-eldt5HmF-1654337319923)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505183602488.png)]

4.注释的双斜线与注释内容之间有且仅有一个空格。

// 注释

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

double first = 3.2d;
int second = (int)first + 2;

6.单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：

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

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

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

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

5）在括号前不要换行

StringBuilder sb = new StringBuilder;
sb.append("yang").append("yao").append("chen")....append("chen");

6.方法参数在定义和传入时，多个参数逗号后面必须加空格。

method(args1, args2, args3);

7.不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

四、OOP规约

1.避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。

2.所有的覆写方法，必须加@Override 注解。

3.Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals。

正确：

"test".equals(object);

错误：

object.equals("test");//不能反着来

4.所有整型包装类对象之间值的比较，全部使用 equals 方法比较。

对于 Integer var = ? 在-128 至 127 之间的赋值，Integer 对象是在 IntegerCache.cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。

5.浮点数之间的等值判断，基本数据类型不能用==来比较，包装数据类型不能用 equals来判断。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-P6q4byAW-1654337319923)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505185004686.png)]

如上所示 BigDecimal 的等值比较应使用 compareTo()方法，而不是 equals()方法。equals()方法会比较值和精度（1.0 与 1.00 返回结果为 false），而 compareTo()则会忽略精度。

6.定义数据对象 DO 类时，属性类型要与数据库字段类型相匹配。

正例：数据库字段的 bigint 必须与类属性的 Long 类型相对应。

反例：某个案例的数据库表 id 字段定义类型 bigint unsigned，实际类对象属性为 Integer，随着 id 越来越大，超过 Integer 的表示范围而溢出成为负数。

7.禁止使用构造方法 BigDecimal(double)的方式把 double 值转化为 BigDecimal 对象。

也就是说只能用上述的new方法

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-LbuwDmjJ-1654337319923)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505185225533.png)]

8.所有的 POJO 类属性必须使用包装数据类型。

9.所有的局部变量使用基本数据类型。

10.定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。

POJO 类的 createTime 默认值为 new Date()，但是这个属性在数据提取时并没有置入具体值，在更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。

11.构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。

12.类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter方法。

13.setter 方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在

getter/setter 方法中，不要增加业务逻辑，增加排查问题的难度。

14.循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-04z2z5Ko-1654337319923)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505185536869.png)]

五、日期时间

1.日期格式化时，传入 pattern 中表示年份统一使用小写的 y。

new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-PsZVQTIA-1654337319924)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505185654182.png)]

2.获取当前毫秒数：System.currentTimeMillis(); 而不是 new Date().getTime()。

3.不允许在程序任何地方中使用：

1）java.sql.Date。

2）java.sql.Time。

3）java.sql.Timestamp。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-5n23wYZH-1654337319924)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505185845796.png)]

4.不要在程序中写死一年为 365 天，避免在公历闰年时出现日期转换错误或程序逻辑错误。

//获取今年的天数
int daysOfThisYear = LocalDate.now().lengthOfYear();
//获取指定某一年的天数
LocalDate.of()

六、集合处理

1.判断所有集合内部的元素是否为空，使用 isEmpty() 方法，而不是 size()==0 的方式。

前者时间复杂度在某些集合中为O(1)，且可读性更好。

2.使用 Map 的方法 keySet()/values()/entrySet()返回集合对象时，不可以对其进行添加元素操作，否则会抛出 UnsupportedOperationException 异常。

3.使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一致、长度为 0 的空数组。

4.不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator 方式，如果并发操作，需要对 Iterator 对象加锁。

List<String>list = new ArrayList<>();
list.add("1");
list.add("2");
Iterator<String> iterator = list.iterator();
while(iterator.hasNext()){String item = irerator.next();if(xxx){iterator.remove();}
}

5.Comparator 实现类要满足如下三个条件

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-sREfVjFl-1654337319924)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505192719782.png)]

七、并发处理

暂时没看。

八、控制语句

1，在一个 switch 块内，每个 case 要么通过 continue/break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default语句并且放在最后，即使它什么代码也没有。

2.当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null判断。

3.在 if/else/for/while/do 语句中必须使用大括号。

4.在高并发场景中，避免使用”等于”判断作为中断或退出的条件。

6.表达异常的分支时，少用 if-else 方式，这种方式可以改写成：

7.除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xxmBvZyJ-1654337319924)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505193605625.png)]

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-vnELVBkM-1654337319924)(…/…/…/Library/Application%20Support/typora-user-images/image-20220505193612946.png)]

九、注释规约

1.类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用 // xxx 方式。

2.所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

3.所有的类都必须添加创建者和创建日期。

 /**
\* @姚同学
\* @date 2022/05/05
*/

4.方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释使用 /* */ 注释，注意与代码对齐。

5.代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。

6.谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

说明：代码被注释掉有两种可能性：

1）后续会恢复此段代码逻辑。

2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉即可，假如需要查阅历史代码，登录代码仓库即可。

7.对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。

十、前后端规约

1.前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体。

说明： 1）协议：生产环境必须使用 HTTPS。 2）路径：每一个 API 需对应一个路径，表示 API 具体的请求地址： a）代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。 b） URL 路径不能使用大写，单词如果需要分隔，统一使用下划线。 c）路径禁止携带表示请求内容类型的后缀，比如".json",“.xml”，通过 accept 头表达即可。 3）请求方法：对具体操作的定义，常见的请求方法如下： a） GET：从服务器取出资源。 b） POST：在服务器新建一个资源。 c） PUT：在服务器更新资源。 d） DELETE：从服务器删除资源。 4）请求内容：URL 带的参数必须无敏感信息或符合安全要求；body 里带参数时必须设置 Content-Type。 5）响应体：响应体 body 可放置多种数据类型，由 Content-Type 头来确定。

2.前后端数据列表相关的接口返回，如果为空，则返回空数组[]或空集合 {}。

（减少前端的null判断）

3.服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，errorCode、errorMessage、用户提示信息四个部分。

说明：四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息要求：简短清晰、提示友好，引导用户进行下一步操作或解释错误原因，提示信息可以包括错误原因、上下文环境、推荐操作等。 errorCode：参考附表 3。errorMessage：简要描述后端出错原因，便于错误排查人员快速定位问题，注意不要包含敏感数据信息。
正例：常见的 HTTP 状态码如下 1） 200 OK: 表明该请求被成功地完成，所请求的资源发送到客户端。 2） 401 Unauthorized: 请求要求身份验证，常见对于需要登录而用户未登录的情况。 3） 403 Forbidden：服务器拒绝请求，常见于机密信息或复制其它登录用户链接访问服务器的情况。 4） 404 Not Found: 服务器无法取得所请求的网页，请求资源不存在。 5） 500 Internal Server Error: 服务器内部错误。

4.在前后端交互的 JSON 格式数据中，所有的 key 必须为小写字母开始的 lowerCamelCase 风格，符合英文表达习惯，且表意完整。

5.对于需要使用超大整数的场景，服务端一律使用 String 字符串类型返回，禁止使用 Long 类型。

6.在翻页场景中，用户输入参数的小于 1，则前端返回第一页参数给后端；后端发现用户输入的参数大于总页数，直接返回最后一页。

7.前后端的时间格式统一为"yyyy-MM-dd HH:mm:ss"，统一为 GMT。

十一、安全规约

1.在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放的机制，如数量限制、疲劳度控制、验证码校验，避免被滥刷而导致资损。

说明：如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并造成短信平台资源浪费。

2.发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。