原文发布于 Medium: Writing custom lint rules for your Kotlin project with detekt
相比于Java来讲，Kotlin的代码分析工具少得可怜。最近在GitHub上看到了一个叫detekt的项目，尝试了一下，感觉十分好用。除了一般的代码格式、复杂度检查之外，它还可以做一些潜在bug、性能问题的检查。它的README中已经很好地讲过了如何使用、配置默认规则，这篇文章里我主要来详细地讲一下如何用它提供的接口写自定义的规则。
把项目克隆到本地
自定义的规则需要依赖于detekt项目的detekt-api, detekt-core和detekt-test部分，而且我会用到项目中给的样例来做讲解，所以把项目克隆下来会方便一些。
git clone https://github.com/arturbosch/detekt.git
如何书写规则
我们先来看看位于detekt/detekt-sample-ruleset中的TooManyFunctions规则：
/**
* @author Artur Bosch
* https://github.com/arturbosch/detekt/blob/master/detekt-sample-ruleset/src/main/kotlin/io/gitlab/arturbosch/detekt/sampleruleset/TooManyFunctions.kt
*/
class TooManyFunctions : Rule() {
override val issue = Issue(javaClass.simpleName, Severity.CodeSmell, "")
private var amount: Int = 0
override fun visitFile(file: PsiFile) {
super.visitFile(file)
if (amount > 10) {
report(CodeSmell(issue, Entity.from(file)))
}
}
override fun visitNamedFunction(function: KtNamedFunction) {
amount++
}
}
detekt是基于Kotlin编译器提供的抽象语法树（AST）工作的，就是说你可以overridevisitFile()、visitClass()之类的函数。在一个visit函数中，调用super.visitXxx()会遍历Xxx在AST中的所有子节点（当然除非你override了一些子节点的visit方法而且没有调用他们的super.visitXxx())。你也可以通过实现自己的DetektVisitor来做遍历，举个栗子，我们来看看detekt自带的NestedBlockDepth规则：
/**
* @author Artur Bosch
* https://github.com/arturbosch/detekt/blob/master/detekt-rules/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/complexity/NestedBlockDepth.kt
*/
class NestedBlockDepth(config: Config = Config.empty, threshold: Int = 3) : ThresholdRule(config, threshold) {
// ...
override fun visitNamedFunction(function: KtNamedFunction) {
val visitor = FunctionDepthVisitor(threshold)
visitor.visitNamedFunction(function)
if (visitor.isTooDeep)
report(ThresholdedCodeSmell(issue, Entity.from(function), Metric("SIZE", visitor.maxDepth, threshold)))
}
private class FunctionDepthVisitor(val threshold: Int) : DetektVisitor() {
internal var depth = 0
internal var maxDepth = 0
internal var isTooDeep = false
private fun inc() {
depth++
if (depth > threshold) {
isTooDeep = true
if (depth > maxDepth) maxDepth = depth
}
}
private fun dec() {
depth--
}
override fun visitLoopExpression(loopExpression: KtLoopExpression) {
inc()
super.visitLoopExpression(loopExpression)
dec()
}
// visit other blocks
}
}
在这个规则中由于每个函数都要做自己的深度计数，让Visitor来保存计数会比像TooManyFunctions那样用全局变量来计数简洁干净得多。还有一个要注意的地方就是可以看到如果想让你的规则可以接受自定义配置的话，在它的构造函数里加上config: Config就可以了。
测试你的规则
用Spek或者JUnit都可以测试规则。我们还是来看项目中给的例子：
/**
* @author Artur Bosch
* https://github.com/arturbosch/detekt/blob/master/detekt-sample-ruleset/src/test/kotlin/io/gitlab/arturbosch/detekt/sampleruleset/TooManyFunctionsSpec.kt
**/
class TooManyFunctionsSpec : SubjectSpek({
subject { TooManyFunctions() }
describe("a simple test") {
it("should find one file with too many functions") {
val findings = subject.lint(code)
assertThat(findings).hasSize(1)
}
}
})
class TooManyFunctionsTest : RuleTest {
override val rule: Rule = TooManyFunctions()
@Test fun findOneFile() {
val findings = rule.lint(code)
assertThat(findings).hasSize(1)
}
}
val code: String =
"""
你想测试的code放这里
"""
例子很简单清晰，就不多做说明了。这里只想强调两点：
- 如果你选择使用Spek，注意你要告诉父类
SubjectSpeck还有下面的subject你在测试哪一条规则。 - 在两个测试中我们都能看到，
subject/rule.lint(String)会编译你给它的字符串然后用它来测试你的规则。如果你不想用字符串的方式来表达你的代码的话，相对应的还有subject/rule.lint(path: Path)函数，只要把你的文件路径传进去就可以了。还有一个比较有用的函数是Rule.format(String/Path), 顾名思义会把你传进去的代码用detekt的格式规则整理好格式。
使用你的规则
cd detekt/detekt-sample-ruleset/
gradle build
你会看到detekt-sample-ruleset/build/libs文件夹里出现了两个jar。 我们需要的是detekt-sample-ruleset-[版本号].jar。我们可以就在detekt这个项目中试用一下这些规则。打开detekt/build.gradle，在文件最底部可以看到一个大概长这样的detekt区块：
detekt {
// ...
profile("main") {
input = "$project.projectDir"
filters = '.*/test/.*, .*/resources/.*, .*/build/.*'
config = "$project.projectDir/detekt-cli/src/main/resources/default-detekt-config.yml"
baseline = "$project.projectDir/reports/baseline.xml"
}
// ...
}
在profile("main")那个区块里加入一行ruleSets = “$projectDir/detekt-sample-ruleset/build/libs/detekt-sample-ruleset-[version].jar”就可以了。
现在在命令行运行：
// 在detekt文件夹中
gradle detektCheck
就可以看到因为我们的样例规则导致build failed:
Ruleset: sample
TooManyFunctions - [Configurations.kt] at detekt-cli/src/main/kotlin/io/gitlab/arturbosch/detekt/cli/Configurations.kt:1:1
这样就可以了，是不是很简单！
如果你想简历你自己的规则集的话，有一些需要注意的地方：
- 把你新建的模块加入到
detekt/settings.gradle里：
rootProject.name = 'detekt'
include 'detekt-api'
// ...
include 'detekt-migration'
include 'my-awesome-ruleset' //<--- 你的规则集在这
- 每当你新建一条规则的时候，都要把它加入到你的
RuleSetProvider的规则集里：
class MyAwesomeProvider(override val ruleSetId: String = "awesome") : RuleSetProvider {
override fun instance(config: Config): RuleSet {
return RuleSet(ruleSetId, listOf(
MyRule1(), // <--- 你的规则
MyRule2()
))
}
}
- detekt用
ServiceLoader来加载所有的规则，所以在你的模块里一定要有一个文件resources/META-INF/services/io.gitlab.arturbosch.detekt.api.RuleSetProvider，在这个文件里要有你的RuleSetProvider的全名（比方说，io.gitlab.arturbosch.detekt.sampleruleset.SampleProvider)
差不多就是这样了，希望有帮到你~