PAYATHON 2026

Rust 中 JSON 反序列化后转 u8 的 struct 应如何定义?

数据小陈

结论

建议把“加载用结构”和“最终业务结构”分开定义:HandJson/CardJson 只负责 Deserialize,Hand/Card 表示转换后的数据。转换逻辑用显式的 TryFrom 或独立函数完成。不要仅仅为了合并两个相似 struct 就引入泛型;泛型应该用来复用算法,加载阶段和业务阶段的差异,用类型名和转换逻辑表达更直接。若转换很简单,也确定以后不需要保留原始 JSON 表示,可以用 #[serde(deserialize_with = "...")] 在反序列化时直接转成 u8,但这样通常不如 DTO + 领域模型清楚,分层也更弱。

为什么分开更清楚

  • 职责不同:*Json 结构只描述 JSON 形状,Hand/Card 描述业务数据。
  • 泛型会把 Deserialize 约束和字段类型差异带进业务代码,读代码的人反而更难判断某个泛型实例处在哪个阶段。
  • String -> u8 的映射可能失败,显式转换能集中处理错误。
  • 命名能直接表达用途:看到 CardJson 就能知道它是传输或反序列化结构。

推荐写法

保留你的 DTO,再写转换:

use serde::Deserialize;
use std::convert::TryFrom;

#[derive(Debug, Deserialize)]
struct HandJson {
    hand_id: u32,
    cards: Vec<CardJson>,
}

#[derive(Debug, Deserialize)]
struct CardJson {
    rank: String,
    suit: String,
}

#[derive(Debug)]
struct Hand {
    hand_id: u32,
    cards: Vec<Card>,
}

#[derive(Debug)]
struct Card {
    rank: u8,
    suit: u8,
}

#[derive(Debug)]
enum ConvertError {
    UnknownRank(String),
    UnknownSuit(String),
}

fn rank_to_u8(rank: &str) -> Result<u8, ConvertError> {
    match rank {
        "two" => Ok(2),
        "three" => Ok(3),
        "nine" => Ok(9),
        "Jack" => Ok(11),
        // 按你的牌面规则补全其他值
        other => Err(ConvertError::UnknownRank(other.to_string())),
    }
}

fn suit_to_u8(suit: &str) -> Result<u8, ConvertError> {
    match suit {
        "Clubs" => Ok(0),
        "Diamonds" => Ok(1),
        "Hearts" => Ok(2),
        "Spades" => Ok(3),
        other => Err(ConvertError::UnknownSuit(other.to_string())),
    }
}

impl TryFrom<CardJson> for Card {
    type Error = ConvertError;

    fn try_from(c: CardJson) -> Result<Self, Self::Error> {
        Ok(Card {
            rank: rank_to_u8(&c.rank)?,
            suit: suit_to_u8(&c.suit)?,
        })
    }
}

impl TryFrom<HandJson> for Hand {
    type Error = ConvertError;

    fn try_from(h: HandJson) -> Result<Self, Self::Error> {
        Ok(Hand {
            hand_id: h.hand_id,
            cards: h
                .cards
                .into_iter()
                .map(Card::try_from)
                .collect::<Result<Vec<_>, _>>()?,
        })
    }
}

读取后转换:

let hand_json: HandJson = serde_json::from_str(&text)?;
let hand = Hand::try_from(hand_json)?;

这里的映射数值只是示例,实际牌面规则要补全。如果你说的“没有任何实现”是指连 TryFrom 都不想加,把上面的转换改成普通函数即可,例如 fn convert_hand(h: HandJson) -> Result<Hand, ConvertError>,逻辑完全一样。

另一种写法:在 Serde 反序列化时转换

如果最终只需要一种 struct,也可以让 Serde 在反序列化字段时直接调用转换函数:

use serde::{Deserialize, Deserializer};

#[derive(Debug, Deserialize)]
struct Card {
    #[serde(deserialize_with = "deserialize_rank")]
    rank: u8,
    #[serde(deserialize_with = "deserialize_suit")]
    suit: u8,
}

fn deserialize_rank<'de, D>(d: D) -> Result<u8, D::Error>
where
    D: Deserializer<'de>,
{
    let s = String::deserialize(d)?;
    rank_to_u8(&s).map_err(serde::de::Error::custom)
}

deserialize_suit 的写法和 deserialize_rank 相同,只是调用 suit_to_u8。这种方式代码更短,但会把 JSON 表示细节绑到业务 struct 上;如果以后要访问原始字符串、转换规则变复杂,或者需要保留中间数据,还是推荐前面的 DTO + 显式转换。

注意事项

  • 不要仅为合并两个相似 struct 就用泛型。泛型应该服务于可复用的逻辑,而不是掩盖阶段差异。
  • 转换可能失败时用 Result 和明确错误,不要假定所有字符串都能安全转成 u8。
  • DTO 命名用 HandJson/CardJson 或 HandDto/CardDto 都行,关键是让读者知道它只在反序列化层使用。
  • 想进一步增强类型安全,可以考虑 Rank(u8)、Suit(u8) newtype 或 enum,但会增加映射代码,按项目规模选择。
  • JSON 字段名和 struct 字段名一致时,不需要额外 #[serde(rename = "...")]。

备注:内容仅供参考。