Kotlin Academy · 课时

使用 KotlinPoet 生成 Kotlin 源文件

Q: 「使用 KotlinPoet 生成 Kotlin 源文件」这节课中我会学到什么？

在 KSP 处理器中使用 KotlinPoet 生成类型安全的 Kotlin 代码。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在 KSP 处理器中使用 KotlinPoet 生成类型安全的 Kotlin 代码。

使用 KotlinPoet 生成 Kotlin 源文件 是 CoddyKit 上的免费 Kotlin Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

什么是 KotlinPoet

KotlinPoet 是 Square 提供的、用于以编程方式生成 .kt 源文件的 Kotlin API。它可以生成格式规范、符合 Kotlin 编程习惯的代码，并能自然地与 KSP 的 CodeGenerator 集成。

添加依赖

将 KotlinPoet 添加到处理器模块中：

dependencies {
    implementation("com.squareup:kotlinpoet:1.17.0")
    implementation("com.squareup:kotlinpoet-ksp:1.17.0") // KSP extensions
}

FileSpec：生成文件的根

FileSpec.builder(packageName, fileName) 是入口点。您可以向其中添加类型、函数和属性，然后通过 KSP 的 CodeGenerator 写出结果：

val file = FileSpec.builder("com.example.generated", "MyFactory")
    .addType( /* TypeSpec here */ )
    .build()

TypeSpec：定义类

使用 TypeSpec.classBuilder() 创建类，使用 objectBuilder() 创建对象，使用 interfaceBuilder() 创建接口。通过链式调用构建器方法，添加函数、属性和父接口：

val classSpec = TypeSpec.classBuilder("MyFactory")
    .addModifiers(KModifier.PUBLIC)
    .addFunction( /* FunSpec */ )
    .build()

FunSpec：生成函数

FunSpec.builder(name) 会创建一个函数。使用 addParameter()、returns() 和 addStatement() 构建函数的签名和主体：

val funSpec = FunSpec.builder("create")
    .addParameter("name", String::class)
    .returns(String::class)
    .addStatement("return "Hello, %L!", name")
    .build()

PropertySpec：生成属性

使用 PropertySpec.builder(name, type) 生成属性。指定 KModifier.PRIVATE、KModifier.OVERRIDE，或使用 mutable() 生成 var：

val propSpec = PropertySpec.builder("tag", String::class)
    .initializer("%S", "MyClass")
    .addModifiers(KModifier.PRIVATE)
    .build()

代码格式说明符

KotlinPoet 在 addStatement() 和 initializer() 中使用格式说明符：

%L — 字面量（不带引号）
%S — 字符串字面量（带引号）
%T — 类型名称（自动处理导入）
%N — 名称（规范或字符串的名称）

使用 %T 自动导入

当您将 %T 与 ClassName 一起使用时，KotlinPoet 会自动添加所需的导入。您无需手动编写导入语句：

val listType = ClassName("kotlin.collections", "List")
val funSpec = FunSpec.builder("items")
    .returns(listType.parameterizedBy(String::class.asTypeName()))
    .addStatement("return emptyList()")
    .build()

写入 KSP CodeGenerator

使用 kotlinpoet-ksp 桥接库，通过 KSP 的 CodeGenerator 写入生成的 FileSpec，同时保留增量构建元数据：

file.writeTo(
    codeGenerator = codeGenerator,
    aggregating = false
)

生成扩展函数

使用 FunSpec.builder(name).receiver(type) 生成扩展函数：

val extFun = FunSpec.builder("toJson")
    .receiver(ClassName("com.example", "User"))
    .returns(String::class)
    .addStatement("return Gson().toJson(this)")
    .build()

实际用例：工厂生成器

KSP 处理器会为数据类添加 @AutoFactory 注解，并使用 KotlinPoet 为每个数据类生成一个伴生工厂对象。生成的文件会放在原始类所在的同一程序包中。

测试生成的代码

在单元测试中使用 KotlinPoet 的 FileSpec.toString()，无需写入磁盘即可断言生成的源代码文本。kotlin-compile-testing-ksp 库可以在测试中编译并执行生成的代码。

快速检查

在 KotlinPoet 中，哪个格式说明符会自动为引用的类添加必要的导入？

回顾：使用 KotlinPoet 生成 Kotlin 源文件

关键要点：

FileSpec → 顶层文件；TypeSpec → 类/对象/接口；FunSpec → 函数；PropertySpec → 属性
使用 %T 表示类型引用——导入会自动添加
在 KSP 处理器中通过 file.writeTo(codeGenerator) 写入
使用 FileSpec.toString() 对生成的输出进行单元测试

常见问题解答

「使用 KotlinPoet 生成 Kotlin 源文件」课时是免费的吗？

是的 — 「使用 KotlinPoet 生成 Kotlin 源文件」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「使用 KotlinPoet 生成 Kotlin 源文件」这节课中我会学到什么？

在 KSP 处理器中使用 KotlinPoet 生成类型安全的 Kotlin 代码。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「使用 KotlinPoet 生成 Kotlin 源文件」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Kotlin Academy