插件不好写？！

插件确实不好写，因为插件是插入庞大的系统当中工作的，那也就意味着写插件需要具备一定的领域知识，包括系统架构、扩展点、业务共性及差异、API及其业务模型对应、安装和测试。而对于开发者而言，学习这些知识的代价绝对是昂贵的。
在《函数式编程思想》一书中，作者Neal Ford提到开发过程当中的两种抽象方式——composable and contextual abstract. 谈及contextual抽象的时候，他把插件系统列为这一抽象中最经典的例子。

Plugin-based architectures are excellent examples of the contextual abstraction. The plug-in API provides a plethora of data structures and other useful context that developers inherit from or summon via already existing methods. But to use the API, a developer must understand what that context provides, and that understanding is sometimes expensive.

大意是开发者能够借助已存在的方法来使用Plugin API中提供的大量数据结构和有用的上下文信息。但是，理解起这些上下文信息有时是很昂贵的。

基于一个共识：开发者的时间都是宝贵的。知道插件难写之后，我的这篇文章才有价值。

理解领域模型

一说写插件，估计大家都会上官网寻找开发指南或者google大量博客来快速完成开发任务。这里不是说这种方式不好，其实一开始我也是这么做的，但是着手开发以后，很快就遭遇处处掣肘。比如：开发sonar plugin，会用到Profile、Rule、Language和Repository等概念。单从代码层面上看，我们很难理清这些概念所代表的模型和它们之间的关系。所以需要从用户的视角来感受这些领域知识。

而用户视角大部分情况下就是UI界面。

规则（Rules）

我们先看看Rules导航栏，左边的单选框是这些规则的过滤条件。
说明规则包含或者被包含这些属性之下：

Rules

• Language：规则对应的某种编程语言。
• Type：规则的类型，比如：缺陷（Bug）、代码坏味道（Code Smell）、易受攻击（Vulnerability）。
• Tag：规则设置的标签，易于检索。
• Repository：承载特定语言下各种规则的容器；通过它可以通过规则的键值（ruleKey）检索。
• Default Severity：触犯规则的严重程度。
  • Blocker：最高等级，阻碍的
  • Critical：高等级，极为严重的
  • Major：较高等级，主要的；默认级别。
  • Minor：较低等级
  • Info：低等级
• Status：规则现在的状态，可用、废弃还是实验版（Beta）。
• Avaiable Since：什么时候开始可用。
• Template：规则模板：比如某些参数可以运行时传入。
• Quality Profile：挑选特定语言下各种规则组成的配置；其中可以启用或禁用一部分规则。

质量Profile（Quality Profile）

再看看Quality Profiles导航栏，左侧栏显示的是某种语言包含的所有Profiles.

Profiles

从关系型数据库的角度，Language和Profile是1对多（one-to-many）关系，但是从领域建模的角度，Profile其实和Language是1对1的关系。所以可以是Profile包含Language属性。利用领域建模的思考方式，可以联想到Repository和Rules是1对多的关系，所以Repository包含一个Rules的集合。Repository和Language是1对1的关系，Repository包含Language属性。那么Rules和Profiles的对应关系呢？多对多。但是我们更关心Profile到Rules这一层的关系，所以选择Profile包含一个Rules的集合。

我整理出这样一份对应关系图：

profile
    - language
    - [rules]
respository
    - lanuage
    - [rules]

现在，缺少Profile和Repository的关系。不过既然有了Rule这一层联系，那么就可以这样考虑，Rule和Repository是1对1的关系（为什么呢？因为每个Rule显然只能存在于一个特定的Repository当中）。所以原图可以修改为：

profile
    - language
    - [rules]
      - rule
        - respository
respository
    - language
    - [rules]

好了。梳理完这些领域知识，我们可以开始依照官方的教程Developing a Plugin.

扫描特定领域语言（DSL）的SonarQube插件

SonarQube 5.6现在只支持Java 8、Maven 3.1以上。当然也支持Gradle。

第一步 创建一个Maven工程

这里有两种方式。第一种方式就是从头开始写起，包括创建工程；另一种就是拷贝官方的样例程序。我自然是推荐第二种做法，不过这里我从零开始开发。

$ mvn archetype:create -DgroupId=com.lambeta -DartifactId=sonar-lambeta -DarchetypeArtifactId=maven-archetype-quickstart

依照官方文档将pom.xml修改如下：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.lambeta</groupId>
    <artifactId>sonar-custom</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>sonar-plugin</packaging>

    <name>sonar-custom</name>
    <url>https://www.lambeta.com</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.sonarsource.sonarqube</groupId>
            <artifactId>sonar-plugin-api</artifactId>
            <!-- minimal version of SonarQube to support. Note that the groupId was "org.codehaus.sonar" before version 5.2 -->
            <version>5.6</version>
            <!-- mandatory scope -->
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>net.sourceforge.pmd</groupId>
            <artifactId>pmd-xml</artifactId>
            <version>5.4.2</version>
        </dependency>
        <dependency>
            <groupId>dom4j</groupId>
            <artifactId>dom4j</artifactId>
            <version>1.6.1</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.sonarsource.sonar-packaging-maven-plugin</groupId>
                <artifactId>sonar-packaging-maven-plugin</artifactId>
                <version>1.16</version>
                <extensions>true</extensions>
                <configuration>
                    <pluginClass>com.lambeta.CustomPlugin</pluginClass>
                    <pluginDescription>how to write sonar plugin</pluginDescription>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

注意： pmd-xml、dom4j会在后面的编程当中使用到。

依据标准的代码结构，新建CustomPlugin.java文件。

├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── lambeta
│   │   │           ├── CustomPlugin.java

第二步 识别扩展点

此时，该去查看API Basics了。不过在写代码之前，还得先了解所谓的扩展点（Extension Points）。

Scanner, which runs the source code analysis
Compute Engine, which consolidates the output of scanners, for example by
computing 2nd-level measures such as ratings
aggregating measures (for example number of lines of code of project = sum of lines of code of all files)
assigning new issues to developers
persisting everything in data stores
Web application

翻译如下

• 扫描器：分析源代码
• 计算引擎：聚合扫描器的输出。举例：计算第二轮measures，如打分；聚合measures（举例：工程中所有代码的行数 = 所有文件的代码行的综合）；给开发者安排新的问题；持久化。
• Web应用程序。
  翻译还不如不翻译！一言不合，去看例子程序...的注释

这三个扩展点，其实对应于API中的三个接口。

扫描器 -> Sensor
计算引擎 -> MeasureComputer
Web应用程序 -> Widget

第三步 定义Sensor（Scanner)

基于扫描DSL源码的需求，我们需要扩展Sensor这个接口。新建CustomSensor.java如下：

public class CustomSensor implements Sensor

    public void describe(SensorDescriptor descriptor) 
    ...
    public void execute(SensorContext context)
    ...

接下来，我们需要定义这门DSL语言的某些属性，以便于识别以及扫描时过滤相关的源文件（通过文件的后缀）。

第四步 定义语言（Language）

新建CustomLanguage如下：

package com.lambeta;
import org.sonar.api.resources.AbstractLanguage;

public class CustomLanguage extends AbstractLanguage {
    public static final String KEY = "custom-key";
    public static final String NAME = "custom-name";

    public CustomLanguage() {
        super(KEY, NAME);
    }

    public String[] getFileSuffixes() {
        return new String[] {"csm.xml"}; //custom这门基于xml的内部DSL的文件后缀
    }
}

我定义了一门基于xml语法的内部DSL，其文件的后缀是csm.xml。比如：right-syntax.csm.xml

Language定义出来了，我们还得定义rule、profile和repository. 回到上文提及的language、rule、profile以及repository的关系图：

profile
    - language
    - [rules]
      - rule
        - respository
respository
    - language
    - [rules]

第五步 定义规则（Rule）

respository
    - language
    - [rules]

我们需要实现接口RulesDefinition

package com.lambeta;
import org.apache.commons.io.Charsets;
import org.apache.commons.io.IOUtils;
import org.sonar.api.server.rule.RulesDefinition;
import org.sonar.api.server.rule.RulesDefinitionXmlLoader;

import java.io.InputStream;

public class CustomRulesDefinition implements RulesDefinition {

    public static final String REPOSITORY_KEY = "custom-repo";
    private final RulesDefinitionXmlLoader xmlLoader;

    public CustomRulesDefinition(RulesDefinitionXmlLoader xmlLoader) {
        this.xmlLoader = xmlLoader;
    }

    public void define(Context context) {

        final InputStream stream = getClass().getResourceAsStream("/rules.xml");
        final NewRepository repository = context.createRepository(REPOSITORY_KEY, CustomLanguage.KEY);

        try {
            if (stream != null) {
                xmlLoader.load(repository, stream, Charsets.UTF_8);
            }
            repository.done();
        } finally {
            IOUtils.closeQuietly(stream);
        }
    }
}

我们通过context新建出一个repository。respository需要一个唯一key作为其标识（可以通过setName方法设置名称）以及一个language key来关联（从UI上可以看出来）。然后，通过DI进来的RulesDefinitionXmlLoader将rules.xml中定义的rules加载进repository中。最后，调用reposiotory.done()宣告加载完成。

定义的rules.xml内容如下：

<?xml version="1.0" encoding="UTF-8" ?>
<rules>
    <rule>
        <key>ComponentsMustNotBeFollowedByComponentsRule</key>

        <name>Components标签后不能跟随Components标签规则</name>
        <description>
            <![CDATA[
                Components标签后不能跟随Components标签
            ]]>
        </description>
        <severity>MINOR</severity>
        <cardinality>SINGLE</cardinality>
        <status>READY</status>
        <tag>custom</tag>
        <example>
            <![CDATA[
                <components>
                <!-- Error, components must be here! -->
                    <components/>
                </components>
            ]]>
        </example>
    </rule>
</rules>

包含了rule的key和其他相关的属性。它们最终显示在UI上，会是这样：

Rule

第六步 定义Profile

profile
    - language
    - [rules]
      - rule
        - respository

我们需要实现接口ProfileDefinition.

package com.lambeta;
import org.apache.commons.io.IOUtils;
import org.sonar.api.profiles.ProfileDefinition;
import org.sonar.api.profiles.RulesProfile;
import org.sonar.api.profiles.XMLProfileParser;
import org.sonar.api.utils.ValidationMessages;

import java.io.InputStreamReader;

public class CustomProfileDefinition extends ProfileDefinition {
    private final XMLProfileParser xmlProfileParser;

    public CustomProfileDefinition(XMLProfileParser xmlProfileParser) {
        this.xmlProfileParser = xmlProfileParser;
    }

    @Override
    public RulesProfile createProfile(ValidationMessages validation) {
        final InputStreamReader reader = new InputStreamReader(getClass().getResourceAsStream("/profile.xml"));

        try {
            return xmlProfileParser.parse(reader, validation);
        } finally {
            IOUtils.closeQuietly(reader);
        }
    }
}

使用DI注入的XMLProfileParser解析profile.xml文件，并生成RulesProfile对象。我们来看看profile.xml的内容：

<?xml version="1.0" encoding="utf-8" ?>
<profile>
    <language>custom-key</language>
    <name>Custom Quality</name>
    <rules>
        <rule>
            <repositoryKey>custom-repo</repositoryKey>
            <key>ComponentsMustNotBeFollowedByComponentsRule</key>
            <priority>MAJOR</priority>
        </rule>
    </rules>
</profile>

这里定义一个名为Custom Quality的profile，它关联CustomLanguage的键值：custom-key. 同时包含了多条rules，每条rule拥有自己的标识key以及其所在的repository（事实上，profile会在repository中通过ruleKey来查找rule）。

写到这里，一个DSL的SonarQube Plugin已经几近完善。但是，我们还缺少至关重要的一环——规则的执行！

第七步 运行PMD扫描代码

PMD简介

我们需要一个静态扫描工具来扫描源代码，发现这些代码存在的缺陷和坏味道。PMD就是这么一款好用的工具。

PMD is a source code analyzer. It finds common programming flaws like unused variables, empty catch blocks, unnecessary object creation, and so forth. It supports Java, JavaScript, PLSQL, Apache Velocity, XML, XSL.

翻译：
PMD是一款源码分析工具。它会发现编程中的普遍缺陷，如未使用的变量、空的catch块、不必要的对象创建等等。它支持分析Java、Javascript、PLSQL、Apache Velocity、XML、XSL语言。

前面提到我定义的是一门基于XML的DSL，那么理所当然，可以借助PMD，扩展XML的扫描规则来满足自己的需求。

PMD在命令行中执行的方式如下：

pmd -d src/ -f xml -R myrule.xml -r dest/report.xml

• -d 代表要扫描的源码目录
• -f 代表报告输出的格式
• -R 代表采用哪些规则来扫描源代码
• -r 代表报告的输出路径

注意：这里PMD的规则和SonarQube中的规则其实没有太大关系，属于两种事物。不过，为方便后续提取PMD输出的报告，需要将PMD规则的名字和Sonar规则的键值保持一致。

我们定义PMD需要使用到的规则集custom-pmd-rules.xml：

<?xml version="1.0"?>
<ruleset name="ExamplePmdRuleset"
         xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">

    <description>
        Example set of configured PMD rules
    </description>

    <rule name="ComponentsMustNotBeFollowedByComponentsRule"
          message="Components tags followed by components tag found!"
          language="xml"
          class="net.sourceforge.pmd.lang.rule.XPathRule">

        <description>
            Tag components must not be followed by components tag.
        </description>

        <priority>1</priority>

        <properties>
            <property name="xpath">
                <value>//components/components</value>
            </property>
        </properties>

        <example>
            <![CDATA[
                <components>
                    <components>
                </components>
            ]]>
        </example>
    </rule>
</ruleset>

这里的类net.sourceforge.pmd.lang.rule.XPathRule来自于我们先前在pom.xml中声明的pmd-xml这个依赖包。它可以让我们通过设置xpath这一属性的值来构建各种不同规则。扫描中XML文件一旦匹配这些xpath规则，就会输出错误报告。

以ComponentsMustNotBeFollowedByComponentsRule这个自定义的规则为例。顾名思义，Components元素下不能再跟着Components元素。它在PMD扫描过程中如果被匹配上，会输出这样的报告：

<?xml version="1.0" encoding="UTF-8"?>
<pmd version="5.4.2" timestamp="2016-06-23T23:06:04.120">
    <file name="/Users/qianyan/github/sonar/sonar-custom/src/test/resources/wrong-syntax-but-not-csm.xml">
        <violation beginline="4"
                   endline="4"
                   begincolumn="5"
                   endcolumn="17"
                   rule="ComponentsMustNotBeFollowedByComponentsRule"
                   ruleset="ExamplePmdRuleset"
                   priority="1">
            Components tags followed by components tag found!
        </violation>
    </file>
    <file name="/Users/qianyan/github/sonar/sonar-custom/src/test/resources/wrong-syntax.csm.xml">
        <violation beginline="4"
                   endline="4"
                   begincolumn="5"
                   endcolumn="17"
                   rule="ComponentsMustNotBeFollowedByComponentsRule"
                   ruleset="ExamplePmdRuleset"
                   priority="1">
            Components tags followed by components tag found!
        </violation>
    </file>
</pmd>

PMD报告转化为Sonar的Issue

由于PMD是由Java编写的，所以我们可以在代码中调用PMD这个类net.sourceforge.pmd.PMD根据我们写好的PMD规则，来扫描Sonar指定的目录及其文件。最后，将PMD输出的XML格式的报告转化成Sonar能够理解的Issue。

代码如下：

public void execute(SensorContext context) {
        File reportFile = new File(context.fileSystem().workDir(), "report.xml"); // 1
        runPMD(context, reportFile); // 2
        convertToIssues(context, doc(reportFile)); // 3
}

1. 指定PMD输出文件的路径；
2. 运行PMD，输出XML格式的报告到1指定的文件当中；
3. 解析报告，并转化为Issue。

下面我们一步步来解释对应的代码：

• runPMD

    private void runPMD(SensorContext context, File reportFile) {
        final String dir = context.settings().getString("sonar.sources");
        final File file = new File(dir);
        String[] pmdArgs = {
                "-f", "xml",
                "-R", "custom-pmd-rules.xml",
                "-d", dir,
                "-r", reportFile.getAbsolutePath(),
                "-e", context.settings().getString("sonar.sourceEncoding"),
                "-language", "xml",
                "-version", "1.0"
        };
        final ClassLoader loader = Thread.currentThread().getContextClassLoader();
        try {
            Thread.currentThread().setContextClassLoader(getClass().getClassLoader());
            PMD.run(pmdArgs);
        } finally {
            Thread.currentThread().setContextClassLoader(loader);
        }
    }

我们通过PMD这个类运行pmdArgs。这里值得注意的是自SonarQube 5.6之后，我们可以通过context.settings()来获取工程的配置了，而不像以前那样依赖注入Settings对象了。

至于Thread.currentThread().setContextClassLoader(getClass().getClassLoader());这步操作和Sonar使用独立的classLoader加载自己的类有关。

• convertToIssues

private void convertToIssues(SensorContext context, Document doc) {
    final Element root = doc.getRootElement();
    final List<Element> files = root.elements("file");
    for (Element file : files) {

        final List<Element> violations = file.elements("violation");
        final String filePath = file.attributeValue("name");
        final FileSystem fs = context.fileSystem();
        final InputFile inputFile = fs.inputFile(fs.predicates().hasAbsolutePath(filePath));
        if (inputFile == null) {
            LOG.info("fs predicates that there is no {}", filePath);
            continue;
        }
        for (Element violation : violations) {
            final String rule = violation.attributeValue("rule");
            final int beginLine = Integer.parseInt(violation.attributeValue("beginline"));
            final int endLine = Integer.parseInt(violation.attributeValue("endline"));
            final int beginColumn = Integer.parseInt(violation.attributeValue("begincolumn"));
            final int endColumn = Integer.parseInt(violation.attributeValue("endcolumn"));
            final NewIssue newIssue = context.newIssue()
                    .forRule(RuleKey.of(CustomRulesDefinition.REPOSITORY_KEY, rule));
            final NewIssueLocation newIssueLocation = newIssue
                    .newLocation()
                    .on(inputFile)
                    .at(inputFile.newRange(beginLine, beginColumn, endLine, endColumn))
                    .message(violation.getText());
            newIssue.at(newIssueLocation).save();
        }
    }
}

这里主要是对PMD生成XML报告的解析和转换。比较需要关注是这块代码：

final InputFile inputFile = fs.inputFile(fs.predicates().hasAbsolutePath(filePath));
if (inputFile == null) {
    LOG.info("fs predicates that there is no {}", filePath);
    continue;
}

InputFile这是Sonar定义的合法的待扫描文件。举个例子：我们定义了一门基于XML的DSL，其文件的后缀是csm.xml，那么合法的待扫描文件就只能是这个后缀的文件了。像上述PMD输出的那份报告中出现的

<file name="/Users/qianyan/github/sonar/sonar-custom/src/test/resources/wrong-syntax-but-not-csm.xml">

就是不合法的。这个文件是以xml作为后缀的，PMD肯定可以扫描它，但是对于Sonar而言，它并不是InputFile（如果不作处理，就会返回null），所以我们需要在转换为Issue之前剔除掉。

最后，不要忘记保存，newIssue.at(newIssueLocation).save();。

Issue呈现在UI上，是这样的：

Issue

第八步 注册所有组件

现在所有的组件已经就绪，是时候将这些组件注册进插件当中了。还记得第一步我们创建的CustomPlugin.java? 所有上述组件，包括Language、Rules、Profiles以及Sensor都得在这个类中进行注册。代码如下：

package com.lambeta;

import org.sonar.api.Plugin;

public class CustomPlugin implements Plugin {
    public void define(Context context) {
        context.addExtension(CustomLanguage.class)
                .addExtension(CustomRulesDefinition.class)
                .addExtension(CustomProfileDefinition.class)
                .addExtension(CustomSensor.class);
    }
}

到此，这个插件算是写完了。那么接下来的问题就是如何运行它？

使用插件扫描工程

下载sonarqube docker镜像

最易于调试的地方莫过于本地了。如果机器是Mac，建议使用Kitematic这个Docker的客户端下载sonarqube的官方镜像，同时将映射的Port定在9000端口上，启动该镜像的容器实例。

sonarqube docker

构建和Copy插件包

在插件的工程根目录下，运行

mvn clean package

然后执行

cp target/sonar-custom-1.0-SNAPSHOT.jar /Users/your-name/Documents/Kitematic/sonarqube/opt/sonarqube/extensions/plugins

如果plugins目录不存在，可以手动创建。执行完命令之后，重启容器。

安装Maven的sonar插件

<!-- settings.xml -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
    https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <usePluginRegistry/>
    <offline/>
    <pluginGroups>
        <pluginGroup>org.sonarsource.scanner.maven</pluginGroup>
    </pluginGroups>
    <profiles>
        <profile>
            <id>sonar</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <!-- Optional URL to server. Default value is http://localhost:9000 -->
                <sonar.host.url>
                  http://192.168.99.100:9000
                </sonar.host.url>
            </properties>
        </profile>
     </profiles>
    <servers/>
    <mirrors/>
    <proxies/>
    <activeProfiles/>
</settings>

将这个settings.xml的文件放到~/.m2下。

运行Maven sonar:sonar

mvn sonar:sonar -Dsonar.sources=src/test/resources/ -Dsonar.language=custom-key -X

src/test/resources目录展开如下：

src/test/resources
├── right-syntax.csm.xml
├── wrong-syntax-but-not-csm.xml
└── wrong-syntax.csm.xml

然后，根据输出提示，访问
http://192.168.99.100:9000/dashboard/index/com.lambeta:sonar-custom

总结

Sonar Plugin

Plugin implements details

--更新 2017.04.07--

1. 官网样例链接

[1] 官方教程
[2] 博客
[3] 官方样例
[4] 本文样例