Thriftgo 反射使用文档

简介

Thriftgo 在 v0.3.0 版本提供了 Thrift IDL 反射功能，可以在运行时获取 Thrift IDL 的相关信息与描述符，并支持通过描述符来找到对应的 Go Type 并进行反射操作。我们可以在运行时使用这些反射查询接口，获取到 IDL 信息，以便进行各种查询和操作，以及更轻松的使用反射。

快速开始

例如有这样一个 IDL

// sample.thrift
namespace go demo

struct A{
    // hello
    1:required string hello
}

struct B{
    // hello
    1:required string hello
}

enum Gender{
    MALE
    FEMALE
}

service MyService{
    B MyMethod(1:required A req)
}

以 Kitex Tool 为例，在代码生成时，额外添加 -thrift with_reflection 参数，执行如下命令

kitex -module xx -thrift with_reflection demo.thrift

生成代码的目录如下：

kitex_gen/
└── demo
    ├── demo-reflection.go
    ├── demo.go
    ├── k-consts.go
    ├── k-demo.go
    └── myservice
        ├── client.go
        ├── invoker.go
        ├── myservice.go
        └── server.go

相比原有场景，会多出 demo-reflection.go 文件。这个文件包含了 demo.thrift 的 IDL 信息记录以及反射相关接口。

// demo-reflection.go
// IDL Name: demo
// IDL Path: demo.thrift

// 记录 Descriptor 与 Go Type 的对应关系
var file_demo_thrift_go_types = []interface{}{
   (*A)(nil),      // Struct 0: demo.A
   (*B)(nil),      // Struct 1: demo.B
   (*Gender)(nil), // Enum 0: demo.Gender
}
var file_demo_thrift *thrift_reflection.FileDescriptor
var file_idl_demo_rawDesc = []byte{0x1f, 0x8b, 0x8, 0x0, 0x0, ......}
}

// 初始化反射信息，并全局注册这个 IDL 的元信息
func init() {
   if file_demo_thrift != nil {
      return
   }
   type x struct{}
   builder := &thrift_reflection.FileDescriptorBuilder{
      Bytes:         file_idl_demo_rawDesc,
      GoTypes:       file_demo_thrift_go_types,
      GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
   }
   file_demo_thrift = thrift_reflection.BuildFileDescriptor(builder)
}

// 生成该 IDL 对应的 File Descriptor 的获取方法
func GetFileDescriptorForDemo() *thrift_reflection.FileDescriptor {
   return file_demo_thrift
}
// 为结构体生成 Descriptor 的获取方法
func (p *A) GetDescriptor() *thrift_reflection.StructDescriptor {
   return file_demo_thrift.GetStructDescriptor("A")
}

//.....

当在 Golang 代码里引入这个包的时候，该 IDL 的元信息就会被初始化并加载记录，在后续的代码中就可以开始使用 Thrift 反射的 API 了。

获取 Descriptor 与 IDL 元信息

我们可以通过 Descriptor 来获取 IDL 里对应的信息。例如通过 StructDescriptor，来获取 IDL 在结构体定义时的信息，以及拿到字段的注释和注解等等：

func main() {
   a := demo.NewA()
   // get struct descriptor from golang struct generated by thriftgo
   desc := a.GetDescriptor()
   fmt.Println(desc.Name)
   fmt.Println(desc.Annotations)

   // get field descriptor from struct descriptor
   helloDesc := desc.GetFieldByName("hello")
   fmt.Println(helloDesc.GetID())
   fmt.Println(helloDesc.GetRequiredness())
   
   // get type descriptor from field descriptor    
   typeDesc := helloDesc.GetType()
   fmt.Println(typeDesc.GetName())
   fmt.Println(typeDesc.IsStruct())
   
   // get annotation and check annotation
   annotations := desc.getAnnotations()
   test.Assert(annotations["key"]=="value1")
}

具体来说，Descriptor 的种类以及他们之间的关系如下：

这些 Descriptor 也是用 Thrift IDL 定义的：https://github.com/cloudwego/thriftgo/blob/main/descriptor.thrift

除了在代码生成里提供 Golang 结构体找到 Descriptor 的方法以外，thrift_reflection 包内也提供了按照 Golang 类型或者名称查找 Descriptor 的方式：

func main() {
   a := demo.NewA()
   desc := a.GetDescriptor()

   // 通过传入一个 golang 对象来找到其类型对应的 Descriptor
   desc = thrift_reflection.GetStructDescriptorByGoType((*demo.A)(nil))
   desc = thrift_reflection.GetStructDescriptorByGoType(a)
 
   // 通过 struct name + filepath 来搜索结构体，如果 filepath 为空，则为模糊匹配第一个 struct name 相同的对象
   desc = thrift_reflection.LookupStruct("A", "demo.thrift")
 
   // 通过 type descriptor 来找到对应的 struct descriptor
   typeDesc := desc.GetFieldByName("xxx").GetType()
   if typeDesc.IsStruct(){
       typeDesc.GetStructDescriptor() 
   }
}

同时也附带了一些常用的工具函数来进行 Descriptor 的查找：

// 查询某结构体中直接和间接依赖的所有 Struct Descriptor
allStructDescs, err := LookupIncludedStructsFromStruct(structDesc)
// 查询某方法中直接和间接依赖的所有 Struct Descriptor
allStructDescs, err := LookupIncludedStructsFromMethod(methodDesc)
// 查询某 Type Descriptor 中直接和间接依赖的所有 Struct Descriptor
allStructDescs, err := LookupIncludedStructsFromType(typeDesc)

获取 GoTypes 与反射操作

Descriptor 也能和 Golang 反射类型配合使用，Descriptor 提供了 GetGoType 方法，用来获取对应的 Golang 类型:

func main() {
   person := &simple.Person{
      Name: "CloudWeGo Guy",
      Id: &simple.IDCard{
         Number: "123",
         Age:    23,
      },
   }
   // get struct descriptor
   pd := person.Descriptor()
   // get go type from struct descriptor
   fmt.Println(pd.GetGoType())
   // get field descriptor
   fd := pd.GetFieldByName("id")
   // reflection
   idCardGoType, err := fd.GetGoType()
   if err != nil {
      idCardInstance := reflect.New(idCardGoType).Elem()
      fmt.Println(idCardInstance)
   }
}

类似的，除了 StructDescriptor，其他 Descriptor 也都有对应的 GoType 获取方法

要注意的是，Descriptor 查询到的信息是来自 IDL 的，名称和 Go 代码的结构体不一定完全一致，因为下划线转驼峰，或者重名避免策略，实际的 IDL 命名和 Golang 代码名称会有出入。例如某结构体的 Field 名叫 my_name，通过 Descriptor 拿到的 Name 为 my_name，但实际上 Golang 结构体里，这个 Field 是 MyName (下划线转驼峰命名)

Descriptor 也可以配合 Golang 反射 API 使用。虽然无法通过 GetFieldByName 来直接查找，但 Descriptor 里的 Field 的顺序是和 Golang 反射里的一致的，可以像下面这段代码一样通过 Descriptor 查找反射字段

goType := structDescriptor.GetGoType()
structEntity := reflect.New(goType).Elem()
for idx, fd := range des.GetFields() {
   reflectField := structEntity.Field(idx)
   // xxxx
}

另外 Thriftgo 也提供了一些简单的关于 Descriptor 与 Golang 反射结合使用的 API，例如下面这段代码，展示了通过 fieldDescriptor 来反射设置某个结构体的字段的值：

func TestReflection(t *testing.T) {

   p := thrift_reflection_test.NewPerson()
   p.Name = "CloudWeGo"

   nameFieldDesc := p.GetDescriptor().GetFieldByName("name")
   assert(t, nameDesc != nil)

   // test get instance value by field descriptor reflection api
   val, err := nameFieldDesc.GetInstanceValue(p)
   assert(t, err == nil)
   stringVal, ok := val.(string)
   assert(t, ok && stringVal == "CloudWeGo")

   // test set instance value by field descriptor reflection api
   err = nameFieldDesc.SetInstanceValue(p, "KiteX")
   assert(t, err == nil)
   assert(t, p.Name == "KiteX")

}

在 Thriftgo v0.3.0 版本中，由于 Thrift 反射功能刚刚发布，所以配合 Golang 反射使用的 API 封装较少，后续会根据用户建议与常用场景，完善这方面的 API。

FAQ

Q：为什么初始化阶段出现错误会直接采用 panic 来停止整个程序

因为若初始化与注册 IDL 时出现错误，导致某个 IDL 无法被注册上，那么在后续的使用里，会影响到 IDL 信息之间的查询结果（例如找不到某个本应存在的 Descriptor），可能会因此导致用户的业务逻辑出错。所以 IDL 注册出错时直接 panic，以明显的方式提示用户。

Q：初始化时报错 “thrift reflection: file ‘xxx’ is already registered”

因为 Thrift IDL 元信息在注册时，是以 IDL 文件的 filepath 为唯一的 Key 的，所以当遇到有重复名称的 IDL 注册时，会报这个提示。这个设计与 Google Protobuf 反射的注册重复报错是类似的。解决方式是根据报错提示的路径找到对应的文件，重新用不同的 IDL 名称再生成代码即可。

Q：考虑把反射信息的生成设置为默认行为吗

目前要生成反射信息，需要 thriftgo 额外开启参数。由于反射功能刚刚推出，可能在后续投入实际使用后可能会有修改，所以打算等该功能较为成熟后，再作为默认行为开启，从而尽可能在现阶段减少对不使用该功能的用户的打扰。

Q：这个功能可以和公共结构体一起使用吗

生成引用结构体公共结构体功能是将本地某个 IDL 对应的 Golang 代码全部指向远端公共仓库的 Golang 代码。Thriftgo 反射功能可以和公共结构体功能一起使用。但有一些需要注意的说明。

首先，公共结构体的远端仓库在生成代码时也需要生成 Thriftgo 反射内容。

理论上，公共结构体场景下，本地的这份 IDL 是要和远端的 IDL 完全一致的。但不排除存在微弱的不一致情况，例如远端 IDL 多了一些结构体，或者某些结构体下增加了新的字段。例如下面的案例：

// 本地 IDL 
struct A{
    1:required string hello;
}

// 远端 IDL 
struct A{
    1:required string hello;
    2:required string hello2;
}

struct B{
    1:required string hello;
}

公共结构体场景生成的 Golang 代码为：

package xxx
import "repo/xxxx/remote"

type A = remote.A

由于实际的 Golang 结构体是使用的远端的，所以在公共结构体场景下，这份 IDL 的元信息在反射注册时将以远端的 IDL 情况为准（也就是既有 A 结构体也有 B 结构体的那个 IDL）。

此外还有一种特殊情况目前无法支持（出现概率极小），当对远端的一个 IDL 进行了拆分，让本地的一份 IDL 对应到了远端的两个 IDL 时，这种场景无法成功注册反射信息。

反馈

当前页面对你有帮助吗？

请告诉我们如何改进.

最后修改 January 13, 2025 : Update release-v0_12_0.md (#1203) (72c8d84)