持续创造，加速成长！这是我参加「日新计划 10 月更文应战」的第 2 天，点击查看活动概况

简介

Sword：一个能够给 Kotlin 函数添加署理的第三方库，基于 KCP 完成。

  1. Sword – 为 Kotlin 函数添加署理功能(一)
  2. Sword – 为 Kotlin 函数添加署理功能(二)

前面两篇文章笔者记载了 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

KSP 基于 KCP 完成，供给了一个简化的编译器插件 API，与 KCP 陡峭的学习曲线相比，KSP 的学习曲线要滑润一些。、

怎么运用 KSP 读者能够参阅官网，本文就不记载建立 KSP 开发环境了，直接进入正题。

笔者先描绘下自己的完成思路：

  1. 首要判别当时模块是否有 InvocationHandler 接口，如若没有，则不处理，

  2. 其次判别当时模块是否有 ProxyHandler 注解，如若没有，则不处理，

  3. 以上两个条件都满意的，再获取包括 ProxyHandler 注解的一切 Kotlin 符号，

  4. 对获取的 Kotlin 符号进行几种条件过滤，意图是保证此符号是 InvocationHandler 接口的完成类，过滤条件：

    1. 判别是否是类，而不是接口、枚举类等，
    2. 判别类是否是公开且不是抽象类，保证当时类能够访问并直接实例化，
    3. 判别是否有主结构办法或主结构办法没有参数，保证有无参结构办法，
    4. 最终判别当时类是否完成了 InvocationHandler 接口。

  5. 经过过滤后的符号，搜集并存储要生成的字段名和全限定名，

  6. 最终经过 KotlinPoet 生成索引类。

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

下面依据完成思路顺次完成。 首要界说一些常量，用于后面代码的编写：

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~