KotlinPoet详细使用指南（上）-六虎

前言

最近写了一个IDL转Kotlin Model Class的Android Studio插件，用到了KotlinPoet这个Square开发的开源库，KotlinPoet是用于生成.kt源文件的Kotlin和JavaAPI。在进行注释处理开发或者处理元数据文件时（例如数据库schemas、protocol、idl）KotlinPoet很有用。开发过程中，发现KotlinPoet的手册没人翻译，也没有一个系统性的教程。所以就对KotlinPoet的手册进行了翻译和收拾。

下载和运用

能够经过下载并引用最新的jar包或经过Maven依赖：

<dependency>
  <groupId>com.squareup</groupId>
  <artifactId>kotlinpoet</artifactId>
  <version>[version]</version>
</dependency>

或经过gradle依赖：

implementation("com.squareup:kotlinpoet:[version]")

最新的开发版本能够在官网中查找。

第一个比如

用咱们最了解的HelloWorld举例：

val greeterClass = ClassName("", "Greeter")
val file = FileSpec.builder("", "HelloWorld")
  .addType(
    TypeSpec.classBuilder("Greeter")
      .primaryConstructor(
        FunSpec.constructorBuilder()
          .addParameter("name", String::class)
          .build()
      )
      .addProperty(
        PropertySpec.builder("name", String::class)
          .initializer("name")
          .build()
      )
      .addFunction(
        FunSpec.builder("greet")
          .addStatement("println(%P)", "Hello, $name")
          .build()
      )
      .build()
  )
  .addFunction(
    FunSpec.builder("main")
      .addParameter("args", String::class, VARARG)
      .addStatement("%T(args[0]).greet()", greeterClass)
      .build()
  )
  .build()
file.writeTo(System.out)

会生成：

class Greeter(val name: String) {
  fun greet() {
    println("""Hello, $name""")
  }
}
fun main(vararg args: String) {
  Greeter(args[0]).greet()
}

为了最大化可移植性和兼容性，如果不指定润饰符，KotlinPoet生的类、办法和变量都带有public。为简练起见，示例中省掉了润饰符。

文件（File）

KotlinPoet顶用FileSpec.builder创立文件，文件是最终代码输出的载体，能够增加一些顶级的目标例如类，objects，办法，特点，类型别号。

val file = FileSpec.builder("", "HelloWorld")
  .addComment()
  .addAnnotation()
  .addImport()
  .addProperty()
  .addType()
  .addFunction()
  .build()

文件创立之后，能够用许多办法输出：

fun writeTo(out: Appendable)
fun writeTo(directory: Path)
fun writeTo(directory: File): Unit = writeTo(directory.toPath())
fun writeTo(filer: Filer)
fun toString(): String = buildString { writeTo(this) }

输出的时分，会按照注释、注解、包名、import、其他成员这个次序输出。

类（Type）

KotlinPoet中运用TypeSpec.classBuilder来创立类、object、接口和枚举，这里咱们只说类，其他的后面会提到。类中能够增加注释、注解、特点、办法、润饰符等候：

TypeSpec.classBuilder("Greeter")
  .addKdoc()
  .addAnnotations()
  .addProperty()
  .addFunction()
  .addModifiers()
  .build()

能够运用superclass指定父类，运用addSuperinterface指定实现的接口：

TypeSpec.classBuilder("Greeter")
  .superclass(BaseResponse::class)
  .addSuperinterface(KeepElement::class)
  .build()

办法（Functions）

KotlinPoet没有给代码块结构模型，没有表达式类、语句类或语法树节点。KotlinPoet直接运用字符串作为代码块，所以方体运用带占位符（KotlinPoet中的占位符用法比较复杂所以咱们在下中讨论）的字符串构成，能够用Kotlin的多行字符串改进代码风格：

val main = FunSpec.builder("main")
  .addCode("""
    |var total = 0
    |for (i in 0 until 10) {
    |    total += i
    |}
    |""".trimMargin())
  .build()

会生成：

fun main() {
  var total = 0
  for (i in 0 until 10) {
    total += i
  }
}

还能够运用beginControlFlow和endControlFlow来协助处理换行符、大括号和缩进：

val main = FunSpec.builder("main")
  .addStatement("var total = 0")
  .beginControlFlow("for (i in 0 until 10)")
  .addStatement("total += i")
  .endControlFlow()
  .build()

能够进一步把循环的范围改成能够装备的：

private fun computeRange(name: String, from: Int, to: Int, op: String): FunSpec {
  return FunSpec.builder(name)
    .returns(Int::class)
    .addStatement("var result = 1")
    .beginControlFlow("for (i in $from until $to)")
    .addStatement("result = result $op i")
    .endControlFlow()
    .addStatement("return result")
    .build()
}

然后调用computeRange("multiply10to20", 10, 20, "*")，会生成：

fun multiply10to20(): kotlin.Int {
  var result = 1
  for (i in 10 until 20) {
    result = result * i
  }
  return result
}

上面比如中的办法是有办法体的。咱们能够用KModifier.ABSTRACT生成没有办法体的笼统办法。当然，笼统办法有必要写在笼统类或接口里。

val flux = FunSpec.builder("flux")
  .addModifiers(KModifier.ABSTRACT, KModifier.PROTECTED)
  .build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addModifiers(KModifier.ABSTRACT)
  .addFunction(flux)
  .build()

会生成：

abstract class HelloWorld {
  protected abstract fun flux()
}

咱们还能够用FunSpec.Builder来给办法增加其他的润饰符，比如KModifier.INLINE。除此之外，FunSpec.Builder还能够用来装备办法的参数、可变参数、注释、注解、类型变量、返回类型、接收器类型等等。

扩展办法（Extension functions）

用FunSpec.Builder指定接收器类型就能生成扩展办法。

val square = FunSpec.builder("square")
  .receiver(Int::class)
  .returns(Int::class)
  .addStatement("var s = this * this")
  .addStatement("return s")
  .build()

会生成：

fun Int.square(): Int {
  val s = this * this
  return s
}

Kotlin中的单行办法

KotlinPoet会把以return最初的办法输出成单行办法。

val abs = FunSpec.builder("abs")
  .addParameter("x", Int::class)
  .returns(Int::class)
  .addStatement("return if (x < 0) -x else x")
  .build()

会生成：

fun abs(x: Int): Int = if (x < 0) -x else x

参数的默许值

如果期望给办法的参数增加默许值。例如，期望给办法的参数b增加默许值为0。

fun add(a: Int, b: Int = 0) {
  print("a + b = ${a + b}")
}

能够用ParameterSpec.builder来装备参数的defaultValue()默许值。

FunSpec.builder("add")
  .addParameter("a", Int::class)
  .addParameter(
    ParameterSpec.builder("b", Int::class)
      .defaultValue("%L", 0)
      .build()
  )
  .addStatement("print("a + b = ${a + b}")")
  .build()

空格默许换行！

当代码行或许超越长度约束的时分，KotlinPoet会用换行符替换代码块中的空格。例如下面的办法：

val funSpec = FunSpec.builder("foo")
  .addStatement("return (100..10000).map { number -> number * number }.map { number -> number.toString() }.also { string -> println(string) }")
  .build()

会生成下面的代码，能够看出also后面就换行了：

fun foo() = (100..10000).map { number -> number * number }.map { number -> number.toString() }.also
{ string -> println(string) }

这不是期望的成果also和后面的{需求在同一行，不过咱们能够用符号来声明完全不想被替换的空格。看下面的比如：

val funSpec = FunSpec.builder("foo")
  .addStatement("return (100..10000).map{ number -> number * number }.map{ number -> number.toString() }.also{ string -> println(string) }")
  .build()

现在将发生以下成果：

fun foo() = (100..10000).map { number -> number * number }.map { number ->
  number.toString()
}.also { string -> println(string) }

结构办法（Constructors）

FunSpec也能够用于结构函数，运用FunSpec.constructorBuilder：

val flux = FunSpec.constructorBuilder()
  .addParameter("greeting", String::class)
  .addStatement("this.%N = %N", "greeting", "greeting")
  .build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addProperty("greeting", String::class, KModifier.PRIVATE)
  .addFunction(flux)
  .build()

会生成：

class HelloWorld {
  private val greeting: String
  constructor(greeting: String) {
    this.greeting = greeting
  }
}

结构办法和其他办法的生成办法是一样的。KotlinPoet会把结构办法放在其他办法的最前面。

当咱们需求指定主结构办法的时分，运用primaryConstructor()：

val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .primaryConstructor(flux)
  .addProperty("greeting", String::class, KModifier.PRIVATE)
  .build()

会生成：

class HelloWorld(greeting: String) {
  private val greeting: String
  init {
    this.greeting = greeting
  }
}

不过这么生成的代码太冗余了，一般Kotlin中咱们会集并同名的主结构办法参数和特点。但KotlinPoet默许不这么干，需求咱们运用initializer办法，告知KotlinPoet特点会被主结构办法初始化：

val flux = FunSpec.constructorBuilder()
  .addParameter("greeting", String::class)
  .build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .primaryConstructor(flux)
  .addProperty(
    PropertySpec.builder("greeting", String::class)
      .initializer("greeting")
      .addModifiers(KModifier.PRIVATE)
      .build()
  )
  .build()

现在会生成：

class HelloWorld(private val greeting: String)

参数（Parameters）

能够用ParameterSpec.builder()或者直接用FunSpec.addParameter()来声明一个参数：

val android = ParameterSpec.builder("android", String::class)
  .defaultValue(""pie"")
  .build()
val welcomeOverlords = FunSpec.builder("welcomeOverlords")
  .addParameter(android)
  .addParameter("robot", String::class)
  .build()

会生成：

fun welcomeOverlords(android: String = "pie", robot: String) {
}

如果参数有注解等额定特点，那就有必要用ParameterSpec.builder()这种办法。

特点（Properties）

和参数一样，特点能够运用PropertySpec.builder或TypeSpec.addProperty创立：

val android = PropertySpec.builder("android", String::class)
  .addModifiers(KModifier.PRIVATE)
  .build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addProperty(android)
  .addProperty("robot", String::class, KModifier.PRIVATE)
  .build()

会生成：

class HelloWorld {
  private val android: String
  private val robot: String
}

如果需求给特点设定KDoc、注释或初始值，需求运用PropertySpec.builder。初始值运用initializer和String.format()：

val android = PropertySpec.builder("android", String::class)
  .addModifiers(KModifier.PRIVATE)
  .initializer("%S + %L", "Oreo v.", 8.1)
  .build()

会生成：

private val android: String = "Oreo v." + 8.1

PropertySpec.Builder默许会生成val的特点，能够经过mutable()把特点设置成var：

val android = PropertySpec.builder("android", String::class)
  .mutable()
  .addModifiers(KModifier.PRIVATE)
  .initializer("%S + %L", "Oreo v.", 8.1)
  .build()

内联特点（Inline properties）

需求特别提一下KotlinPoet对内联特点的处理：

val android = PropertySpec.builder("android", String::class)
  .mutable()
  .addModifiers(KModifier.INLINE)
  .build()

上面的代码会抛出反常：

java.lang.IllegalArgumentException: KotlinPoet doesn't allow setting the inline modifier on
properties. You should mark either the getter, the setter, or both inline.

这是因为被inline润饰的特点应该至少有一个getter办法，会被编译器内联：

val android = PropertySpec.builder("android", String::class)
  .mutable()
  .getter(
    FunSpec.getterBuilder()
      .addModifiers(KModifier.INLINE)
      .addStatement("return %S", "foo")
      .build()
  )
  .build()

增加了getter办法之后，成果如下：

var android: kotlin.String
  inline get() = "foo"

如果咱们想在上面的特点中增加一个非内联的setter怎么办，咱们能够：

val android = PropertySpec.builder("android", String::class)
  .mutable()
  .getter(
    FunSpec.getterBuilder()
      .addModifiers(KModifier.INLINE)
      .addStatement("return %S", "foo")
      .build()
  )
  .setter(
    FunSpec.setterBuilder()
      .addParameter("value", String::class)
      .build()
  )
  .build()

生成的成果在预期之中：

var android: kotlin.String
  inline get() = "foo"
  set(`value`) {
  }

最终如果咱们又期望运用KModifier.INLINE把setter变成inline办法，KotlinPoet能够做到生成包装好的代码：

inline var android: kotlin.String
  get() = "foo"
  set(`value`) {
  }

删去getter办法或setter办法的润饰符会把这种包装再翻开。

之所以KotlinPoet不允许inline直接符号特点而是符号getter/setter办法的原因是，如果KotlinPoet允许inline直接符号特点，那么每次getter/setter办法状况发生变化的时分，程序员有必要手动增加/删去润饰符才能取得正确且可编译的输出。

接口（Interfaces）

KotlinPoet中运用TypeSpec.interfaceBuilder定义接口，留意定义接口办法时，有必要有ABSTRACT的润饰符：

val helloWorld = TypeSpec.interfaceBuilder("HelloWorld")
  .addProperty("buzz", String::class)
  .addFunction(
    FunSpec.builder("beep")
      .addModifiers(KModifier.ABSTRACT)
      .build()
  )
  .build()

生成成果如下，留意ABSTRACT的润饰符在生成代码时被省掉了：

interface HelloWorld {
  val buzz: String
  fun beep()
}

Kotlin在1.4版本加入了fun interface语法，增加了对函数式（SAM）接口的支撑。在KotlinPoet 中能够运用TypeSpec.funInterfaceBuilder()创立函数式接口：

val helloWorld = TypeSpec.funInterfaceBuilder("HelloWorld")
  .addFunction(
    FunSpec.builder("beep")
      .addModifiers(KModifier.ABSTRACT)
      .build()
  )
  .build()
// Generates...
fun interface HelloWorld {
  fun beep()
}

目标声明（Object）

KotlinPoet中运用TypeSpec.objectBuilder声明Object：

val helloWorld = TypeSpec.objectBuilder("HelloWorld")
  .addProperty(
    PropertySpec.builder("buzz", String::class)
      .initializer("%S", "buzz")
      .build()
  )
  .addFunction(
    FunSpec.builder("beep")
      .addStatement("println(%S)", "Beep!")
      .build()
  )
  .build()

KotlinPoet相同也支撑用TypeSpec.companionObjectBuilder声明伴生目标，并用addType()加到类中：

val companion = TypeSpec.companionObjectBuilder()
  .addProperty(
    PropertySpec.builder("buzz", String::class)
      .initializer("%S", "buzz")
      .build()
  )
  .addFunction(
    FunSpec.builder("beep")
      .addStatement("println(%S)", "Beep!")
      .build()
  )
  .build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addType(companion)
  .build()

伴生目标也能够指定名称，如果不指定的话会运用默许名称Companion。

枚举（Enums）

KotlinPoet运用于TypeSpec.enumBuilder创立枚举类型，并运用addEnumConstant()来增加枚举值：

val helloWorld = TypeSpec.enumBuilder("Roshambo")
  .addEnumConstant("ROCK")
  .addEnumConstant("SCISSORS")
  .addEnumConstant("PAPER")
  .build()

会生成：

enum class Roshambo {
  ROCK,
  SCISSORS,
  PAPER
}

KotlinPoet支撑Kotlin中花哨的枚举，支撑枚举值重写办法或调用超类的结构函数。示例：

val helloWorld = TypeSpec.enumBuilder("Roshambo")
  .primaryConstructor(
    FunSpec.constructorBuilder()
      .addParameter("handsign", String::class)
      .build()
  )
  .addEnumConstant(
    "ROCK", TypeSpec.anonymousClassBuilder()
      .addSuperclassConstructorParameter("%S", "fist")
      .addFunction(
        FunSpec.builder("toString")
          .addModifiers(KModifier.OVERRIDE)
          .addStatement("return %S", "avalanche!")
          .returns(String::class)
          .build()
      )
      .build()
  )
  .addEnumConstant(
    "SCISSORS", TypeSpec.anonymousClassBuilder()
      .addSuperclassConstructorParameter("%S", "peace")
      .build()
  )
  .addEnumConstant(
    "PAPER", TypeSpec.anonymousClassBuilder()
      .addSuperclassConstructorParameter("%S", "flat")
      .build()
  )
  .addProperty(
    PropertySpec.builder("handsign", String::class, KModifier.PRIVATE)
      .initializer("handsign")
      .build()
  )
  .build()

会生成：

enum class Roshambo(private val handsign: String) {
  ROCK("fist") {
    override fun toString(): String = "avalanche!"
  },
  SCISSORS("peace"),
  PAPER("flat");
}

匿名内部类（Anonymous Inner Classes）

上面枚举的代码中，咱们运用了TypeSpec.anonymousClassBuilder()来声明匿名内部类，也能够在代码块顶用%L引用：

val comparator = TypeSpec.anonymousClassBuilder()
  .addSuperinterface(Comparator::class.parameterizedBy(String::class))
  .addFunction(
    FunSpec.builder("compare")
      .addModifiers(KModifier.OVERRIDE)
      .addParameter("a", String::class)
      .addParameter("b", String::class)
      .returns(Int::class)
      .addStatement("return %N.length - %N.length", "a", "b")
      .build()
  )
  .build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addFunction(
    FunSpec.builder("sortByLength")
      .addParameter("strings", List::class.parameterizedBy(String::class))
      .addStatement("%N.sortedWith(%L)", "strings", comparator)
      .build()
  )
  .build()

会生成如下的类：

class HelloWorld {
  fun sortByLength(strings: List<String>) {
    strings.sortedWith(object : Comparator<String> {
      override fun compare(a: String, b: String): Int = a.length - b.length
    })
  }
}

能够运用TypeSpec.Builder.addSuperclassConstructorParameter()办法传递超类结构函数的参数。

注解（Annotations）

不带参数的，简略的注解能够直接用addAnnotation()：

val test = FunSpec.builder("test string equality")
  .addAnnotation(Test::class)
  .addStatement("assertThat(%1S).isEqualTo(%1S)", "foo")
  .build()

在办法上生成了@Test注解：

@Test
fun `test string equality`() {
  assertThat("foo").isEqualTo("foo")
}

AnnotationSpec.builder()能够用addMember设置注解的参数：

val logRecord = FunSpec.builder("recordEvent")
  .addModifiers(KModifier.ABSTRACT)
  .addAnnotation(
    AnnotationSpec.builder(Headers::class)
      .addMember("accept = %S", "application/json; charset=utf-8")
      .addMember("userAgent = %S", "Square Cash")
      .build()
  )
  .addParameter("logRecord", LogRecord::class)
  .returns(LogReceipt::class)
  .build()

生成的注解会带着accept和userAgent特点：

@Headers(
  accept = "application/json; charset=utf-8",
  userAgent = "Square Cash"
)
abstract fun recordEvent(logRecord: LogRecord): LogReceipt

注解的特点也能够是注解，用%L做占位符：

val headerList = ClassName("", "HeaderList")
val header = ClassName("", "Header")
val logRecord = FunSpec.builder("recordEvent")
  .addModifiers(KModifier.ABSTRACT)
  .addAnnotation(
    AnnotationSpec.builder(headerList)
      .addMember(
        "[\n⇥%L,\n%L⇤\n]",
        AnnotationSpec.builder(header)
          .addMember("name = %S", "Accept")
          .addMember("value = %S", "application/json; charset=utf-8")
          .build(),
        AnnotationSpec.builder(header)
          .addMember("name = %S", "User-Agent")
          .addMember("value = %S", "Square Cash")
          .build()
      )
      .build()
  )
  .addParameter("logRecord", logRecordName)
  .returns(logReceipt)
  .build()

会生成：

@HeaderList(
  [
    Header(name = "Accept", value = "application/json; charset=utf-8"),
    Header(name = "User-Agent", value = "Square Cash")
  ]
)
abstract fun recordEvent(logRecord: LogRecord): LogReceipt

KotlinPoet支撑注解运用处目标（Annotation use-site targets）：

val utils = FileSpec.builder("com.example", "Utils")
  .addAnnotation(
    AnnotationSpec.builder(JvmName::class)
      .useSiteTarget(UseSiteTarget.FILE)
      .build()
  )
  .addFunction(
    FunSpec.builder("abs")
      .receiver(Int::class)
      .returns(Int::class)
      .addStatement("return if (this < 0) -this else this")
      .build()
  )
  .build()

会生成：

@file:JvmName
package com.example
import kotlin.Int
import kotlin.jvm.JvmName
fun Int.abs(): Int = if (this < 0) -this else this

结束

下部分咱们会讨论占位符的用法，和剩下的一小部分KotinPoet手册的内容。

KotlinPoet详细使用指南（上）

前言

下载和运用

第一个比如

文件（File）

类（Type）

办法（Functions）

扩展办法（Extension functions）

Kotlin中的单行办法

参数的默许值

空格默许换行！

结构办法（Constructors）

参数（Parameters）

特点（Properties）

内联特点（Inline properties）

接口（Interfaces）

目标声明（Object）

枚举（Enums）

匿名内部类（Anonymous Inner Classes）

注解（Annotations）

结束

相关文章

Hilt 实战 | 创建应用级别 CoroutineScope

本周SQL优化实战分享

Flutter中好用的快捷键（Android Studio）

🤖️ 如何逐步关闭 MIUI 无处不在的广告

作者信息