简介
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
KSP 基于 KCP 实现，提供了一个简化的编译器插件 API，与 KCP 陡峭的学习曲线相比，KSP 的学习曲线要平滑一些。
如何使用 KSP 读者可以参考官网，本文就不记录搭建 KSP 开发环境了，直接进入正题。
笔者先描述下自己的实现思路：
-
首先判断当前模块是否有
InvocationHandler接口，如若没有，则不处理， -
其次判断当前模块是否有
ProxyHandler注解，如若没有，则不处理， -
以上两个条件都满足的，再获取包含
ProxyHandler注解的所有Kotlin符号， -
对获取的
Kotlin符号进行几种条件过滤，目的是确保此符号是InvocationHandler接口的实现类，过滤条件：- 判断是否是类，而不是接口、枚举类等，
- 判断类是否是公开且不是抽象类，确保当前类可以访问并直接实例化，
- 判断是否有主构造方法或主构造方法没有参数，确保有无参构造方法，
- 最后判断当前类是否实现了
InvocationHandler接口。
-
通过过滤后的符号，收集并存储要生成的字段名和全限定名，
-
最后通过
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
网友评论