Go 语言中的 CBOR 编解码器

fxamacker/cbor 是一个用于编码和解码 CBOR 和 CBOR 序列的库。

CBOR 是 JSON、MessagePack、Protocol Buffers 等的可信替代品。CBOR 是由 IETF STD 94 (RFC 8949) 定义的互联网标准，设计目标是在未来数十年内保持相关性。

fxamacker/cbor 被 Arm Ltd.、Cisco、EdgeX Foundry、Flow Foundation、Fraunhofer-AISEC、Kubernetes、Let's Encrypt (ISRG)、Linux Foundation、Microsoft、Mozilla、Oasis Protocol、Tailscale、Teleport 等项目使用。

请参阅快速开始和发布版本。🆕 UnmarshalFirst 和 DiagnoseFirst 可以解码 CBOR 序列。cbor.MarshalToBuffer() 和 UserBufferEncMode 接受用户指定的缓冲区。

fxamacker/cbor

fxamacker/cbor 是一个完全符合 IETF STD 94 (RFC 8949) 的 CBOR 编解码器。它还支持 CBOR 序列（RFC 8742）和扩展诊断表示法（RFC 8610 的附录 G）。

特性包括对 CBOR 标签的全面支持、核心确定性编码、重复映射键检测等。

设计平衡了安全性、速度、并发性、编码数据大小、可用性等方面的权衡。

具有可配置设置的安全解码

fxamacker/cbor 具有可配置的限制等，可以防御恶意 CBOR 数据。

相比之下，encoding/gob 不设计用于对抗性输入的加固。

安全解码与可配置设置

fxamacker/cbor 具有可配置的限制等，可以防御恶意 CBOR 数据。

相比之下，encoding/gob 不设计用于对抗性输入的加固。

fxamacker/cbor 在拒绝格式错误的 CBOR 数据方面非常快速。例如，尝试将 10 字节的恶意 CBOR 数据解码为 []byte（使用默认设置）：

编解码器	速度 (ns/op)	内存	分配次数
fxamacker/cbor 2.5.0	44 ± 5%	32 B/op	2 allocs/op
ugorji/go 1.2.11	5353261 ± 4%	67111321 B/op	13 allocs/op
最新比较使用:

输入: []byte{0x9B, 0x00, 0x00, 0x42, 0xFA, 0x42, 0xFA, 0x42, 0xFA, 0x42}
go1.19.10, linux/amd64, i5-13600K (禁用所有 e-cores, DDR4 @2933)
go test -bench=. -benchmem -count=20

先前的比较

编解码器	速度 (ns/op)	内存	分配次数
fxamacker/cbor 2.5.0-beta2	44.33 ± 2%	32 B/op	2 allocs/op
fxamacker/cbor 0.1.0 - 2.4.0	~44.68 ± 6%	32 B/op	2 allocs/op
ugorji/go 1.2.10	5524792.50 ± 3%	67110491 B/op	12 allocs/op
ugorji/go 1.1.0 - 1.2.6	💥 运行时:	内存不足:	无法分配

输入: []byte{0x9B, 0x00, 0x00, 0x42, 0xFA, 0x42, 0xFA, 0x42, 0xFA, 0x42}
go1.19.6, linux/amd64, i5-13600K (DDR4)
go test -bench=. -benchmem -count=20

使用结构体标签实现更小的编码

结构体标签（toarray, keyasint, omitempty）可以减少结构体的编码大小。

示例：将3层嵌套的Go结构体编码为1字节CBOR

https://go.dev/play/p/YxwvfPdFQG2

// 示例：编码嵌套结构体（使用omitempty标签）
// - encoding/json:  18字节JSON
// - fxamacker/cbor:  1字节CBOR
package main
import (
	"encoding/hex"
	"encoding/json"
	"fmt"

	"github.com/fxamacker/cbor/v2"
)

type GrandChild struct {
	Quux int `json:",omitempty"`
}

type Child struct {
	Baz int        `json:",omitempty"`
	Qux GrandChild `json:",omitempty"`
}

type Parent struct {
	Foo Child `json:",omitempty"`
	Bar int   `json:",omitempty"`
}

func cb() {
	results, _ := cbor.Marshal(Parent{})
	fmt.Println("hex(CBOR): " + hex.EncodeToString(results))

	text, _ := cbor.Diagnose(results) // 诊断表示法
	fmt.Println("DN: " + text)
}

func js() {
	results, _ := json.Marshal(Parent{})
	fmt.Println("hex(JSON): " + hex.EncodeToString(results))

	text := string(results) // JSON
	fmt.Println("JSON: " + text)
}

func main() {
	cb()
	fmt.Println("-------------")
	js()
}

输出结果(DN是诊断表示法):

hex(CBOR): a0
DN: {}
-------------
hex(JSON): 7b22466f6f223a7b22517578223a7b7d7d7d
JSON: {"Foo":{"Qux":{}}}

使用多个结构体标签的示例

alt text

结构体标签简化了需要使用整数键的CBOR数组或映射的CBOR协议的使用。

CBOR标签

CBOR标签在TagSet中指定。

可以使用TagSet创建自定义模式来处理CBOR标签。

em, err := opts.EncMode()                  // 无CBOR标签
em, err := opts.EncModeWithTags(ts)        // 不可变的CBOR标签
em, err := opts.EncModeWithSharedTags(ts)  // 可变的共享CBOR标签

TagSet和使用它的模式对于并发使用是安全的。DecMode也有等效的API。

使用TagSet和TagOptions的示例

// 使用"解码CWT"示例中定义的signedCWT结构体。

// 创建TagSet(并发安全)。
tags := cbor.NewTagSet()
// 注册标签COSE_Sign1 18和signedCWT类型。
tags.Add(	
	cbor.TagOptions{EncTag: cbor.EncTagRequired, DecTag: cbor.DecTagRequired}, 
	reflect.TypeOf(signedCWT{}), 
	18)

// 创建带有不可变标签的DecMode。
dm, _ := cbor.DecOptions{}.DecModeWithTags(tags)

// 解组到带标签支持的signedCWT。
var v signedCWT
if err := dm.Unmarshal(data, &v); err != nil {
	return err
}

// 创建带有不可变标签的EncMode。
em, _ := cbor.EncOptions{}.EncModeWithTags(tags)

// 使用标签号组织signedCWT。
if data, err := cbor.Marshal(v); err != nil {
	return err
}