Go Marshal 输出 XML 时怎么控制根节点和属性

用 Go 的 encoding/xml.Marshal 生成对外 XML 时，根节点和属性不要交给默认命名猜测。把 XMLName 或 xml.Name 放在结构体里，使用 xml:"name,attr" 明确属性，再用 a>b 表达嵌套路径，输出结构才会和协议约定保持一致。

固定根节点优先使用 XMLName xml.Name 配合结构体标签；命名空间写入 xml.Name.Space，属性使用 ,attr，可选字段再叠加 omitempty。Marshal 不会自动添加 XML 声明，是否加声明要由调用方决定。

用 XMLName 先把根节点固定下来

Marshal 选择元素名有明确顺序：结构体的 XMLName 标签、XMLName 字段值、承载该值的字段标签、字段名，最后才是被序列化类型的名称。对外报文不要依赖最后两项，否则结构体改名可能让 XML 根节点悄悄变化。

最小模型可以把根节点、订单号、客户和明细分开。XMLName 本身不会作为普通子元素输出，它只是参与元素名称判断。

type Order struct {
	// XMLName 固定根元素为 order，避免使用 Go 类型名 Order。
	XMLName xml.Name `xml:"order"`
	ID      string   `xml:"id,attr"`
	Buyer   string   `xml:"buyer"`
	Lines   []Line   `xml:"line"`
}

type Line struct {
	// 属性名写在逗号前，字段值仍然保持普通 Go 类型。
	SKU   string `xml:"sku,attr"`
	Title string `xml:"title"`
}

如果根节点标签和外层字段标签同时定义了名称，两者需要一致；否则应先统一协议名称，再继续添加子字段。这里的 id,attr 只影响 XML 形态，不会改变 ID 在 Go 中的字段类型。

用 xml.Name 区分根节点名称和命名空间

需要命名空间时，把根节点声明成 xml.Name，并填入 Space 与 Local。Space 是命名空间标识，Local 是元素的本地名；解析器返回的 Space 通常是规范化后的命名空间 URL，而不是文档中的短前缀。

type Envelope struct {
	// Space 表达命名空间标识，Local 表达根元素本地名称。
	XMLName xml.Name `xml:"Envelope"`
	Version string   `xml:"version,attr"`
	Order   Order    `xml:"Order"`
}

func newEnvelope() Envelope {
	return Envelope{
		// 用完整 URI 表示命名空间，避免把 ns 当成协议事实。
		XMLName: xml.Name{Space: "urn:example:orders", Local: "Envelope"},
		Version: "1",
	}
}

如果协议只要求固定根节点而没有命名空间，可以只使用 xml:"Envelope" 标签，不必人为填入 Space。命名空间前缀由 XML 文档的表示方式决定，业务代码应围绕 URI 和本地名保持一致。

用 ,attr、omitempty 和嵌套路径控制字段形态

结构体标签是控制 XML 形状的主要入口。字段写成 name,attr 时会成为属性；写成 ,attr 时使用 Go 字段名作为属性名；omitempty 会在值为空时省略字段。需要稳定父子关系时，可以用 address>city 这类路径让字段落到嵌套元素中。

同一个父路径下的相邻字段可以合并到一个父元素中，但不同字段的路径要提前设计好，避免一部分数据写成属性、另一部分又误写成同名子元素。对可能为空的属性，也要确认对方协议是要求空属性，还是允许整个属性缺席。

用 MarshalIndent 和错误检查交付可读 XML

调试接口报文时，MarshalIndent 比单行 Marshal 更容易检查根节点、属性和嵌套层级。它仍然遵循同一套标签规则。成功后如果需要 XML 声明，可以显式拼接 xml.Header；该声明不是 Marshal 自动加入的内容。

func encodeOrder(order Order) ([]byte, error) {
	// 缩进只改善可读性，不改变字段映射规则。
	body, err := xml.MarshalIndent(order, "", "  ")
	if err != nil {
		// channel、function、map 等不支持的值应把错误交给上层。
		return nil, fmt.Errorf("marshal order xml: %w", err)
	}
	// Header 是可选的协议声明，需要调用方明确加入。
	return append([]byte(xml.Header), body...), nil
}

排查结果时按三层看：根节点是否和协议一致；属性是否真的用了 ,attr；嵌套字段是否使用了正确路径。若 Marshal 报错，先看结构体中是否混入了不支持的 map、函数或 channel，再检查标签路径是否互相冲突。

常见问题

为什么结构体改名后 XML 根节点也变了？

因为没有提供明确的 XMLName 标签或字段值，Marshal 会退回使用字段名或类型名。对外模型应显式声明根元素。

Space 可以直接写成 ns 吗？

不建议把短前缀当作命名空间标识。应使用协议定义的命名空间 URI，并把本地名称放在 Local 中。

属性为什么没有出现在 XML 中？

检查字段标签是否写成了 name,attr 或 ,attr，以及字段值是否被 omitempty 判定为空。

相关依据

encoding/xml 的官方文档说明了 Marshal 的元素名选择顺序、,attr、omitempty、嵌套路径和不支持类型的错误行为；xml.Name 的说明也明确区分了 Space 与 Local。实际项目中应以目标 XML 协议的命名空间、属性是否可省略和声明要求为准。

参考：Go encoding/xml 官方文档、Go 标准库 encoding/xml 源码。