【学习笔记】编程规约

梦里梦外; 2023-06-26 12:28 47阅读 0赞

# 概述 #

阿里Java开发手册对编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约进行了规范并且进行了开源，整个手册针对java程序的诞生过程进行较为全面的规范，并且有插件（P3C）进行检查（结尾附地址）。即使不是java软件工程师，手册中的很大一部分也能对大部分编程工作者（例如算法工程师、数据分析师）有建设性的帮助，其中最主要的是编程规约这一部分，抛去OOP规约（面向对象编程、集合处理）可能稍对java基础有一定要求，剩余部分基本可以看做通用规范，因此，作为一名辛勤的大自然搬运工，这里记录以便日后时常查看学习。

<table> 
 <thead> 
  <tr> 
   <th>类别</th> 
   <th>规约</th> 
   <th>数量</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>编程规约</td> 
   <td>命名风格</td> 
   <td>16</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>常量定义</td> 
   <td>5</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>代码格式</td> 
   <td>12</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>OOP规约</td> 
   <td>21</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>集合处理</td> 
   <td>14</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>并发处理</td> 
   <td>15</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>控制语句</td> 
   <td>10</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>注释规约</td> 
   <td>11</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>其它</td> 
   <td>8</td> 
  </tr> 
  <tr> 
   <td>异常日志</td> 
   <td>异常处理</td> 
   <td>13</td> 
  </tr> 
  <tr> 
   <td>日志规约</td> 
   <td></td> 
   <td>9</td> 
  </tr> 
  <tr> 
   <td>单元测试</td> 
   <td></td> 
   <td>16</td> 
  </tr> 
  <tr> 
   <td>安全规约</td> 
   <td></td> 
   <td>8</td> 
  </tr> 
  <tr> 
   <td>MySQL数据库</td> 
   <td>建表规约</td> 
   <td>15</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>索引规约</td> 
   <td>11</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>SQL语句</td> 
   <td>11</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>ORM映射</td> 
   <td>10</td> 
  </tr> 
  <tr> 
   <td>工程结构</td> 
   <td>应用分层</td> 
   <td>3</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>二方库依赖</td> 
   <td>10</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>服务器</td> 
   <td>5</td> 
  </tr> 
  <tr> 
   <td>设计规约</td> 
   <td></td> 
   <td>16</td> 
  </tr> 
 </tbody> 
</table>

# 命名风格 #

*  【强制】代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
 *  【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
 *  【强制】类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID 等。

JavaServerlessPlatform / UserDO / XmlService / TcpUdpDeal / TaPromotion

>  *  DO（ Data Object）：与数据库表结构一一对应，通过DAO层向上传输数据源对象。
>  *  DTO（ Data Transfer Object）：数据传输对象，Service或Manager向外传输的对象。
>  *  BO（ Business Object）：业务对象。 由Service层输出的封装业务逻辑的对象。
>  *  VO（ View Object）：显示层对象，通常是Web向模板渲染引擎层传输的对象。
>  *  AO (Application Object) :应用对象,在 Web 层与 Service 层之间抽象的复用对象模型,极为贴近展示层,复用度不高。
>  *  POJO 是 DO / DTO / BO / VO 的统称.

*  【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。

localValue / getHttpMessage() / inputUserId

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

MAX_STOCK_COUNT / CACHE_EXPIRED_TIME

*  【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
 *  【强制】类型与中括号紧挨相连来表示数组。
 *  【强制】POJO 类中布尔类型变量都不要加 is 前缀，否则部分框架解析会引起序列化错误。

说明：在本文 MySQL 规约中的建表约定第一条，表达是与否的值采用 is\_xxx 的命名方式，所以，需要在设置从 is\_xxx 到 xxx 的映射关系。

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

应用工具类包名为 com.alibaba.ai.util、类名为 MessageUtils

*  【强制】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名，使可读性降低。
 *  【强制】杜绝完全不规范的缩写，避免望文不知义。
 *  【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。
 *  【推荐】在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度。

startTime / workQueue / nameList / TERMINATED_THREAD_COUNT

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

public class OrderFactory;
    
    public class LoginProxy;
    
    public class ResourceObserver;

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

接口方法签名 void commit();
    
    接口基础常量 String COMPANY = "alibaba";

*  接口和实现类的命名有两套规则

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

CacheServiceImpl 实现 CacheService 接口

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

> SOA：Service-Oriented Architecture，面向服务架构。服务间只通过接口进行沟通。

*  【参考】枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。  
    说明：枚举其实就是特殊的类，域成员均为常量，且构造方法被默认强制是私有

枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。

*  【参考】各层命名规约

A) Service/DAO 层方法命名规约

*  获取单个对象的方法用 get 做前缀。
 *  获取多个对象的方法用 list 做前缀，复数形式结尾如：listObjects。
 *  获取统计值的方法用 count 做前缀。
 *  插入的方法用 save/insert 做前缀。
 *  删除的方法用 remove/delete 做前缀。
 *  修改的方法用 update 做前缀。

B) 领域模型命名规约

*  数据对象：xxxDO，xxx 即为数据表名。
 *  数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
 *  展示对象：xxxVO，xxx 一般为网页名称。
 *  POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

> 领域模型是一个分析模型，帮助系统分析人员、用户认识现实业务的工具，描述的是业务中涉及到的实体及其相互之间的关系，它是需求分析的产物，与问题域相关。

# 常量定义 #

*  【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。
 *  【强制】在 long 或者 Long 赋值时，数值后使用大写的 L，不能是小写的 l，小写容易跟数
 *  【推荐】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

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

*  【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
    
     *  跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
     *  应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。
     *  子工程内部共享常量：即在当前子工程的 constant 目录下。
     *  包内共享常量：即在当前包下单独的 constant 目录下。
     *  类内共享常量：直接在类内部 private static final 定义。
 *  【推荐】如果变量值仅在一个固定范围内变化用 enum 类型来定义。

public enum SeasonEnum {
    
    SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);
    
    private int seq;
    
    SeasonEnum(int seq) {
    
    this.seq = seq;
    
    }
    
    public int getSeq() {
    
    return seq;
    
    }
    
    }

# 代码格式 #

*  【强制】如果是大括号内为空，则简洁地写成\{\}即可，大括号中间无需换行和空格；如果是非空代码块则：
    
     *  左大括号前不换行。
     *  左大括号后换行。
     *  右大括号前换行。
     *  右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。
 *  【强制】左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格；而左大括号前需要空格。
 *  【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。
 *  【强制】任何二目、三目运算符的左右两边都需要加一个空格。

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

*  【强制】采用 4 个空格缩进，禁止使用 tab 字符。

说明：如果使用 tab 缩进，必须设置 1 个 tab 为 4 个空格。IDEA 设置 tab 为 4 个空格时，请勿勾选 Use tab character；而在 eclipse 中，必须勾选 insert spaces for tabs。

public static void main(String[] args) {
    
    // 缩进 4 个空格
    
    String say = "hello";
    
    // 运算符的左右必须有一个空格
    
    int flag = 0;
    
    // 关键词 if 与括号之间必须有一个空格，括号内的 f 与左括号，0 与右括号不需要空格 if (flag == 0) {
    
    System.out.println(say);
    
    }
    
    // 左大括号前加空格且不换行；左大括号后换行
    
    if (flag == 1) {
    
    System.out.println("world");
    
    // 右大括号前换行，右大括号后有 else，不用换行
    
    } else {
    
    System.out.println("ok");
    
    // 在右大括号后直接结束，则必须换行
    
    }
    
    }

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

// 这是示例注释，请注意在双斜线之后有一个空格

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

long first = 1000000000000L;
    
    int second = (int)first + 2;

*  【强制】单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则
    
     *  第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。
     *  运算符与下文一起换行。
     *  方法调用的点符号与下文一起换行。
     *  方法调用中的多个参数需要换行时，在逗号后进行。
     *  在括号前不要换行，见反例。

StringBuilder sb = new StringBuilder();
    
    // 超过 120 个字符的情况下，换行缩进 4 个空格，点号和方法名称一起换行
    
    sb.append("Jack").append("Ma")...
    
        .append("alibaba")...
    
        .append("alibaba")...
    
        .append("alibaba");

反例：
    
    StringBuilder sb = new StringBuilder();
    
    // 超过 120 个字符的情况下，不要在括号前换行
    
    sb.append("Jack").append("Ma")...append
    
        ("alibaba");
    
    // 参数很多的方法调用可能超过 120 个字符，不要在逗号前换行 method(args1, args2, args3, ...
    
        , argsX);

*  【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。

method(args1, args2, args3);

*  【强制】IDE 的 text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式，不要使用 Windows 格式。
 *  【推荐】单个方法的总行数不超过 80 行。  
    说明：除注释之外的方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数不超过80 行。
 *  【推荐】没有必要增加若干空格来使变量的赋值等号与上一行对应位置的等号对齐。

int one = 1;
    
    long two = 2L;
    
    float three = 3F;
    
    StringBuilder sb = new StringBuilder();

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

说明：任何情形，没有必要插入多个空行进行隔开。

# 控制语句 #

*  【强制】在一个 switch 块内，每个 case 要么通过 continue/break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使它什么代码也没有。
 *  【强制】当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null 判断。
 *  【强制】在 if/else/for/while/do 语句中必须使用大括号。
 *  【强制】在高并发场景中，避免使用”等于”判断作为中断或退出的条件。

> 如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。

*  【推荐】表达异常的分支时，少用 if-else 方式。

这种方式可以改写成：
    
    if (condition) {
    
    ...
    
    return obj;
    
    }
    
    // 接着写 else 的业务逻辑代码;

*  【强制】请勿超过 3 层。

> 超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现，其中卫语句即代码逻辑先考虑失败、异常、中断、退出等直接返回的情况，以方法多个出口的方式，解决代码中判断分支嵌套的问题，这是逆向思维的体现。

public void findBoyfriend(Man man) {
    
        if (man.isUgly()) {
    
            System.out.println("本姑娘是外貌协会的资深会员");
    
            return;
    
        }
    
        if (man.isPoor()) {
    
            System.out.println("贫贱夫妻百事哀");
    
            return;
    
        }
    
        if (man.isBadTemper()) {
    
                System.out.println("银河有多远，你就给我滚多远");
    
                return;
    
        }
    
        System.out.println("可以先交往一段时间看看");
    
    }

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

// 伪代码如下
    
    final boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
    
     
    
    if (existed) {
    
    ...
    
    }

*  【推荐】不要在其它表达式（尤其是条件表达式）中，插入赋值语句。
 *  【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的 try-catch 操作（这个 try-catch 是否可以移至循环体外）。
 *  【推荐】避免采用取反逻辑运算符。

正例：使用 if (x < 628) 来表达 x 小于 628。
    
    反例：使用 if (!(x >= 628)) 来表达 x 小于 628。

*  【推荐】接口入参保护，这种场景常见的是用作批量操作的接口。
 *  【参考】下列情形，需要进行参数校验：
    
     *  调用频次低的方法。
     *  执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
     *  需要极高稳定性和可用性的方法。
     *  对外提供的开放接口，不管是 RPC/API/HTTP 接口。
     *  敏感权限入口。
 *  【参考】下列情形，不需要进行参数校验：
    
     *  极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。
     *  底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一台服务器中，所以 DAO 的参数校验，可以省略。
     *  被声明成 private 只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

# 注释规约 #

*  【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/\**内容*/格式，不得使用// xxx 方式。
 *  【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

> 对子类的实现要求，或者调用注意事项，请一并说明。

*  【强制】所有的类都必须添加创建者和创建日期。
 *  【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/\* \*/注释，注意与代码对齐。
 *  【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。
 *  【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
 *  【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
 *  【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。
 *  【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
 *  【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
 *  【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

>  *  待办事宜（TODO）:（标记人，标记时间，\[预计处理时间\]）  
>     表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。
>  *  错误，不能工作（FIXME）:（标记人，标记时间，\[预计处理时间\]）  
>     在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

# 参考资料 #

[《阿里Java开发手册》][Java]

[《阿里Java开发手册》][Java 1]

[P3C开源项目][P3C]

[P3C插件使用文档][P3C 1]

[高效代码50例][50]

--------------------

*  [Doraengineer’s blog说明][Doraengineer_s blog]

[Java]: https://yq.aliyun.com/articles/656256
[Java 1]: http://click.aliyun.com/m/1000019584/
[P3C]: https://github.com/alibaba/p3c
[P3C 1]: https://github.com/alibaba/p3c/wiki/IDEA%E6%8F%92%E4%BB%B6%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3
[50]: https://yq.aliyun.com/articles/739987
[Doraengineer_s blog]: https://blog.csdn.net/weixin_42641395/article/details/82558190