serde-xml-rs 默认不支持字段重命名或属性/文本混合,因其xml映射规则隐式:字段默认为子元素,不生成属性或区分文本内容;需用#[serde(rename = "@attr")]或#[serde(rename = "$value")]等特殊语法显式控制。

为什么 serde-xml-rs 默认不支持字段重命名或属性/文本混合?
serde-xml-rs 基于 serde 的泛型机制,但它的 XML 映射规则比 JSON 更隐式:它默认把 struct 字段当子元素,不生成 XML 属性,也不区分“元素文本内容”和“子元素”。比如 #[serde(rename = "foo")] 对字段名有效,但对 XML 属性、文本节点或命名空间无效——这些需要显式标注或自定义访问器。
用 #[serde(rename = "...")] 和 #[serde(rename_attributes = "...")] 控制元素名和属性名
字段重命名只影响元素名;要生成属性,必须配合 #[serde(rename = "$value")] 或 #[serde(rename = "@attr")] 语法(注意:这是 serde-xml-rs 特有的约定,不是标准 serde)。
-
#[serde(rename = "@id")]→ 生成 XML 属性id="..." -
#[serde(rename = "$value")]→ 把字段值作为父元素的文本内容(而非子元素) -
#[serde(rename = "$text")]是别名,效果同$value - 多个
@xxx字段会合并为同一层的属性;多个$value字段会冲突,只能有一个
#[derive(Deserialize, Serialize)]
struct Person {
#[serde(rename = "@id")]
id: u32,
#[serde(rename = "$value")]
name: String,
}
序列化后是:<person id="42">Alice</person>,而不是 <person><id>42</id><name>Alice</name></person>。
如何处理混合内容(属性 + 文本 + 子元素)?
XML 允许一个元素同时有属性、文本内容和子元素(例如 <tag attr="x">text<child></child></tag>),但 serde-xml-rs 原生不支持。必须拆成三个字段,并用特殊 rename 标记:
-
#[serde(rename = "@attr")]→ 属性 -
#[serde(rename = "$value")]→ 文本内容(仅一个) - 普通字段名 → 子元素(如
child: Child)
注意:如果结构体里既有 $value 又有子元素字段,serde-xml-rs 能正确解析,但反序列化时若 XML 文本为空(如 <tag><child></child></tag>),$value 字段会得到空字符串而非 None —— 需手动用 Option<string></string> 并加 #[serde(default)] 处理。
自定义序列化/反序列化逻辑要用 serialize_with 和 deserialize_with
当内置映射不够用(比如日期格式、枚举转特定字符串、CDATA 包裹),需写独立函数并用属性标注。函数签名必须严格匹配:
- 序列化函数:
fn<s>(val: &T, ser: S) -> Result</s>,其中S: Serializer - 反序列化函数:
fn(de: D) -> Result<t d::error></t>,其中D: Deserializer
例如把 u64 时间戳转为 ISO8601 字符串写入 XML 文本:
fn serialize_ts_as_iso8601<S>(ts: &u64, ser: S) -> Result<(), S::Error>
where
S: serde::Serializer,
{
let dt = chrono::NaiveDateTime::from_timestamp_opt(*ts as i64, 0).unwrap();
ser.serialize_str(&dt.format("%Y-%m-%dT%H:%M:%SZ").to_string())
}
然后在字段上写:#[serde(serialize_with = "serialize_ts_as_iso8601")]。
真实项目中最容易被忽略的是命名空间(xmlns)和 CDATA 支持——serde-xml-rs 完全不处理它们,必须手写 XML 字符串拼接或换用 quick-xml + 手动 serde 集成。










