仓颉语言 std.reflect 反射包核心类 API 完全指南:ClassTypeInfo、TypeInfo 家族与成员信息模型实战

原创2026-10-14 09:58:201,445 阅读
文章标签:编程语言语言运行时标准库内存管理OpenHarmony

仓颉语言 std.reflect 反射包核心类 API 完全指南:ClassTypeInfo、TypeInfo 家族与成员信息模型实战

本文以仓库文档 reflect_package_classes.md 为主体,系统讲解仓颉(Cangjie)标准库 std.reflect 反射包中 21 个核心类的定义、属性、方法、异常约定与可运行示例,并结合 type_info_cjnative.cj 等源码剖析其实现原理。读完本文,你将掌握如何在运行时通过类型信息(TypeInfo)获取类、结构体、接口、枚举、函数、元组等类型的元数据,完成构造器匹配、函数/属性/变量读写、泛型调用、包动态加载等实战操作,并理解反射的可见性边界与平台限制。

一、std.reflect 包概览:反射能力与核心模型

std.reflect 包为仓颉程序提供反射能力,使程序能够在运行时获取各种实例的类型信息,并执行读、写、调用等操作。根据 reflect_package_overview.md 的说明,该包当前不支持 macOS 平台(部分 API 亦不支持 iOS)。

反射能力有三条核心边界:

  • 全局信息反射:只能访问全局可见的 public 变量和函数;对于当前包,可以反射访问所有全局定义的类型,而对于外部导入的包或动态加载的模块,只能访问其中 public 可见性的全局类型。
  • 成员信息反射:类型内只有 public 可见性的成员(实例/静态成员变量、属性、函数)可以被反射访问,非 public 修饰符或默认修饰符的成员不可见。
  • 类型覆盖范围:TypeInfo.of(Any) 通用入口目前不支持函数类型、元组类型和枚举类型的运行时类型(这些类型有各自专用的 of 重载)。

TypeInfo 家族:统一的类型信息抽象

整个反射包以 sealed abstract class TypeInfo 为根。它提供所有数据类型的通用操作接口,开发者通常无需向下转型到 ClassTypeInfo 等具体子类即可完成大部分反射操作。其直接子类包括:

子类 描述对象
PrimitiveTypeInfo 基本数据类型(Nothing、Unit、Rune、Bool、各整数/浮点类型)
StructTypeInfo struct 数据类型
ClassTypeInfo class 数据类型
InterfaceTypeInfo interface 数据类型

在仓库源码 type_info_cjnative.cj 中可以看到,TypeInfo 内部持有一个指向类型元数据的指针 _info: CPointer<Unit>,并对实例函数、静态函数、属性、注解、父接口、修饰符等元数据做了惰性缓存(Option<Collection<...>> 字段),通过 getOrCreate 统一创建与缓存 TypeInfo 实例,说明反射元数据是按需解析并缓存的。

二、类型信息获取入口:get / of 三态模型

除 GenericTypeInfo、ParameterInfo 外,绝大多数类型信息类都提供三种静态获取方式,以 ClassTypeInfo 为例:

public redef static func get(qualifiedName: String): ClassTypeInfo     // 按限定名查找
public redef static func of(a: Any): ClassTypeInfo                     // 按实例运行时类型
public redef static func of<T>(): ClassTypeInfo                        // 按编译期类型参数

2.1 get(String):按限定名查找

get 通过类型的限定名(qualified name)查找类型信息。限定名格式为:(module_name/)?(default|package_name)(.package_name)*.(type_name)。例如 default.Rectangular 表示无模块名、包名为 default 的类型 Rectangular。

失败时抛出:

  • InfoNotFoundException:找不到与限定名匹配的类型信息;
  • IllegalTypeException:找到的类型信息不是本类所描述的类型。
import std.reflect.*

public class Rectangular {}

main(): Unit {
    let ty = ClassTypeInfo.get("default.Rectangular")
    println(ty)   // 输出:default.Rectangular
    return
}

2.2 of(Any):按实例运行时类型

of(a: Any) 获取实例 a 的运行时类型信息。运行时类型由程序执行期间的动态绑定决定,绑定在实例对象上;在继承场景下,运行时类型可能与静态类型不同。失败时抛出 InfoNotFoundException、IllegalTypeException。

package test
import std.reflect.*

public class Rectangular {}

main(): Unit {
    var r = Rectangular()
    let ty = ClassTypeInfo.of(r)
    println(ty)   // 输出:test.Rectangular
    return
}

2.3 of():按类型参数

of<T>() 直接获取类型 T 的信息。T 支持类型别名(包括内置别名如 Int、UInt、Rune 以及用户自定义别名)。

import std.reflect.*

public class Rectangular {}

main(): Unit {
    let ty = ClassTypeInfo.of<Rectangular>()
    println(ty)   // 输出:default.Rectangular
    return
}

注意:TypeInfo.of(Any) 目前不支持函数类型、元组类型、枚举类型的运行时类型。当传入参数运行时类型为 class 类型时,调用会解析到 TypeInfo 上即将废弃的 static func of(Object) 重载,返回 ClassTypeInfo 且不抛异常;当必须强制类型种类时,应使用 of<T>()。

三、TypeInfo:所有类型的通用反射接口

TypeInfo 是所有类型信息的公共父类,源码位于 type_info_cjnative.cj。

3.1 基础属性:name 与 qualifiedName

  • public prop name: String:类型名,不含模块和包前缀。注意:
    • 类型别名的类型信息本质上是其底层真实类型的信息,因此返回的是真实类型名。例如类型别名 Byte 的 name 是 UInt8 而非 Byte;
    • 对可见性低于 public 的类型,name 是编译器生成的内部名,既不可读也不稳定。
  • public prop qualifiedName: String:限定名,包含模块和包名前缀。注意:
    • 内置仓颉数据类型及 std 模块 core 包下所有类型的限定名不带任何模块/包名前缀;
    • 无显式模块/包名上下文中定义的类型,限定名带 default 前缀(如 default.MyType);
    • 可见性低于 public 的类型的限定名是编译器生成的内部名(如 default._CN7defaultU0000003a6imS13MyTypeE),不符合上述格式;这类类型只能通过实例或内部名获取,用可读的 package.Type 调用 get(String) 会抛 InfoNotFoundException。

3.2 成员信息集合属性

属性 类型 功能与注意事项
instanceFunctions Collection<InstanceFunctionInfo> 所有 public 实例成员函数信息;无则返回空集合;遍历顺序不保证;对 struct/class 不包含继承的实例成员函数
instanceProperties Collection<InstancePropertyInfo> 所有 public 实例成员属性信息;规则同 instanceFunctions
staticFunctions Collection<StaticFunctionInfo> 所有 public 静态成员函数信息;对 struct/class/interface 不包含继承的静态成员函数
staticProperties Collection<StaticPropertyInfo> 所有 public 静态成员属性信息;规则同 staticFunctions
superInterfaces Collection<InterfaceTypeInfo> 直接实现的全部接口类型信息;所有类型默认隐式实现 Any 接口;当前 struct 类型仅支持获取 Any 接口类型
modifiers Collection<ModifierInfo> 类型全部修饰符信息;interface 类型天然具有 open 语义,集合始终含 open 修饰符;反射只针对 public 类型,故所有访问控制修饰符被忽略
annotations Collection<Annotation> 类型上的全部注解;无注解返回空集合;顺序不保证

3.3 按名称查找成员

TypeInfo 提供 6 个按名称精确查找成员的方法,均以 InfoNotFoundException 表示未匹配到对应 public 成员:

public func getInstanceFunction(name: String, parameterTypes: Array<TypeInfo>): InstanceFunctionInfo
public func getInstanceFunctions(name: String): Array<InstanceFunctionInfo>
public func getInstanceProperty(name: String): InstancePropertyInfo
public func getStaticFunction(name: String, parameterTypes: Array<TypeInfo>): StaticFunctionInfo
public func getStaticFunctions(name: String): Array<StaticFunctionInfo>
public func getStaticProperty(name: String): StaticPropertyInfo

带 parameterTypes 的重载用于精确匹配重载函数;不带参数类型列表的 getXxxFunctions(name) 返回所有同名成员(含全部重载)。例如:

import std.reflect.*

public class Rectangular {
    public var length = 4
    public var width = 5
    public func area(): Int64 {
        return length * width
    }
}

main(): Unit {
    let ty = TypeInfo.get("default.Rectangular")
    var gif = ty.getInstanceFunction("area")   // 精确获取
    println(gif)                               // 输出:func area(): Int64
    var gifs = ty.getInstanceFunctions("area") // 获取全部同名函数
    println(gifs)                              // 输出:[func area(): Int64]
    return
}

3.4 类型关系与工具方法

  • public func isSubtypeOf(supertype: TypeInfo): Bool:判断当前类型信息所表示的类型是否为参数 supertype 所表示类型的子类型。示例中 class Square <: Rectangular,则 Square 的类型信息调用 isSubtypeOf(Rectangular 的类型信息) 返回 true。
  • public func hashCode(): Int64:类型信息哈希值,内部实现使用类型限定名字符串的哈希码。
  • public func toString(): String:类型信息的字符串形式,内部实现返回该类型信息的限定名字符串。
  • public operator func ==(that: TypeInfo): Bool / !=:比较两个类型信息是否相等,内部实现比较限定名是否相等。
  • 注解查询三方法:findAnnotation<T>()(返回 ?T,重复注解或未匹配返回 None)、findAllAnnotations<T>()(返回 Array<T>)、getAllAnnotations()(返回 Array<Annotation>)。

源码佐证:TypeInfo.get(String) 在 type_info_cjnative.cj 中会将 :: 替换为 /,无 . 的类型名自动加上 std.core. 前缀(如 Int64 → std.core.Int64),再通过运行时 getTypeTemplate 获取类型模板指针——这解释了为何内置类型限定名无包前缀。

四、ClassTypeInfo:类类型信息

public class ClassTypeInfo <: TypeInfo,描述 class 类型信息。

4.1 集合属性

属性 类型 功能与注意事项
constructors Collection<ConstructorInfo> 该 class 全部 public 构造器信息;无则空集合;顺序不保证
instanceVariables Collection<InstanceVariableInfo> 全部 public 实例变量信息;无则空集合;顺序不保证;不包含继承的实例变量
staticVariables Collection<StaticVariableInfo> 全部 public 静态变量信息;无则空集合;顺序不保证;不包含继承的静态变量
sealedSubclasses Collection<ClassTypeInfo> 仅当该类具有 sealed 语义时,返回同包内全部子类类型信息;无 sealed 语义返回空集合;有 sealed 语义时集合永不为空(类型本身是其自身子类)
superClass Option<ClassTypeInfo> 直接父类;理论上只有 Object 类没有直接父类

4.2 构造器操作

construct(Array<Any>):按参数列表搜索并调用匹配的 public 构造器,返回 Any 类型实例。异常:InvocationTargetException(该类为 abstract,抽象类无法实例化)、InfoNotFoundException(args 无法匹配任何 public 构造器)。

package test
import std.reflect.*

public class Rectangular {
    public var length = 4
    public var width = 5
    public var myName = ""
    public init() {}
    public init(name: String) { myName = name }
    public init(name: String, length: Int64, width: Int64) {
        myName = name
        this.length = length
        this.width = width
    }
}

main(): Unit {
    let ty = ClassTypeInfo.get("test.Rectangular")
    ty.construct()                    // 无参构造
    ty.construct("Small rectangular") // 单参构造
    ty.construct("Big rectangular", 1, 1) // 三参构造
    return
}

getConstructor(Array<TypeInfo>):按参数类型信息列表匹配 public 构造器,未匹配抛 InfoNotFoundException。

let ty = ClassTypeInfo.get("test.Rectangular")
let ci01 = ty.getConstructor(StructTypeInfo.get("String"))
println(ci01)  // 输出:init(String)
let ci02 = ty.getConstructor(StructTypeInfo.get("String"), PrimitiveTypeInfo.get("Int64"), PrimitiveTypeInfo.get("Int64"))
println(ci02)  // 输出:init(String, Int64, Int64)

4.3 变量查询

  • getInstanceVariable(name: String): InstanceVariableInfo:按名称匹配实例变量,未匹配抛 InfoNotFoundException。示例中 getInstanceVariable("myName") 输出 myName: String。
  • getStaticVariable(name: String): StaticVariableInfo:按名称匹配静态变量,未匹配抛 InfoNotFoundException。示例中 getStaticVariable("area") 输出 static area: Int64。

4.4 语义判定

  • isAbstract(): Bool:是否为抽象类。
  • isOpen(): Bool:是否具有 open 语义。注意:并非只有用 open 修饰符修饰的 class 才有 open 语义,例如 abstract class 无论是否带 open 修饰符都具有 open 语义。
  • isSealed(): Bool:是否具有 sealed 语义。

五、StructTypeInfo:结构体类型信息

public class StructTypeInfo <: TypeInfo,描述 struct 类型信息。提供 constructors、instanceVariables、staticVariables 三个集合属性以及 construct(Array<Any>)、getConstructor(Array<TypeInfo>)、getInstanceVariable(String)、getStaticVariable(String)、get/get(String)、of(Any)、of<T>() 等方法,语义与 ClassTypeInfo 对应方法一致。

重要实现限制——Struct 变量修改需手动装箱/拆箱:由于实现限制,当前修改 Struct 类型的变量/属性需要手动装箱拆箱,示例如下:

import std.reflect.*

public struct SA {
    public var v1 = 11
}

main() {
    var sa = SA()
    let saObj: Any = sa
    StructTypeInfo.of<SA>().getInstanceVariable("v1").setValue(saObj, 22)
    sa = (saObj as SA).getOrThrow()
    println(sa.v1) // 输出 22
}

construct(Array<Any>) 示例:StructTypeInfo.get("default.Rectangular").construct(2, 3) as Rectangular 构造实例后,getOrThrow().length 输出 2。

六、EnumTypeInfo 与 EnumConstructorInfo:枚举类型与构造器信息

平台限制:以下枚举反射相关 API 不支持 macOS、iOS 平台。

6.1 EnumTypeInfo

public class EnumTypeInfo <: TypeInfo,描述 enum 类型信息。

  • constructors: Collection<EnumConstructorInfo>:枚举全部构造器(case)信息。
  • get(String):qualifiedName 可以是枚举类型名或构造器限定名,例如 default.E、default.E.M1、default.E.M2(Int64)、default.E.M3(Int64, String);非法输入抛 IllegalTypeException。
  • of(Any):按枚举实例获取所属枚举类型信息。注意:当参数运行时类型是 class 类型时,调用会解析到 TypeInfo 上将废弃的 of(Object) 重载,返回 ClassTypeInfo 且不抛异常;需要强制类型种类时应使用 of<T>()。
  • of<T>():获取枚举类型 T 的信息,T 非枚举抛 IllegalTypeException。
  • construct(constructor: String, args: Array<Any>): Any:按构造器签名与参数构造枚举实例。签名如 M3(Int64, String),无关联值的构造器只写名称(如 M1)。异常:InfoNotFoundException(签名找不到)、InvocationTargetException(参数个数或类型不匹配)。
package test
import std.reflect.*

public enum E {
    | M1
    | M3(Int64, String)
}

main(): Unit {
    let e = EnumTypeInfo.get("test.E")
    let inst = (e.construct("M3(Int64, String)", [42, "abc"]) as E).getOrThrow()
    match (inst) {
        case E.M3(v1, v2) => println("${v1}, ${v2}") // 输出:42, abc
        case _ => println("unexpected")
    }
    return
}
  • destruct(instance: Any): (EnumConstructorInfo, ReadOnlyList<Any>):解构枚举实例,返回其构造器信息与关联值。异常:InvocationTargetException(实例不属于该枚举)、InfoNotFoundException(找不到匹配构造器签名)。
  • getConstructor(constructor: String, argsCount!: Int64 = 0): EnumConstructorInfo:按构造器名与参数个数查找。默认 0 匹配无参构造器(即无关联值的 case);若想忽略参数个数按名查找,可遍历 constructors 属性按名过滤。未匹配抛 InfoNotFoundException。
public enum E {
    | M1
    | M2(Int64)
    | M2(Int64, Int64)
}
// e.getConstructor("M1")            → test.E.M1
// e.getConstructor("M2", argsCount: 1) → test.E.M2(Int64)
// e.getConstructor("M2", argsCount: 2) → test.E.M2(Int64, Int64)

6.2 EnumConstructorInfo

public class EnumConstructorInfo <: Equatable<EnumConstructorInfo> & Hashable & ToString,描述枚举构造器(case)信息,用于检查构造器参数类型与注解,或按构造器构造/解构枚举实例。

成员 签名/类型 功能与注意事项
annotations Collection<Annotation> 该枚举构造器上的注解
enumTypeInfo EnumTypeInfo 所属枚举的 EnumTypeInfo;声明类型非枚举时抛 MisMatchException
name String 构造器名(不含包前缀)
qualifiedName String 构造器限定名,如 test.E.M2(Int64)
parameters ReadOnlyList<TypeInfo> 按声明顺序的构造器参数类型列表
apply(args: Array<Any>): Any 方法 以给定参数调用该枚举构造器并返回枚举实例;参数个数或运行时类型不匹配抛 InvocationTargetException
getAssociatedValues(instance: Any): ReadOnlyList<Any> 方法 获取给定枚举实例的关联值列表(按声明顺序);instance 非本构造器创建时抛 IllegalTypeException(不支持 macOS/iOS)
get/get(String) 静态 按限定名获取,如 EnumConstructorInfo.get("test.E.M2(Int64)");不合法抛 IllegalTypeException
of(instance: Any) 静态 获取给定枚举实例所属的构造器信息;instance 非该枚举实例抛 IllegalTypeException(不支持 macOS/iOS)
== / hashCode() / toString() 成员 相等比较、哈希、字符串表示(与 qualifiedName 相同)

枚举构造器调用示例:

package test
import std.reflect.*

public enum E {
    | M1
    | M2(Int64)
    | M3(Int64, String)
}

main(): Unit {
    let ctor = EnumConstructorInfo.get("test.E.M3(Int64, String)")
    let inst = (ctor.apply([7, "hi"]) as E).getOrThrow()
    match (inst) {
        case E.M3(v1, v2) => println("${v1}, ${v2}") // 输出:7, hi
        case _ => println("unexpected")
    }
    return
}

七、InterfaceTypeInfo:接口类型信息

public class InterfaceTypeInfo <: TypeInfo,描述 interface 类型信息。

  • sealedSubtypes: Collection<TypeInfo>:仅当接口具有 sealed 语义时返回该接口包内全部子类型信息;无 sealed 语义返回空集合;有 sealed 语义时集合不会为空(接口自身是其自身子类型)。
  • isSealed(): Bool:是否具有 sealed 语义。
  • get(String) / of(Any) / of<T>():获取方式与 ClassTypeInfo 一致;of(Any) 传入 class 类型实例时同样会解析到将废弃的 of(Object) 重载。
import std.reflect.*

public interface Rectangular {}

main(): Unit {
    let ty = InterfaceTypeInfo.get("default.Rectangular")
    println(ty)  // 输出:default.Rectangular
    return
}

八、PrimitiveTypeInfo:基本数据类型信息

public class PrimitiveTypeInfo <: TypeInfo,描述基本数据类型信息(不支持 macOS、iOS)。基本数据类型包括:无类型 Nothing、单元类型 Unit、字符类型 Rune、布尔类型 Bool、整数类型(Int8/Int16/Int32/Int64/IntNative/UInt8/UInt16/UInt32/UInt64/UIntNative)以及浮点类型(Float16/Float32/Float64)。

import std.reflect.*

main(): Unit {
    var pti = PrimitiveTypeInfo.get("Int64")
    println(pti)          // 输出:Int64
    var a = 10
    var pti2 = PrimitiveTypeInfo.of(a)  // 输出:Int64
    var pti3 = PrimitiveTypeInfo.of<Int64>() // 输出:Int64
    return
}

九、FunctionTypeInfo:函数类型信息

public class FunctionTypeInfo <: TypeInfo,描述函数类型(函数值/闭包)信息,用于获取参数与返回类型信息(不支持 macOS、iOS)。

成员 签名/类型 功能
parameters ReadOnlyList<TypeInfo> 函数类型参数类型列表(按声明顺序)
returnType TypeInfo 函数类型返回类型信息
of(Any) 静态 按实例运行时类型获取;of(Any) 传 class 实例时同样解析到将废弃的 of(Object) 重载
of<T>() 静态 按函数类型 T 获取
apply(instance: Any, args: Array<Any>): Any 方法 按参数顺序调用函数并返回结果;参数个数不匹配抛 IllegalArgumentException,参数运行时类型不匹配抛 IllegalTypeException
package test
import std.reflect.*

func add(a: Int64, b: Int64): Int64 {
    a + b
}

main(): Unit {
    let f: (Int64, Int64) -> Int64 = add
    let info = FunctionTypeInfo.of(f)
    println(info.parameters.size)   // 输出:2
    println(info.returnType.name)   // 输出:Int64
    let res = (info.apply(f, [1, 2]) as Int64).getOrThrow()
    println(res)                    // 输出:3
    return
}

十、TupleTypeInfo 与 GenericTypeInfo:元组与泛型类型信息

10.1 TupleTypeInfo

public class TupleTypeInfo <: TypeInfo,描述元组类型信息(不支持 macOS、iOS)。

成员 签名/类型 功能
elements ReadOnlyList<TypeInfo> 按元组声明顺序的各元素类型信息列表
of(Any) 静态 按实例运行时类型获取(运行时类型为元组)
of<T>() 静态 按元组类型 T 获取
construct(args: Array<Any>): Any 方法 按元素顺序传值构造元组实例;参数个数不符抛 IllegalArgumentException,元素类型不符抛 IllegalTypeException
destruct(instance: Any): ReadOnlyList<Any> 方法 将元组实例解构为只读元素列表;运行时类型不匹配抛 IllegalTypeException
package test
import std.reflect.*

main(): Unit {
    let info = TupleTypeInfo.of((1, "abc", true))
    println(info.elements.size)      // 输出:3
    println(info.elements[0].name)   // 输出:Int64
    println(info.elements[1].name)   // 输出:String
    println(info.elements[2].name)   // 输出:Bool
    let info2 = TupleTypeInfo.of<(Int64, Bool)>()
    println(info2.name)              // 输出:Tuple<Int64, Bool>
    return
}

construct / destruct 组合示例(含 class 与 struct 元素):

let tp = (1, S(0), C(1))
let info = TupleTypeInfo.of(tp)
let constructed = (info.construct([42, S(99), C(100)]) as (Int64, S, C)).getOrThrow()
println(constructed[0])  // 42
println(constructed[1].v) // 99
println(constructed[2].v) // 100
let destructed = info.destruct(tp)
println(destructed.size) // 3

10.2 GenericTypeInfo

public class GenericTypeInfo <: TypeInfo & Equatable<GenericTypeInfo>,描述泛型类型信息。仅提供 operator func ==(that: GenericTypeInfo): Bool 用于泛型类型信息的相等比较。它在全局函数、实例函数、静态函数的 genericParams: Collection<GenericTypeInfo> 属性中作为元素出现(见下文函数信息章节)。

十一、构造函数信息:ConstructorInfo 与 ParameterInfo

11.1 ConstructorInfo

public class ConstructorInfo <: Equatable<ConstructorInfo> & Hashable & ToString,描述构造器信息,用于 class/struct 的 constructors 属性及 getConstructor 返回值。

成员 签名/类型 功能与注意事项
annotations Collection<Annotation> 构造器上的全部注解;无注解返回空集合
parameters ReadOnlyList<ParameterInfo> 构造器参数类型列表;参数顺序不保证,需用 ParameterInfo.index 确定实际位置
apply(args: Array<Any>): Any 方法 以给定参数调用本构造器。异常:InvocationTargetException(所属类型为抽象类)、IllegalArgumentException(参数个数不匹配)、IllegalTypeException(某参数运行时类型不是对应参数声明类型的子类型)
findAllAnnotations<T>() / findAnnotation<T>() / getAllAnnotations() 方法 注解查询(见后文注解章节)
hashCode() / toString() / == / != 成员 哈希、字符串表示、相等比较

parameters 使用示例(注意用 index 定位参数位置):

for (i in ty.constructors) {
    for (j in i.parameters) {
        println("${i} has input parameter ${j}")
    }
}
// 输出示例:
// init(String) has input parameter String
// init(String, Int64, Int64) has input parameter String
// init(String, Int64, Int64) has input parameter Int64
// init(String, Int64, Int64) has input parameter Int64

11.2 ParameterInfo

public class ParameterInfo <: Equatable<ParameterInfo> & Hashable & ToString,描述函数参数信息。

成员 签名/类型 功能与注意事项
annotations Collection<Annotation> 参数上的全部注解;无注解空集合
index Int64 参数在所属函数中的位置索引,从 0 开始计数
name String 参数名
typeInfo TypeInfo 参数声明类型的类型信息
findAllAnnotations<T>() / findAnnotation<T>() / getAllAnnotations() 方法 注解查询
hashCode() / toString() / == / != 成员 哈希、字符串表示、相等比较

十二、函数信息:GlobalFunctionInfo / InstanceFunctionInfo / StaticFunctionInfo

这三类都实现 Equatable + Hashable + ToString,分别描述全局函数、实例成员函数、静态成员函数信息。它们共享大量共性成员,下表合并展示:

成员 全局函数 实例函数 静态函数 功能与注意事项
annotations ✓ ✓ ✓ 函数上的全部注解
name ✓ ✓ ✓ 函数名;所有重载共享同名;实例/静态运算符重载函数的 name 是运算符符号本身,如 +、*、[]
parameters ✓ ✓ ✓ 参数信息列表;顺序不保证,用 ParameterInfo.index 定位
returnType ✓ ✓ ✓ 返回类型信息
genericParams ✓ ✓ ✓ 泛型参数信息列表;无泛型参数返回空集合(不抛异常)
modifiers ✗ ✓ ✓ 全部修饰符信息;即使未显式写某修饰符,只要具备其语义也会包含(如接口中的成员函数天然 open)
apply(args) ✓ ✗ ✗ 以参数列表调用全局函数
apply(instance, args) ✗ ✓ ✗ 指定实例并传参调用实例函数
apply(thisType, args) ✗ ✗ ✓ 传入所属类类型信息与参数调用静态函数
apply(genericTypeArgs, args) ✓ ✗ ✗ 传泛型实参列表与参数列表调用全局泛型函数
apply(instance, genericTypeArgs, args) ✗ ✓ ✗ 调用泛型实例函数
apply(thisType, genericTypeArgs, args) ✗ ✗ ✓ 调用泛型静态函数
isAbstract() ✗ ✓ ✗ 实例函数是否具有 abstract 语义
isOpen() ✗ ✓ ✗ 实例函数是否具有 open 语义;interface 类型中的实例成员函数天然具有 open 语义
注解三查询 ✓ ✓ ✓ findAllAnnotations<T>()、findAnnotation<T>()、getAllAnnotations()
hashCode() / toString() / == / != ✓ ✓ ✓ 哈希、字符串表示、相等比较

12.1 调用语义与异常约定

各 apply 重载遵循统一约定:

  • args 中元素类型必须与函数参数类型完全匹配,否则参数校验失败;
  • 泛型版本(带 genericTypeArgs)用于调用泛型函数:非泛型函数调用泛型版本会抛 InvocationTargetException,泛型函数调用非泛型版本同样抛 InvocationTargetException;
  • genericTypeArgs 数量与函数 genericParams 数量不符抛 IllegalArgumentException;
  • args 数量与形参数量不符抛 IllegalArgumentException;
  • 某实参运行时类型不是对应形参声明类型的子类型,抛 IllegalTypeException;args 与 genericTypeArgs 不满足函数参数类型约束时同样抛 IllegalTypeException;
  • 实例函数是 abstract 或没有实现时抛 InvocationTargetException;静态函数函数体未实现时抛 InfoNotFoundException;
  • 实例函数 apply 中 instance 运行时类型与函数所属类型不匹配抛 IllegalTypeException;静态函数 apply 中 thisType 与函数签名不匹配抛 IllegalArgumentException。

12.2 调用示例

实例函数:

import std.reflect.*

public class Rectangular {
    public var length = 4
    public var width = 5
    public func area(): Int64 {
        return length * width
    }
}

main(): Unit {
    let ty = ClassTypeInfo.get("default.Rectangular")
    var gif = ty.getInstanceFunction("area")
    var r = Rectangular()
    var result = gif.apply(r) as Int64
    println(result)   // 输出:Some(20)
    return
}

静态函数:

package test
import std.reflect.*

public class Rectangular {
    public static func myName(): String {
        "my name is Rectangular"
    }
}

main(): Unit {
    let ty = ClassTypeInfo.get("test.Rectangular")
    let sf = ty.getStaticFunction("myName")
    let result = sf.apply(ty) as String
    println(result)   // 输出:Some(my name is Rectangular)
    return
}

十三、变量信息:GlobalVariableInfo / InstanceVariableInfo / StaticVariableInfo

三类变量信息同样实现 Equatable + Hashable + ToString,共性成员如下:

成员 全局变量 实例变量 静态变量 功能与注意事项
annotations ✓ ✓ ✓ 变量上的全部注解
name ✓ ✓ ✓ 变量名
typeInfo ✓ ✓ ✓ 变量声明类型的类型信息
modifiers ✗ ✓ ✓ 修饰符信息集合;静态变量/属性的修饰符集合内容当前"较为杂乱、尚未统一"
getValue() ✓ ✗ ✓ 获取变量值(全局/静态无需实例)
getValue(instance: Any) ✗ ✓ ✗ 获取指定实例中该变量的值;instance 运行时类型与变量所属类型严格匹配(非子类型)否则抛 IllegalTypeException
setValue(newValue: Any) ✓ ✗ ✓ 设置变量值;变量不可变抛 IllegalSetException;newValue 运行时类型非声明类型子类型抛 IllegalTypeException
setValue(instance: Any, newValue: Any) ✗ ✓ ✗ 设置指定实例中的变量值;异常同 getValue/setValue 组合
isMutable(): Bool ✓ ✓ ✓ 是否可变:var 修饰可变,let 修饰不可变
注解三查询 ✓ ✓ ✓ findAllAnnotations<T>()、findAnnotation<T>()、getAllAnnotations()
hashCode() / toString() / == / != ✓ ✓ ✓ 哈希、字符串表示、相等比较

实例变量读写示例:

public class Rectangular {
    public var length = 4
    public var width = 5
}

main(): Unit {
    let ty = ClassTypeInfo.get("default.Rectangular")
    var gip = ty.getInstanceVariable("width")
    var r = Rectangular()
    let v = gip.getValue(r) as Int64
    println(v)   // 输出:Some(5)
    return
}

静态变量读写示例:

public class Rectangular {
    public static var area: Int64 = 10
}

main(): Unit {
    let ty = ClassTypeInfo.get("test.Rectangular")
    let sv = ty.getStaticVariable("area")
    println(sv.getValue() as Int64)   // 输出:Some(10)
    sv.setValue(20)
    println(sv.getValue() as Int64)   // 输出:Some(20)
    return
}

十四、属性信息:InstancePropertyInfo / StaticPropertyInfo

属性(prop)信息类描述实例/静态成员属性。与变量(var/let)不同,属性带 get()/set(v) 访问器,读写走访问器逻辑。

成员 实例属性 静态属性 功能与注意事项
annotations ✓ ✓ 属性上的全部注解
name ✓ ✓ 属性名
typeInfo ✓ ✓ 属性声明类型信息
modifiers ✓ ✓ 修饰符信息集合;静态属性的修饰符集合内容当前"较为杂乱、尚未统一"
getValue(instance: Any) ✓ ✗ 读取指定实例中属性值(走 get() 访问器);instance 类型严格匹配否则抛 IllegalTypeException
getValue() ✗ ✓ 读取静态属性值
setValue(instance, newValue) ✓ ✗ 写实例属性(走 set(v) 访问器);不可修改抛 IllegalSetException
setValue(newValue) ✗ ✓ 写静态属性;异常同上
isMutable(): Bool ✓ ✓ 是否可修改:mut 修饰符修饰则可修改
isAbstract() ✓ ✗ 实例属性是否抽象
isOpen() ✓ ✗ 实例属性是否具有 open 语义
注解三查询 / 哈希 / 字符串 / 相等 ✓ ✓ 通用成员

注意:静态属性若缺少有效实现(如 interface 类型中的抽象静态属性),getValue()/setValue() 本应抛 UnsupportedException,但因后端支持不足尚未实现该行为。

实例属性示例(属性 width 只有 get() 访问器):

public class Rectangular {
    public var length = 4
    public prop width: Int64 {
        get() { 5 }
    }
}

main(): Unit {
    let ty = ClassTypeInfo.get("default.Rectangular")
    var gip = ty.getInstanceProperty("width")
    var r = Rectangular()
    var result = gip.getValue(r) as Int64
    println(result)   // 输出:Some(5)
    return
}

静态可变属性示例(mut prop area):

public class Rectangular {
    private static var valueArea = 0
    public static mut prop area: Int64 {
        get() { valueArea }
        set(v) { valueArea = v }
    }
}

main(): Unit {
    let ty = ClassTypeInfo.get("test.Rectangular")
    let sp = ty.getStaticProperty("area")
    sp.setValue(10)
    let result = sp.getValue() as Int64
    println(result)   // 输出:Some(10)
    return
}

十五、PackageInfo:包级反射与动态加载

public class PackageInfo <: Equatable<PackageInfo> & Hashable & ToString,描述包信息,支持遍历包内类型/函数/变量以及运行时动态加载 Cangjie 动态库。

15.1 包信息属性

属性 类型 功能与注意事项
name String 包名,不含模块名与父包名;例如限定名 a/b.c.d 的包,其 name 为 d
qualifiedName String 包限定名,格式为 `(module_name/)?(default
parentPackage PackageInfo 父包信息;父包未加载抛 InfoNotFoundException
rootPackage PackageInfo 根包信息;包本身是根包时返回自身(例如 a.b.c 的 rootPackage 是 a,a 的 rootPackage 是 a);根包未加载抛 InfoNotFoundException
subPackages Collection<PackageInfo> 已加载子包集合;顺序不保证
typeInfos Collection<TypeInfo> 包内全部全局定义的 public 类型信息;当前不包含反射尚未支持的类型
functions Collection<GlobalFunctionInfo> 包内全部 public 全局函数信息
variables Collection<GlobalVariableInfo> 包内全部 public 全局变量信息
version String 包版本号;由于动态库中目前拿不到版本信息,恒返回空字符串
organizationName String 包的组织名(不支持 macOS/iOS)

15.2 包内成员查找

  • getFunction(name: String, parameterTypes: Array<TypeInfo>): GlobalFunctionInfo:按名称与参数类型列表匹配全局函数,未匹配抛 InfoNotFoundException;
  • getFunctions(name: String): Array<GlobalFunctionInfo>:返回全部同名全局函数;
  • getVariable(name: String): GlobalVariableInfo:按名匹配全局变量;
  • getTypeInfo(qualifiedTypeName: String): TypeInfo:按限定类型名匹配包内 public 类型;
  • getSubPackage(qualifiedName: String): PackageInfo:按限定名获取子包;无效或未加载抛 InfoNotFoundException。

15.3 动态加载:PackageInfo.load(String)

public static func load(path: String): PackageInfo

在运行时从指定路径动态加载 Cangjie 动态库模块并获取其包信息。约定与异常:

  • 为兼容性考虑,路径中的共享库文件名无需扩展名(如 .so、.dll);
  • 如果某 package 已通过静态加载方式导入(如 import),再对其动态加载会抛异常;
  • 异常约定:ReflectException(共享库加载失败 / 重载同名或同文件名共享库 / 动态库内部包含多个 Package)、IllegalArgumentException(路径无效)。

完整实战示例(摘自 dynload.md):先建动态库模块再建可执行工程,运行时反射读写动态库中的全局变量:

$ mkdir -p myProject/myPackage && cd myProject/myPackage
# 初始化 Cangjie 动态库模块,使 myPackage 中的 Cangjie 功能可被动态编译
$ cjpm init --type=dynamic --name myPackage
$ cat << EOF > src/myPackage.cj
package myPackage

public var myPublicGlobalVariable0: Int64 = 2333
public let myPublicGlobalVariable1 = MyPublicType("Initializing myPublicGlobalVariable1 in myPackage")

public class MyPublicType {
    public MyPublicType(message: String) {
        println(message)
    }
    public static func myPublicStaticMemeberFunction() {
        println("myPackage.MyPublicType.myPublicStaticMemeberFunction is called.")
    }
    static let myStaticVariable = MyPublicType("Initializing myStaticVariable in myPackage.MyPublicType")
}
EOF
$ cjpm build

再创建可执行目录,通过反射动态加载并操作动态库中的全局变量:

package myExecutableDirectory
import std.reflect.*

main(): Unit {
    // 加载 Cangjie 动态库(无需扩展名)
    let myPackage = PackageInfo.load("../myPackage/target/release/myPackage/libmyPackage")
    println(myPackage.name)
    TypeInfo.get("myPackage.MyPublicType") |> println

    let myPublicGlobalVariable0 = myPackage.getVariable("myPublicGlobalVariable0")
    (myPublicGlobalVariable0.getValue() as Int64).getOrThrow() |> println
    myPublicGlobalVariable0.setValue(666)
    (myPublicGlobalVariable0.getValue() as Int64).getOrThrow() |> println
}

运行输出:

Initializing myPublicGlobalVariable1 in myPackage
Initializing myStaticVariable in myPackage.MyPublicType
myPackage
myPackage.MyPublicType
2333
666

十六、注解反射:统一的查询三方法

凡携带注解的反射对象(类型、构造器、函数、变量、属性、参数等)均提供三个注解查询方法:

  • findAnnotation<T>(): ?T where T <: Annotation:尝试获取应用到对象上的某类型注解;成功匹配返回注解,注解重复或匹配失败返回 None;
  • findAllAnnotations<T>(): Array<T> where T <: Annotation:获取全部指定类型的注解;无匹配返回空数组;
  • getAllAnnotations(): Array<Annotation>:获取对象上的全部注解。

例如对枚举构造器查询注解(无注解场景):

package test
import std.reflect.*

public enum E {
    | M1
}

main(): Unit {
    let ctor = EnumTypeInfo.get("test.E").getConstructor("M1")
    println(ctor.getAllAnnotations().size)          // 输出:0
    println(ctor.findAnnotation<A1>().isNone())     // 输出:true(未定义 A1 注解时)
    return
}

十七、实战总结:反射编程的通用流程

综合以上 21 个类,仓颉反射编程遵循如下通用模式:

  1. 获取类型信息:优先用 XxxTypeInfo.get("限定名")、of(实例) 或 of<T>() 三种入口之一拿到 TypeInfo;
  2. 查询成员:通过 TypeInfo 基类上的 getInstanceFunction/getStaticProperty/instanceVariables 等集合属性或精确查找方法获得成员信息对象;
  3. 读取元数据:从成员信息上取 name、typeInfo、parameters(注意用 ParameterInfo.index 定位参数顺序)、modifiers、annotations 等;
  4. 执行操作:调用 apply(函数/构造器)、getValue/setValue(变量/属性)、construct/destruct(枚举/元组);
  5. 包级操作:用 PackageInfo.get/load 进入包命名空间,遍历或动态加载模块。

使用中务必牢记三点边界:只能反射 public 可见的全局类型与成员;struct 变量修改需手动装箱/拆箱;枚举、函数、元组、PrimitiveTypeInfo 相关 API 及部分 of(Any) 语义在 macOS/iOS 上不可用,且 TypeInfo.of(Any) 对函数/元组/枚举运行时类型暂不支持。更多类型信息实战可参考 typeInfo.md(TypeInfo.of 三连查:name、qualifiedName、instanceFunctions.size),成员信息遍历与注解使用可参考同目录下 memberInfo.md、annotation.md。

登录后查看全文
cangjie_runtime