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

Posted 嘴巴吃糖了

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Sword - 为 Kotlin 函数增加代理功能相关的知识,希望对你有一定的参考价值。

简介

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

  1. Sword - 为 Kotlin 函数增加代理功能(一)
  2. Sword - 为 Kotlin 函数增加代理功能(二)

前面两篇文章笔者记录了 Sword 的实现过程,本篇文章简单记录下如何使用 Sword 以及如何通过 KSPInvocationHandler 生成 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)
     
 

笔者创建了两个测试函数:getTextNoArggetTextArg,一个函数没有参数,另一个函数有多个不同类型的参数。这两个函数上都有 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 的实现类生成全限定名索引。

此方案参考自 EventBusEvent 事件生成 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 生成索引类。

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

 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,
 )

接下来主要分析 SymbolProcessorprocess(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~

作者:guodongAndroid
链接:https://juejin.cn/post/7154009899251269639

最后

如果想要成为架构师或想突破20~30K薪资范畴,那就不要局限在编码,业务,要会选型、扩展,提升编程思维。此外,良好的职业规划也很重要,学习的习惯很重要,但是最重要的还是要能持之以恒,任何不能坚持落实的计划都是空谈。

如果你没有方向,这里给大家分享一套由阿里高级架构师编写的《Android八大模块进阶笔记》,帮大家将杂乱、零散、碎片化的知识进行体系化的整理,让大家系统而高效地掌握Android开发的各个知识点。

相对于我们平时看的碎片化内容,这份笔记的知识点更系统化,更容易理解和记忆,是严格按照知识体系编排的。

全套视频资料:

一、面试合集

二、源码解析合集


三、开源框架合集


欢迎大家一键三连支持,若需要文中资料,直接点击文末CSDN官方认证微信卡片免费领取↓↓↓

以上是关于Sword - 为 Kotlin 函数增加代理功能的主要内容,如果未能解决你的问题,请参考以下文章

Kotlin基础-扩展

使用 Kotlin 协程创建动态代理

Sword pcre库函数学习一

Sword pcre库函数学习三

Sword pcre库函数学习二

Spring 代理类和 Kotlin 中的空指针异常