【Java学习】定制阿里巴巴Java开发规约插件（完整教程）

左手的ㄟ右手 2023-02-20 15:57 12阅读 0赞

### 文章目录 ###

*  一、使用文档
 *  二、问题概述
 *   *   *  1、准备工作
         *  2、p3c-pmd自定规则
         *  3、p3c-pmd配置规则
         *  4、p3c-pmd编写提示
         *  5、p3c-pmd单元测试
         *  6、p3c-pmd插件打包
         *  7、idea-plugin插件打包
         *  8、安装插件
 *  三、常见问题
 *   *   *  1、ideaIC下载超时
         *  2、打包未使用jar

# 一、使用文档 #

[IDEA插件官方使用文档][IDEA]

插件涵盖了插件安装、插件规范、代码扫描、插件配置、配置规则、提交检测等

阿里巴巴代码规范扫描插件，以下简称规约插件。通常情况下，很多公司都会使用代码检测插件来检测公司项目的开发人员是否是规范开发，并且是否存在漏洞、书写规范等问题，目前来说，最好的检测手段就是阿里巴巴推出的代码检测插件 [Alibaba Java Coding Guidelines][]，同时配合《阿里巴巴Java开发手册》来进行约束。

# 二、问题概述 #

假设我们使用插件的时候，发现一些不符合公司常规的开发方式，比如说，代码规约插件中，对未定义就使用的变量，也会提出警告，该变量为魔法值，需要先定义，这种类似的问题，实际上对于不是很细节的公司来说，是不需要的，所以我们就需要定制开发规范，比如说把这个魔法值去掉，不让它检测到，官方也提供了相应的插件配置方法， [idea-plugin 插件使用方法][idea-plugin]，但我需要增加方法呢，通过配置的手段就实现不了，所以这里我们定制代码规约插件，最终来基于阿里规约实现自己的自定义规范。

下面以增加一个扫描规范为案例，举例说明如何定制代码规约插件。案例内容为：增加一个扫描方法，当参数个数超过10个的时候，则将该方法记录到扫描规范中，并提示方法参数个数不能大于10个。

### 1、准备工作 ###

官方准备的版本为

1.  Project JDK: 1.7+
2.  Gradle: 3.0+（Require JDK1.8+ for gradle）

我个人本次教程使用的是

1.  JDK 1.8
2.  Maven 3.6.0
3.  Gradle: 5.1.1

配置idea的maven仓库地址和gradle的仓库地址，我这里是使用同一个目录。

将阿里p3c项目源码拉取到本地 [p3c][Alibaba Java Coding Guidelines]，不直接导入项目，因为项目中maven和gradle都有，所以我们使用open打开文件目录，然后把 p3c-pmd 构建成 maven 项目。

> 我使用的IDEA版本为 IntelliJ IDEA 2019.1 x64，这个只是提一下，并不影响

### 2、p3c-pmd自定规则 ###

打开阿里p3c-pmd工程，开始编写我们的自定义规则。

阿里已经写了很多规则，我们现在要编写的规则属于面向对象范畴，可以把规则写到 `com.alibaba.p3c.pmd.lang.java.rule.oop` 包下，新建一个规则类`MethodParameterCountRule`，继承自AbstractAliRule，重写 visit方法

package com.alibaba.p3c.pmd.lang.java.rule.oop;
    
    import com.alibaba.p3c.pmd.lang.java.rule.AbstractAliRule;
    import net.sourceforge.pmd.lang.ast.Node;
    import net.sourceforge.pmd.lang.java.ast.ASTCompilationUnit;
    import net.sourceforge.pmd.lang.java.ast.ASTFormalParameters;
    
    import java.util.List;
    
    /** * 方法参数列表个数不宜过长（最多为10个） * * @author Tellsea * @date 2020-7-8 */
    public class MethodParameterCountRule extends AbstractAliRule { 
    
    
        private static final String METHOD_XPATH = "//MethodDeclarator";
    
        private static final Integer PARAMETER_COUNT_LIMIT = 10;
    
    
        @Override
        public Object visit(ASTCompilationUnit node, Object data) { 
            try { 
                // 找到所方法节点
                List<Node> methodNodes = node.findChildNodesWithXPath(METHOD_XPATH);
                if (methodNodes != null && methodNodes.size() > 0) { 
                    for (Node methodNode : methodNodes) { 
                        // 找到每个方法的参数列表声明
                        List<ASTFormalParameters> formalParameters = methodNode.findChildrenOfType(ASTFormalParameters.class);
                        if (formalParameters.get(0).getParameterCount() >= PARAMETER_COUNT_LIMIT) { 
                            // 违反规则提示信息，第二个参数是提示信息位置，第三个参数是提示信息key，第四个参数用来替换提示信息
                            // 中的占位符，这里获取的节点image属性就是方法名称
                            addViolationWithMessage(data, methodNode,
                                    "java.oop.MethodParameterCountRule.violation.msg",
                                    new Object[]{ methodNode.getImage()});
                        }
                    }
                }
            } catch (Exception e) { 
                e.printStackTrace();
            }
            return super.visit(node, data);
        }
    }

### 3、p3c-pmd配置规则 ###

将编写好规则配置到 `resources/rulesets/java/ali-oop.xml` 文件中

### 4、p3c-pmd编写提示 ###

messages.xml 中文

messages\_en.xml 英文

### 5、p3c-pmd单元测试 ###

编写测试样例，将要测试的源代码写到test目录对应的xml文件中  
`test/resources/com/alibaba/p3c/pmd/lang/java/rule/oop/xml` 下创建 `MethodParameterCountRule.xml` 配置文件

<?xml version="1.0" encoding="UTF-8"?>
    <test-data xmlns="http://pmd.sourceforge.net/rule-tests" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pmd.sourceforge.net/rule-tests https://pmd.sourceforge.io/rule-tests_1_0_0.xsd">
    
        <code-fragment id="测试样例">
            <![CDATA[ package org.p3c.demo; public class Demo { public void methodA(int a) { } public void methodB(int a, int b, int c, int d, int e, int f, int g, int h, int i, int j) { } } ]]>
        </code-fragment>
        <test-code>
            
            <description>预期问题个数0</description>
            <expected-problems>0</expected-problems>
            <code-ref id="测试样例" />
        </test-code>
    </test-data>

编写单元测试，修改`com.alibaba.p3c.pmd.lang.java.rule.oop.OopRuleTest`文件，增加为如下

public class OopRuleTest extends SimpleAggregatorTst { 
    
        // 加载CLASSPATH下的rulesets/java/ali-oop.xml
        private static final String RULESET = "java-ali-oop";
    
        @Override
        public void setUp() { 
            addRule(RULESET, "EqualsAvoidNullRule");
            addRule(RULESET, "WrapperTypeEqualityRule");
            addRule(RULESET, "PojoNoDefaultValueRule");
            addRule(RULESET, "PojoMustUsePrimitiveFieldRule");
            addRule(RULESET, "PojoMustOverrideToStringRule");
            addRule(RULESET, "StringConcatRule");
            addRule(RULESET, "BigDecimalAvoidDoubleConstructorRule");
            // 新增自定义规则
            addRule(RULESET, "MethodParameterCountRule");
        }
    
        @Test
        public void methodParameterCountRuleTest() { 
            Rule rule = this.findRule(RULESET, "MethodParameterCountRule");
            runTests(rule, "MethodParameterCountRule");
        }
    }

运行单元测试，因为样例代码中methodB不符合规范，但是我们预期问题个数写的是0，所以单元测试不会通过  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NzYyMjM3_size_16_color_FFFFFF_t_70]

### 6、p3c-pmd插件打包 ###

p3c-pmd 目录下运行命令

mvn -DskipTests=true clean install

打包完成后，可以在你的 maven 仓库中找到打包的jar文件，例如：  
`D:\App\apache-maven-3.6.0\maven-repository\com\alibaba\p3c\p3c-pmd\2.0.1\p3c-pmd-2.0.1.jar`  
到此，规则我们就制定好了，只需要打包插件安装包即可。

### 7、idea-plugin插件打包 ###

先找到项目目录下的 idea-plugin 下的 `gradlew.bat` 文件，直接在Windows下双击运行。  
然后在 idea-plugin 目录执行打包命令

gradle clean buildDependents build

打包完成后会生成`idea-plugin/p3c-idea/build/distributions/p3c-idea-2.0.2.zip` 插件安装包，然后使用idea本地安装插件的方式，安装我们自定义打包的插件即可正常使用。

### 8、安装插件 ###

如果本身的idea插件已经安装了 `Alibaba Java Coding Guidelines` 则卸载插件，重启之后通过 `Install plugin from disk` 本地安装，选择之前打包的插件 `p3c-idea-2.0.2.zip` 即可。

# 三、常见问题 #

### 1、ideaIC下载超时 ###

执行打包命令时，需要下载国外资源，可能导致多次请求超时

FAILURE: Build failed with an exception.
    
    * What went wrong:
    A problem occurred configuring project ':p3c-common'.
    > Could not resolve all files for configuration ':p3c-common:detachedConfiguration3'.
       > Could not download ideaIC-145.258.11.zip (com.jetbrains.intellij.idea:ideaIC:145.258.11)
          > Could not get resource 'https://cache-redirector.jetbrains.com/www.jetbrains.com/intellij-repository/releases/com/jetbrains/intellij/idea/ideaIC/145.258.11
    /ideaIC-145.258.11.zip'.
             > Connection reset
    
    * Try:
    Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.
    
    * Get more help at https://help.gradle.org
    
    Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
    Use '--warning-mode all' to show the individual deprecation warnings.
    See https://docs.gradle.org/6.5/userguide/command_line_interface.html#sec:command_line_warnings

这里我们直接通过报错的地址，使用迅雷之类的下载软件，下载文件内容，`https://cache-redirector.jetbrains.com/www.jetbrains.com/intellij-repository/releases/com/jetbrains/intellij/idea/ideaIC/145.258.11 /ideaIC-145.258.11.zip`， 然后根据目录，粘贴到 maven 中，粘贴以后，如果还有类似问题，多打几次包即可（我是这样解决的）。

### 2、打包未使用jar ###

[IDEA]: 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
[Alibaba Java Coding Guidelines]: https://github.com/alibaba/p3c
[idea-plugin]: https://github.com/alibaba/p3c/blob/master/idea-plugin/README_cn.md
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NzYyMjM3_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200708133510304.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NzYyMjM3,size_16,color_FFFFFF,t_70