Sword - 为 Kotlin 函数增加代理功能(三)_valfq(2)，做了3年HarmonyOS鸿蒙还没看过OkHttp源码

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数HarmonyOS鸿蒙开发工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则几千的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年HarmonyOS鸿蒙开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上HarmonyOS鸿蒙开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新

如果你觉得这些内容对你有帮助，可以添加VX：vip204888 （备注鸿蒙获取）

一个人可以走的很快，但一群人才能走的更远。不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎扫码加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

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 开发环境了，直接进入正题。

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

0. 首先判断当前模块是否有 InvocationHandler 接口，如若没有，则不处理，

1. 其次判断当前模块是否有 ProxyHandler 注解，如若没有，则不处理，

2. 以上两个条件都满足的，再获取包含 ProxyHandler 注解的所有 Kotlin 符号，

3. 对获取的 Kotlin 符号进行几种条件过滤，目的是确保此符号是 InvocationHandler 接口的实现类，过滤条件：

   0. 判断是否是类，而不是接口、枚举类等，
   1. 判断类是否是公开且不是抽象类，确保当前类可以访问并直接实例化，
   2. 判断是否有主构造方法或主构造方法没有参数，确保有无参构造方法，
   3. 最后判断当前类是否实现了 InvocationHandler 接口。

4. 通过过滤后的符号，收集并存储要生成的字段名和全限定名，

5. 最后通过 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,
 )

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

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

问题的过程中，笔者参考 EventBus 的实现，结合问题本身的逻辑，形成自己的解决方案。

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

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

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

期待下篇再见，happy~

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