Documentation
¶
Overview ¶
Package variant 提供 GAP 消息和 RPC 负载使用的动态值模型。
Variant 是统一的协议值包装，持有 TypeId 和对应的可读值。内置值包括整数、 浮点数、布尔值、字节串、字符串、Null、Array、Map、Error 和 CallChain。 自定义值需要实现 Value 接口，并通过 VariantCreator 注册后，才能根据 TypeId 反序列化。
常用入口：
- NewVariant：把已有 ReadableValue 包装为 Variant。
- ToVariant：把常见 Go 值转换为 Variant。
- Variant.ToNative：把反序列化后的 GAP 值转换为指定 Go reflect.Type。
- Array.Snapshot：冻结 Array 的编码载荷，用于延迟交付或跨 goroutine 交付后的写出。快照 Array 是只读形态，只用于后续编码。
Index ¶
- Variables
- type Array
- type Bool
- type Byte
- type Bytes
- type Call
- type CallChain
- type Double
- type Error
- type Float
- type IVariantCreator
- type Int
- type Int8
- type Int16
- type Int32
- type Int64
- type Map
- type Null
- type ReadableValue
- type String
- type TypeId
- type Uint
- type Uint8
- type Uint16
- type Uint32
- type Uint64
- type Value
- type Variant
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // ErrInvalidCast 表示动态值无法安全转换为目标 Go 类型。 ErrInvalidCast = fmt.Errorf("%w: invalid cast", ErrVariant) )
View Source
var ( // ErrNotDeclared 表示指定动态值类型 ID 尚未注册。 ErrNotDeclared = fmt.Errorf("%w: variant not declared", ErrVariant) )
View Source
var ( // ErrSnapshotReadonly 表示试图向只读数组快照解码数据。 ErrSnapshotReadonly = fmt.Errorf("%w: snapshot array is readonly", ErrVariant) )
View Source
var ( // ErrVariant 是 GAP 动态值处理错误的根错误。 ErrVariant = errors.New("gap-variant") )
Functions ¶
This section is empty.
Types ¶
type Array ¶
type Array struct {
Items []Variant // 非快照形态的数组项。
IsSnapshot bool // 是否为只读编码快照。
SnapshotBytes binaryutil.Bytes // 快照编码；可回收快照使用完后必须释放。
}
Array 保存有序动态值；快照形态只保留已编码字节且不可写入。
func (Array) ReleaseIfSnapshot ¶ added in v0.3.68
func (v Array) ReleaseIfSnapshot()
ReleaseIfSnapshot 释放快照持有的可回收字节缓冲区；非快照调用无效。
type Call ¶ added in v0.1.69
type Call struct {
Svc string // 服务名。
Addr string // 通信地址。
Timestamp time.Time // 产生或转发调用的时间。
Transit bool // 是否为中转节点。
}
Call 描述 RPC 调用链中的一个来源或中转节点。
type CallChain ¶ added in v0.1.69
type CallChain []Call
CallChain 按调用传播顺序保存来源和中转节点。
type Error ¶
Error 是包含数值错误码和消息的可传输错误。
type IVariantCreator ¶
type IVariantCreator interface {
// Declare 注册值指针的具体类型；重复 ID 会 panic。
Declare(v Value)
// New 创建指定类型 ID 对应的新值指针。
New(typeId TypeId) (Value, error)
// NewReflected 创建指定类型 ID 对应的新反射值。
NewReflected(typeId TypeId) (reflect.Value, error)
}
IVariantCreator 按类型 ID 注册并构造动态值。
type Map ¶
type Map struct {
// Entries 保存键值对，允许使用可比较的 Variant 作为键。
Entries generic.UnorderedSliceMap[Variant, Variant]
}
Map 以无序切片映射保存动态键值对。
func NewMapFromGoMap ¶ added in v0.3.68
func NewMapFromGoMap[K comparable, V any](m map[K]V) (Map, error)
NewMapFromGoMap 将 Go map 的键和值转换为动态值映射；迭代顺序不保证稳定。
func NewMapFromSliceMap ¶ added in v0.3.68
NewMapFromSliceMap 按 SliceMap 的顺序转换键值对。
func NewMapFromUnorderedSliceMap ¶ added in v0.3.68
func NewMapFromUnorderedSliceMap[K comparable, V any](m generic.UnorderedSliceMap[K, V]) (Map, error)
NewMapFromUnorderedSliceMap 按当前存储顺序转换键值对。
type ReadableValue ¶ added in v0.3.59
type ReadableValue interface {
io.Reader
// Size 返回值编码后的字节数。
Size() int
// TypeId 返回动态值类型 ID。
TypeId() TypeId
// Indirect 返回对应的 Go 值。
Indirect() any
}
ReadableValue 表示可编码到 GAP 动态值字节流的值。
type TypeId ¶
type TypeId uint32
TypeId 标识 GAP 动态值的具体类型。
const ( // TypeId_None 表示未设置动态值类型。 TypeId_None TypeId = iota // TypeId_Int 标识 int。 TypeId_Int // TypeId_Int8 标识 int8。 TypeId_Int8 // TypeId_Int16 标识 int16。 TypeId_Int16 // TypeId_Int32 标识 int32。 TypeId_Int32 // TypeId_Int64 标识 int64。 TypeId_Int64 // TypeId_Uint 标识 uint。 TypeId_Uint // TypeId_Uint8 标识 uint8。 TypeId_Uint8 // TypeId_Uint16 标识 uint16。 TypeId_Uint16 // TypeId_Uint32 标识 uint32。 TypeId_Uint32 // TypeId_Uint64 标识 uint64。 TypeId_Uint64 // TypeId_Float 标识 float32。 TypeId_Float // TypeId_Double 标识 float64。 TypeId_Double // TypeId_Byte 标识 byte。 TypeId_Byte // TypeId_Bool 标识 bool。 TypeId_Bool // TypeId_Bytes 标识 []byte。 TypeId_Bytes // TypeId_String 标识 string。 TypeId_String // TypeId_Null 标识空值。 TypeId_Null // TypeId_Array 标识动态值数组。 TypeId_Array // TypeId_Map 标识动态值映射。 TypeId_Map // TypeId_Error 标识可传输错误。 TypeId_Error // TypeId_CallChain 标识 RPC 调用链。 TypeId_CallChain // TypeId_Customize 是自定义类型 ID 的起始偏移。 TypeId_Customize = 32 )
内置动态值类型 ID。自定义类型必须从 TypeId_Customize 起分配。
func GenTypeIdT ¶ added in v0.3.68
GenTypeIdT 根据具名类型 T 的完整名称生成自定义类型 ID；*T 必须实现 Value。
func (TypeId) NewReflected ¶
NewReflected 使用进程级类型构建器创建此类型的新反射值。
type Variant ¶
type Variant struct {
TypeId TypeId // 动态值类型 ID。
Value ReadableValue // 实际值。
Reflected reflect.Value // 解码自定义类型时创建的反射值；自行构造时可为空。
}
Variant 将类型 ID 与可编码值关联，并可保留解码时创建的反射值。
func NewVariant ¶ added in v0.3.68
func NewVariant(v ReadableValue) (Variant, error)
NewVariant 用值自身的类型 ID 创建动态值包装。
Source Files
¶
- doc.go
- native_to_variant.go
- typeid.go
- typeid_builtin.go
- value.go
- value_builtin_array.go
- value_builtin_bool.go
- value_builtin_byte.go
- value_builtin_bytes.go
- value_builtin_callchain.go
- value_builtin_double.go
- value_builtin_error.go
- value_builtin_float.go
- value_builtin_int.go
- value_builtin_int16.go
- value_builtin_int32.go
- value_builtin_int64.go
- value_builtin_int8.go
- value_builtin_map.go
- value_builtin_null.go
- value_builtin_string.go
- value_builtin_uint.go
- value_builtin_uint16.go
- value_builtin_uint32.go
- value_builtin_uint64.go
- value_builtin_uint8.go
- variant.go
- variant_to_native.go
- variantcreator.go
Click to show internal directories.
Click to hide internal directories.