Go encoding/xml把 XML 属性映射到结构体的标签写法

Go 的 encoding/xml 映射 XML 属性时，关键不是字段名，而是结构体标签里的 ,attr：例如 xml:"id,attr" 会把 的 id 放进结构体。字段必须是可导出的；属性缺失时，普通字段得到零值，指针字段则可以保留“没有提供”的区别。

最小写法是 Field string `xml:"name,attr"`。需要兼容协议扩展时再加 []xml.Attr `xml:",any,attr"`，不要把属性误写成普通元素标签。

下面用一个设备清单的小项目串起来：先解码 XML，再处理可选属性和未知属性，最后用同一套标签编码回 XML。示例只围绕属性映射，不引入第三方 XML 框架。

先把属性标签写成 name,attr

XML 属性位于开始标签内部，结构体标签的格式是“属性名加 ,attr”。xml.Unmarshal 会按显式属性名匹配，不要求 Go 字段名与 XML 名称相同。

package main

import (
    "encoding/xml"
    "fmt"
    "log"
)

type Device struct {
    // 显式指定 XML 属性名，字段名可以保持 Go 的命名习惯。
    ID     string `xml:"id,attr"`
    Status string `xml:"status,attr"`
}

func main() {
    input := []byte(``)
    var device Device
    if err := xml.Unmarshal(input, &device); err != nil {
        // 解析失败要立刻返回，避免把半成品当成有效配置。
        log.Fatal(err)
    }
    fmt.Printf("id=%s status=%s\n", device.ID, device.Status)
}

这里的 id,attr 和 status,attr 是两个独立映射。若写成 xml:"id"，它表示寻找名为 id 的子元素，而不是读取 id="..."。同样，字段名首字母小写也不会被反射写入，配置结构体应保留导出字段。

用指针和基础类型处理空值

属性不存在与属性存在但内容为空，业务上不一定相同。字符串会得到空字符串，整数会得到零值；如果要判断“配置是否提供”，可以用指针字段。

type DeviceConfig struct {
    // 指针让缺失属性保持 nil，便于区分“未配置”和“配置为 0”。
    Retry *int  `xml:"retry,attr"`
    Debug *bool `xml:"debug,attr"`
}

func describe(cfg DeviceConfig) string {
    // 先判断指针，再解引用，避免把缺省值误当成明确配置。
    if cfg.Retry == nil {
        return "retry 未提供"
    }
    return fmt.Sprintf("retry=%d", *cfg.Retry)
}

数字和布尔属性仍会按文本转换；非法文本应让 Unmarshal 返回错误，而不是在后续业务逻辑里悄悄纠正。对于必须存在的属性，解码后应显式检查零值或指针状态。

用 any,attr 接住未列出的属性

协议经常会新增属性。把所有字段都提前写死会让结构体频繁修改；xml:",any,attr" 可以把没有被其他 ,attr 字段匹配的属性收集起来。

type DeviceEnvelope struct {
    ID      string     `xml:"id,attr"`
    Extras  []xml.Attr `xml:",any,attr"`
}

func extraValue(attrs []xml.Attr, want string) (string, bool) {
    // 只读取未知属性集合，不覆盖显式字段的协议含义。
    for _, attr := range attrs {
        if attr.Name.Local == want {
            return attr.Value, true
        }
    }
    return "", false
}

例如 firmware、region 这类扩展属性会进入 Extras。注意它不是“任意属性覆盖器”：已经被显式标签匹配的 id 不应再从扩展集合中取一遍，业务层也要定义未知属性是记录、告警还是拒绝。

把属性映射放进嵌套结构

真实清单通常有根节点和多个设备节点。根节点的属性、设备节点的属性应由各自的结构体负责，不要把所有字段平铺到一个结构体中。

type Inventory struct {
    XMLName xml.Name `xml:"inventory"`
    Source  string   `xml:"source,attr"`
    Devices []Device `xml:"device"`
}

func loadInventory(data []byte) (Inventory, error) {
    var inventory Inventory
    // XMLName 还能限制根元素名称，列表字段负责重复的 device 子元素。
    if err := xml.Unmarshal(data, &inventory); err != nil {
        return Inventory{}, err
    }
    return inventory, nil
}

这种分层让映射边界清楚：source 属于 inventory，id 属于每个 device。字段标签中的 device 是子元素匹配，和 source,attr 的属性匹配互不冲突。

用 Marshal 验收双向标签

读取成功不代表写回时一定符合协议。Marshal 对带 ,attr 的字段会生成属性；加上 omitempty 后，零值字段会被省略。

type Device struct {
    ID     string `xml:"id,attr"`
    Status string `xml:"status,attr,omitempty"`
}

func encodeDevice(device Device) ([]byte, error) {
    // MarshalIndent 只负责可读格式；属性是否出现由标签和字段值决定。
    return xml.MarshalIndent(device, "", "  ")
}

验收时重点看三件事：属性名是否仍是协议规定的名字；可选字段为空时是否应省略；未知属性是否需要在编码阶段重新保留。any,attr 更适合接收扩展，若要原样写回，还需明确编码模型和字段类型，不能默认认为解码后会自动双向无损。

速查：固定属性用 name,attr；缺失与零值要区分就用指针；扩展属性用 ,any,attr；嵌套元素仍使用普通元素路径；写回 XML 前用 MarshalIndent 检查属性名和可选字段边界。

相关问题

为什么属性字段读不到？先检查标签是否带 ,attr、字段是否导出，以及 XML 属性名是否与标签显式名称完全一致。

未知属性会自动报错吗？未匹配的属性默认不会落入普通字段；需要保留时显式增加 []xml.Attr `xml:",any,attr"`，再由业务决定如何处理。

参考资料：https://pkg.go.dev/encoding/xml