仓颉语言 std.reflect 反射包核心类 API 完全指南:ClassTypeInfo、TypeInfo 家族与成员信息模型实战
仓颉语言 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 个类,仓颉反射编程遵循如下通用模式:
- 获取类型信息:优先用
XxxTypeInfo.get("限定名")、of(实例)或of<T>()三种入口之一拿到TypeInfo; - 查询成员:通过
TypeInfo基类上的getInstanceFunction/getStaticProperty/instanceVariables等集合属性或精确查找方法获得成员信息对象; - 读取元数据:从成员信息上取
name、typeInfo、parameters(注意用ParameterInfo.index定位参数顺序)、modifiers、annotations等; - 执行操作:调用
apply(函数/构造器)、getValue/setValue(变量/属性)、construct/destruct(枚举/元组); - 包级操作:用
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。