在 JSON / YAML / TOML / Lua / Python / JavaScript 六种文本格式之间互相转换结构化数据。文本进,文本出,一次调用。
out, err := structure.Convert(input, structure.JSON, structure.YAML)- 保序:映射键顺序在保序格式之间原样传递
- 数字保真:
int64 → uint64 → *big.Int三级承载,2^53 以上整数不失精度 - 原生 any 互通:
FromAny/ToAny与map[string]any/[]any双向转换,键序默认规范化、可选保真(见下) - 只解析不执行:Lua / Python / JavaScript 走纯字面量子集,AST 白名单解释,永不执行代码
- 并发安全:无包级可变状态
go get github.com/aura-studio/structure/v2要求 Go 1.25 及以上。
根包 structure 是门面(facade)。数据模型、格式枚举、六个编解码器各自独立成包:
structure 门面:Parse / Encode / Convert / ParseFormat / FromAny / ToAny,按格式分派
├── node 数据模型:Node、OrderedMap、承载阶梯、原生 any 转换、深度与合法性校验、哨兵错误
├── format 格式枚举与 ParseError(不 import node,两个独立的根)
├── codec
│ ├── json yaml toml lua python js 每个包一对 Parse / Encode
│ └── internal/emit 缩进等编码器共用的小工具
├── internal/nodetest 各包共用的夹具与深嵌套生成器
└── tests 门面的测试与 fuzz 语料
依赖是单向的:node 与 format 互不相识,codec/* 依赖两者,门面依赖全部。唯一一条 codec 到 codec 的边是 codec/js → codec/json(JS 编码器复用 JSON 渲染器,两边共用同一套转义,避免各自漂移)。
tests 是一个独立的测试包,本身不含任何库代码,也没有任何包 import 它。它只能通过公开面触达门面,所以它同时充当门面 API 的可用性检验:任何一处该导出而没导出的东西,在这里会直接编译不过。
门面里的每个导出名都是类型别名或一行转发,不是新定义的类型:
type Node = node.Node
type OrderedMap = node.OrderedMap
type ParseError = format.ParseError所以 structure.OrderedMap 与 node.OrderedMap 是同一个类型,errors.As 用两种写法都能匹配,json.Marshaler 检测与 type switch 也一致。只用一种格式就直接 import 对应子包,需要按格式分派再用门面。
未来的扩展(比如 merge)落在新的子包里,不动这条依赖链。
文本进出的三个函数,Convert 等于 Parse 接 Encode:
// 直接转换
yamlText, err := structure.Convert(jsonText, structure.JSON, structure.YAML)
// 分两步,中间可以检查或改写 Node 树
node, err := structure.Parse(tomlText, structure.TOML)
if err != nil {
return err
}
node.(*structure.OrderedMap).Set("extra", int64(1))
out, err := structure.Encode(node, structure.Python)
// 从字符串解析格式名(大小写不敏感,支持 yml / py / python3 / javascript / ecmascript 别名)
f, err := structure.ParseFormat("yml") // => structure.YAMLFromAny / ToAny 在 map[string]any / []any(也就是 json.Unmarshal 产出的形状)与 Node 之间双向转换:
// 编码前转一次
n, err := structure.FromAny(map[string]any{"a": 1, "b": []any{true, "x"}})
out, err := structure.Encode(n, structure.YAML)
// 解析后转回来
n, err = structure.Parse(jsonText, structure.JSON)
v := structure.ToAny(n) // => map[string]any
// 输入里已有的 *OrderedMap 想按作者写的顺序出去
n, err = structure.FromAny(cfg, structure.KeepOrder())Parse / Encode 的签名与行为零改动:Encode 依然拒绝裸 map[string]any,Parse 也依然只产出 *OrderedMap。转换是调用方在边界上显式做的一步,不是隐式强转——所以模型内部一个映射永远只有一种表示。下面的键序模式同样只作用于这一步:Node 树里映射始终是插入有序的 *OrderedMap,模式决定的是往里装什么顺序,不是模型有几种形态。
- 整个 int / uint 族都收(含无类型常量默认的
int),统一落到int64 → uint64 → *big.Int阶梯;uint族一律经uint64,不会出现int64(uint64(1<<63))静默变负 json.Number收(配Decoder.UseNumber就能把 2^53 以上的整数原样带进来),float32加宽为float64- 键序分两种模式(下一节详述):默认把每个映射的键都排序,
KeepOrder()让输入里已有的*OrderedMap保留插入顺序 - 其余类型按名字拒绝:
map[any]any、map[string]string、[]string、[]byte、数组、struct、指针、time.Time、time.Duration、big.Float、chan、func、complex,以及任何具名类型。刻意不设fmt.Stringer/error兜底——这些类型全都有String(),兜底会把1<<100从正确的整数静默变成带引号的字符串,还能通过Validate - 输入不必是容器:转换器不管根形状,
FromAny(42)得到int64(42),顶层标量的拒绝仍由Validate/Encode负责。UTF-8 校验同理
Go 的 map 没有顺序,所以 FromAny 必须替它定一个——用 sort.Strings 而不是裸 range:六个编码器里五个严格按插入序输出,裸 range 会让同一个程序两次运行的输出不一样。这一条两种模式下都不变,没有选项能关掉。
真正有得选的是输入里已有的 *OrderedMap,它本来就带着顺序:
| 调用 | 输入里的 *OrderedMap |
输入里的 Go map | 适用场景 |
|---|---|---|---|
FromAny(v) |
排序 | 排序 | 规范化:等价数据不论来源都转成同一份文本 |
FromAny(v, KeepOrder()) |
保留插入序 | 排序 | 保真:输入的顺序本身是信息,比如重写一份手写配置 |
KeepOrder() 只保顺序,不发明顺序——Go map 没有顺序可保,所以两种模式下一样排序。规则逐层生效而非逐次调用:KeepOrder() 下一个 *OrderedMap 里套着 Go map,外层保序、内层照样排序。
两种模式都不保证顺序能落到文本:TOML 表内顺序与 Lua 哈希顺序在各自规范里没有意义,这两个编码器可能重排键,无论 Node 里装的是什么。哪些格式真把顺序带过去,以 format.PreservesOrder 为准,别另记一份清单。
ToAny 方向只有对称的签名,没有对称的能力:Go map 装不住顺序,所以 KeepOrder() 在这边的含义是「不转换映射」,也就只剩深拷贝一次——对任何合法 Node 都与 node.Clone 的结果相同,实现上就是直接委派给它。要顺序就别走 ToAny:
structure.Encode(n, structure.JSON) // 有序
json.Marshal(n) // 有序(*OrderedMap 自带 MarshalJSON)
json.Marshal(structure.ToAny(n)) // 无序——Go map 把顺序丢了Parse 返回、Encode 接受的中间表示是 Node(即 any),合法承载类型恰好这几种:
| 类型 | 说明 |
|---|---|
*OrderedMap |
映射,字符串键,保留插入顺序 |
[]Node |
数组 |
nil |
null / None / nil |
bool |
布尔 |
int64 |
有符号整数(首选承载) |
uint64 |
超出 int64 的无符号整数 |
*big.Int |
超出 uint64 的任意精度整数 |
float64 |
浮点;NaN/±Inf 只有 YAML 和 TOML 可编码 |
string |
文本;时间/日期一律规范化为字符串 |
其他 Go 类型一律被 Encode 拒绝。文档根必须是映射或数组,裸标量顶层返回 ErrTopLevelScalar(这是「不包含纯单值不嵌套结构」的落地)。
输入输出都必须是合法 UTF-8:Parse 在分派前校验并给出出错位置,Encode 校验字符串值与映射键。六种格式的规范都要求 UTF-8 源文本,而按字节工作的 Python / Lua 解析器会把野字节带进字符串,编码器按 rune 遍历时又会静默替换成 U+FFFD——这条往返静默损坏是 FuzzRoundTrip 发现的,现已在两端堵住,语料保留为回归种子。
OrderedMap 是 map + 双向链表,Get/Set/Delete/Len 均 O(1),Set 已存在的键就地更新不改变位置。它提供 All() iter.Seq2[string, Node] 供 range-over-func 遍历,Clone() 深拷贝,以及保序的 MarshalJSON()。
var pe *structure.ParseError
if errors.As(err, &pe) {
fmt.Println(pe.Format, pe.Line, pe.Column, pe.Msg)
}哨兵错误,全部支持 errors.Is:
| 哨兵 | 含义 |
|---|---|
ErrUnsupportedStructure |
目标格式无法表示该结构(同时匹配 errors.ErrUnsupported) |
ErrTooDeep |
嵌套超过 10000 层 |
ErrTopLevelScalar |
根不是映射或数组 |
ErrDuplicateKey |
重复映射键(JSON / YAML / Python 拒绝) |
编码侧的拒绝项:
| 目标格式 | 顶层数组 | nil 值 | NaN/±Inf | 其他限制 |
|---|---|---|---|---|
| JSON | ✅ | ✅ | ❌ | — |
| YAML | ✅ | ✅ | ✅ | — |
| TOML | ❌ 根须是表 | ❌ 无 null | ✅ | 整数上限 int64,uint64/big.Int 越界报错 |
| Lua | ✅ | 数组元素 ❌ / map 键跳过 | ❌ | 哈希段键排序输出 |
| Python | ✅ | ✅ | ❌ | — |
| JS | ✅ | ✅ | ❌ | 输出即 JSON 文本 |
解析侧的子集约定:
- Lua:
parsing.ParseExp解析表构造器字面量。表要么是纯数组段,要么是纯字符串键哈希段,混合报错;函数、调用、算术表达式一律拒绝;k = nil按 Lua 语义删除该键。 - Python:手写递归下降,对齐
ast.literal_eval。支持三引号、r/u前缀、完整转义表、0x/0o/0b、PEP 515 下划线分隔、元组(规范化为数组)。拒绝 bytes、f-string、set、complex、\N{name}、隐式字符串拼接、非字符串 dict 键。 - JavaScript:goja 的纯解析器(只
ParseFile,绝不RunString),AST 白名单解释。对象/数组/字符串/数字/布尔/null/一元 ±数字之外全部拒绝;数组空位(elision)变nil;__proto__当普通键。 - YAML:yaml.v3 的
yaml.Node路线。不支持多文档、锚点、别名、合并键、自定义 tag、!!binary。超出 uint64 被 yaml.v3 降级为!!float的整数会按原文还原成*big.Int。 - TOML:BurntSushi 解析,再用
MetaData.Keys()的文档序把无序 map 回放成有序树(表数组的每个元素靠游标定位,嵌套[[a.b]]在每个新a元素里重新计数)。内联表没有可恢复的顺序,按键名排序保证确定性。四种时间类型全部规范化为字符串。
- YAML 不保留注释、锚点、别名、合并键、多文档、自定义 tag、
!!binary。%YAML 1.2指令被拒绝:yaml.v3 只实现 1.1,吞掉指令按 1.1 解析会静默改变y/no、八进制等标量的含义,报错比静默降级安全。 - Lua 只支持纯数组表与纯字符串键字典表;按 Lua 5.3 词法解析,不保证 5.4 新语法。
- Python dict 键冻结为字符串;不支持 bytes / set / complex / Ellipsis /
\N{name}/ 隐式拼接。 - JS 输出即 JSON 文本(是合法的 JS 子集);数字样键在真实 JS 引擎里会被重排(ECMA-262 §10.1.11.1 的运行时行为,非本库缺陷,生成文本仍按插入序)。
- goja 以伪版本固定(上游无 semver tag),其
ast包自述接口可能变更,升级需回归。 - yaml.v3 仓库已 archived;v3.0.1 代码稳定、零依赖,仍是事实标准。
OrderedMap层已隔离该依赖,长期可评估切换。 - TOML 时间值转换后是字符串(语义降级,往返不等型)。
- 深度上限 10000 硬编码(对齐标准库
encoding/json与encoding/xml先例),不可配置。Go 的栈溢出不可 recover,所以这个上限由各解析器显式检查。 - 保序只对 JSON / YAML / Python / JS 有语义保证。TOML 表内顺序、Lua 哈希顺序在各自规范里都无意义,本库输出确定但不承诺与输入一致。
- 输入输出一律要求合法 UTF-8,不支持其他编码,也不为野字节提供逃逸表示。需要处理二进制请先自行转成 base64 等文本形式。
- 不含 XML。XML 的数据模型(属性、混合内容、单根、值无类型)与这里的 Node 模型不同构,硬塞进来只能靠
@attr/#text这类约定,往返语义不干净,故整包移除。 - Go 的 map 装不住顺序,所以
FromAny对它一律sort.Strings换确定性(KeepOrder()也不例外),ToAny方向则无从补救——要顺序就别转成原生 map,Encode与json.Marshal都直接吃Node。KeepOrder()能保下的只有输入里已有的*OrderedMap,且这层顺序仍可能被 TOML / Lua 编码器丢掉(见第 9 条)。 FromAny的输入必须是树。自引用环会撞上MaxDepth变成可恢复的ErrTooDeep,但共享的无环子树(DAG)不去重:每个引用都会被展开,60 层同一个子树出现两次就是 2^60 条路径。有共享结构请自己先去重。
go test ./... # 全量
go test -race ./... # 竞态
bash scripts/coverage.sh # 覆盖率门禁(默认 95%)
go test -bench=. ./... # 基准测试按符号归属分布:某个断言测什么符号,就放在那个符号所在的包里。node 的承载与校验测试在 node/,format 的枚举与位置计算在 format/,每种格式的解析/编码分支在 codec/<格式>/,其中依赖未导出符号的少数用例(如 TOML 的游标编码、YAML 的 plainSafe、各编码器 validate 之后不可达的防御分支)用同包测试直接驱动。夹具集中在 internal/nodetest,各包共用。
门面自己的契约——跨格式一致性、格式归属、Parse/Encode 两端的整篇拒绝——放在 tests/。根包目录下没有测试文件,所以 structure.go 的覆盖率靠 tests/ 经 -coverpkg=./... 回填;go test ./... 里根包显示 [no test files] 是预期的。这样做的代价是门面的未导出符号不能再被测试直接调用,收益是这些断言只能走公开面,与真实调用者同路。
测试面:
- 36 格转换矩阵:六格式两两互转全组合,共享嵌套/顶层数组/空容器夹具,TOML 目标附带顶层数组的错误期望。
- Round-trip:每格式
Parse(Encode(n))深等值。比较器nodeEqual对保序格式逐位置比键,对无序格式只比键值;浮点按位比较且 NaN==NaN;整数跨int64/uint64/*big.Int承载做数值比较。 - 等价链:
JSON→YAML→TOML→JSON ≡ JSON→TOML→JSON;另有JSON→Lua→JSON一条,用无序比较验证丢序格式仍然保值。 - 错误面:每格式的非法语法、顶层标量、超深(10001 层 →
ErrTooDeep,1000 层通过)、重复键,以及各格式特有的拒绝项。 - 原生 any 转换:逐类型钉承载(不只比数值——
uint落int64或int落float64都会数值相等而破坏阶梯)、拒绝清单逐类型、深度边界 10000/10001、自引用环与相互引用、不改动调用方输入。门面侧另测转换结果能喂给全部六个编码器,以及ToAny输出能过json.Marshal。 - 键序两模式:模式 × 结构矩阵(纯 Go map/纯
*OrderedMap/两种互相嵌套/数组内含映射/空映射/空字符串键/深层嵌套)每格两种模式各验一次,期望值写成整棵树的 JSON 文本——*OrderedMap自带的MarshalJSON按插入序输出,一个字符串就把每一层的键序钉住。两种模式各跑 50 次重复确认键序恒定(Go 随机化 map 遍历,未排序的实现几次内就会红),ToAny(n, KeepOrder())与Clone(n)用有序比较对齐并单独验*big.Int真被拷贝,另有 8 goroutine 混跑两种模式的-race用例钉住「模式是值不是状态」。 - Fuzz:
FuzzParse(断言永不 panic、根必为容器、返回的 Node 通过validate)与FuzzRoundTrip(Encode→Parse→深等值);tests/testdata/fuzz/FuzzParse/每格式 ≥3 条真实种子(语料按包目录定位,所以它跟着测试一起放在tests/下)。种子的第一个字节是格式选择器,按Format序数索引,所以序数只增不改(移除 XML 时做过一次紧凑重排,语料在同一个提交里同步改了选择字节;format包有测试把序数钉死)。 - Benchmark:各格式 Parse/Encode 与代表性 Convert 路径,
b.Loop()+ReportAllocs+SetBytes。
覆盖率门禁默认 95%,可用环境变量覆盖:
COVERAGE_THRESHOLD=97 bash scripts/coverage.sh| 依赖 | 用途 |
|---|---|
gopkg.in/yaml.v3 |
YAML 的 yaml.Node 保序解析与编码 |
github.com/BurntSushi/toml |
TOML 解析(MetaData.Keys() 提供文档序) |
github.com/arnodel/golua |
Lua 表达式解析器(纯解析,无 VM) |
github.com/dop251/goja |
JavaScript 解析器(只用 parser/ast,不启动运行时) |
JSON 走标准库,TOML、Lua、Python、JS 的编码器全部手写。