Sword - 为 Kotlin 函数增加代理功能(三)

简介

Sword：一个可以给 Kotlin 函数增加代理的第三方库，基于 KCP 实现。

前面两篇文章笔者记录了 Sword 的实现过程，本篇文章简单记录下如何使用 Sword 以及如何通过 KSP 为 InvocationHandler 生成 FqName 索引类 HandlerFqName。

下面我们先看下如何使用 Sword 吧。

应用

// `InvocationHandler` 实现类1
class GetTextNoArgInvocationHandler : InvocationHandler {

    private val TAG = GetTextNoArgInvocationHandler::class.java.simpleName

    override fun invoke(className: String, methodName: String, args: Array<Any?>): Any? {
        Log.e(TAG, "invoke: className = $className, methodName = $methodName, args(${args.size}) = ${args.joinToString()}")
        return "guodongAndroid-Debug"
    }
}

// `InvocationHandler` 实现类2
class GetTextArgInvocationHandler : InvocationHandler {

    private val TAG = GetTextArgInvocationHandler::class.java.simpleName

    override fun invoke(className: String, methodName: String, args: Array<Any?>): Any? {
        Log.e(TAG, "invoke: className = $className, methodName = $methodName, args(${args.size}) = ${args.joinToString()}")
        return User("guodongAndroid-Debug", 18)
    }
}

在上面的代码片段中，笔者创建了两个 InvocationHandler 实现类，对原始函数的返回值进行了替换，接下来创建测试类：

向 Proxy 注解中的 handler 参数注入 InvocationHandler 实现类的全限定名(Fully Qualified Name)，其实现类必须有无参构造方法。

// 测试类
class Test {

    @Proxy(
        enable = BuildConfig.isDebug,
        // 注入 `InvocationHandler` 实现类的全限定名
        handler = "com.guodong.android.sword.app.GetTextNoArgInvocationHandler"
    )
    fun getTextNoArg() = "guodongAndroid"

    @Proxy(
        enable = BuildConfig.isDebug,
        // 注入 `InvocationHandler` 实现类的全限定名
        handler = "com.guodong.android.sword.app.GetTextArgInvocationHandler"
    )
    fun getTextArg(
        b: Byte,
        z: Boolean,
        c: Char,
        s: Short,
        i: Int,
        l: Long,
        f: Float,
        d: Double,
        str: String,
        ia: IntArray,
        sa: Array<String>,
        ls: List<String>,
        lls: List<List<String>>,
        map: Map<String, String>,
        user: User,
        callback: Callback,
    ): User {
        return User("guodongAndroid-Release", 28)
    }
}

笔者创建了两个测试函数：getTextNoArg 和 getTextArg，一个函数没有参数，另一个函数有多个不同类型的参数。这两个函数上都有 Proxy 注解，并且注解的参数 enable 都处于开启状态，handler 参数都注入了对应 InvocationHandler 实现类的全限定名。

下面执行测试逻辑，分别调用上述两个函数：

val test = Test()

val textNoArg = test.getTextNoArg()
Log.e(TAG, "onCreate: textNoArg = ${textNoArg.length}")

val textArg = test.getTextArg(
    1,
    false,
    'A',
    1,
    1,
    1,
    1F,
    1.0,
    "test",
    intArrayOf(),
    Array(0) { "" },
    listOf(),
    listOf(),
    mapOf(),
    User("1", 1),
    object : Callback {
        override fun onSuccess() {
        }

        override fun onFailure(cause: Throwable) {
        }
    })
Log.e(TAG, "onCreate: textArg = $textArg")

原始输出结果：

1.MainActivity: onCreate: textNoArg = 14
2.MainActivity: onCreate: textArg = User(name=guodongAndroid-Release, age=28)

代理输出结果：

1.GetTextNoArgInvocationHandler: invoke: className = Test, methodName = getTextNoArg, args(0) = 
2.MainActivity: onCreate: textNoArg = 20
3.GetTextArgInvocationHandler: invoke: className = Test, methodName = getTextArg, args(16) = 1, false, A, 1, 1, 1, 1.0, 1.0, test, [I@156552e7, [Ljava.lang.String;@110de94, [], [], {}, User(name=1, age=1), com.guodong.android.sword.app.MainActivity$onCreate$textArg$2@12780d3d
4.onCreate: textArg = User(name=guodongAndroid-Debug, age=18)

从上面的输出结果可以看出，Proxy 注解生效了：调用上述两个函数后成功执行了代理类的 invoke 函数。

至此，Sword 的使用就结束了，是不是比较简单呢？

但是这里有个问题：我们在给 Proxy 注解的 handler 参数注入 InvocationHandler 实现类的全限定名时使用的是硬编码，如果我们修改了实现类的类名，而忘记修改此处的全限定名，代码在运行时就会发生错误了。

针对这个问题，笔者的第一想法是使用 handler = GetTextNoArgInvocationHandler::class.java.name，但是不行，注解参数必须是编译期常量，此路不通了。

后面笔者想到一种方案：为 InvocationHandler 的实现类生成全限定名索引。

此方案参考自 EventBus 为 Event 事件生成 EventIndex ，不过 EventBus 使用 APT 技术进行实现，而 Sword 选择使用 KSP 实现。

接下来我们就看看如何为 InvocationHandler 的实现类生成全限定名索引吧。

首先看下最后的索引类 HandlerFqName 效果：

HandlerFqName

// The file is automatic generated by Sword, don't modify it.
package com.guodong.android.sword.app

import kotlin.String

/**
 * The class is automatic generated by Sword, don't modify it.
 *
 * [com.guodong.android.sword.api.kt.InvocationHandler]实现类的全限定名
 */
public object HandlerFqName {
  /**
   * [com.guodong.android.sword.app.GetTextArgInvocationHandler]
   */
  public const val GetTextArgInvocationHandler: String =
      "com.guodong.android.sword.app.GetTextArgInvocationHandler"

  /**
   * [com.guodong.android.sword.app.GetTextNoArgInvocationHandler]
   */
  public const val GET_TEXT_NO_ARG: String =
      "com.guodong.android.sword.app.GetTextNoArgInvocationHandler"
}

ProxyHandler

/**
 * 标记[InvocationHandler]的实现类, 为其生成`FqName`索引类`HandlerFqName`
 *
 * 使用 ksp 实现
 */
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
annotation class ProxyHandler(
    /**
     * 生成字段的名称, 默认为类名
     *
     * `paramName`参数名称不要随意变动
     */
    val paramName: String = ""
)

在 api-kotlin 模块中新增 ProxyHandler 注解，此注解用于标记 InvocationHandler 的实现类，为其生成FqName索引，比如我们标记在 GetTextNoArgInvocationHandler 类上：

@ProxyHandler("GET_TEXT_NO_ARG")
class GetTextNoArgInvocationHandler : InvocationHandler

其中 paramName 参数可以指定生成字段的名称，如果没有设置，默认生成的字段名称为实现类的类名：HandlerFqName.GetTextArgInvocationHandler。

KSP

KSPopen in new window 基于 KCP 实现，提供了一个简化的编译器插件 API，与 KCP 陡峭的学习曲线相比，KSP 的学习曲线要平滑一些。、

如何使用 KSP 读者可以参考官网open in new window，本文就不记录搭建 KSP 开发环境了，直接进入正题。

笔者先描述下自己的实现思路：

首先判断当前模块是否有 InvocationHandler 接口，如若没有，则不处理，
其次判断当前模块是否有 ProxyHandler 注解，如若没有，则不处理，
以上两个条件都满足的，再获取包含 ProxyHandler 注解的所有 Kotlin 符号，
对获取的 Kotlin 符号进行几种条件过滤，目的是确保此符号是 InvocationHandler 接口的实现类，过滤条件：
1. 判断是否是类，而不是接口、枚举类等，
2. 判断类是否是公开且不是抽象类，确保当前类可以访问并直接实例化，
3. 判断是否有主构造方法或主构造方法没有参数，确保有无参构造方法，
4. 最后判断当前类是否实现了 InvocationHandler 接口。
通过过滤后的符号，收集并存储要生成的字段名和全限定名，
最后通过 KotlinPoet 生成索引类。

idea

下面根据实现思路依次实现。首先定义一些常量，用于后面代码的编写：

companion object {
    // 对应`ProxyHandler`注解里的`paramName`参数名称
    private const val PARAM_NAME = "paramName"

    // 生成索引类的包名，提供给外部配置，默认`com.guodong.android.sword`
    private const val PACKAGE_NAME_PARAM_NAME = "sword.pkg"

    // 默认索引类的包名
    private const val DEFAULT_PACKAGE_NAME = "com.guodong.android.sword"
    
    // 索引类所在文件名
    private const val FILE_NAME = "HandlerFqName"
    
    // 索引类的类名
    private const val CLASS_NAME = "HandlerFqName"
}

再定义一个实体，用于存储生成的字段名和全限定名：

data class ProxyHandlerParam(
    /**
     * 参数名称, 默认为类名
     */
    val paramName: String,

    /**
     * [InvocationHandler]实现类的全限定名
     *
     * e.g. com.example.ProxyTestInvocationHandler
     */
    val fqName: String,
)

接下来主要分析 SymbolProcessor 的 process(resolver: Resolver) 函数，下面代码是思路中前两步的具体实现：

private val mInvocationHandlerName = requireNotNull(InvocationHandler::class.qualifiedName)
private val mProxyHandlerName = requireNotNull(ProxyHandler::class.qualifiedName)

override fun process(resolver: Resolver): List<KSAnnotated> {
    // 判断当前模块是否有 `InvocationHandler` 接口，如若没有，则不处理
    val mProxyHandlerType =
    	resolver.getClassDeclarationByName(mProxyHandlerName)?.asType(emptyList())
    if (mProxyHandlerType == null) {
        logger.warn("$TAG: Not found `ProxyHandler`")
        return emptyList()
    }

    // 判断当前模块是否有 `ProxyHandler` 注解，如若没有，则不处理
    val mInvocationHandlerType =
    	resolver.getClassDeclarationByName(mInvocationHandlerName)?.asType(emptyList())
    if (mInvocationHandlerType == null) {
        logger.warn("$TAG: Not found `InvocationHandler`")
        return emptyList()
    }
    
    ...
}

获取包含 ProxyHandler 注解的所有 Kotlin 符号比较简单，通过 KSP 提供的 API，我们可以很方便的获取到：

val symbols = resolver.getSymbolsWithAnnotation(mProxyHandlerName)

下面根据实现思路的第四步过滤我们获取到的符号：

val classDeclaration = symbols
	.filter { it.validate() }
	.filterIsInstance<KSClassDeclaration>()
	.filter { declaration ->
         // Class
         val isClass = declaration.classKind == ClassKind.CLASS

         // Public && !Abstract
         val isPublic =
         Modifier.PUBLIC in declaration.modifiers || declaration.modifiers.isEmpty()
         val isNotAbstract = Modifier.ABSTRACT !in declaration.modifiers

         // 无参构造方法
         val primaryConstructor = declaration.primaryConstructor
         val hasNoArgumentConstructor =
         primaryConstructor == null || primaryConstructor.parameters.isEmpty()

         // 实现`InvocationHandler`接口
         val isImplInvocationHandler =
         declaration.superTypes.any { ref -> ref.resolve() == mInvocationHandlerType }

         isClass && isPublic && isNotAbstract && hasNoArgumentConstructor && isImplInvocationHandler
	}

过滤符号后，就可以收集并存储要生成的字段名和全限定名了：

val params = mutableListOf<ProxyHandlerParam>()
for (declaration in classDeclaration) {
    for (annotation in declaration.annotations) {
        // 这里笔者没有判断当前`annotation`是否是`ProxyHandler`可能会存在问题
        // 因为`resolve()`函数的注释中描述调用此函数的代价比较昂贵, 应尽可能避免调用，这里又是在遍历中调用，所以笔者就没有判断
        // 如果存在问题，我们可以给`ProxyHandler`注解的`paramName`参数换个唯一不会重复的名称
        /*if (annotation.annotationType.resolve() != mProxyHandlerType) {
            continue
        }*/
        
        for (argument in annotation.arguments) {
            val name = argument.name?.asString() ?: continue
            // 判断是否是`ProxyHandler`注解中的参数名称
            if (name == PARAM_NAME) {
                // 获取注解中的参数值
                val value: String = argument.value as? String ?: continue
                // 获取当前实现类的全限定名
                val fqName: String = declaration.qualifiedName?.asString() ?: continue

                // 如果注解没有注入参数名则使用类名
                val paramName = value.ifEmpty { declaration.simpleName.asString() }
                
                // 收集存储
                val param = ProxyHandlerParam(paramName, fqName)
                params.add(param)
            }
        }
    }
}

收集我们所需的数据后，最后就可以生成索引类了，笔者使用 KotlinPoet 来生成索引类：

// 构建类中的全限定名属性
val propertySpecs = params.map { param ->
    PropertySpec.builder(param.paramName, String::class)
        .addModifiers(KModifier.CONST)
        .initializer("%S", param.fqName)
        .addKdoc("[${param.fqName}]")
        .build()
}

// 构建`HandlerFqName`类
val type = TypeSpec.objectBuilder(CLASS_NAME)
    .addKdoc("The class is automatic generated by Sword, don't modify it.\n\n")
    .addKdoc("[${mInvocationHandlerName}]实现类的全限定名")
    .addProperties(propertySpecs)
    .build()

// 获取包名
val pkg = env.options[PACKAGE_NAME_PARAM_NAME]
val packageName = if (pkg.isNullOrEmpty()) {
    DEFAULT_PACKAGE_NAME
} else {
    pkg
}

// 构建`HandlerFqName`文件
val fileBuilder = FileSpec.builder(packageName, FILE_NAME)
    .addFileComment("The file is automatic generated by Sword, don't modify it.")
    .addType(type)

// 创建生成文件的依赖关系
val sources =
    classDeclaration.map { it.containingFile }.filterNotNull().toList().toTypedArray()
val dependencies = Dependencies(true, *sources)

// 生成索引类
fileBuilder.build().writeTo(codegen, dependencies)

至此，通过 KSP 生成索引类完成。

总结

本文简单记录了 Sword 的使用方式，以及在使用过程中发现的问题，最后使用 KSP 解决问题的过程。在解决问题的过程中，笔者参考 EventBus 的实现，结合问题本身的逻辑，形成自己的解决方案。

通过解决这个问题的过程，笔者感受到学习开源项目的魅力，当我们遇到问题时，或许开源项目也遇到过类似问题并有成熟的解决方案供我们参考。

最近笔者对 Sword 的功能实现有新的想法：通过 Kotlin IR 进行实现。

目前这只是一个初步想法，理论上实现起来应该比使用 ASM 简单一些吧，待笔者实现后再记录一下吧。

下篇再见，happy~

Sword - 为 Kotlin 函数增加代理功能(三)

# Sword - 为 Kotlin 函数增加代理功能(三)

# 简介

# 应用

# HandlerFqName

# ProxyHandler

# KSP

# 总结

Sword - 为 Kotlin 函数增加代理功能(三)

简介

应用

HandlerFqName

ProxyHandler

KSP

总结