跳到主要内容
版本:v1.6.x

代码风格和质量指南

1 拉取请求与变更规则

  1. ISSUE/PR(拉取请求) 的引导和命名

    • 新建 PR 后需要在 PR 页面的 Github Development 按钮处关联已存在的对应 ISSUE(若无建议新建对应ISSUE)

    • 标题命名格式(英文,小写)
      [feature/bugfix/doc/improve/refactor/bug/cleanup] title

  2. 添加描述信息

    • 新建 PR 时请仔细描述此贡献,描述文档和代码同样重要。审阅者可以从描述中,而不仅仅是从代码中,了解问题和解决方案。
    • 勾选是否完成了对应的 Checklist。
  3. 建议一次 PR 只包含一个功能/一种修复/一类改进/一种重构/一次清理/一类文档等

  4. 提交消息(英文,小写,无特殊字符)
    消息的提交应遵循与 PR 类似的模式:[feature/bugfix/doc/improve/refactor/bug/cleanup] title

2 代码检查样式

2.1 配置 Checkstyle

  1. 安装 Checkstyle-IDEA 插件.
  2. 打开 Checkstyle 设置. 点击 SettingsToolsCheckstyle
  3. 设置 Checkstyle version 的版本为: 10.14.2
  4. 设置 Scan scopeOnly Java sources (including tests)
  5. 点击 + 按钮在 Configuration 部分打开一个对话框选择 checkstyle 配置文件。
    1. 输入描述名称,比如:hertzbeat。
    2. 选择 Use a local checkstyle file
    3. 设置 File 路径为: script/checkstyle/checkstyle.xml
    4. 选择 Store relative to project location
    5. 点击 NextNextFinish
  6. 激活刚才的 Checkstyle 配置。
  7. 点击 OK
  • 后端代码规范 Maven 插件:checkstyle 后端运行 mvn checkstyle:checkstyle

  • 前端代码格式化插件 eslint 前端运行 npm run lint:fix

3 编程规范

3.1 命名风格

  1. 优先为变量命名选择名词,这样更容易区分变量方法

      Cache<String> publicKeyCache;
  2. 变量的拼音缩写是禁止的(排除地名等名词),例如chengdu。

  3. 推荐的变量名以 类型 结尾。 对于 Collection/List 类型的变量,取 xxxx (复数表示多个元素)或以 xxxList (特定类型)结束。 对于 map 类型的变量,清晰地描述 keyvalue

      Map<Long, User> idUserMap;
    Map<Long, String> userIdNameMap;
  4. 通过其名称直观地知道变量的类型和含义。 方法名称应首先以动词开始,如下所示:

      void computeVcores(Object parameter1);

    注意:在 Builder 工具类中不必严格遵循这项规则。

3.2 常量变量定义

  1. 多余的字符串应提取为常量

    如果一个常量被硬编码两次或多次,请直接提取它为常量并更改相应的引用。 通常,log 中的常量可以忽略提取。

    • 负面示例:

      public static RestResponse success(Object data) {
      RestResponse resp = new RestResponse();
      resp.put("status", "success");
      resp.put("code", ResponseCode.CODE_SUCCESS);
      resp.put("data", data);
      return resp;
      }

      public static RestResponse error() {
      RestResponse resp = new RestResponse();
      resp.put("status", "error");
      resp.put("code", ResponseCode.CODE_FAIL);
      resp.put("data", null);
      return resp;
      }
    • 正面示例:

      字符串提取为常量引用。

        public static final String STATUS = "status";
      public static final String CODE = "code";
      public static final String DATA = "data";

      public static RestResponse success(Object data) {
      RestResponse resp = new RestResponse();
      resp.put(STATUS, "success");
      resp.put(CODE, ResponseCode.CODE_SUCCESS);
      resp.put(DATA, data);
      return resp;
      }

      public static RestResponse error() {
      RestResponse resp = new RestResponse();
      resp.put(STATUS, "error");
      resp.put(CODE, ResponseCode.CODE_FAIL);
      resp.put(DATA, null);
      return resp;
      }
  2. 确保代码的可读性和直观性

  • annotation 符号中的字符串不需要提取为常量。

  • 被引用的 packageresource 名称不需要提取为常量。

  1. 未被重新分配的变量也必须声明为 final 类型。

  2. 关于 constant/variable 行的排序顺序

    按以下顺序对类中的变量行进行排序:

    1. public static final V, static final V,protected static final V, private static final V
    2. public static v, static v,protected static v, private static v
    3. public v, v, protected v, private v

3.3 方法规则

  1. 按照 publicprotectedprivate 的顺序对类中的方法进行排序。

    类的静态方法可以放在非静态方法之后,并根据一致的方法可见性进行排序。

  2. 当方法有限制时,方法的参数和返回值需要用 @Nonnull@Nullable 注释和约束进行注释。

    例如,如果参数不能为 null,最好添加一个 @Nonnull 注释。如果返回值可以为 null,则应首先添加 @Nullable 注释。

    注意:包名为 javax.validation.requirements
  3. 如果方法中的代码行数太多,请尝试在适当的点上使用多个子方法来分段方法体。

    一般来说,需要坚持以下原则:

    • 便于测试
    • 有好的语义
    • 易于阅读

    此外,还需要考虑在组件、逻辑、抽象和场景等方面的切割是否合理。

    然而,目前还没有明确的演示定义。在演变过程中,我们将为开发者提供更多的示例,以便他们有更清晰的参考和理解。

3.4 集合规则

  1. 对于返回的 collection 值,除非有特殊的 concurrent (如线程安全),总是返回 interface,例如:

    • 如果使用 ArrayList,则返回 List
    • 如果使用 HashMap,则返回 Map
    • 如果使用 HashSet,则返回 Set
  2. 如果存在多线程,可以使用以下声明或返回类型:

      private CurrentHashMap map;
    public CurrentHashMap funName();
  3. 使用 isEmpty() 而不是 length() == 0 或者 size() == 0

    • 负面示例:

      if (pathPart.length() == 0) {
      return;
      }
    • 正面示例:

      if (pathPart.isEmpty()) {
      return;
      }

3.5 并发处理

  1. 需要管理 线程池,使用统一的入口点获取 线程池

    注意:在演变过程中,我们将为开发者提供更多的示例,以便他们有更清晰的参考和理解。
  2. 线程池 需要进行资源约束,以防止因处理不当导致的资源泄露。

3.6 控制/条件语句

  1. 避免因不合理的 条件/控制 分支顺序导致:

    • 多个代码行的 深度n+1
    • 多余的行

一般来说,如果一个方法的代码行深度由于连续嵌套的 if... else.. 超过了 2+ Tabs,那么应该考虑试图

  • 合并分支
  • 反转分支条件
  • 提取私有方法

以减少代码行深度并提高可读性,例如:

  • 联合或将逻辑合并到下一级调用中

    • 负面示例:
        if (isInsert) {
      save(platform);
      } else {
      updateById(platform);
      }
    • 正面示例:
        saveOrUpdate(platform);
  • 合并条件

    • 负面示例:
        if (expression1) {
      if(expression2) {
      ......
      }
      }
    • 正面示例:
       if (expression1 && expression2) {
      ......
      }
  • 反转条件

    • 负面示例:

        public void doSomething() {
      // 忽略更深的代码块行
      // .....
      if (condition1) {
      ...
      } else {
      ...
      }
      }
    • 正面示例:

        public void doSomething() {
      // 忽略更深的代码块行
      // .....
      if (!condition1) {
      ...
      return;
      }
      // ...
      }
  • 使用单一变量或方法减少复杂的条件表达式

    • 负面示例:

        if (dbType.indexOf("sqlserver") >= 0 || dbType.indexOf("sql server") >= 0) {
      ...
      }
    • 正面示例:

        if (containsSqlServer(dbType)) {
      ....
      }
      //.....
      // containsSqlServer的定义

在未来,使用 sonarlintbetter highlights 检查代码深度看起来是个不错的选择。

3.7 代码注释规则

  1. 方法缺少注释:

    • When:该方法何时可以被调用
    • How:如何使用此方法以及如何传递参数等
    • What:此方法实现了哪些功能
    • Note:在调用此方法时开发人员应注意什么
  2. 缺少必要的类头部描述注释。

    添加 WhatNote 等,如上述 1 中提到的。

  3. 在接口中的方法声明必须被注释。

    • 如果实现的语义和接口声明的注释内容不一致,则具体的实现方法也需要用注释重写。

    • 如果方法实现的语义与接口声明的注释内容一致,则建议不写注释以避免重复的注释。

  4. 在注释行中的第一个词需要大写,如 param 行,return 行。 如果特殊引用作为主题不需要大写,需要注意特殊符号,例如引号。

3.8 Java Lambda 表达式

  1. 更倾向于使用 non-capturing lambda(不包含对外部范围的引用的lambda)。 Capturing lambda 在每次调用时都需要创建一个新的对象实例。Non-capturing lambda 可以为每次调用使用相同的实例。

    • 负面示例:

        map.computeIfAbsent(key, x -> key.toLowerCase())
    • 正面示例:

       map.computeIfAbsent(key, k -> k.toLowerCase());
  2. 考虑使用方法引用而不是内联lambda

    • 负面示例:

        map.computeIfAbsent(key, k-> Loader.load(k));
    • 正面示例:

        map.computeIfAbsent(key, Loader::load);

3.9 Java Streams

  • 在任何对性能敏感的代码中避免使用 Java Streams。

  • 使用 Java Streams 的主要动机是为了提高代码的可读性。因此,它们可以在代码的某些部分中很好地匹配,这些部分不是数据密集型的,而是处理协调。

  • 即使在后一种情况下,也试图限制范围到一个方法,或者一个内部类中的几个私有方法。

3.10 前置条件检查

  1. 使用统一的 Utils.requireXXX 来完成前提的验证,如果可能的话,用新的前置条件检查替换 AlertXXException.throwIfXXX

3.11 StringUtils

  1. 使用 StringUtils.isBlank 而不是 StringUtils.isEmpty

    • 负面示例:

      if (StringUtils.isEmpty(name)) {
      return;
      }
    • 正面示例:

      if (StringUtils.isBlank(name)) {
      return;
      }
  2. 使用 StringUtils.isNotBlank 而不是 StringUtils.isNotEmpty

    • 负面示例:

      if (StringUtils.isNotEmpty(name)) {
      return;
      }
    • 正面示例:

      if (StringUtils.isNotBlank(name)) {
      return;
      }
  3. 使用 StringUtils.isAllBlank 而不是 StringUtils.isAllEmpty

    • 负面示例:

      if (StringUtils.isAllEmpty(name, age)) {
      return;
      }
    • 正面示例:

      if (StringUtils.isAllBlank(name, age)) {
      return;
      }

3.12 Enum

  1. 枚举值比较

    • 负面示例:

      if (status.equals(JobStatus.RUNNING)) {
      return;
      }
    • 正面示例:

      if (status == JobStatus.RUNNING) {
      return;
      }
  2. 枚举类不需要实现 Serializable

    • 负面示例:

      public enum JobStatus implements Serializable {
      ...
      }
    • 正面示例:

      public enum JobStatus {
      ...
      }
  3. 使用 Enum.name() 而不是 Enum.toString()

    • 负面示例:

      System.out.println(JobStatus.RUNNING.toString());
    • 正面示例:

      System.out.println(JobStatus.RUNNING.name());
  4. 枚举类名称统一使用 Enum 后缀

    • 负面示例:

      public enum JobStatus {
      ...
      }
    • 正面示例:

      public enum JobStatusEnum {
      ...
      }

3.13 Deprecated 注解

  • 负面示例:

    @deprecated
    public void process(String input) {
    ...
    }
  • 正面示例:

    @Deprecated
    public void process(String input) {
    ...
    }

4 日志

  1. 使用 占位符 进行日志输出:

    • 负面示例
        log.info("Deploy cluster request " + deployRequest);
    • 正面示例
        log.info("load plugin:{} to {}", file.getName(), appPlugins);
  2. 打印日志时,注意选择 日志级别

    当打印日志内容时,如果传递了日志占位符的实际参数,必须避免过早评估,以避免由日志级别导致的不必要评估。

    • 负面示例:

      假设当前日志级别为 INFO

       // 忽略声明行。
      List<User> userList = getUsersByBatch(1000);
      LOG.debug("All users: {}", getAllUserIds(userList));
    • 正面示例:

      在这种情况下,我们应该在进行实际的日志调用之前提前确定日志级别,如下所示:

       // 忽略声明行。
      List<User> userList = getUsersByBatch(1000);
      if (LOG.isDebugEnabled()) {
      LOG.debug("All ids of users: {}", getAllIDsOfUsers(userList));
      }

5 测试

  1. 建议使用 JUnit5 进行测试用例的准备。

  2. 实现的接口需在e2e模块下编写e2e测试用例脚本。

参考资料