新建规约扫描配置文件_云原生应用组装平台 BizWorks-阿里云帮助中心

BizWorks Toolkit支持通过配置化的方式，在项目中动态维护自定义的研发规约，这份配置文件即为规约扫描配置，文件所在路径为.bizworks/inspections.yaml。

前提条件

BizWorks Toolkit版本大于等于2.2.0。

步骤一：新建规约扫描配置文件

如果您还没有配置规约扫描配置文件，可以在项目根目录或.bizworks目录，通过单击New > BizWorks 配置文件 > 规约扫描配置新建文件，具体路径如下图所示。新建后的配置文件会自动打开，且配置文件会自动创建在 .bizworks/inspections.yaml目录。

如果规约扫描配置文件已经存在，在项目根目录或.bizworks目录，单击New > BizWorks配置文件 > 规约扫描配置后，会直接打开该文件。

上图配置文件中，默认生成的配置项对应的校验规则如下表所示（部分配置项通过enabled: false关闭了校验功能）：

规则类型	默认提示信息	规则说明
指定包路径下存放DTO的Converter类， Converter类名按指定的后缀命名。	DTO的Converter类名不满足命名规范，应该以“`DtoConverter`”为后缀。	指定包路径为可配置项；后缀“`DtoConverter`”为可配置项。
DTO的Converter类中需要包含指定的方法名。	DTO的Converter类中需要包含指定的方法名：toDto()、toEntity()命名。	指定方法名toDto()、toEntity()为可配置项。
指定包路径下存放DO的Converter类， Converter类名按指定的后缀命名。	DO的Converter类名不满足命名规范，应该以“`DoConverter`”为后缀。	指定包路径为可配置项；后缀“`DoConverter`”为可配置项。
DO的Converter类中需要包含指定的方法名。	DO的Converter类中需要包含指定的方法名：toDo()、toEntity()命名。	方法名toDo()、toEntity()为可配置项。
指定包路径下存放聚合根、实体对象、值对象。	聚合根、实体对象、值对象未放在指定包路径下。	指定包路径为可配置项；对象类型（聚合根、实体对象、值对象）为可配置项。
聚合根类名按指定后缀命名。	聚合根类名不满足命名规范，应该以“`Agg`”为后缀。	后缀“`Agg`”为可配置项。
实体对象类名按指定后缀命名。	实体对象类名不满足命名规范，应该以“`Entity`”为后缀。	后缀“`Entity`”为可配置项。
值对象类名按指定后缀命名。	值对象类名不满足命名规范，应该以“`VO`”为后缀。	后缀“`VO`”为可配置项。
指定的包路径下，枚举类名按指定后缀命名。	枚举类名不满足命名规范，应该以“`Enum`”为后缀。	指定包路径为可配置项；后缀“`Enum`”为可配置项。
指定包路径下存放Repository类， Repository类名按指定的后缀命名。	Repository类名不满足命名规范，应该以“`Repository`”为后缀。	指定包路径为可配置项；后缀“`Repository`”为可配置项。
domain层指定包路径下存放的Repository需要是接口。	domain层指定包路径下存放的Repository需要是接口。	指定包路径为可配置项。
自定义包路径下类名的按指定后缀命名。	“`xxx.xxx`”路径下存在类名不满足命名规范，应该以“`xxx`”为后缀。	自定义包路径“`xxx.xxx`”为可配置项；后缀“`xxx`”为可配置项。
自定义包路径下类是实现类。	“`xxx.xxx`”路径下存在类不是实现类，需要调整。	自定义包路径“`xxx.xxx`”为可配置项；接口、抽象类、实现类等定义为可配置项。
自定义包路径下类是接口或抽象类。	“`xxx.xxx`”路径下存在类不是接口或抽象类，需要调整。	自定义包路径“`xxx.xxx`”为可配置项；接口、抽象类、实现类等定义为可配置项。
指定包路径下存放Mapper。	Mapper未构建在指定目录下。	涉及多种配置方式，仅支持检测MyBatis注解；指定包路径为可配置项。
指定包路径下存放Mapper，Mapper类名按指定的后缀命名。	Mapper类名不满足命名规范，应该以“`Mapper`”为后缀。	指定包路径为可配置项；后缀“`Mapper`”为可配置项。
指定包路径下存放数据对象，数据对象类名按指定的后缀命名。	数据对象类名不满足命名规范，应该以“`DO`”为后缀。	指定包路径为可配置项；后缀“`DO`”为可配置项。
指定包路径下存放Repository实现类， Repository实现类名按指定的后缀命名。	Repository实现类名不满足命名规范，应该以“`RepositoryImpl`”为后缀。	指定包路径为可配置项；后缀“`RepositoryImpl`”为可配置项。
指定包路径下存放的Repository需要是实现类。	指定包路径下存放的Repository需要是实现类，不应该是接口。	指定包路径为可配置项。
指定包路径下存放DTO类， DTO类名按指定的后缀命名。	DTO类名不满足命名规范，应该以“`DTO`”为后缀。	指定包路径为可配置项；后缀“`DTO`”为可配置项。

步骤二：修改默认配置

通过上述步骤一：新建规约扫描配置文件操作创建的规约扫描配置文件，其内容来源于默认模板，包含一些默认开启或关闭的示例。其中package的com.alibaba.bizworks.demo 需要替换为项目的真实package配置文件才会生效。

说明

您可以通过快捷键触发替换操作：

如果您使用的是Mac系统：command+R
如果您使用的是Windows系统：Ctrl+R

步骤三：执行规约扫描验证

在全局或目录执行规约扫描验证

打开IDEA，在项目左侧导航栏的目录上，单击右键后，选择BizWorks > BizWorks规约扫描（按目录触发执行验证），您也可以在根目录触发（全项目级别的执行验证）。

下图为执行规约扫描验证的截图示例：

在Editor中即时校验

在Editor编辑过程中，界面会显示即时校验反馈。

配置管理

在项目下方的配置管理页签，列出了项目中的规约扫描配置信息，同时也支持通过双击或右击菜单跳转。

在规约扫描配置有变动时，您可以单击重新加载规约扫描配置重新扫描发现项目中的配置。

规约扫描配置生效

规约扫描配置生效的时间点或方式如下：

项目启动自动加载。
修改规约扫描配置文件后自动重新加载。
通过菜单手动加载：BizWorks > 重新加载规约扫描配置。
说明
当规约扫描配置文件并非由IDEA可感知的变动引起时（例如：命令行git同步其他协作者的改动，外部其他Editor修改等），您如果发现当前校验规则与预期不符，可以尝试手动重新加载。

规约扫描配置内容说明

`BwBasicClassRule`（基础的类校验规则）

完整的规约扫描配置规则示例如下（在默认的模板中也包含如下示例规则）：

      # 下面这个是关闭的完整字段配置示例
      # name 必填
      - name: "完整 BwBasicClassRule Inspection示例"
        # 非必填；项目内Inspection编码, 不可重复，用于区分规则，如果不填则会根据内部规则生成
        code: "demoCustomRule"
        # 非必填；规则描述
        description: "Simple Inspection"
        # 非必填；提示信息, 内置变量
        tip: "类不符合要求，后缀应为"
        # 非必填；类型，内置类型直接使用类型名。默认为 BwBasicClassRule
        type: "BwBasicClassRule"
        # 非必填；是否启用, 默认启用；当前为示例规则，仅容配置参考，故设置为 false
        enabled: false
        # 非必填；参照 IntelliJ 级别配置。严重程度，默认 使用 defaultSeverity 配置 , 可选值为 error,warning,weak (weak warning含义)
        severity: error
        # 必填；约束的作用域
        scopes:
          # type 默认是 include，可选 exclude
          - type: include
            package: "com.alibaba.bizworks.client.dto"
            # 类型,任意匹配即可
            defTypes:
              - "class"
              - "abstract"
              - "interface"
              - "enum"
            # 后缀
            suffixes:
              - "DTO"
              - "Repository"
              - "Enum"
            annotations:
              # 多条 annotation 之间是或的关系
              - qualifiedName: "com.alibaba.bizworks.core.specification.ddd.ValueObject"
                attributes:
                  - name: "isValueObject"
                    value: "true"
          # 多条 scope 之间是 and 的关系，在上一条的基础上进一步缩小范围。同时，是否冲突由用户自己控制
          - type: exclude
            defTypes:
              - "interface"
        # 必填；检查约束不支持多条，但单条上面每个配置可以支持按需配置
        constraint:
          package: "com.alibaba.bizworks.client.dto"
          # 约束下复数形式同样支持配置多项，规则仍是任意一个匹配
          suffixes:
            - "DTO"
            - "Repository"
            - "Enum"
          annotations:
            - qualifiedName: "com.alibaba.bizworks.core.specification.ddd.ValueObject"
              attributes:
                - name: "isValueObject"
                  value: "true"
          defTypes:
            - "class"
            - "abstract"
            - "interface"
            - "enum"
          # 约束项指明要求所有都满足的，则会匹配所有
          containAllMethods:
            - "toDto"
            - "toEntity"

通过阅读注释中说明信息，您会发现其中有很多内容都是有默认值可以不配置的，所以默认模板中大量的规则实际都是简化后的简单规则，具体如下所示：

      - name: "指定包路径下存放DTO的Converter类，Converter类名按指定的后缀命名"
        scopes:
          - package: "com.alibaba.bizworks.demo.*.app.converter"
        constraint:
          suffixes:
            - "Converter"

常见问题

当界面出现“规约扫描配置加载过程中存在错误”提示时应如何处理？

在规约扫描配置加载过程中，如果配置文件缺失，或配置文件内容有误，IDEA右下角会有错误提示，请参照提示信息确认配置文件内容正确。

提示一：配置文件不存在！规约扫描配置加载失败，保留现状。
提示二：配置解析出错，请检查配置。
提示三：错误规则。具体请参见下图。

说明

如果是配置文件缺失或配置文件格式等原因导致配置整体解析错误，则IDEA会保留在重新加载前生效的规则。
如果配置文件解析正常，但部分规则内容不符合配置约定，是无效规则（比如缺少必要的name等），则会忽略不符合配置要求的规则，加载生效其余有效的规则。