KotlinPoet 中 toClassName 方法的正确使用方式

在 Kotlin 代码生成库 KotlinPoet 的最新版本中，toClassName() 方法的行为发生了变化，这可能会影响使用 KSP（Kotlin Symbol Processing）处理注解的开发者的代码。

问题背景

在 KotlinPoet 的早期版本（如 1.18.1）中，toClassName() 方法可以处理带有类型参数的泛型类型。然而，在新版本中，当尝试对带有类型参数的 KSType 调用 toClassName() 时，会抛出 IllegalStateException 异常，提示开发者应该使用 toTypeName() 方法替代。

正确用法

根据 KotlinPoet 仓库维护者的说明，toClassName() 方法仅适用于确定不包含泛型参数的类型。对于泛型类型，正确的做法是：

1. 使用 toTypeName() 方法获取完整的类型名称
2. 如果需要获取原始类型（不带泛型参数），可以先获取 KSClassDeclaration 引用，然后对其调用 toClassName()

代码示例

假设我们有如下接口和注解：

interface TestInterface<T : Any>

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.SOURCE)
annotation class MyAnnotation

在 KSP 处理器中，正确的处理方式应该是：

getSymbolsWithAnnotation(MyAnnotation.qualifiedName!!)
    .filterIsInstance<KSClassDeclaration>()
    .getAllSuperTypes()
    .first { 
        it.declaration.toClassName() == TestInterface::class.toClassName() 
    }

版本兼容性说明

这一变化属于行为修正（bug fix），因为早期版本允许对泛型类型使用 toClassName() 实际上是不正确的行为。开发者应该将代码迁移到使用 toTypeName() 或通过声明获取原始类名的方式。

总结

KotlinPoet 对类型名称处理方法的严格化有助于提高代码生成的安全性和准确性。开发者在使用 KSP 处理泛型类型时，应当注意区分以下场景：

• 需要完整类型信息（包括泛型参数）：使用 toTypeName()
• 只需要原始类型信息：通过 declaration.toClassName() 获取

这一变化虽然可能导致现有代码需要调整，但从长远来看有助于避免潜在的类型处理错误。