AST解析Gradle入门与实践

发表于 3年以前 | 总阅读数：596 次

本文要点：

了解Gradle构建工具和Groovy语言
了解通过AST方式去修改Gradle文件

本文源码基于org.codehaus.groovy:groovy-all:3.0.8分析。

理解Gradle

01 什么是Gradle？

这是来自官网的描述，做为一种自动化构建工具，可以总结以下三点：

① 更快构建；

② 自动化；

③ 更好交付；

Gradle使用一种基于Groovy的特定领域语言来声明项目设置，而不是繁琐复杂的XML。帮开发者做了依赖、打包、部署、发布、各种渠道的差异管理等工作。同样，为了减少软件开发人员所需要做出的决定，而又不失灵活性，Gradle也遵循约定优于配置的设计范式。

截止到目前，官方支持的项目种类有Java、Groovy、Kotlin、Scala、C++、Swift等。

02 Gradle与Maven比较

两者均是项目构建工具，Gradle提供功能更加丰富的依赖管理，包括严格版本、降级、多种变体等，下面从最大两方面来对比：

灵活性：Google 选择 Gradle 作为Android的官方构建工具，不是因为构建脚本是代码，而是因为 Gradle 可以使用最基础的能力去扩展。同时灵活的插件扩展也给开发者带来便利。
性能：Gradle构建项目通过跟踪任务输入输出来避免不必要的构建，做到增量更新，配合构建缓存策略，进一步加快构建速度，同时Gradle会开启守护进程，将构建信息缓存在内存中。与大部分Maven构建相比，速度至少提升2倍，在大型项目构建上，表现更佳，提升将近100倍。

详细比较见官网：maven-vs-gradle

03 Gradle与Groovy、Java的关系

Gradle看似配置文件，又似脚本语言，更像是一个编程语言。

Gradle作为一种构建工具，Gradle选择了Groovy。Groovy基于Java并拓展了Java，Groovy可以无缝衔接上所有Java库。

Groovy是一种脚本语言。当执行Groovy脚本时，Groovy会先将其编译成Java类字节码，然后通过JVM来执行这个Java类，由于Groovy代码在真正执行的时候已经变成了Java字节码，所以JVM根本不知道自己运行的是Groovy代码。

我将Android工程的基本配置文件，通过groovyc来编译，如下图所示：

可以看出，Gradle文件最终也是被编译成class文件，在JVM上运行。

理解AST

01 什么是AST？

编译器在将我们的源码编译成字节码之前，会先将源代码转换为 AST ( Abstract Syntax Tree，抽象语法树 )，以便于语义分析。

常见的使用场景有：IDE、代码优化、lint检查、代码兼容等；

02 Groovy AST过程

大致可将过程分为三个步骤：

① Parse（解析）：接收源码并输出 AST；

Lexical Analysis （词法分析）：把字符串形式的源代码转换为tokens流（每个词和符号都转换成token）；

Syntactic Analysis （语法分析）：把token流转换成 AST形式。该阶段会利用token中的信息把它们转换成一个 AST结构，以便于后续的操作；

② Transform （转换）：接收 AST 并对其进行遍历，在此过程中对节点进行添加、更新及移除等操作；

③ Generate （生成）：将转换后的AST重新生成字符串形式的代码；

在Generate阶段，Java和JS语言提供了标准的API，用于回写到源码中，但是Groovy并没有提供，简单概括为通过Transform阶段修改完语法树后，Groovy没法将语法树还原成Gradle文件，这也是我们需要去探索解决的问题之一。

03 Groovy常见的语句和表达式

在Groovy语言中，要想上手AST，必须对常见的语句和表达式有所了解，分别对应Statement和Expression，两者均是继承ASTNode。

在AST中，所有语句都通过Statement来描述，常见的有：

① ExpressionStatement：写法上会忽略返回值的普通方法调用，实际上，会return最后一个方法，如下所示：


//不包含大括号内容
repositories {
    google()
    jcenter()
    mavenCentral()    // 默认会return最后一个
}

② BlockStatement：任意Statement的集合，如下所示：


//大括号内容，不包含dependencies和大括号
dependencies {
    implementation 'org.codehaus.groovy:groovy-all:3.0.8'
    api 'org.junit.jupiter:junit-jupiter-api:5.6.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'
}

③ IfStatement：分支语句

④ ForStatement/DoWhileStatement/WhileStatement：循环语句

⑤ TryCatchStatement：异常捕获语句

......

所有表达式都通过Expression来描述，常见的有：

① ArgumentListExpression：方法参数列表表达式，如下所示：

// org.codehaus.groovy:groovy-all:3.0.8为implementation方法的第一个参数
implementation 'org.codehaus.groovy:groovy-all:3.0.8'

③ ConstantExpression：常量表达式

④ ConstructorCallExpression：构造方法表达式

⑤ LambdaExpression：Lambda方法表达式

⑥ListExpression：列表表达式，如下所示：


// 其中['*.jar', '*.aar']为ListExpression表示
implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')

⑦MapEntryExpression：映射表达式，如下所示：

// name: 'org.codehaus.groovy:groovy-all'和ext: 'aar'均为MapEntryExpression，其中name和ext为Map的key implementation(name: 'org.codehaus.groovy:groovy-all', ext: 'aar')

⑧MethodCallExpression：方法调用表达式

NamedArgumentListExpression：方法参数映射表达式，如下所示：


// implementation括号里的内容
implementation(name: 'org.codehaus.groovy:groovy-all', ext: 'aar')

⑨ TupleExpression：元组（静态不可变）表达式，如下所示：


//(include: ['*.jar', '*.aar'], dir: 'libs')为TupleExpression表达式
implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')

⑩VariableExpression：变量表达式

......

04 转换各个阶段介绍

从输入一个Gradle文件路径，到转换结束，总共经历9个阶段，每个阶段含义不一样，下面分别来简单介绍下，按先后顺序排序：

① INITIALIZATION阶段：初始化，重置编译器，打开文件等开始工作前的准备;

② PARSING阶段：解析源码，做词法分析，生成CST（具体语法树），如下所示:

// org\codehaus\groovy\control\SourceUnit.java
public void parse() throws CompilationFailedException {
// ......
    try (Reader reader = source.getReader()) {
        parserPlugin = getConfiguration().getPluginFactory().createParserPlugin();
        // 转换为CST
        cst = parserPlugin.parseCST(this, reader);
    } catch (IOException e) {
        getErrorCollector().addFatalError(new SimpleMessage(e.getMessage(), this));
    }
}

③ CONVERSION阶段：CST 到 AST 的转换，如下所示:


// org/codehaus/groovy/control/CompilationUnit.java
public void compile(int throughPhase) throws CompilationFailedException {
    //......
    while (throughPhase >= phase && phase <= Phases.ALL) {
        //......
        if (phase == Phases.CONVERSION) {
            //转换为AST，最终调Antlr4ParserPlugin的buildAST实现
            buildASTs();
        }
        //......       
    }
}


// org/apache/groovy/parser/antlr4/Antlr4ParserPlugin.java
public ModuleNode buildAST(final SourceUnit sourceUnit, final ClassLoader classLoader, final Reduction cst) {
    AstBuilder builder = new AstBuilder(sourceUnit,
            sourceUnit.getConfiguration().isGroovydocEnabled(),
    sourceUnit.getConfiguration().isRuntimeGroovydocEnabled()
    );
    //生成AST
    return builder.buildAST();
}

④ SEMANTIC_ANALYSIS阶段：语义分析，该阶段处理的逻辑较多，CompilationUnit类初始的过程中，会加入StaticImportVisitor、InnerClassVisitor、GenericsVisitor、AnnotationCollectorTransform和StaticVerifier这5个处理Visitor，涉及代码较多，只摘主要流程，如下所示：

// org/codehaus/groovy/control/CompilationUnit.java
public void compile(int throughPhase) throws CompilationFailedException {
    //......  
    while (throughPhase >= phase && phase <= Phases.ALL) {
        if (phase == Phases.SEMANTIC_ANALYSIS) {
            //AST结构调整，最终会调用到resolve的闭包
            resolve.doPhaseOperation(this);
            if (dequeued()) continue;
        }
        //......  
    }
}
private final ISourceUnitOperation resolve = (final SourceUnit source) -> {
    for (ClassNode classNode : source.getAST().getClasses()) {
        GroovyClassVisitor visitor = new VariableScopeVisitor(source);
        //初始AST变量范围
        visitor.visitClass(classNode);
        resolveVisitor.setClassNodeResolver(classNodeResolver);
        //将特殊写法，比如：C[], foo as C, (C) foo ，转为ClassExpression
        resolveVisitor.startResolving(classNode, source);
    }
};

⑤ CANONICALIZATION阶段：AST转换完成，该阶段会处理内部类和枚举；

⑥ INSTRUCTION_SELECTION阶段：类生成前处理，该阶段会桥接私有方法，方便外部类调用，同时为私有字段添加特殊访问器，方便内部类访问；

⑦ CLASS_GENERATION阶段：类生成，该阶段会对类做排序和优化，包括对静态字段替换常量、删除多余引用等，同时做最后的合法性检查，检查内容较多，可参考CompilationUnit.classgen的call方法，最终会生成Java的class数据；

⑧ OUTPUT阶段：将class文件输出到磁盘；

⑨ FINALIZATION阶段：结束。

官方提供了ASTTransformation类，是以注解的形式来注入属性或者方法等，实际上也是在上述各个阶段获取注解，并添加自定义的处理器，简化整个流程，实现的逻辑在org/codehaus/groovy/transform/ASTTransformationVisitor.java类中，感兴趣同学可以自行查看源码。

从上述各个阶段介绍，可以大致知道，如果你想要修改AST结构，最佳时机是CONVERSION，此阶段AST结构已形成，处理大致已完成，后续阶段都在处理语义和产物class文件。

实践

由于Groovy语言关于AST资料较少，只能通过阅读源码来探索，包括上述的偏理论介绍，大部分属于个人见解，不准地方欢迎指出讨论。下面手把手编写一个demo，目标是将工程里的test.gradle配置文件，通过解析成AST结构，动态新增如下代码：


dependencies {
     testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.0'
}

修改完AST结构后，能够将AST回写回build.gradle文件。

01 创建工程

由于本文是介绍Gradle相关，所以我直接在idea里面创建Gradle工程，创建后工程目录如下：

其中test.gradle文件内容如下：


plugins {
    id 'groovy'
    id 'java'
}
group 'org.example'
version '1.0-SNAPSHOT'
repositories {
    mavenCentral()
}
dependencies {
    implementation 'org.codehaus.groovy:groovy-all:3.0.8'
}
test {
    useJUnitPlatform()
}

02 源码解析成AST

能看懂上述概念介绍，相信写出解析代码并不难，大家也可参照官方ASTTransformation注解的形式来实现，但是注解局限性太大，不够灵活，这里我从脚本的角度来做解析，方便以后做工程化或自动化，demo以最小可运行展示，如下：

// 创建产物输出路径
File outDir = new File(System.getProperty("user.dir") + '/out')
if (!outDir.exists()) {
    outDir.mkdirs()
}
// groovy非常方便的file -> string
String sourceString = new File('test.gradle').text
// class产物文件名
String outputClassName = 'testGradle'
// groovy的源码包装
GroovyCodeSource codeSource = new GroovyCodeSource(sourceString, outputClassName, '')
// 当前要处理的阶段，这里在CONVERSION阶段去做修改
int currentPhase = Phases.CONVERSION
// AST编译的核心类，会收集编译器所有数据
CompilationUnit cu = new CompilationUnit(new CompilerConfiguration(CompilerConfiguration.DEFAULT) {
    @Override
    File getTargetDirectory() {
        // 继承编译默认配置，重写class文件输出位置
        return outDir
    }
}, codeSource.codeSource, null)
// 要转换的代码，内部会new一个SourceUnit，该类负责具体的AST转换，转换工作会移交到Antlr4ParserPlugin中，并最终由AstBuilder来完成
cu.addSource(codeSource.getName(), sourceString)
// 每个阶段处理完后回调
cu.setProgressCallback(new CompilationUnit.ProgressCallback() {
    @Override
    void call(ProcessingUnit context, int phase) throws CompilationFailedException {
        println('当前阶段：' + phase)
    }
})
// 开始处理源码，参与所有阶段
cu.compile(Phases.ALL)

运行上述代码，可得：

生成了test.gradle转换成class文件的产物，该产物是将test.gradle先转为AST结构，后将AST结构转换编译成class文件，供JVM运行。

03 修改AST结构

接着，需要去修改AST结构，来满足我们想动态添加依赖（testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.0'）的目的。

这里需要先介绍下转换时机，官方提供了三种回调：

① IGroovyClassOperation：对生成class文件的处理回调（只在OUTPUT阶段生效）；

② IPrimaryClassNodeOperation：对所有ClassNode的处理回调（只在CONVERSION和往后阶段）；

③ ISourceUnitOperation：对SourceUnit的处理回调（全程阶段参与，因为SourceUnit一直都存在）；

每个阶段操作接口不一样，因此addPhaseOperation时候需要写对对应操作接口，不然会出现不回调的尴尬情况，以下从源码摸索出来：

// 添加指定阶段的自定义操作
cu.addPhaseOperation(new CompilationUnit.IPrimaryClassNodeOperation() {
    @Override
    void call(SourceUnit source, GeneratorContext context, ClassNode classNode) throws CompilationFailedException {
        // 处理自定义逻辑，回调只会产生在CONVERSION和往后阶段，此时AST转换初步完成，才会有ClassNode产生
        println('IPrimaryClassNodeOperation：' +  source.name)

    }
}, currentPhase)
cu.addPhaseOperation(new CompilationUnit.IGroovyClassOperation() {
    @Override
    void call(GroovyClass groovyClass) throws CompilationFailedException {
        // 处理自定义逻辑，回调次数取决于生成多少个class文件（包含内部类）,只会在OUTPUT阶段回调，因为这个阶段才会产生class文件
        println('IGroovyClassOperation：' + groovyClass.name)
    }
})
cu.addPhaseOperation(new CompilationUnit.ISourceUnitOperation() {
    @Override
    void call(SourceUnit source) throws CompilationFailedException {
        // 处理自定义逻辑，AST生成前后都会参与，SourceUnit中的值会随每个阶段变化，需要注意判空
        println('ISourceUnitOperation：' + source.getAST())
    }
}, currentPhase)
cu.addFirstPhaseOperation(new CompilationUnit.IPrimaryClassNodeOperation() {
    @Override
    void call(SourceUnit source, GeneratorContext context, ClassNode classNode) throws CompilationFailedException {
        // 处理自定义逻辑，不建议加在CONVERSION和之前阶段，因为addFirstPhaseOperation会置为最先处理，此时虽然AST已经生成，但是并未将ModuleNode加入CompileUnit中，所以不生效
        println('addFirstPhaseOperation：' + source.name)
    }
}, currentPhase)
cu.addNewPhaseOperation(new CompilationUnit.ISourceUnitOperation() {
    @Override
    void call(SourceUnit source) throws CompilationFailedException {
        // 处理自定义逻辑，这块从源码上看等同于addPhaseOperation，最终也会被加入主队列中去处理
        println('addNewPhaseOperation：' + source.getAST())
    }
}, currentPhase)

综上，可看出可选的回调有两种，一种是IPrimaryClassNodeOperation，一种是ISourceUnitOperation，两种回调同样都需要在CONVERSION阶段去处理，该阶段AST结构已经生成，且还没做后续加工处理，是最佳时机。

下面我在IPrimaryClassNodeOperation中去修改AST结构：


cu.addPhaseOperation(new CompilationUnit.IPrimaryClassNodeOperation() {
    @Override
    void call(SourceUnit source, GeneratorContext context, ClassNode classNode) throws CompilationFailedException {
        // 处理自定义逻辑，回调只会产生在CONVERSION和往后阶段，此时AST转换初步完成，才会有ClassNode产生
        println('IPrimaryClassNodeOperation：' +  source.name)
        // 通过AST主入口去遍历所有方法调用
        source.getAST().getStatementBlock().visit(new CodeVisitorSupport() {
            @Override
            void visitMethodCallExpression(MethodCallExpression call) {
                super.visitMethodCallExpression(call)
                // 该例子中，会有id、plugins、group、version、mavenCentral、repositories、implementation、dependencies、useJUnitPlatform和test方法
                println('处理方法名：' +  call.methodAsString)
                // 只处理dependencies方法
                if (!call.methodAsString.equals("dependencies")) {
                    return
                }
                // 找到AST中dependencies的结构
                if (call.arguments && call.arguments[0] && call.arguments[0] instanceof ClosureExpression) {
                    ClosureExpression closureExpression = (ClosureExpression) call.arguments[0]
                    if (closureExpression.code && closureExpression.code instanceof BlockStatement) {
                        // 添加组件（testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.0'）
                        BlockStatement blockStatement = (BlockStatement) closureExpression.code
                        // 构造一个方法名
                        ConstantExpression testImplementation = new ConstantExpression( 'testImplementation')
                        // 构造方法入参
                        ArrayList implementationValues = new ArrayList()
                        ConstantExpression implementationValue = new ConstantExpression('org.junit.jupiter:junit-jupiter-api:5.6.0')
                        implementationValues.add(implementationValue)
                        ArgumentListExpression methodCallArguments = new ArgumentListExpression(implementationValues)
                        // 构造一个方法调用
                        MethodCallExpression methodCall = new MethodCallExpression(VariableExpression.THIS_EXPRESSION, testImplementation, methodCallArguments)
                        ExpressionStatement expressionStatement = new ExpressionStatement(methodCall)
                        // 添加到AST树中
                        blockStatement.addStatement(expressionStatement)
                    }
                }
            }
        })
    }
}, currentPhase)

对于找到源码中的AST结构比较费劲，可以使用官方提供的GroovyConsole工具来查找。

运行上述代码，我们来看下产物：

可以看到，在最终的class产物中，我们已经将依赖动态加入。

04 AST还原成Gradle

上面的实践，我只是动态修改依赖并产生class产物，并没有修改原文件test.gradle文件。

那么问题来了，怎么回写gradle文件？官方并没有提供类似的回写能力。做过JS或者Java的AST人都知道，他们都提供了回写方法，而且非常好用，如下所示：

// JS
const generate = require('@babel/generator').default;
// 转换语法树
const astOutput = generate(codeString, { quotes: 'single', retainLines: true });
// AST输出JS代码
console.log(astOutput.code)
// Java
CompilationUnit cu = new CompilationUnit();
......
// AST输出Java代码
System.out.println(cu.toString());

但Groovy并没有提供，但我们又很想要，怎么办？只能翻groovy源码，从里到外翻了几遍后，更绝望了，确认没有。

没有其他办法了吗？也不是。什么办法？手撸一个，把语法树一个个还原回来，难吗？不难，工作量的问题。我们可以从简单的语法入手，一步步完善。

整个过程，我参考了org.codehaus.groovy:groovy-console-3.0.8中的groovy\console\ui\AstNodeToScriptAdapter.groovy类的做法，先看下回写逻辑：


// 输出覆盖原始gradle文件
StringWriter writer = new StringWriter()
File outputFile = new File(outDir.absolutePath + "/output.gradle")
// 将AST结构转为最终的Gradle文件
AstNodeToScriptVisitor astNodeToScriptVisitor = new AstNodeToScriptVisitor(writer)
astNodeToScriptVisitor.visitClass(cu.getFirstClassNode())
outputFile.write(writer.toString())

如果单纯借助此类，可以来看下最终回写的产物output.gradle内容：

可以看到，已经完全变样，一堆没用的代码，既臃肿又原始，明显不能符合我的审美标准，为此，基于AstNodeToScriptAdapter一顿魔改，改动代码就不贴了，如果能看懂以上内容，相信改动也是非常轻松，最后贴一张最终的产物：

可以看出，虽然不能百分百还原，有些许不一样，但已经无限接近，使用上还是能接受的。

总结

上述我们介绍了Gradle，也介绍了Groovy的AST，同时从简单的demo入手，手把手修改了AST结构，那问题来了，会了这些能做什么呢？本人有以下两个不成熟的观点：

Gradle已经开始替换Maven和Ant等自动化构建工具，从Android项目入手，到Java项目，再到Swift项目，相信未来会有越来越多的项目加入，随着傻瓜化和低代码普及，需要脚本自动化去修改gradle文件。（本文已讲解大致思路）
可以发现AST其实和具体语言关系不大，整个流程都是相通的，任何语言都能抽象成AST形式，而且有对应的语句和表达式。如果你愿意（日子过得太无聊），完全可以借道AST，将JS代码直接转成Java或者Groovy。

参考资料：

https://docs.gradle.org/current/userguide/userguide.html

http://www.groovy-lang.org/api.html