原文：https://edenxio.github.io/2019/02/01/Android%20%E6%9E%84%E5%BB%BA%E8%84%9A%E6%9C%AC%E4%BB%8EGroovy%E8%BF%81%E7%A7%BB%E5%88%B0Kotlin%20DSL/

为什么要迁移？

因为 Groovy 是动态语言，在用作 Android 构建脚本的时候，经常有些问题：

• 很差的IDE支持(自动提示等)
• 性能问题
• 很多错误在build时才报出，而不是编译期
• 难以debug
• 重构很麻烦
  
  …

kotlin 并非动态语言，但却兼具了 Groovy 的灵活性和静态语言的特点，是一种类型安全的 DSL，很大程度上解决了上述的问题。

所以，开始吧！！

环境准备：

• 升级 Gradle Wrapper 到5.0+

  1 2 3 4 5 6

  # gradle-wrapper.properties distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-5.1-all.zip

• Gradle 5.0 只支持Java 8及以上，确保你的Java环境满足要求
• 升级所有的Gradle 插件

基本原则

由于Groovy和kotlin语言特性上的不同，我们迁移时需要遵循以下基本原则。

字符串

Groovy 中字符串单双引号都行，但是kotlin中字符串必须是双引号。所以第一步先把所有的build.gradle和settings.gradle里的''全部替换为""

赋值/传值

在Groovy中xx yy可以表示对变量xx赋与值yy，也可以表示调用函数xx，yy是参数，如Android中常见的：

1
2
3
4
5
6
7
8
9
10
11

defaultConfig { 
  // 赋值
  versionName "1.0"
  // 函数调用
  minSdkVersion 16 
}

dependencies {
    // 函数调用
    api 'org.greenrobot:eventbus:3.1.1'
}

而在kotlin中则是和Java一样的语法，相应的，上面的栗子迁移后：

1
2
3
4
5
6
7
8

defaultConfig {
    versionName = "1.0"
    minSdkVersion(16)
}

dependencies {
    api("org.greenrobot:eventbus:3.1.1")
}

知道了这个区别，但是很多xx yy 到底是赋值还是函数调用不好分辨，比如versionName "1.0" 是赋值，而minSdkVersion 16居然是函数调用。我们可以利用Android Studio的辅助功能，在kotlin-dsl 中是可以快速点选查看方法的源码的（mac 下 cmd + click）,而对属性变量就没啥反应，所以可以根据这个小trick来分辨。

Task

由于Koltin 是静态类型语言，Groovy是动态语言，前者是类型安全的，他们的性质区别很明显的体现在了 task 的创建和配置上。详情可以参考Gradle官方迁移教程

1
2
3
4
5
6
7
8

// groovy
task clean(type: Delete) {
    delete rootProject.buildDir
}
// kotiln-dsl
tasks.register("clean", Delete::class) {
    delete(rootProject.buildDir)
}

迁移步骤

1. 字符串单引号变双引号
2. 重命名所有xx.gradle脚本文件，加上.kts后缀
3. 插件声明 DSL的目标是尽可能具有声明性。 Kotlin DSL 使用plugins代码块来生成静态扩展函数以利用这些插件。因此，我们需要将之前Groovy中所有apply plugin xxx 移动到一个plugins代码块中：

   1 2 3 4 5

   // Groovy apply plugin: 'com.android.application' apply plugin: 'kotlin-android' apply plugin: 'kotlin-android-extensions' apply plugin: 'kotlin-kapt'

   1 2 3 4 5 6 7

   // Kotlin-dsl plugins { id("com.android.application") kotlin("android") kotlin("android.extensions") kotlin("kapt") }

   id()是应用插件的标准方法，kotlin()是应用Kotlin插件的方法，我们查看源码可以发现，它只是封装了一下id()方法，省略了org.jetbrains.kotlin.:

   1 2	fun PluginDependenciesSpec.kotlin(module: String): PluginDependencySpec = id("org.jetbrains.kotlin.$module")

4. 按前面提到的基本原则改写所有语句

示例

apply

除了apple 插件外，apply 还可以用来应用其他的gradle文件：

1
2
3
4
5

//groovy
apply from: 'custom.gradle'

// kotlin-dsl
apply(from = "custom.gradle")

依赖

依赖管理作为 gradle 的基本功能，gradle 提供了非常丰富的方法，下面以分三种情形进行说明。

基本情形

1
2
3
4
5
6
7

// groovy
implementation project(':library')
implementation 'com.jakewharton:butterknife:8.8.1'

// kotlin
implementation(project(":library"))
implementation("com.jakewharton:butterknife:8.8.1")

fileTree

使用 groovy 添加本地目录 jar 包依赖：

1
2

// groovy
implementation fileTree(include: '*.jar', dir: 'libs')

查看 fileTree 函数源码：

1
2

//org.gradle.api.Project
ConfigurableFileTree fileTree(Map<String, ?> args);

需要传入的是Map，因此迁移到 kotlin-dsl 可以这样写：

1

implementation(fileTree(mapOf("include" to listOf("*.jar"), "dir" to "libs")))

特别类型库依赖

之前在groovy中添加特别类型库依赖：

1

implementation(name: 'splibrary', ext: 'aar')

按前面提到的基本原则，我们会这样改写：

1
2

// wrong
implementation (name="splibrary",ext = "aar")

但实际上会导致失败。跳转到 kotlin-dsl implementation的源码找原因：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

fun DependencyHandler.`implementation`(dependencyNotation: Any)...

fun DependencyHandler.`implementation`(
    dependencyNotation: String,
    dependencyConfiguration: Action<ExternalModuleDependency>
)...

fun DependencyHandler.`implementation`(
    group: String,
    name: String,
    version: String? = null,
    configuration: String? = null,
    classifier: String? = null,
    ext: String? = null,
    dependencyConfiguration: Action<ExternalModuleDependency>? = null
)...

...

可以看到implementation有许多重载方法，可以用来处理各种依赖来源及设置的条件。在第三种实现对应的是我们的情况，其中group参数是必填的。

因此在kotlin-dsl中需要这样写：

1

implementation (group="",name="splibrary",ext = "aar")

必须加一个group还是很奇怪的，而目前看来这是一个bug (Gitub issue)

build variants

构建变体代表我们可以为应用构建的一个不同版本，比如“全功能release版”，”全功能”就是一种 productFlavor, “release” 则是一种 buildType，通过自定义并组合多种 productFlavor 和 buildType 可以构建多种不同版本的应用。

在 Groovy 中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

productFlavors {
        demo {
            dimension "app"
        }
        full {
            dimension "app"
            multiDexEnabled true
        }
    }

buildTypes {
        release {
            signingConfig signingConfigs.signConfig
            minifyEnabled true
            debuggable false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }

        debug {
            minifyEnabled false
            debuggable true
        }
    }
signingConfigs {
        release {
            storeFile file("myreleasekey.keystore")
            storePassword "password"
            keyAlias "MyReleaseKey"
            keyPassword "password"
        }
        debug {
            ...
        }
    }

在 kotlin-dsl 中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

productFlavors {
    create("demo") {
        dimension = "app"
    }
    create("full") {
        dimension = "app"
        multiDexEnabled = true
    }
}

buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            isDebuggable = false
            proguardFiles(getDefaultProguardFile("proguard-android.txtt"), "proguard-rules.pro")
        }
        
        getByName("debug") {
            isMinifyEnabled = false
            isDebuggable = true
        }
    }
    
signingConfigs {
        create("release") {
            storeFile = file("myreleasekey.keystore")
            storePassword = "password"
            keyAlias = "MyReleaseKey"
            keyPassword = "password"
        }
        getByName("debug") {
            ...
        }
    }

说明：

1. create() 和 getByName()是哪儿来的？demo,full,release等为什么作为字符串变成函数的参数了？

   在Groovy中，buildTypes 和 productFlavors 以及 signingConfigs 这几个函数都接收一个Action<? super NamedDomainObjectContainer<T>> 的接口作为参数，Action 是一个函数式接口，其唯一的方法接收一个 NamedDomainObjectContainer接口的实现类对象作为参数，而这个接口的主要方法就包含了 create() 和 getByName()，这俩方法有一些重载方法，但都包含一个字符串参数作为 T 的对象标识name。在 Groovy 中的full,release等值都会作为这个参数的值传入。

   以signingConfigs为例，用 Java 代码来演示可以更详细的展示这个调用层级：

   1 2 3 4 5 6 7

   signingConfigs(signingConfigContainer -> { signingConfigContainer.create("release",signingConfig ->{ signingConfig.setStorePassword("xxxx"); signingConfig.setKeyAlias("xx.yy.zz"); }); });

   *signingConfigContainer 就是接口 NamedDomainObjectContainer<SigningConfig>的实现类。

2. create() 和 getByName() 在什么时候使用？

   在NamedDomainObjectContainer和其子接口NamedDomainObjectCollection的Api 文档中已详细说明，简而言之，当其中的元素(i.e.productFlavor/buildType)已经存在则调用getByName()，否则使用create()创建新对象。

   而buildTypes中的debug和release以及 signingConfigs 中的debug都是默认存在的，通过查看Android Gradle插件的源码可以发现这一点：

   1 2 3 4 5

   // com.android.build.gradle.AppPlugin signingConfigContainer.create(DEBUG) buildTypeContainer.create(DEBUG) buildTypeContainer.create(RELEASE)

   因此这三者是调用getByName()方法进行配置的。

3. 在属性配置的代码块中，boolean 类型的赋值为什么有的在原来的表示（指 Groovy 中的表示）前加了is (e.g. minifyEnabled)，有的不加 (e.g. multiDexEnabled)？

   这其实就是 kotlin 和 java 的互调用规则决定的。 我们进行属性配置的这些类，即 SigningConfig BuildType 等，其源码都是 Java。

   从 kotlin 中调用 Java，遵循 getterter 和 setter 的 Java 约定的方法（名称以 get开头的无参数方法和名称以set开头的单参数方法）在 Kotlin 中表示为属性，对boolean类型属性有两种情况：

   1. 当 Java 类中的某boolean类型属性的getter/setter方法形如setXxx() isXxx()的时候，kotlin进行取值或赋值调用都是isXxx:

   1 2 3

   if(!isXxx){ isXxx = true }

   2. 形如通常的getXxx()和setXxx()的时候，kotlin的调用则不带前缀is。
      跳转到BuildType等的源码可以发现，minifyEnabled 属于第一种情况，而multiDexEnabled属于第二种情况，因此转为kotlin时前者需要带前缀is。

访问gradle.properties中的配置

我们通常会把签名信息、版本信息等配置写在gradle.properties中，groovy访问的时候直接引用即可:

1
2
3
4
5
6
7
8

# gradle.properties

version_code=1
version_name=1

# build.gradle
versionCode Integer.parseInt(version_code)
versionName version_name

而在kotlin-dsl的早期版本 (v0.16.3, Gradle 4.7 之前) 却无法直接访问，现在可以通过委托属性来访问：

1
2
3
4
5
6
7

# build.gradle.kts

val version_code: String by project
val version_name: String by project
...
versionCode = Integer.parseInt(version_code)
versionName = version_name

关于 ext

Google 官方推荐的一个 Gradle 配置最佳实践是在项目最外层 build.gradle 文件的ext代码块中定义项目范围的属性，然后在所有模块间共享这些属性，比如我们通常会这样存放依赖的版本号。

1
2
3
4
5
6
7
8
9

// build.gradle

ext {
    compileSdkVersion = 28
    buildToolsVersion = "28.0.3"

    supportLibVersion = "28.0.0"
    ...
}

但是由于缺乏IDE的辅助(跳转查看、全局重构等都不支持)，实际使用体验欠佳。

随着 Gradle 5.0的发布，Gradle官方现在推荐将这些内容声明在一个专用文件夹buildSrc中。App目录结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

.
├── app
    ├── build.gradle.kts
    └── src
        ├── main
        └── test
├── build.gradle.kts
├── buildSrc
└── src
    └── main
        └── kotlin
            ├── Depends.kt
            └── Versions.kt
├── build.gradle.kts
 ...
└── settings.gradle

依赖和版本号等值存放在了Depends.kt和Versions.kt文件中。

具体操作可以参考 Sam Edwards 的视频教程，以及 DroidKaigi 的2018开发者大会的 App 源码

尾巴

如文章开头所述，Kotiln-dsl 是一种更友好的 DSL语言，它是类型安全的，具有完善的IDE辅助支持（代码自动提示补全，快速跳转等），语法也非常灵活，同时也有很好的可读性，虽然目前与Groovy的兼容还没有100%完成，但对功能基本没有什么影响。

但目前的kotlin-dsl也有一些问题，如 ProAndroidDev 的文章中提到的，因为额外的类型安全检查，kotlin-dsl在性能上会有所损失，大型项目在迁移之前做个性能测试会更稳妥。

References

• Android Gradle Kotlin DSL 迁移
• Apache Groovy - 字符串表示
• ProAndroidDev - Migrating Android build scripts from Groovy to Kotlin DSL
• Gradle Guides - Migrating build logic from Groovy to Kotlin
• Gradle Docs - Organizing Gradle Projects
• kotlin - Type-Safe Builders
• kotlin-dsl Github issues - accessing gradle properties
• kotlin-dsl samples