阿里巴巴开发规范
2021-10-06 17:04:57 3 举报AI智能生成
登录查看完整内容
为你推荐
查看更多
阿里巴巴开发规范手册
作者其他创作
大纲/内容
【强制】命名均不能以下划线或美元符号，也不能以下划线或美元符号结束
【强制】严禁使用拼音与英文混合，更不允许直接使用中文
【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。
【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
【强制】中括号是数组类型的一部分，数组定义如下：String[] args
【强制】POJO 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。
【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
【强制】杜绝完全不规范的缩写，避免望文不知义。
【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。
【推荐】如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。
【推荐】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
1）【强制】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀与接口区别。
2【推荐】如果是形容能力的接口名称，取对应的形容词做接口名（通常是–able 的形式）。正例：AbstractTranslator 实现 Translatable
接口和实现类的命名有两套规则：
【参考】枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。
1） 获取单个对象的方法用 get 做前缀。2） 获取多个对象的方法用 list 做前缀。3） 获取统计值的方法用 count 做前缀。4） 插入的方法用 save/insert 做前缀。5） 删除的方法用 remove/delete 做前缀。6） 修改的方法用 update 做前缀。
Service/DAO 层方法命名规约
1） 数据对象：xxxDO，xxx 即为数据表名。2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。3） 展示对象：xxxVO，xxx 一般为网页名称。4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。
领域模型命名规约
【参考】各层命名规约
命名风格
【强制】不允许任何魔法值（即未经定义的常量）直接出现在代码中。
【强制】long 或者 Long 初始赋值时，使用大写的 L，不能是小写的 l，小写容易跟数字 1 混淆，造成误解。
【推荐】不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护。说明：大而全的常量类，非得使用查找功能才能定位到修改的常量，不利于理解和维护。
1） 跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
2） 应用内共享常量：放置在一方库中，通常是 modules 中的 constant 目录下。
3） 子工程内部共享常量：即在当前子工程的 constant 目录下。
4） 包内共享常量：即在当前包下单独的 constant 目录下。
5） 类内共享常量：直接在类内部 private static final 定义。
【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
【推荐】如果变量值仅在一个范围内变化，且带有名称之外的延伸属性，定义为枚举类。下面正例中的数字就是延伸信息，表示星期几。
常量定义
【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：1） 左大括号前不换行。2） 左大括号后换行。3） 右大括号前换行。4） 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。
【强制】 左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格。
【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。
【强制】任何二目、三目运算符的左右两边都需要加一个空格。
【强制】采用 4 个空格缩进
【强制】注释的双斜线与注释内容之间有且仅有一个空格。
【强制】单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：1） 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。2） 运算符与下文一起换行。3） 方法调用的点符号与下文一起换行。4） 方法调用时，多个参数，需要换行时，在逗号后进行。5） 在括号前不要换行，见反例。
【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。
【强制】IDE 的 text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式，不要使用 Windows 格式。
【推荐】没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。
【推荐】方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。
代码格式
【强制】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可
【强制】所有的覆写方法，必须加@Override 注解。
【强制】相同参数类型，相同业务含义，才可以使用 Java 的可变参数[可变参数是放在最后面的]，避免使用 Object。
【强制】外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。
【强制】不能使用过时的类或方法。
【强制】Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。
【强制】所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。
关于基本数据类型与包装数据类型的使用标准如下：1） 【强制】所有的 POJO 类属性必须使用包装数据类型。2） 【强制】RPC 方法的返回值和参数必须使用包装数据类型。3） 【推荐】所有的局部变量使用基本数据类型。
【强制】定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。
【强制】序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败；如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。
【强制】构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
【强制】POJO 类必须写 toString 方法。使用 IDE 的中工具：source> generate toString时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。
【推荐】使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
【推荐】当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读，此条规则优先于第 15 条规则。
【推荐】 类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter方法
【推荐】setter 方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在getter/setter 方法中，不要增加业务逻辑，增加排查问题的难度。
【推荐】循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。说明：反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行append 操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费。
【推荐】final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 final 关键字：1） 不允许被继承的类，如：String 类。2） 不允许修改引用的域对象，如：POJO 类的域变量。3） 不允许被重写的方法，如：POJO 类的 setter 方法。4） 不允许运行过程中重新赋值的局部变量。5） 避免上下文重复使用一个变量，使用 final 描述可以强制重新定义一个变量，方便更好地进行重构。
【推荐】慎用 Object 的 clone 方法来拷贝对象。
【推荐】类成员与方法访问控制从严：1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。2） 工具类不允许有 public 或 default 构造方法。3） 类非 static 成员变量并且与子类共享，必须是 protected。4） 类非 static 成员变量并且仅在本类使用，必须是 private。5） 类 static 成员变量如果仅在本类使用，必须是 private。6） 若是 static 成员变量，必须考虑是否为 final。7） 类成员方法只供类内部调用，必须是 private。8） 类成员方法只对继承类公开，那么限制为 protected。
OOP 规约
【强制】关于 hashCode 和 equals 的处理，遵循如下规则：1） 只要重写 equals，就必须重写 hashCode。2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。3） 如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals。
【强制】ArrayList的subList结果不可强转成ArrayList，否则会抛出ClassCastException异常
【强制】在 subList 场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增加、删除均会产生 ConcurrentModificationException 异常。
【强制】使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一样的数组，大小就是 list.size()。
【强制】使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常。
【强制】泛型通配符<? extends T>来接收返回的数据，此写法的泛型集合不能使用 add 方法，而<? super T>不能使用 get 方法，做为接口调用赋值时易出错。
【强制】不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator方式，如果并发操作，需要对 Iterator 对象加锁。
【强制】 在 JDK7 版本及以上，Comparator 要满足如下三个条件，不然 Arrays.sort，Collections.sort 会报 IllegalArgumentException 异常。说明：三个条件如下1） x，y 的比较结果和 y，x 的比较结果相反。2） x>y，y>z，则 x>z。3） x=y，则 x，z 比较结果和 y，z 比较结果相同。
【推荐】集合初始化时，指定集合初始值大小。
【推荐】使用 entrySet 遍历 Map 类集合 KV，而不是 keySet 方式进行遍历。
【推荐】高度注意 Map 类集合 K/V 能不能存储 null 值的情况
【参考】合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。
集合处理
【强制】获取单例对象需要保证线程安全，其中的方法也要保证线程安全。说明：资源驱动类、工具类、单例工厂类都需要注意。
【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
【强制】线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。说明：使用线程池的好处是减少在创建和销毁线程上所花的时间以及系统资源的开销，解决资源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题
【强制】线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。说明：Executors 返回的线程池对象的弊端如下：1）FixedThreadPool 和 SingleThreadPool:允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。2）CachedThreadPool 和 ScheduledThreadPool:允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。
【强制】SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为static，必须加锁，或者使用 DateUtils 工具类。
【强制】高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。说明：尽可能使加锁的代码块工作量尽可能的小，避免在锁代码块中调用 RPC 方法。
【强制】对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。
【强制】并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。说明：如果每次访问冲突概率小于 20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于 3 次。
【强制】多线程并行处理定时任务时，Timer 运行多个 TimeTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。
【推荐】使用 CountDownLatch 进行异步转同步操作，每个线程退出前必须调用 countDown方法，线程执行代码注意 catch 异常，确保 countDown 方法被执行到，避免主线程无法执行至 await 方法，直到超时才返回结果。说明：注意，子线程抛出异常堆栈，不能在主线程 try-catch 到。
【推荐】避免 Random 实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed 导致的性能下降。说明：Random 实例包括 java.util.Random 的实例或者 Math.random()的方式。正例：在 JDK7 之后，可以直接使用 API ThreadLocalRandom，而在 JDK7 之前，需要编码保证每个线程持有一个实例。
【推荐】在并发场景下，通过双重检查锁（double-checked locking）实现延迟初始化的优化问题隐患(可参考 The \"Double-Checked Locking is Broken\" Declaration)，推荐解决方案中较为简单一种（适用于 JDK5 及以上版本），将目标属性声明为 volatile 型。
【参考】volatile 解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但是如果多写，同样无法解决线程安全问题。如果是 count++操作，使用如下类实现：AtomicInteger count = new AtomicInteger(); count.addAndGet(1); 如果是 JDK8，推荐使用 LongAdder 对象，比 AtomicLong 性能更好（减少乐观锁的重试次数）。
【参考】 HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在开发过程中可以使用其它数据结构或加锁来规避此风险。
【参考】ThreadLocal 无法解决共享对象的更新问题，ThreadLocal 对象建议使用 static修饰。这个变量是针对一个线程内所有操作共享的，所以设置为静态变量，所有此类实例共享此静态变量 ，也就是说在类第一次被使用时装载，只分配一块存储空间，所有此类的对象(只要是这个线程内定义的)都可以操控这个变量。
并发处理
编程规范
异常日志
【强制】好的单元测试必须遵守 AIR 原则。
【强制】单元测试应该是全自动执行的，并且非交互式的。测试框架通常是定期执行的，执行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元测试中不准使用 System.out 来进行人肉验证，必须使用 assert 来验证。
【强制】保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。
【强制】单元测试是可以重复执行的，不能受到外界环境的影响。
【强制】对于单元测试，要保证测试粒度足够小，有助于精确定位问题。单测粒度至多是类级别，一般是方法级别。
【强制】核心业务、核心应用、核心模块的增量代码确保单元测试通过。
【强制】单元测试代码必须写在如下工程目录：src/test/java，不允许写在业务代码目录下。
【推荐】单元测试的基本目标：语句覆盖率达到 70%；核心模块的语句覆盖率和分支覆盖率都要达到 100%
【推荐】编写单元测试代码遵守 BCDE 原则，以保证被测试模块的交付质量。
【推荐】对于数据库相关的查询，更新，删除等操作，不能假设数据库里的数据是存在的，或者直接操作数据库把数据插入进去，请使用程序插入或者导入数据的方式来准备数据。
【推荐】和数据库相关的单元测试，可以设定自动回滚机制，不给数据库造成脏数据。或者对单元测试产生的数据有明确的前后缀标识。
【推荐】对于不可测的代码建议做必要的重构，使代码变得可测，避免为了达到测试要求而书写不规范测试代码。
【推荐】在设计评审阶段，开发人员需要和测试人员一起确定单元测试范围，单元测试最好覆盖所有测试用例（UC）。
【推荐】单元测试作为一种质量保障手段，不建议项目发布后补充单元测试用例，建议在项目提测前完成单元测试。
【参考】为了更方便地进行单元测试，业务代码应避免以下情况： 构造方法中做的事情过多。 存在过多的全局变量和静态方法。 存在过多的外部依赖。 存在过多的条件语句。说明：多层条件语句建议使用卫语句、策略模式、状态模式等方式重构。
【参考】不要对单元测试存在如下误解： 那是测试同学干的事情。本文是开发手册，凡是本文内容都是与开发同学强相关的。 单元测试代码是多余的。汽车的整体功能与各单元部件的测试正常与否是强相关的。 单元测试代码不需要维护。一年半载后，那么单元测试几乎处于废弃状态。 单元测试与线上故障没有辩证关系。好的单元测试能够最大限度地规避线上故障。
单元测试
安全规范
【强制】表达是与否概念的字段，必须使用 is_xxx 的方式命名，数据类型是 unsigned tinyint（ 1 表示是，0 表示否）。
【强制】表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下划线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。
【强制】表名不使用复数名词。
【强制】禁用保留字，如 desc、range、match、delayed 等，请参考 MySQL 官方保留字。
【强制】主键索引名为 pk_字段名；唯一索引名为 uk_字段名；普通索引名则为 idx_字段名。
【强制】小数类型为 decimal，禁止使用 float 和 double。
【强制】如果存储的字符串长度几乎相等，使用 char 定长字符串类型。
【强制】varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
【推荐】表的命名最好是加上“业务名称_表的作用”。
【推荐】库名与应用名称尽量一致。
【推荐】如果修改字段含义或对字段表示的状态追加时，需要及时更新字段注释。
【推荐】字段允许适当冗余，以提高查询性能，但必须考虑数据一致。冗余字段应遵循：1）不是频繁修改的字段。2）不是 varchar 超长字段，更不能是 text 字段。
【推荐】单表行数超过 500 万行或者单表容量超过 2GB，才推荐进行分库分表。
【参考】合适的字符存储长度，不但节约数据库表空间、节约索引存储，更重要的是提升检索速度。
建表规约
【强制】业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。说明：不要以为唯一索引影响了 insert 速度，这个速度损耗可以忽略，但提高查找速度是明显的；另外，即使在应用层做了非常完善的校验控制，只要没有唯一索引，根据墨菲定律，必然有脏数据产生。
【强制】超过三个表禁止 join。需要 join 的字段，数据类型必须绝对一致；多表关联查询时，保证被关联的字段需要有索引。
【强制】在 varchar 字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度即可。
【强制】页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。
【推荐】如果有 order by 的场景，请注意利用索引的有序性。order by 最后的字段是组合索引的一部分，并且放在索引组合顺序的最后，避免出现 file_sort 的情况，影响查询性能。
【推荐】利用覆盖索引来进行查询操作，避免回表。
【推荐】利用延迟关联或者子查询优化超多分页场景。
）consts 单表中最多只有一个匹配行（主键或者唯一索引），在优化阶段即可读取到数据。2）ref 指的是使用普通的索引（normal index）。3）range 对索引进行范围检索。
【推荐】SQL 性能优化的目标：至少要达到 range 级别，要求是 ref 级别，如果可以是 consts最好。
【推荐】建组合索引的时候，区分度最高的在最左边。
【推荐】防止因字段类型不同造成的隐式转换，导致索引失效。
【参考】创建索引时避免有如下极端误解：1）宁滥勿缺。认为一个查询就需要建一个索引。2）宁缺勿滥。认为索引会消耗空间、严重拖慢更新和新增速度。3）抵制惟一索引。认为业务的惟一性一律需要在应用层通过“先查后插”方式解决。
索引规约
【强制】不要使用 count(列名)或 count(常量)来替代 count(*)，count(*)是 SQL92 定义的标准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。说明：count(*)会统计值为 NULL 的行，而 count(列名)不会统计此列为 NULL 值的行。
【强制】使用 ISNULL()来判断是否为 NULL 值。说明：NULL 与任何值的直接比较都为 NULL。1） NULL<>NULL 的返回结果是 NULL，而不是 false。2） NULL=NULL 的返回结果是 NULL，而不是 true。3） NULL<>1 的返回结果是 NULL，而不是 true。
【强制】在代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。
【强制】不得使用外键与级联，一切外键概念必须在应用层解决。
【强制】禁止使用存储过程，存储过程难以调试和扩展，更没有移植性。
【强制】数据订正时，删除和修改记录时，要先 select，避免出现误删除，确认无误才能执行更新语句。
【推荐】in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控制在 1000 个之内。
【参考】如果有全球化需要，所有的字符存储与表示，均以 utf-8 编码，注意字符统计函数的区别。
【参考】TRUNCATE TABLE 比 DELETE 速度快，且使用的系统和事务日志资源少，但 TRUNCATE无事务且不触发 trigger，有可能造成事故，故不建议在开发代码中使用此语句。说明：TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。
)SQL 语句
mysql数据库
工程结构
阿里巴巴开发规范
0 条评论
回复 删除
下一页
