元编程：反射

// 方式一：通过实例获取 —— 得到的是对象的实际运行时类型
val str = "Hello Kotlin"
val kClass1 = str::class  // 返回 KClass<String>
 
// 方式二：通过类型直接获取 —— 在编译期就确定的类型引用
val kClass2 = String::class  // 返回 KClass<String>
 
// 两者的微妙区别在多态场景下体现得淋漓尽致
open class Animal
class Dog : Animal()
 
val animal: Animal = Dog()          // 声明类型是 Animal，实际类型是 Dog
println(animal::class)              // class Dog —— 反射看到的是真实类型
println(animal::class.simpleName)   // Dog

// build.gradle.kts 中添加依赖
dependencies {
    // Kotlin 反射库，提供 KClass、KFunction、KProperty 等完整 API
    implementation("org.jetbrains.kotlin:kotlin-reflect")
}

import kotlin.reflect.KClass
import kotlin.reflect.full.*  // 扩展函数所在包，提供 memberProperties 等便捷 API
 
// 定义一个示例数据类
data class User(
    val name: String,       // 只读属性
    var age: Int,           // 可变属性
    val email: String = ""  // 带默认值的属性
)
 
fun exploreKClass() {
    // 获取 KClass 实例
    val kClass: KClass<User> = User::class
 
    // --- 基本身份信息 ---
    println(kClass.simpleName)      // "User" —— 不含包名的短名称
    println(kClass.qualifiedName)   // "com.example.User" —— 完整限定名
 
    // --- 类的性质判断 ---
    println(kClass.isData)          // true —— 是否为 data class
    println(kClass.isAbstract)      // false —— 是否为抽象类
    println(kClass.isSealed)        // false —— 是否为密封类
    println(kClass.isOpen)          // false —— data class 默认 final
    println(kClass.isFinal)         // true —— 是否为 final 类
    println(kClass.isCompanion)     // false —— 是否为伴生对象
 
    // --- 构造函数 ---
    // primaryConstructor 获取主构造函数（Kotlin 特有概念）
    val primaryCtor = kClass.primaryConstructor
    println(primaryCtor)            // fun <init>(String, Int, String): User
    // constructors 获取所有构造函数
    println(kClass.constructors.size)  // 1
 
    // --- 成员列表 ---
    // memberProperties 获取类中声明的所有属性（不含继承的）
    kClass.memberProperties.forEach { prop ->
        println("${prop.name}: ${prop.returnType}")
        // 输出：name: kotlin.String
        //       age: kotlin.Int
        //       email: kotlin.String
    }
}

// Kotlin KClass -> Java Class
val javaClass: Class<User> = User::class.java
 
// Java Class -> Kotlin KClass
val kotlinClass: KClass<User> = javaClass.kotlin
 
// 从实例获取 Java Class（注意写法差异）
val user = User("Alice", 30)
val jClass: Class<out User> = user.javaClass      // Java 风格
val kClass: KClass<out User> = user::class         // Kotlin 风格

import kotlin.reflect.KCallable
 
data class Book(val title: String, val price: Double) {
    fun describe(): String = "$title costs $$price"
}
 
fun exploreKCallable() {
    val kClass = Book::class
 
    // members 返回所有 KCallable（包含属性 + 函数 + 继承自 Any 的方法）
    kClass.members.forEach { callable: KCallable<*> ->
        println("${callable.name} -> 返回类型: ${callable.returnType}")
    }
    // 输出示例：
    // title -> 返回类型: kotlin.String
    // price -> 返回类型: kotlin.Double
    // describe -> 返回类型: kotlin.String
    // equals -> 返回类型: kotlin.Boolean
    // hashCode -> 返回类型: kotlin.Int
    // toString -> 返回类型: kotlin.String
    // copy -> 返回类型: Book
    // component1 -> 返回类型: kotlin.String
    // component2 -> 返回类型: kotlin.Double
}

// KCallable 的关键成员（简化展示）
interface KCallable<out R> {
    val name: String                    // 名称（函数名或属性名）
    val parameters: List<KParameter>    // 参数列表
    val returnType: KType               // 返回类型
    val typeParameters: List<KTypeParameter>  // 泛型类型参数
    val visibility: KVisibility?        // 可见性（PUBLIC, PRIVATE 等）
    val isAbstract: Boolean             // 是否抽象
    val isFinal: Boolean                // 是否 final
    val isOpen: Boolean                 // 是否 open
    val isSuspend: Boolean              // 是否为挂起函数（协程相关）
 
    // 核心方法：通过反射调用
    fun call(vararg args: Any?): R      // 按位置传参调用
    fun callBy(args: Map<KParameter, Any?>): R  // 按命名参数调用（支持默认值）
}

import kotlin.reflect.full.memberFunctions
import kotlin.reflect.full.primaryConstructor
 
data class Point(val x: Int, val y: Int) {
    fun distanceTo(other: Point): Double {
        // 计算两点之间的欧几里得距离
        val dx = (x - other.x).toDouble()
        val dy = (y - other.y).toDouble()
        return Math.sqrt(dx * dx + dy * dy)
    }
}
 
fun reflectiveCall() {
    // 1. 通过反射创建实例
    val ctor = Point::class.primaryConstructor!!  // 获取主构造函数
    val p1 = ctor.call(3, 4)                      // 反射调用构造函数，等价于 Point(3, 4)
    val p2 = ctor.call(0, 0)                      // 创建原点
 
    println(p1)  // Point(x=3, y=4)
 
    // 2. 通过反射调用成员函数
    val distFn = Point::class.memberFunctions
        .first { it.name == "distanceTo" }         // 按名称查找函数
 
    // call 的第一个参数是 receiver（即 this），后续是函数参数
    val distance = distFn.call(p1, p2)             // 等价于 p1.distanceTo(p2)
    println("Distance: $distance")                 // Distance: 5.0
 
    // 3. 查看函数的参数信息
    distFn.parameters.forEach { param ->
        println("参数: ${param.name}, 类型: ${param.type}, 索引: ${param.index}")
    }
    // 输出：
    // 参数: null, 类型: Point, 索引: 0       <-- 这是隐式的 this（receiver）
    // 参数: other, 类型: Point, 索引: 1      <-- 这是显式参数
}

open class Base {
    open fun greet() = "Hello from Base"
}
 
class Derived : Base() {
    override fun greet() = "Hello from Derived"
}
 
fun main() {
    val obj: Base = Derived()
    val kClass = obj::class
    println("${kClass.simpleName}, ${kClass.isFinal}, ${kClass.isOpen}")
}

import kotlin.reflect.KClass
 
// ========== 方式一：通过类名获取（编译期类型） ==========
// 语法：类名::class
// 返回类型：KClass<类名>，这是一个编译期就确定的精确类型
val stringClass: KClass<String> = String::class
// 此时 stringClass 的泛型参数是 String，编译器完全知道它指向哪个类
 
val intClass: KClass<Int> = Int::class
// 对于 Kotlin 基本类型，::class 返回的是 Kotlin 自己的 KClass
// 而不是 Java 的 int.class 或 Integer.class
 
// ========== 方式二：通过实例获取（运行时类型） ==========
// 语法：实例::class
// 返回类型：KClass<out T>，注意这里有 out 协变标记
val greeting: String = "Hello, Kotlin Reflection!"
val runtimeClass: KClass<out String> = greeting::class
// 为什么是 KClass<out String>？
// 因为实例的实际运行时类型可能是 String 的子类（虽然 String 是 final 的）
// 编译器用 out 来表达"至少是 String 或其子类型"的语义
 
// ========== 多态场景下的运行时类型 ==========
open class Animal(val name: String)          // 基类
class Dog(name: String) : Animal(name)       // 子类
class Cat(name: String) : Animal(name)       // 子类
 
fun printActualClass(animal: Animal) {
    // animal 的编译期类型是 Animal
    // 但 ::class 返回的是运行时的实际类型
    val kClass: KClass<out Animal> = animal::class
    println("编译期声明类型: Animal")
    println("运行时实际类型: ${kClass.simpleName}")
    // simpleName 返回类的简单名称（不含包名）
}
 
fun main() {
    printActualClass(Dog("Buddy"))
    // 输出：
    // 编译期声明类型: Animal
    // 运行时实际类型: Dog
 
    printActualClass(Cat("Whiskers"))
    // 输出：
    // 编译期声明类型: Animal
    // 运行时实际类型: Cat
}

fun main() {
    // 可空类型的类引用
    val nullableStr: String? = "not null"
    // 注意：不能对可空变量直接用 ::class
    // val cls = nullableStr::class  // 编译错误！
 
    // 正确做法：先进行空检查，或使用安全调用
    if (nullableStr != null) {
        // 智能转换后，nullableStr 变成非空类型，可以安全使用 ::class
        val cls = nullableStr::class
        println(cls.simpleName) // 输出: String
    }
 
    // 另一种方式：使用 let
    nullableStr?.let {
        println(it::class.simpleName) // 输出: String
    }
 
    // 如果值确实为 null
    val actualNull: String? = null
    // actualNull::class  // 编译错误：不能对可空类型使用 ::class
    // 这是 Kotlin 的类型安全设计——null 没有类型，自然没有 KClass
}

import kotlin.reflect.KClass
import kotlin.reflect.full.*  // 引入扩展函数：memberProperties, memberFunctions 等
 
// 定义一个有代表性的类结构用于演示
data class User(
    val id: Long,              // 只读属性
    var name: String,          // 可变属性
    val email: String = ""     // 带默认值的属性
) {
    // 次构造器
    constructor(name: String) : this(0L, name, "")
 
    // 成员函数
    fun greet(): String = "Hi, I'm $name"
 
    // 伴生对象
    companion object {
        const val TABLE_NAME = "users"
        fun create(name: String): User = User(name = name)
    }
}
 
fun main() {
    // 获取 KClass 引用
    val kClass: KClass<User> = User::class
 
    // ========== 1. 命名信息 ==========
    println("simpleName: ${kClass.simpleName}")
    // 输出: simpleName: User
    // simpleName 是不含包名的短名称
 
    println("qualifiedName: ${kClass.qualifiedName}")
    // 输出: qualifiedName: com.example.User（取决于你的包名）
    // qualifiedName 是包含完整包路径的全限定名
    // 注意：匿名类和局部类的 qualifiedName 为 null
 
    // ========== 2. 修饰符检查 ==========
    println("isFinal: ${kClass.isFinal}")       // true，Kotlin 类默认 final
    println("isOpen: ${kClass.isOpen}")          // false
    println("isAbstract: ${kClass.isAbstract}")  // false
    println("isSealed: ${kClass.isSealed}")      // false
    println("isData: ${kClass.isData}")          // true，因为是 data class
    println("isInner: ${kClass.isInner}")        // false
    println("isCompanion: ${kClass.isCompanion}")// false，User 本身不是伴生对象
 
    // visibility 返回 KVisibility 枚举
    println("visibility: ${kClass.visibility}")  // PUBLIC
 
    // ========== 3. 构造器 ==========
    // primaryConstructor 获取主构造器
    val primaryCtor = kClass.primaryConstructor
    println("主构造器参数: ${primaryCtor?.parameters?.map { "${it.name}: ${it.type}" }}")
    // 输出: 主构造器参数: [id: kotlin.Long, name: kotlin.String, email: kotlin.String]
 
    // constructors 获取所有构造器（包括主构造器和次构造器）
    println("构造器总数: ${kClass.constructors.size}")
    // 输出: 构造器总数: 2（主构造器 + 次构造器）
 
    // ========== 4. 成员查询 ==========
    // memberProperties 获取类自身声明的属性（不含继承的）
    println("\n--- 成员属性 ---")
    kClass.memberProperties.forEach { prop ->
        // prop 是 KProperty1<User, *> 类型
        println("  ${prop.name}: ${prop.returnType}, 只读=${prop is kotlin.reflect.KMutableProperty1}")
    }
    // 输出:
    //   email: kotlin.String, 只读=false
    //   id: kotlin.Long, 只读=false
    //   name: kotlin.String, 只读=true  (var 属性是 KMutableProperty1)
 
    // memberFunctions 获取成员函数（含继承自 Any 的）
    println("\n--- 成员函数 ---")
    kClass.memberFunctions.forEach { func ->
        println("  ${func.name}(${func.parameters.size} params) -> ${func.returnType}")
    }
    // 会列出 greet, equals, hashCode, toString, copy, component1/2/3 等
 
    // ========== 5. 伴生对象 ==========
    val companion = kClass.companionObject
    println("\n伴生对象类名: ${companion?.simpleName}")
    // 输出: 伴生对象类名: Companion
 
    val companionInstance = kClass.companionObjectInstance
    println("伴生对象实例: $companionInstance")
    // 输出: 伴生对象实例: com.example.User$Companion@xxxx
 
    // ========== 6. 超类型信息 ==========
    println("\n--- 超类型 ---")
    kClass.supertypes.forEach { supertype ->
        println("  $supertype")
    }
    // 输出: kotlin.Any（data class 默认继承 Any）
}

fun describeType(kClass: KClass<*>): String = when (kClass) {
    // 直接用 KClass 实例做匹配
    String::class  -> "这是一个字符串类型"
    Int::class     -> "这是一个整数类型"
    List::class    -> "这是一个列表类型"
    else           -> "未知类型: ${kClass.simpleName}"
}
 
fun main() {
    println(describeType(String::class))  // 这是一个字符串类型
    println(describeType("hello"::class)) // 这是一个字符串类型
    // 无论通过类名还是实例获取，指向同一个类的 KClass 都相等
}

object AppConfig {
    val version = "1.0.0"
    fun printVersion() = println("App v$version")
}
 
fun main() {
    val kClass = AppConfig::class
    // objectInstance 对于 object 声明返回其单例实例
    // 对于普通 class 返回 null
    val instance = kClass.objectInstance
    println(instance === AppConfig) // true，确实是同一个单例
    instance?.printVersion()        // App v1.0.0
}

fun main() {
    val stringClass = String::class
 
    // isInstance 检查一个值是否是该类的实例
    println(stringClass.isInstance("hello"))  // true
    println(stringClass.isInstance(42))       // false
    println(stringClass.isInstance(null))     // false，null 不是任何类的实例
 
    // 这在需要动态类型检查时非常有用
    // 比如实现一个简单的依赖注入容器
    val registry = mutableMapOf<KClass<*>, Any>()
    registry[String::class] = "default"
    registry[Int::class] = 42
 
    // 类型安全的获取
    inline fun <reified T : Any> get(): T? {
        val value = registry[T::class]
        // 用 isInstance 做运行时类型验证
        return if (T::class.isInstance(value)) value as T else null
    }
}

import kotlin.reflect.jvm.javaField
import kotlin.reflect.jvm.javaMethod
import kotlin.reflect.jvm.kotlinFunction
import kotlin.reflect.jvm.kotlinProperty
 
data class Person(val name: String, var age: Int)
 
fun main() {
    // ========== KClass <-> Java Class 互转 ==========
 
    // Kotlin -> Java：使用 .java 属性
    val kClass = Person::class
    val javaClass: Class<Person> = kClass.java
    println("Java Class: ${javaClass.name}")
    // 输出: Java Class: com.example.Person
 
    // Java -> Kotlin：使用 .kotlin 扩展属性
    val backToKClass = javaClass.kotlin
    println("KClass: ${backToKClass.simpleName}")
    // 输出: KClass: Person
 
    // 两者指向同一个类，互转后相等
    println("互转后相等: ${kClass == backToKClass}") // true
 
    // ========== 从实例获取 Java Class ==========
    val person = Person("Alice", 30)
 
    // 方式一：通过 KClass 中转
    val cls1 = person::class.java
 
    // 方式二：直接用 Java 风格（Kotlin 也支持）
    val cls2 = person.javaClass
 
    // 两者结果相同
    println("两种方式相等: ${cls1 == cls2}") // true
 
    // ========== KFunction <-> Method ==========
    val kFunction = Person::greet  // 假设 Person 有 greet 方法
    // 注意：需要 import kotlin.reflect.jvm.javaMethod
    // val javaMethod = kFunction.javaMethod
    // val backToKFunction = javaMethod?.kotlinFunction
 
    // ========== KProperty <-> Field ==========
    val kProperty = Person::name
    // 注意：需要 import kotlin.reflect.jvm.javaField
    val javaField = kProperty.javaField
    println("Java Field name: ${javaField?.name}")  // name
    println("Java Field type: ${javaField?.type}")   // class java.lang.String
    // val backToKProperty = javaField?.kotlinProperty
}

// ========== 差异一：基本类型的处理 ==========
fun main() {
    // Kotlin 的 KClass 对基本类型有统一的抽象
    val intKClass = Int::class
    println("KClass simpleName: ${intKClass.simpleName}")  // Int
 
    // 但转成 Java Class 时，会得到 primitive type
    val intJavaClass = Int::class.java
    println("Java Class: $intJavaClass")          // int
    println("是否基本类型: ${intJavaClass.isPrimitive}") // true
 
    // 如果你需要的是包装类型（Integer），使用 javaPrimitiveType / javaObjectType
    val intPrimitive = Int::class.javaPrimitiveType
    val intWrapper = Int::class.javaObjectType
    println("Primitive: $intPrimitive")  // int
    println("Wrapper: $intWrapper")      // class java.lang.Integer
 
    // 这个区别在与 Java 反射 API 交互时非常重要
    // 比如通过反射查找方法时，参数类型必须精确匹配
 
    // ========== 差异二：属性 vs 字段 ==========
    // Kotlin 的 KProperty 是"属性"的抽象，包含 getter/setter
    // Java 的 Field 是"字段"的抽象，是底层存储
    // 一个 Kotlin val 属性 = 一个 private Java field + 一个 public getter method
    // 一个 Kotlin var 属性 = 一个 private Java field + getter + setter
 
    // ========== 差异三：可空性信息 ==========
    // KClass/KType 保留了 Kotlin 的可空性信息
    // Java Class/Type 没有可空性概念（需要靠注解 @Nullable 等）
    data class Example(val nullable: String?, val nonNull: String)
    val props = Example::class.memberProperties
    props.forEach { p ->
        println("${p.name}: ${p.returnType}, isMarkedNullable=${p.returnType.isMarkedNullable}")
    }
    // 输出:
    // nonNull: kotlin.String, isMarkedNullable=false
    // nullable: kotlin.String?, isMarkedNullable=true
    // Java 反射无法区分这两者
}

import kotlin.reflect.KClass
 
// 模拟一个简化的"服务定位器"模式
// 这在 Android 开发（Koin）和后端开发（Spring）中非常常见
class ServiceLocator {
    // 内部用 Java Class 作为 key（因为很多 Java 库需要 Class 对象）
    private val services = mutableMapOf<Class<*>, Any>()
 
    // 对外暴露 Kotlin 风格的 API，接受 KClass
    fun <T : Any> register(kClass: KClass<T>, instance: T) {
        // 内部转换为 Java Class 存储
        services[kClass.java] = instance
    }
 
    // 使用 reified 泛型让调用更自然
    inline fun <reified T : Any> get(): T? {
        // T::class 获取 KClass，.java 转为 Java Class 用于查找
        return services[T::class.java] as? T
    }
 
    // 也提供接受 Java Class 的重载，方便 Java 代码调用
    fun <T : Any> register(javaClass: Class<T>, instance: T) {
        services[javaClass] = instance
    }
 
    fun <T : Any> get(javaClass: Class<T>): T? {
        return services[javaClass] as? T
    }
}
 
// 使用示例
interface Logger { fun log(msg: String) }
class ConsoleLogger : Logger {
    override fun log(msg: String) = println("[LOG] $msg")
}
 
fun main() {
    val locator = ServiceLocator()
 
    // Kotlin 风格注册
    locator.register(Logger::class, ConsoleLogger())
 
    // Kotlin 风格获取（利用 reified，无需传 class 参数）
    val logger = locator.get<Logger>()
    logger?.log("Service located!") // [LOG] Service located!
 
    // Java 风格获取（在与 Java 代码互操作时使用）
    val logger2 = locator.get(Logger::class.java)
    logger2?.log("Java style!")     // [LOG] Java style!
}

open class Base
class Derived : Base()
 
fun identify(obj: Base) {
    val kClass = obj::class
    println("${kClass.simpleName}, isFinal=${kClass.isFinal}")
}
 
fun main() {
    identify(Derived())
}

// 定义一个普通的数据类
data class User(val name: String, val age: Int)
 
fun main() {
    // 通过 ::class 获取 KClass 实例
    val kClass = User::class
 
    // simpleName: 只返回类名本身，不含包路径
    println(kClass.simpleName)      // 输出: User
 
    // qualifiedName: 返回 "包名.类名" 的完整路径
    println(kClass.qualifiedName)   // 输出: com.example.User（取决于你的包声明）
}

fun main() {
    // 匿名对象没有语言层面的名字
    val anonymous = object : Runnable {
        override fun run() {}
    }
 
    // 匿名对象的 simpleName 和 qualifiedName 均为 null
    println(anonymous::class.simpleName)      // 输出: null
    println(anonymous::class.qualifiedName)   // 输出: null
 
    // 函数内部定义的局部类
    class LocalHelper
 
    // 局部类有 simpleName，但 qualifiedName 为 null
    println(LocalHelper::class.simpleName)      // 输出: LocalHelper
    println(LocalHelper::class.qualifiedName)   // 输出: null
}

fun safeClassName(kClass: KClass<*>): String {
    // 优先使用 qualifiedName，其次 simpleName，最后兜底 "<anonymous>"
    return kClass.qualifiedName
        ?: kClass.simpleName
        ?: "<anonymous>"
}

import kotlin.reflect.full.*  // 需要引入反射扩展库
 
// 定义一个基类
open class Animal(val species: String) {
    // 基类中的一个普通方法
    open fun sound(): String = "..."
}
 
// 子类继承 Animal，并新增自己的属性和方法
class Dog(
    val name: String,       // Dog 自己声明的属性
    val age: Int            // Dog 自己声明的属性
) : Animal("Canine") {
    // Dog 自己声明的方法
    fun fetch(item: String): String = "$name fetches $item"
 
    // 重写父类方法
    override fun sound(): String = "Woof!"
}
 
fun main() {
    val kClass = Dog::class
 
    // --- members: 包含自身 + 继承的所有成员 ---
    println("=== members (全部成员) ===")
    kClass.members.forEach { member ->
        // 打印每个成员的名称和返回类型
        println("  ${member.name} -> ${member.returnType}")
    }
    // 会看到: name, age, fetch, sound, species, equals, hashCode, toString 等
 
    println()
 
    // --- declaredMembers: 仅 Dog 自己声明的成员 ---
    println("=== declaredMembers (仅自身声明) ===")
    kClass.declaredMembers.forEach { member ->
        println("  ${member.name} -> ${member.returnType}")
    }
    // 只会看到: name, age, fetch, sound（因为 sound 被 override 了，算 Dog 声明的）
 
    println()
 
    // --- declaredMemberProperties: 仅 Dog 自己声明的属性 ---
    println("=== declaredMemberProperties ===")
    kClass.declaredMemberProperties.forEach { prop ->
        // 属性有 name 和 returnType
        println("  ${prop.name}: ${prop.returnType}")
    }
    // 输出: name: kotlin.String, age: kotlin.Int
 
    println()
 
    // --- constructors: 所有构造函数 ---
    println("=== constructors ===")
    kClass.constructors.forEach { ctor ->
        // 打印构造函数的参数列表
        val params = ctor.parameters.joinToString { "${it.name}: ${it.type}" }
        println("  constructor($params)")
    }
    // 输出: constructor(name: kotlin.String, age: kotlin.Int)
}

import kotlin.reflect.KMutableProperty1
import kotlin.reflect.full.memberProperties
 
data class Config(
    var host: String = "localhost",  // 可变属性
    var port: Int = 8080,            // 可变属性
    val version: String = "1.0"      // 不可变属性
)
 
fun main() {
    val kClass = Config::class
 
    // 从所有成员属性中，筛选出可变属性（var 声明的）
    val mutableProps = kClass.memberProperties
        .filterIsInstance<KMutableProperty1<Config, *>>()
 
    println("可变属性:")
    mutableProps.forEach { prop ->
        // KMutableProperty1 才有 set 方法
        println("  var ${prop.name}: ${prop.returnType}")
    }
    // 输出: var host: kotlin.String, var port: kotlin.Int
    // version 不会出现，因为它是 val
}

import kotlin.reflect.full.supertypes
import kotlin.reflect.full.superclasses
 
// 定义接口
interface Serializable
interface Loggable {
    fun log(message: String)
}
 
// 抽象基类
abstract class BaseEntity(val id: Long)
 
// 具体类，同时继承基类和两个接口
class Order(
    id: Long,
    val product: String,
    val quantity: Int
) : BaseEntity(id), Serializable, Loggable {
    override fun log(message: String) {
        println("[Order#$id] $message")
    }
}
 
fun main() {
    val kClass = Order::class
 
    // --- supertypes: 返回 List<KType>，包含直接父类和接口 ---
    println("=== supertypes (直接父类型) ===")
    kClass.supertypes.forEach { supertype ->
        // KType 的 toString() 会显示完整的类型信息
        println("  $supertype")
    }
    // 输出:
    //   BaseEntity
    //   Serializable
    //   Loggable
 
    println()
 
    // --- superclasses: 返回 List<KClass<*>>，只包含类（不含接口） ---
    println("=== superclasses ===")
    kClass.superclasses.forEach { superclass ->
        println("  ${superclass.simpleName}")
    }
    // 输出:
    //   BaseEntity
    //   Any（所有 Kotlin 类的隐式父类）
}

import kotlin.reflect.KClass
import kotlin.reflect.full.superclasses
 
/**
 * 递归收集一个类的完整继承链（BFS 广度优先）
 * 返回从当前类到 Any 的所有祖先类
 */
fun KClass<*>.allSuperclasses(): List<KClass<*>> {
    // 用一个可变集合做去重（菱形继承时同一个类可能出现多次）
    val visited = mutableSetOf<KClass<*>>()
    // BFS 队列
    val queue = ArrayDeque<KClass<*>>()
 
    // 将直接父类加入队列
    queue.addAll(this.superclasses)
 
    while (queue.isNotEmpty()) {
        // 取出队首元素
        val current = queue.removeFirst()
        // 如果已经访问过，跳过（处理菱形继承）
        if (current in visited) continue
        // 标记为已访问
        visited.add(current)
        // 将 current 的父类也加入队列
        queue.addAll(current.superclasses)
    }
 
    return visited.toList()
}
 
fun main() {
    // ArrayList 的继承链相当深
    val chain = ArrayList::class.allSuperclasses()
    chain.forEach { println(it.simpleName) }
    // 会看到: AbstractMutableList, MutableList, AbstractMutableCollection, ... Any
}

import kotlin.reflect.KTypeParameter
import kotlin.reflect.KVariance
 
// 一个带有多个类型参数的泛型类
// out V 表示协变，T : Comparable<T> 表示有上界约束
class Repository<K : Any, out V : Comparable<V>>(
    private val store: MutableMap<K, V> = mutableMapOf()
)
 
fun main() {
    val kClass = Repository::class
 
    println("类名: ${kClass.simpleName}")
    println("类型参数数量: ${kClass.typeParameters.size}")
    println()
 
    kClass.typeParameters.forEachIndexed { index, param: KTypeParameter ->
        println("--- 类型参数 #$index ---")
 
        // name: 类型参数的名称
        println("  名称: ${param.name}")
 
        // variance: 声明处型变
        val varianceStr = when (param.variance) {
            KVariance.INVARIANT -> "不变 (invariant)"   // 既不是 in 也不是 out
            KVariance.IN        -> "逆变 (in)"          // 消费者
            KVariance.OUT       -> "协变 (out)"         // 生产者
        }
        println("  型变: $varianceStr")
 
        // upperBounds: 上界约束列表
        println("  上界约束:")
        param.upperBounds.forEach { bound ->
            println("    $bound")
        }
        println()
    }
}

import kotlin.reflect.full.memberProperties
import kotlin.reflect.full.createType
import kotlin.reflect.jvm.jvmErasure
 
// 一个持有泛型属性的类
class Container {
    // 这个属性的类型是 List<String>，泛型参数在编译时被记录到元数据中
    val items: List<String> = listOf("a", "b", "c")
 
    // Map<String, Int> 有两个类型参数
    val mapping: Map<String, Int> = mapOf("x" to 1)
}
 
fun main() {
    val kClass = Container::class
 
    kClass.memberProperties.forEach { prop ->
        println("属性: ${prop.name}")
 
        // prop.returnType 是 KType，包含完整的泛型信息
        val returnType = prop.returnType
        println("  返回类型: $returnType")
 
        // jvmErasure: 擦除后的原始类型
        println("  擦除类型: ${returnType.jvmErasure.simpleName}")
 
        // arguments: 类型参数列表，每个元素是 KTypeProjection
        if (returnType.arguments.isNotEmpty()) {
            println("  类型参数:")
            returnType.arguments.forEachIndexed { i, projection ->
                // projection.type 可能为 null（星号投影 * 时）
                val typeStr = projection.type?.toString() ?: "*"
                // projection.variance 表示使用处型变（null 表示 * 投影）
                val varianceStr = projection.variance?.name ?: "STAR"
                println("    [$i] $typeStr ($varianceStr)")
            }
        }
        println()
    }
}

import kotlin.reflect.full.*
 
// 密封类
sealed class Shape {
    data class Circle(val radius: Double) : Shape()
    data class Rectangle(val w: Double, val h: Double) : Shape()
}
 
// 抽象类
abstract class Engine
 
// 伴生对象示例
class MyService {
    companion object Factory {
        fun create(): MyService = MyService()
    }
}
 
fun main() {
    // --- isAbstract: 是否是抽象类 ---
    println("Engine isAbstract: ${Engine::class.isAbstract}")           // true
    println("Shape isAbstract: ${Shape::class.isAbstract}")             // true（sealed 也是 abstract）
    println("Shape.Circle isAbstract: ${Shape.Circle::class.isAbstract}") // false
 
    // --- isSealed: 是否是密封类 ---
    println("Shape isSealed: ${Shape::class.isSealed}")                 // true
 
    // --- sealedSubclasses: 密封类的所有直接子类 ---
    println("Shape 的子类:")
    Shape::class.sealedSubclasses.forEach {
        println("  ${it.simpleName}")
    }
    // 输出: Circle, Rectangle
 
    // --- isData: 是否是 data class ---
    println("Circle isData: ${Shape.Circle::class.isData}")             // true
 
    // --- isCompanion: 是否是伴生对象 ---
    println("Factory isCompanion: ${MyService.Factory::class.isCompanion}") // true
 
    // --- companionObject: 获取伴生对象的 KClass ---
    val companion = MyService::class.companionObject
    println("MyService 的伴生对象: ${companion?.simpleName}")            // Factory
 
    // --- companionObjectInstance: 获取伴生对象的实例 ---
    val instance = MyService::class.companionObjectInstance
    println("伴生对象实例: $instance")
 
    // --- isOpen / isFinal ---
    println("Shape isOpen: ${Shape::class.isOpen}")                     // false（sealed 不是 open）
    println("Shape isFinal: ${Shape::class.isFinal}")                   // false（sealed 也不是 final）
 
    // --- visibility: 可见性修饰符 ---
    println("MyService visibility: ${MyService::class.visibility}")     // PUBLIC
 
    // --- objectInstance: 获取 object 单例的实例 ---
    // 对于 object 声明（单例），这个属性返回唯一实例；对于普通类返回 null
    object AppConfig {
        val debug = true
    }
    // 注意：局部 object 无法通过 ::class.objectInstance 获取
}

import kotlin.reflect.KClass
import kotlin.reflect.KVisibility
import kotlin.reflect.full.*
 
/**
 * 打印一个 KClass 的完整类型信息报告
 * 包括：名称、修饰符、类型参数、继承关系、成员列表
 */
fun <T : Any> printClassReport(kClass: KClass<T>) {
    // ========== 1. 基本名称信息 ==========
    println("╔══════════════════════════════════════")
    println("║ 类名: ${kClass.simpleName ?: "<anonymous>"}")
    println("║ 全限定名: ${kClass.qualifiedName ?: "<none>"}")
 
    // ========== 2. 修饰符信息 ==========
    val modifiers = buildList {
        if (kClass.isAbstract) add("abstract")       // 是否抽象
        if (kClass.isSealed) add("sealed")           // 是否密封
        if (kClass.isData) add("data")               // 是否数据类
        if (kClass.isOpen) add("open")               // 是否可继承
        if (kClass.isFinal) add("final")             // 是否最终类
        if (kClass.isCompanion) add("companion")     // 是否伴生对象
        if (kClass.isInner) add("inner")             // 是否内部类
        if (kClass.isFun) add("fun")                 // 是否函数式接口
        if (kClass.isValue) add("value")             // 是否值类
    }
    println("║ 修饰符: ${modifiers.joinToString(", ").ifEmpty { "none" }}")
    println("║ 可见性: ${kClass.visibility ?: "unknown"}")
 
    // ========== 3. 类型参数 ==========
    if (kClass.typeParameters.isNotEmpty()) {
        println("║ 类型参数:")
        kClass.typeParameters.forEach { tp ->
            // 显示名称、型变、上界
            val bounds = tp.upperBounds.joinToString(" & ")
            println("║   ${tp.variance.name} ${tp.name} : $bounds")
        }
    }
 
    // ========== 4. 继承关系 ==========
    println("║ 直接父类型:")
    kClass.supertypes.forEach { st ->
        println("║   $st")
    }
 
    // ========== 5. 构造函数 ==========
    println("║ 构造函数 (${kClass.constructors.size} 个):")
    kClass.constructors.forEach { ctor ->
        val params = ctor.parameters.joinToString(", ") {
            // 显示参数名、类型、是否可选
            val optional = if (it.isOptional) " = ..." else ""
            "${it.name}: ${it.type}$optional"
        }
        println("║   constructor($params)")
    }
 
    // ========== 6. 声明的属性 ==========
    println("║ 声明的属性 (${kClass.declaredMemberProperties.size} 个):")
    kClass.declaredMemberProperties.forEach { prop ->
        // 判断是 val 还是 var
        val mutability = if (prop is kotlin.reflect.KMutableProperty<*>) "var" else "val"
        val vis = prop.visibility?.name?.lowercase() ?: ""
        println("║   $vis $mutability ${prop.name}: ${prop.returnType}")
    }
 
    // ========== 7. 声明的函数 ==========
    println("║ 声明的函数 (${kClass.declaredFunctions.size} 个):")
    kClass.declaredFunctions.forEach { func ->
        val params = func.parameters
            .drop(1) // 第一个参数是 receiver（this），跳过
            .joinToString(", ") { "${it.name}: ${it.type}" }
        println("║   fun ${func.name}($params): ${func.returnType}")
    }
 
    println("╚══════════════════════════════════════")
}
 
// ---------- 测试用的类 ----------
interface Printable {
    fun prettyPrint(): String
}
 
data class Book(
    val title: String,
    val author: String,
    val year: Int = 2024
) : Printable {
    var rating: Double = 0.0
 
    override fun prettyPrint(): String = "\"$title\" by $author ($year)"
 
    fun isClassic(): Boolean = year < 2000
}
 
fun main() {
    // 对 Book 类执行完整的反射报告
    printClassReport(Book::class)
}

import kotlin.reflect.full.declaredMemberProperties
import kotlin.reflect.full.memberProperties
 
open class Parent {
    val x: Int = 1
    val y: String = "hello"
}
 
class Child : Parent() {
    val z: Double = 3.14
}
 
fun main() {
    val declared = Child::class.declaredMemberProperties.map { it.name }.sorted()
    val all = Child::class.memberProperties.map { it.name }.sorted()
    println("declared=$declared, all=$all")
}

// 定义一个普通的顶层函数
fun greet(name: String): String {
    return "Hello, $name!"
}
 
fun main() {
    // 使用 :: 获取函数引用，得到 KFunction1<String, String> 类型
    val funcRef = ::greet
 
    // funcRef 现在是一个对象，可以赋值、传递、存储
    println(funcRef)           // 输出: fun greet(kotlin.String): kotlin.String
    println(funcRef("World"))  // 像普通函数一样调用，输出: Hello, World!
}

fun square(x: Int): Int = x * x
 
fun main() {
    val ref = ::square
 
    // 作为反射对象使用 —— 获取元数据
    println(ref.name)        // 输出: square
    println(ref.returnType)  // 输出: kotlin.Int
 
    // 作为函数类型使用 —— 传入高阶函数
    val results = listOf(1, 2, 3, 4).map(ref)
    println(results)         // 输出: [1, 4, 9, 16]
}

class Calculator {
    // 成员函数
    fun add(a: Int, b: Int): Int = a + b
}
 
fun String.exclaim(): String = "$this!"  // 扩展函数
 
fun main() {
    // ① 成员函数引用：第一个参数是接收者实例
    val addRef = Calculator::add
    val calc = Calculator()
    // 成员函数引用调用时，第一个参数必须传入实例对象
    println(addRef.call(calc, 3, 5))  // 输出: 8
 
    // ② 绑定成员函数引用：已绑定特定实例，无需再传接收者
    val boundAddRef = calc::add
    println(boundAddRef.call(10, 20)) // 输出: 30
 
    // ③ 扩展函数引用：与成员函数类似，第一个参数是接收者
    val exclaimRef = String::exclaim
    println(exclaimRef.call("Kotlin")) // 输出: Kotlin!
 
    // ④ 构造函数引用：使用 ::ClassName 语法
    val ctorRef = ::Calculator
    val newCalc = ctorRef.call()       // 创建新实例
    println(newCalc)                   // 输出: Calculator@xxxx
}

import kotlin.reflect.full.* // 引入反射扩展
import kotlin.reflect.KParameter
 
// 定义一个参数丰富的函数，用于演示参数元数据
fun sendMessage(
    to: String,                    // 必选参数
    message: String,               // 必选参数
    priority: Int = 0,             // 可选参数，有默认值
    encrypted: Boolean = false     // 可选参数，有默认值
): String {
    return "[$priority] To $to: $message (encrypted=$encrypted)"
}
 
fun main() {
    // 获取函数引用
    val func = ::sendMessage
 
    // 遍历所有参数，打印详细元数据
    func.parameters.forEach { param ->
        println("────────────────────────")
        println("索引 (index):      ${param.index}")       // 参数在列表中的位置
        println("名称 (name):       ${param.name}")        // 参数名称
        println("类型 (type):       ${param.type}")        // 参数的 KType
        println("种类 (kind):       ${param.kind}")        // INSTANCE / EXTENSION_RECEIVER / VALUE
        println("可选 (isOptional): ${param.isOptional}")  // 是否有默认值
    }
}

import kotlin.reflect.KParameter
 
// 演示三种 KParameter.Kind
class Host {
    // 成员扩展函数：同时拥有 INSTANCE 和 EXTENSION_RECEIVER
    fun String.memberExtension(suffix: String): String {
        return "$this@Host: $this$suffix"
    }
}
 
fun main() {
    // 获取成员扩展函数的引用
    val func = Host::class.memberExtensionFunctions.first { it.name == "memberExtension" }
 
    func.parameters.forEach { param ->
        // kind 可能是:
        //   INSTANCE           -> 类实例 (this@Host)
        //   EXTENSION_RECEIVER -> 扩展接收者 (this: String)
        //   VALUE              -> 普通值参数 (suffix)
        println("${param.kind} -> name=${param.name}, type=${param.type}")
    }
}

fun process(items: List<String?>, count: Int?): Map<String, Int> {
    return emptyMap()
}
 
fun main() {
    val func = ::process
 
    func.parameters.forEach { param ->
        val type = param.type
        println("参数: ${param.name}")
        println("  类型: $type")                              // 完整类型字符串
        println("  分类器 (classifier): ${type.classifier}")  // 基础类型 KClass
        println("  可空 (isMarkedNullable): ${type.isMarkedNullable}") // 是否标记为可空
        println("  泛型参数 (arguments): ${type.arguments}")  // 泛型类型参数列表
        println()
    }
 
    // 返回类型同样可以获取
    println("返回类型: ${func.returnType}")
    println("返回类型泛型参数: ${func.returnType.arguments}")
}

import kotlin.reflect.full.functions
 
class MathUtils {
    fun multiply(a: Int, b: Int): Int = a * b
    fun divide(a: Double, b: Double): Double = a / b
}
 
fun main() {
    val utils = MathUtils()
    val kClass = utils::class
 
    // 通过名称查找函数
    val multiplyFunc = kClass.functions.first { it.name == "multiply" }
    val divideFunc = kClass.functions.first { it.name == "divide" }
 
    // 使用 call 动态调用
    // 注意：成员函数的第一个参数必须是实例对象
    val product = multiplyFunc.call(utils, 6, 7)
    println("6 × 7 = $product")  // 输出: 6 × 7 = 42
 
    val quotient = divideFunc.call(utils, 22.0, 7.0)
    println("22 ÷ 7 = $quotient") // 输出: 22 ÷ 7 = 3.142857142857143
}

fun add(a: Int, b: Int): Int = a + b
 
fun main() {
    val func = ::add
 
    // ✅ 正确调用
    println(func.call(3, 4))  // 输出: 7
 
    // ❌ 参数数量不对 —— 抛出 IllegalArgumentException
    try {
        func.call(3)
    } catch (e: IllegalArgumentException) {
        println("参数数量错误: ${e.message}")
    }
 
    // ❌ 参数类型不对 —— 抛出 IllegalArgumentException
    try {
        func.call("3", "4")  // 传入 String 而非 Int
    } catch (e: IllegalArgumentException) {
        println("参数类型错误: ${e.message}")
    }
}

fun greet(name: String, greeting: String = "Hello"): String {
    return "$greeting, $name!"
}
 
fun main() {
    val func = ::greet
 
    // ✅ 传入所有参数
    println(func.call("Alice", "Hi"))  // 输出: Hi, Alice!
 
    // ❌ 尝试省略默认参数 —— 抛出异常
    try {
        func.call("Alice")  // 少了 greeting 参数
    } catch (e: IllegalArgumentException) {
        println("call 不支持默认参数: ${e.message}")
    }
}

import kotlin.reflect.KParameter
 
// 一个参数较多、部分有默认值的函数
fun createUser(
    name: String,
    age: Int,
    email: String = "unknown@example.com",
    role: String = "user",
    active: Boolean = true
): String {
    return "User(name=$name, age=$age, email=$email, role=$role, active=$active)"
}
 
fun main() {
    val func = ::createUser
 
    // 构建参数 Map：只传必选参数 + 想覆盖的可选参数
    val params = func.parameters  // 获取参数列表
 
    val argsMap = mutableMapOf<KParameter, Any?>()
 
    // 遍历参数，按名称填充值
    for (param in params) {
        when (param.name) {
            "name"  -> argsMap[param] = "Alice"
            "age"   -> argsMap[param] = 30
            "role"  -> argsMap[param] = "admin"
            // email 和 active 不传，使用默认值
        }
    }
 
    // 使用 callBy 调用，省略的可选参数自动使用默认值
    val result = func.callBy(argsMap)
    println(result)
    // 输出: User(name=Alice, age=30, email=unknown@example.com, role=admin, active=true)
}

import kotlin.reflect.KFunction
import kotlin.reflect.KParameter
import kotlin.reflect.full.primaryConstructor
 
// ── 模拟的服务类 ──
class Logger {
    fun log(msg: String) = println("[LOG] $msg")
}
 
class Database(val connectionString: String = "jdbc:default://localhost") {
    fun query(sql: String) = "Result of: $sql"
}
 
class UserService(
    val logger: Logger,           // 必选依赖
    val database: Database,       // 必选依赖
    val maxRetries: Int = 3       // 可选配置，有默认值
) {
    fun findUser(id: Int): String {
        logger.log("Finding user $id")
        return database.query("SELECT * FROM users WHERE id = $id")
    }
}
 
// ── 简易 DI 容器 ──
class SimpleContainer {
    // 存储已注册的实例，key 是 KClass
    private val registry = mutableMapOf<kotlin.reflect.KClass<*>, Any>()
 
    // 注册实例
    fun <T : Any> register(instance: T) {
        registry[instance::class] = instance
    }
 
    // 通过反射自动创建实例
    inline fun <reified T : Any> resolve(): T {
        val kClass = T::class
        val constructor = kClass.primaryConstructor
            ?: throw IllegalArgumentException("${kClass.simpleName} 没有主构造函数")
 
        // 构建 callBy 所需的参数 Map
        val argsMap = mutableMapOf<KParameter, Any?>()
 
        for (param in constructor.parameters) {
            // 在注册表中查找匹配类型的实例
            val resolved = registry.entries.find { (key, _) ->
                // classifier 是参数类型对应的 KClass
                key == param.type.classifier
            }?.value
 
            if (resolved != null) {
                // 找到了依赖，放入 Map
                argsMap[param] = resolved
            } else if (!param.isOptional) {
                // 必选参数找不到依赖，抛出异常
                throw IllegalArgumentException(
                    "无法解析参数: ${param.name}: ${param.type}"
                )
            }
            // 可选参数找不到依赖时，不放入 Map，callBy 会使用默认值
        }
 
        // 使用 callBy 调用构造函数，可选参数自动使用默认值
        return constructor.callBy(argsMap) as T
    }
}
 
fun main() {
    val container = SimpleContainer()
 
    // 注册基础依赖
    container.register(Logger())
    container.register(Database("jdbc:mysql://prod-server:3306/mydb"))
 
    // 自动解析并创建 UserService
    // maxRetries 没有注册，但它是可选参数，callBy 会使用默认值 3
    val userService = container.resolve<UserService>()
 
    // 验证注入成功
    println(userService.findUser(42))
    println("maxRetries = ${userService.maxRetries}")  // 输出: maxRetries = 3
}

fun format(
    text: String,
    uppercase: Boolean = false,
    trim: Boolean = true,
    maxLength: Int = 100
): String {
    var result = text
    if (trim) result = result.trim()                    // 根据 trim 参数决定是否去除空白
    if (uppercase) result = result.uppercase()          // 根据 uppercase 参数决定是否转大写
    if (result.length > maxLength) {                    // 超过最大长度则截断
        result = result.take(maxLength) + "..."
    }
    return result
}
 
fun main() {
    val func = ::format
 
    // ── 使用 call：必须传入全部 4 个参数 ──
    val r1 = func.call("  hello world  ", true, true, 50)
    println(r1)  // 输出: HELLO WORLD
 
    // ── 使用 callBy：只传需要的参数，其余用默认值 ──
    val textParam = func.parameters.first { it.name == "text" }
    val uppercaseParam = func.parameters.first { it.name == "uppercase" }
 
    val r2 = func.callBy(mapOf(
        textParam to "  hello world  ",
        uppercaseParam to true
        // trim 默认 true，maxLength 默认 100
    ))
    println(r2)  // 输出: HELLO WORLD
}

import kotlin.reflect.full.primaryConstructor
import kotlin.reflect.full.valueParameters
 
data class Point(val x: Double, val y: Double) {
    // 次构造函数
    constructor(xy: Double) : this(xy, xy)
}
 
fun main() {
    val kClass = Point::class
 
    // 获取主构造函数
    val primary = kClass.primaryConstructor!!
    println("主构造函数参数:")
    primary.valueParameters.forEach { p ->
        // valueParameters 只包含 VALUE 类型的参数，排除了 INSTANCE 等
        println("  ${p.name}: ${p.type}")
    }
 
    // 获取所有构造函数
    println("\n所有构造函数 (共 ${kClass.constructors.size} 个):")
    kClass.constructors.forEach { ctor ->
        val paramStr = ctor.parameters.joinToString(", ") { "${it.name}: ${it.type}" }
        println("  Point($paramStr)")
    }
 
    // 通过反射调用构造函数创建实例
    val p1 = primary.call(3.0, 4.0)
    println("\np1 = $p1")  // 输出: p1 = Point(x=3.0, y=4.0)
 
    // 使用 :: 语法获取构造函数引用
    val ctorRef = ::Point
    val p2 = ctorRef(5.0, 6.0)  // 像普通函数一样调用
    println("p2 = $p2")          // 输出: p2 = Point(x=5.0, y=6.0)
}

import kotlin.reflect.full.functions
import kotlin.reflect.jvm.isAccessible
 
class Demo {
    // 各种修饰符的函数
    inline fun inlineFunc(block: () -> Unit) = block()
    operator fun plus(other: Demo): Demo = this
    infix fun combine(other: Demo): Demo = this
    suspend fun asyncWork(): String = "done"
    external fun nativeCall()
    private fun secret(): String = "hidden"
}
 
fun main() {
    val kClass = Demo::class
 
    kClass.functions.forEach { func ->
        // 跳过从 Any 继承的函数
        if (func.name in listOf("equals", "hashCode", "toString")) return@forEach
 
        println("函数: ${func.name}")
        println("  isInline:    ${func.isInline}")    // 是否是 inline 函数
        println("  isOperator:  ${func.isOperator}")  // 是否是 operator 函数
        println("  isInfix:     ${func.isInfix}")     // 是否是 infix 函数
        println("  isSuspend:   ${func.isSuspend}")   // 是否是 suspend 函数
        println("  isExternal:  ${func.isExternal}")  // 是否是 external 函数
        println("  isAbstract:  ${func.isAbstract}")  // 是否是抽象函数
        println("  isFinal:     ${func.isFinal}")     // 是否是 final 函数
        println("  isOpen:      ${func.isOpen}")      // 是否是 open 函数
        println("  visibility:  ${func.visibility}")  // 可见性: PUBLIC, PRIVATE, etc.
        println()
    }
}

import kotlin.reflect.KFunction
import kotlin.reflect.full.declaredFunctions
import kotlin.reflect.full.findAnnotation
import kotlin.reflect.full.valueParameters
 
// 自定义注解，标记可被分发的命令
@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class Command(
    val name: String,           // 命令名称
    val description: String     // 命令描述
)
 
// 命令处理器类
class CommandHandler {
 
    @Command("hello", "向用户打招呼")
    fun hello(name: String, greeting: String = "你好"): String {
        return "$greeting, $name!"
    }
 
    @Command("add", "计算两个数的和")
    fun add(a: Int, b: Int): String {
        return "$a + $b = ${a + b}"
    }
 
    @Command("repeat", "重复输出文本")
    fun repeat(text: String, times: Int = 3, separator: String = " "): String {
        // 将文本重复指定次数，用分隔符连接
        return List(times) { text }.joinToString(separator)
    }
}
 
// 命令分发器：通过反射自动发现和调用命令
class CommandDispatcher(private val handler: Any) {
 
    // 缓存：命令名 -> KFunction 映射
    private val commands: Map<String, KFunction<*```kotlin
>> = handler::class.declaredFunctions
        .filter { it.findAnnotation<Command>() != null }  // 只保留有 @Command 注解的函数
        .associateBy { it.findAnnotation<Command>()!!.name } // 以命令名为 key 建立映射
 
    // 列出所有可用命令
    fun listCommands() {
        println("可用命令:")
        commands.forEach { (name, func) ->
            val cmd = func.findAnnotation<Command>()!!
            val paramStr = func.valueParameters.joinToString(", ") { p ->
                // 构建参数签名字符串，可选参数加上 "?" 标记
                val optional = if (p.isOptional) " (可选)" else ""
                "${p.name}: ${p.type}$optional"
            }
            println("  /$name($paramStr) — ${cmd.description}")
        }
    }
 
    // 分发并执行命令
    fun dispatch(commandName: String, args: Map<String, Any?>): Any? {
        // 查找命令对应的函数
        val func = commands[commandName]
            ?: throw IllegalArgumentException("未知命令: /$commandName")
 
        // 构建 callBy 所需的参数 Map
        val argsMap = mutableMapOf<kotlin.reflect.KParameter, Any?>()
 
        for (param in func.parameters) {
            when (param.kind) {
                // INSTANCE 参数：传入 handler 实例
                kotlin.reflect.KParameter.Kind.INSTANCE -> {
                    argsMap[param] = handler
                }
                // VALUE 参数：从用户传入的 args 中查找
                kotlin.reflect.KParameter.Kind.VALUE -> {
                    val value = args[param.name]
                    if (value != null) {
                        // 用户提供了该参数的值
                        argsMap[param] = value
                    } else if (!param.isOptional) {
                        // 必选参数缺失，抛出友好的错误信息
                        throw IllegalArgumentException(
                            "命令 /$commandName 缺少必选参数: ${param.name} (${param.type})"
                        )
                    }
                    // 可选参数未提供时不放入 Map，callBy 自动使用默认值
                }
                else -> { /* EXTENSION_RECEIVER 等情况此处忽略 */ }
            }
        }
 
        // 使用 callBy 执行函数，自动处理默认参数
        return func.callBy(argsMap)
    }
}
 
fun main() {
    val handler = CommandHandler()
    val dispatcher = CommandDispatcher(handler)
 
    // 列出所有命令
    dispatcher.listCommands()
    println()
 
    // 调用 /hello 命令，省略可选参数 greeting
    val r1 = dispatcher.dispatch("hello", mapOf("name" to "Kotlin"))
    println("/hello -> $r1")  // 输出: /hello -> 你好, Kotlin!
 
    // 调用 /hello 命令，覆盖默认的 greeting
    val r2 = dispatcher.dispatch("hello", mapOf("name" to "World", "greeting" to "Hey"))
    println("/hello -> $r2")  // 输出: /hello -> Hey, World!
 
    // 调用 /add 命令
    val r3 = dispatcher.dispatch("add", mapOf("a" to 17, "b" to 25))
    println("/add -> $r3")    // 输出: /add -> 17 + 25 = 42
 
    // 调用 /repeat 命令，只传必选参数
    val r4 = dispatcher.dispatch("repeat", mapOf("text" to "Kotlin"))
    println("/repeat -> $r4") // 输出: /repeat -> Kotlin Kotlin Kotlin
 
    // 调用 /repeat 命令，覆盖部分可选参数
    val r5 = dispatcher.dispatch("repeat", mapOf(
        "text" to "Go",
        "times" to 5,
        "separator" to "-"
    ))
    println("/repeat -> $r5") // 输出: /repeat -> Go-Go-Go-Go-Go
}