新增完善中文文档，优化拓展lazy性能

DreamMoonCai · Nov 19, 2024 · 9135c5c · 9135c5c
1 parent e05e6bb
commit 9135c5c
Show file tree

Hide file tree

Showing 3 changed files with 458 additions and 5 deletions.
diff --git a/.../api/public/io/github/dreammooncai/yukireflection/factory/KReflectionFactory.md b/.../api/public/io/github/dreammooncai/yukireflection/factory/KReflectionFactory.md
@@ -1856,7 +1856,7 @@ fun <T> KClass<*>.bindProperty(
     extensionRef: Any?,
     isUseMember: Boolean,
     isLazy: Boolean,
-    noinline mappingRules: KPropertyFinder.(property: KProperty<*>) -> Unit
+    mappingRules: KPropertyFinder.(property: KProperty<*>) -> Unit
 ): BindingInstanceSupport.NonNull<T>
 ```
 ```kotlin:no-line-numbers
@@ -1865,7 +1865,7 @@ fun <T> KClass<*>.bindPropertyOrNull(
     extensionRef: Any?,
     isUseMember: Boolean,
     isLazy: Boolean,
-    noinline mappingRules: KPropertyFinder.(property: KProperty<*>) -> Unit
+    mappingRules: KPropertyFinder.(property: KProperty<*>) -> Unit
 ): BindingInstanceSupport.Nullable<T>
 ```
 
@@ -1877,4 +1877,52 @@ fun <T> KClass<*>.bindPropertyOrNull(
 
 > 与指定 `KProperty` 取得/绑定映射关系
 
+## BindingInstanceSignatureSupport <span class="symbol">- class</span>
 
+```kotlin:no-line-numbers
+open class BindingInstanceSignatureSupport<T>(
+    private val thisRefClass: KClass<*>,
+    private var thisRef: Any?,
+    private val declaringClass: KClass<*>? = null,
+    private val loader: ClassLoader? = null,
+    private val isLazy: Boolean,
+    private val mappingRules: KPropertySignatureFinder.(property: KProperty<*>) -> Unit
+)
+```
+
+**变更记录**
+
+`v1.0.0` `新增`
+
+**功能描述**
+
+> 委托绑定映射 ` KPropertySignature` 实例。
+
+## KClass.bindPropertySignature <span class="symbol">- ext-method</span>
+
+```kotlin:no-line-numbers
+fun <T> KClass<*>.bindPropertySignature(
+    thisRef: Any?,
+    declaringClass: KClass<*>? = null,
+    loader: ClassLoader? = null,
+    isLazy: Boolean,
+    mappingRules: KPropertySignatureFinder.(property: KProperty<*>) -> Unit
+): BindingInstanceSupport.NonNull<T>
+```
+```kotlin:no-line-numbers
+fun <T> KClass<*>.bindPropertySignatureOrNull(
+    thisRef: Any?,
+    declaringClass: KClass<*>? = null,
+    loader: ClassLoader? = null,
+    isLazy: Boolean,
+    mappingRules: KPropertySignatureFinder.(property: KProperty<*>) -> Unit
+): BindingInstanceSupport.Nullable<T>
+```
+
+**变更记录**
+
+`v1.0.0` `添加`
+
+**功能描述**
+
+> 与指定 `KPropertySignature` 取得/绑定映射关系
diff --git a/docs-source/src/zh-cn/api/special.md b/docs-source/src/zh-cn/api/special.md
@@ -148,3 +148,168 @@ Test::class.property { type = List::class.generic(String::class.variance(KVarian
 Test::class.property { type = List::class.generic(String::class.checkVariance()) } // 获取c
 Test::class.function { param(List::class.generic(Short::class)) } // 获取s
 ```
+
+::: tip
+
+更多功能请参考 [KClass.generic](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kclass-generic-ext-method)、[KClass.genericSuper](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kclass-genericSuper-ext-method)、[KCallable.generic](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kcallable-generic-ext-method) 方法。
+
+:::
+
+## 快速映射属性/函数
+
+> 这里是关于 Kotlin 类的属性绑定拓展功能和介绍。
+
+### bind进行绑定属性
+
+使用 `KYukiReflection` 可以轻松通过委托绑定某个 `属性` 减少反复书写简单属性的书写...
+
+假设宿主有以下类 并且在模块中可以直接引用
+
+> 示例如下
+
+```kotlin
+class Test {
+    val name = "test"
+    val param:MutableList<Int> = mutableListOf(1,2,3)
+    var size = 6
+    var nullable:String? = null
+    companion object {
+        val static = 1
+    }
+}
+```
+
+通过 `bindProperty` 绑定属性可以快速绑定属性，支持 `var` 和 `val` 字段，只需要定义的属性名和类型即可
+
+> 示例如下
+
+```kotlin
+// 创建 Test 实例
+val instance = Test()
+//通过以下方式快速绑定映射属性
+val name by Test::class.bindProperty<String>(instance)
+name == instance.name // 这是等价的
+
+val param:MutableList<Int> by Test::class.bindProperty(instance)
+param.add(4)
+instance.param[3] == 4 // 这是等价的操作的是同一个对象
+
+var size by Test::class.bindProperty<Int>(instance)
+size = 7//支持var字段 此操作同时会修改 instance.size
+// 你也可以绑定静态/对象属性，不需要实例
+val static:Int by Test.Companion::class.bindProperty()
+
+val nullable by Test::class.bindPropertyOrNull<String>(instance)
+nullable?.isEmpty() // 对于可空属性可以使用bindPropertyOrNull
+```
+
+以上示例可以使用原始方式进行操作，但是通过 `bindProperty`、`bindPropertyOrNull` 可以减少重复书写
+
+> 示例如下
+
+```kotlin
+// 创建 Test 实例
+val instance = Test()
+
+val nameRes = Test::class.property { 
+    this.name = "name"
+    this.type = String::class
+}.get(instance)
+nameRes.string() == instance.name // 这是等价的
+
+val param = Test::class.property {
+    this.name = "param"
+    this.type = MutableList::class.generic(Int::class)
+}.get(instance).cast<MutableList<Int>>()!!
+param.add(4)
+instance.param[3] == 4 // 这是等价的操作的是同一个对象
+
+val sizeRes = Test::class.property {
+    this.name = "size"
+    this.type = Int::class
+}.get(instance)
+sizeRes.set(7)//支持var字段 此操作同时会修改 instance.size
+
+// 你也可以绑定静态/对象属性，不需要实例
+val static = Test.Companion::class.property {
+    this.name = "static"
+    this.type = Int::class
+}.get().int()
+
+val nullableRes = Test::class.property {
+    this.name = "nullable"
+    this.type = String::class
+}.get(instance)
+nullableRes.cast<String>()?.isEmpty() // 稍显复杂
+```
+
+对于损坏的Kotlin类同样支持 `bindPropertySignature`、`bindPropertySignatureOrNull` 方法
+
+了解了 `bindProperty` 后，即使 `Test` 无法在模块中直接调用我们也可以很轻松的把 `Test` 的模板做出来
+
+> 示例如下
+
+```kotlin
+import kotlin.reflect.KClass
+
+// 将 Test 的实例作为 thisRef 传入
+class TestTemplate(thisRef: Any) {
+    companion object {
+        lateinit var thisRefClass: KClass<*> // 通过自己的方式获取 Test 的Class
+        val static by thisRefClass.bindProperty<Int>()
+    }
+
+    val name by thisRefClass.bindProperty<String>(thisRef)
+    val param by thisRefClass.bindProperty<MutableList<Int>>(thisRef)
+    var size by thisRefClass.bindProperty<Int>(thisRef)
+    val nullable by thisRefClass.bindPropertyOrNull<String>(thisRef)
+}
+```
+
+::: tip
+
+更多功能请参考 [KClass.bindProperty](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kclass-bindProperty-ext-method)、[KClass.bindPropertyOrNull](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kclass-bindPropertyOrNull-ext-method)、[KClass.bindPropertySignature](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kclass-bindPropertySignature-ext-method)、[KClass.bindPropertySignatureOrNull](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kclass-bindPropertySignatureOrNull-ext-method) 方法。
+
+:::
+
+### 快速附加已知属性/函数到查找器
+
+部分情况下我们已经有与需要查找的目标 `属性/函数` 大部分特征一样的另一个 `属性/函数` ，我们可以通过 `attach` 方法快速附加已知 `属性/函数` 到查找器
+
+> 示例如下
+
+```kotlin
+//宿主中假设有以下类
+class Test {
+    val param:MutableList<Int> = mutableListOf(1,2,3)
+    fun test(){/*...*/}
+    fun test(param:List<Int>){/*...*/}
+    fun run(){/*...*/}
+}
+//模块中创建与之类似的类
+interface TestTemplate {
+    val param: MutableList<Int>
+    fun test()
+    fun test(param:List<Int>)
+    fun run()
+}
+Test::class.property {
+    TestTemplate::param.attach()
+}.give() == Test::param//这是等价的 相当于使用TestTemplate的属性名和属性类型在Test中查找
+Test::class.function {
+    attachEmptyParam(TestTemplate::test)
+    attach(TestTemplate::test)//attach默认优先匹配有一个及以上参数的函数
+}.give()//遇到重载的函数如test时可以通过指定泛型列表来确定使用哪个进行附加
+
+//不过也有其他更轻便的方法，上述场景只是更换了 属性/函数 的所属KClass 那我们可以像下面这样
+TestTemplate::param.toKProperty(Test::class)//直接把TestTemplate的param转换为Test下的param
+TestTemplate::run.toKFunction(Test::class)//直接把TestTemplate的run转换为Test下的run，这样就不需要attach了但是不适用于重载
+val test:KFunction2<*,List<Int>,Unit> = TestTemplate::test // 通过这样复杂的显示声明类型也可以指定获取但并不实用
+test.toKFunction(Test::class)
+```
+
+::: tip
+
+更多功能请参考 [KCallable.toKCallable](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kcallable-toKCallable-ext-method)、[KProperty.toKProperty](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kproperty-toKProperty-ext-method)、[KFunction.toKFunction](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kfunction-toKFunction-ext-method)、[KPropertyFinder.attach](../api/public/io/github/dreammooncai/yukiReflection/factory/KReflectionFactory#kpropertyfinder-attach-ext-method)、[KFunctionFinder.attach](../api/public/io/github/dreammooncai/yukiReflection/factory/KFunctionAttachFactory#kfunctionfinder-attach-ext-method) 方法。
+
+:::