用途
该技能用于在 litellm-rust 中新增或修改以单个字符串表示的枚举,或梳理手写的字符串转换代码。核心目标是在引入 Strum 与 serde_with 的同时,保持解析行为、线上取值(wire values)以及生成的 schema 不变。
表示方式的选择
对于拼写固定、且需要未知字符串回退的枚举,推荐同时使用 strum::EnumString 与 strum::Display,并配合 serde_with::DeserializeFromStr 与 serde_with::SerializeDisplay。每个线上拼写应写在 Strum 属性中,而不是在手写的 Serde match 中重复。
Strum 实现的是字符串转换 trait,而非 Serde trait:EnumString 实现 FromStr,Display 负责格式化线上字符串,两个 serde_with derive 负责把这些 trait 接入 Serde。AsRefStr 提供借用字符串访问器,属于可选项。
示例:
#[derive(
Clone,
Debug,
PartialEq,
Eq,
strum::AsRefStr,
strum::EnumString,
strum::Display,
serde_with::DeserializeFromStr,
serde_with::SerializeDisplay,
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))]
pub enum EventType {
#[strum(serialize = "event.created")]
Created,
#[strum(default, transparent)]
Other(String),
}
每个变体应使用 #[strum(serialize = "...")] 显式拼写,不要使用 serialize_all。当存在多个可接受的别名时,应把 to_string 设为既有的规范输出,否则 Strum Display 会选择最长的 serialize 拼写。
只使用契约所需的 derive:仅需反序列化的类型应保持仅反序列化;不要为封闭枚举添加未知变体,也不要为当前没有序列化契约的类型派生 Serde。
对于封闭的单元枚举,使用带 rename 或 rename_all 的普通 Serde derive 仍然合适。仅为替换可用的 Serde derive 而引入 Strum 与 serde_with 价值不大。当某类型同时具有 Serde 与 Strum 解析时,在共享解析器前应比较两者接受的输入:Strum 的大小写不敏感解析不应让严格的 JSON 解析也变得大小写不敏感。
迁移时保持行为
修改前应先阅读类型、其调用方以及现有测试。需要保持的行为包括:规范输出、可接受的别名、大小写敏感性、空白处理、未知值、畸形输入拒绝,以及现有的公开转换契约。仅委托给 Strum 派生 trait 的包装器应被移除,调用方直接使用 FromStr 和 From<Enum> for &'static str。即使 Serde 不再使用,只要调用方需要或出于兼容性考虑,仍应保留那些附加行为的转换。
使用工作区依赖,仅在需要时在 crate 中启用 serde_with.workspace = true。应查看 Cargo.toml 与 Cargo.lock 中的版本和已启用特性,而不是为本次重构升级依赖。
移除被替换的手写 Serde 实现和过时的 Serde 转换属性。不要将新 derive 与已经派生相同 Serde trait 的 wire_type、request_type 或 response_type 别名组合使用。应在本地展开必要的非 Serde derive 与 schema 属性,而不是为无关类型修改共享别名。
保持生成的 schema,包括标题与定义名称。开放字符串枚举需要字符串 schema,并包含未知值。当替换此前提供该 schema 的 Serde from/into 属性时,应通过 #[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))] 保留其 schema 行为,并比较完整的生成结果。schemars(with = "String") 同样生成字符串 schema,但会改变 schema 名称与标题,因此仅在其已符合契约时保留。
对于结构化字符串或 Strum 无法忠实表达的校验,应保留自定义的 FromStr 与 Display 实现,其 Serde 适配器仍可使用 DeserializeFromStr 与 SerializeDisplay。不要用字符串解析替换 JSON visitor、带标签的载荷枚举、宽松值包装器或领域转换。
若用户要求做梳理(survey),应记录候选与例外,而不迁移源码。若用户要求批准批量迁移,应先给出具体范围并等待批准。
验证契约
应使用具名 rstest 用例扩展现有的映射测试,同时断言解析到预期变体以及序列化为预期线上字符串。对于开放枚举,应包含未知字符串与空字符串;存在别名时包含可接受别名;并包含对非字符串 JSON 的拒绝。仅断言解码不能证明往返正确。
结构化解析器应使用有效与无效载荷进行测试,包括其现有错误行为。对于支持 schema 的类型,应检查字符串 schema,并在启用 schema 特性下运行受影响的 crate 测试。当转换 API 或 derive 别名发生变化时,应运行受影响的下游检查。
上游参考
本指南撰写时,工作区使用 Strum 0.28.0 与 serde_with 3.16.1。应查阅对应版本的 EnumString 文档、Display 文档、DeserializeFromStr 文档与 SerializeDisplay 文档。Schemars 文档说明了 schema 覆盖与 Serde 转换属性。