cloudevent

Documentation

Index

• type AttributeValue
  • func NewAttributeValue(v any) AttributeValue
  • func (v AttributeValue) AsBool() (bool, bool)
  • func (v AttributeValue) AsBytes() ([]byte, bool)
  • func (v AttributeValue) AsFloat64() (float64, bool)
  • func (v AttributeValue) AsInt32() (int32, bool)
  • func (v AttributeValue) AsInt64() (int64, bool)
  • func (v AttributeValue) AsString() (string, bool)
  • func (v AttributeValue) MarshalJSON() ([]byte, error)
  • func (v *AttributeValue) UnmarshalJSON(data []byte) error
• type CloudEvent
  • func DecodeAndWrap[T any](data []byte, codec codec.Codec, metadata CloudEventMetadata) (*CloudEvent[*T], error)
• type CloudEventMetadata
• type Extensions
  • func (e Extensions) Get(key string) (AttributeValue, bool)
  • func (e Extensions) Keys() []string
  • func (e Extensions) WithAny(key string, value any) Extensions
  • func (e Extensions) WithBool(key string, value bool) Extensions
  • func (e Extensions) WithBytes(key string, value []byte) Extensions
  • func (e Extensions) WithFloat64(key string, value float64) Extensions
  • func (e Extensions) WithInt32(key string, value int32) Extensions
  • func (e Extensions) WithInt64(key string, value int64) Extensions
  • func (e Extensions) WithString(key string, value string) Extensions

Types

type AttributeValue

type AttributeValue struct {
	// contains filtered or unexported fields
}

AttributeValue 是 CloudEvent 扩展属性值的包装类型 内部存储 any 类型值，支持类型安全的读取

使用示例:

val := NewAttributeValue("hello")
str, ok := val.AsString()  // "hello", true
num, ok := val.AsInt64()   // 0, false

func NewAttributeValue

func NewAttributeValue(v any) AttributeValue

NewAttributeValue 创建包装后的扩展属性值

func (AttributeValue) AsBool

func (v AttributeValue) AsBool() (bool, bool)

AsBool 尝试将值转换为 bool，返回 (值, 是否成功)

func (AttributeValue) AsBytes

func (v AttributeValue) AsBytes() ([]byte, bool)

AsBytes 尝试将值转换为 []byte，返回 (值, 是否成功)

func (AttributeValue) AsFloat64

func (v AttributeValue) AsFloat64() (float64, bool)

AsFloat64 尝试将值转换为 float64，返回 (值, 是否成功)

func (AttributeValue) AsInt32

func (v AttributeValue) AsInt32() (int32, bool)

AsInt32 尝试将值转换为 int32，返回 (值, 是否成功)

func (AttributeValue) AsInt64

func (v AttributeValue) AsInt64() (int64, bool)

AsInt64 尝试将值转换为 int64，返回 (值, 是否成功)

func (AttributeValue) AsString

func (v AttributeValue) AsString() (string, bool)

AsString 尝试将值转换为 string，返回 (值, 是否成功)

func (AttributeValue) MarshalJSON

func (v AttributeValue) MarshalJSON() ([]byte, error)

MarshalJSON 实现 JSON 序列化，自动解包内部值

func (*AttributeValue) UnmarshalJSON

func (v *AttributeValue) UnmarshalJSON(data []byte) error

UnmarshalJSON 实现 JSON 反序列化，自动包装为 AttributeValue

type CloudEvent

type CloudEvent[T any] struct {
	CloudEventMetadata
	Data T
}

CloudEvent 表示 CloudEvents 1.0 规范的事件 T 是事件数据的类型，可以是具体的业务结构体或 []byte

使用示例:

event := &CloudEvent[UserCreatedEvent]{
    CloudEventMetadata: CloudEventMetadata{
        Id:          "uuid-xxx",
        Source:      "urn:eventapi:client",
        SpecVersion: "1.0",
        Type:        "acme.user.created.v1",
        Subject:     "user.123",
        Extensions:  Extensions{}.WithString("trace_id", "abc"),
    },
    Data: UserCreatedEvent{...},
}

func DecodeAndWrap

func DecodeAndWrap[T any](
	data []byte,
	codec codec.Codec,
	metadata CloudEventMetadata,
) (*CloudEvent[*T], error)

DecodeAndWrap 反序列化事件数据并包装为带类型的 CloudEvent

type CloudEventMetadata

type CloudEventMetadata struct {
	// Id 是事件的唯一标识符，同一事件源产生的事件不能有重复 Id
	// 必填字段，格式: UUID v4
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id
	Id string

	// Source 标识事件发生的上下文，通常是事件源的标识
	// 必填字段，格式: URI 或 URN
	// 例如: "urn:eventapi:service:user-service", "/myapp/users"
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source
	Source string

	// SpecVersion 是 CloudEvents 规范的版本号
	// 必填字段，固定值: "1.0"
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion
	SpecVersion string

	// Type 描述事件类型，用于路由、过滤和处理
	// 必填字段，格式: {reverse-domain}.{event-name}.{version}
	// 例如: "acme.user.created.v1", "io.github.order.paid.v2"
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type
	Type string

	// DataContentType 描述事件数据的内容类型 (MIME type)
	// 可选字段，由 Codec 自动填充
	// 例如: "application/json", "application/protobuf"
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#datacontenttype
	DataContentType string

	// DataSchema 指向描述事件数据格式的 schema
	// 可选字段
	// 例如: "https://acme.com/schemas/user-created.json"
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#dataschema
	DataSchema string

	// Time 是事件生成的时间戳
	// 可选字段，由事件源在生成时填充
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#time
	Time time.Time

	// Subject 标识事件相关的资源或主题
	// 可选字段，用于消息路由和过滤
	// 从 proto 中标记为 (eventapi.v1.is_subject) = true 的字段提取
	// 例如: "user.123", "order.456"
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject
	Subject string

	// Extensions 是自定义扩展属性，用于传递协议无关的元数据
	// 可选字段，通过 Extensions.WithXxx() 方法添加
	// 常见扩展: trace_id, tenant_id, correlation_id
	// 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#extension-context-attributes
	Extensions Extensions
}

CloudEventMetadata 包含 CloudEvent 的元数据（标准属性） 参考: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md

type Extensions

type Extensions map[string]AttributeValue

Extensions 是 CloudEvent 扩展属性集合 支持链式调用设置多种类型的属性值

使用示例:

// 创建扩展属性
ext := Extensions{}.
    WithString("trace_id", "abc-123").
    WithInt64("timestamp", time.Now().Unix()).
    WithBool("is_test", true)

// 读取属性
traceId, ok := ext.Get("trace_id")
if ok {
    id, _ := traceId.AsString()
}

func (Extensions) Get

func (e Extensions) Get(key string) (AttributeValue, bool)

Get 获取扩展属性值，返回 (值, 是否存在)

func (Extensions) Keys

func (e Extensions) Keys() []string

Keys 返回所有扩展属性的 key 列表

func (Extensions) WithAny

func (e Extensions) WithAny(key string, value any) Extensions

WithAny 添加任意类型的扩展属性

func (Extensions) WithBool

func (e Extensions) WithBool(key string, value bool) Extensions

WithBool 添加布尔类型的扩展属性

func (Extensions) WithBytes

func (e Extensions) WithBytes(key string, value []byte) Extensions

WithBytes 添加 []byte 类型的扩展属性

func (Extensions) WithFloat64

func (e Extensions) WithFloat64(key string, value float64) Extensions

WithFloat64 添加 float64 类型的扩展属性

func (Extensions) WithInt32

func (e Extensions) WithInt32(key string, value int32) Extensions

WithInt32 添加 int32 类型的扩展属性

func (Extensions) WithInt64

func (e Extensions) WithInt64(key string, value int64) Extensions

WithInt64 添加 int64 类型的扩展属性

func (Extensions) WithString

func (e Extensions) WithString(key string, value string) Extensions

WithString 添加字符串类型的扩展属性