在 Rust 中使用 Serde 处理json

xuejianxinokok2024-03-13 14:22

在 Rust 中使用 Serde 处理json

在本文中，我们将讨论 Serde、如何在 Rust 应用程序中使用它以及一些更高级的提示和技巧。

什么是serde？

Rust中的serde crate用于高效地序列化和反序列化多种格式的数据。它通过提供两个可以使用的traits来实现这一点，这两个traits为 Deserialize 和 Serialize 。作为生态系统中最著名的 crate 之一，它目前支持 20 多种类型的序列化（反序列化）。

首先，您需要将 crate 安装到您的 Rust 应用程序中：

bash 复制代码 
cargo add serde

使用serde

Deserializing and Serializing 数据

序列化和反序列化数据的简单方法是添加 serde derive 功能。这会添加一个宏，您可以使用它来自动实现 Deserialize 和 Serialize traits - 您可以使用 --features 标志（短的 -F 来实现）：

bash 复制代码 
cargo add serde -F derive

然后我们可以将宏添加到我们想要实现 Deserialize 或 Serialize 的任何结构体或枚举中：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct MyStruct {
    message: String,
    // ... the rest of your fields
}

这允许我们使用任何支持 serde 的crate 在所述格式之间进行转换。作为示例，让我们使用 serde-json 与 JSON 格式相互转换：

rust 复制代码 
use serde_json::json;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct MyStruct {
    message: String,
}

fn to_and_from_json() {
    let json = json!({"message": "Hello world!"});
    let my_struct: MyStruct = serde_json::from_str(&json).unwrap();

    assert_eq!(my_struct, MyStruct { message: "Hello world!".to_string());

    assert!(serde_json::to_string(my_struct).is_ok());
}

如果您有兴趣在 Rust 应用程序中使用 serde-json ，我们有一篇讨论JSON 解析库的文章，您可以在此处查看。

我们还可以对许多源进行反序列化和序列化，包括文件流 I/O、JSON 字节数组等。

自定义实现反序列化和序列化

为了更好地理解 serde 在底层是如何工作的，我们还可以自定义实现 Deserialize 和 Serialize 。这相当复杂，但现在我们将实现一个简单的。下面是序列化 i32 基元类型的简单实现：

rust 复制代码 
use serde::{Serializer, Serialize};

impl Serialize for i32 {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_i32(*self)
    }
}

为了能够转换类型， serde 内部要求我们使用实现 Serializer 的类型。要为不是原生(primitive)类型 实现 Serialize ，我们可以通过序列化为原生(primitive)类型来扩展它，然后从原生(primitive)类型转换为我们想要的任何类型。如果我们想要对结构进行自定义序列化，我们也可以使用 SerializeStruct trait来执行相同的操作：

rust 复制代码 
use serde::ser::{Serialize, Serializer, SerializeStruct};

struct Color {
    r: u8,
    g: u8,
    b: u8,
}

impl Serialize for Color {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        // 3 is the number of fields in the struct.
        let mut state = serializer.serialize_struct("Color", 3)?;
        state.serialize_field("r", &self.r)?;
        state.serialize_field("g", &self.g)?;
        state.serialize_field("b", &self.b)?;
        state.end()
    }
}

注意，要序列化字段，字段类型还需要实现 Serialize 。如果有未实现 Serialize 的自定义类型，则需要实现 Serialize 或使用 Serialize derive宏（如果结构体/枚举 类型 包含所有实现 Serialize 的类型）。

The Deserialize trait is a little bit different and is a fair bit more complicated to implement. To be able to deserialize to a type, the type itself needs to implement Sized which means that there are a number of types which can't use this trait (for example &str) because they are unsized types. To deserialize a type, you also need to use a type that implements the Visitor trait.
Deserialize trait 有点不同，并且实现起来要复杂一些。为了能够反序列化为类型，类型本身需要实现 Sized 这意味着有许多类型不能使用此特征（例如 &str ），因为它们是unsized 类型。要反序列化类型，您还需要使类型实现 Visitor trait。

Visitor trait使用 Rust 中的 Visitor 设计模式。这意味着它封装了一种对相同大小的对象集合进行操作的算法。它允许您编写多种不同的算法来操作数据，而无需更改任何原始功能。您可以在这里了解更多相关信息。

下面是一个 MessageVisitor 类型的示例，该类型尝试将多种类型反序列化为 String：

rust 复制代码 
use std::fmt;

use serde::de::{self, Visitor};

struct MessageVisitor;

impl<'de> Visitor<'de> for MessageVisitor {
    type Value = String;

    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
        formatter.write_str("A message that can either be deserialized from an i32 or String")
    }

    fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
    where
        E: de::Error,
    {
        Ok(value)
    }

    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
    where
        E: de::Error,
    {
        Ok(value.to_owned())
    }

    fn visit_i32<E>(self, value: i32) -> Result<Self::Value, E>
    where
        E: de::Error,
    {
        Ok(value.to_string())
    }
}

正如您所看到的，实现的代码量相当大！然而，它也使我们能够使实现变得更加简单。通过实现 Visitor 特征，可以将实现它的类型传递给 Deserialize 方法，然后将 JSON 反序列化到我们的结构中：

rust 复制代码 
use serde::{Deserialize, Deserializer};

impl<'de> Deserialize<'de> for MyStruct {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        // note: don't use unwrap in production!
        let message = deserializer.deserialize_string(MessageVisitor).unwrap();
        Ok(Self { message })
    }
}

您还可以在此处找到有关反序列化结构的文档。但是，一般来说，建议您使用 derive 功能宏，因为手动实现（如前面所示）代码量相当大。该实现主要涉及使用访问者来访问映射或序列，然后迭代元素以将其反序列化。

使用 serde 属性

当涉及到 serde 时，crate 还具有许多有用的属性宏，我们可以在类型上使用它们，以允许在反序列化字段或序列化为结构时进行字段重命名等操作。最好的例子之一是当您与用某种语言编写的 API 进行交互时，该语言的键可能是 Rust 中的保留关键字。您可以添加 #[serde(rename)] 属性宏，如下所示：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
pub struct MyStruct {
    #[serde(rename = "type")]
    kind: String
}

这可以让您解决名称冲突的问题！

您还可以使用 rename_all 属性将所有字段重命名为另一个大小写：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MyStruct {
    my_message: String
}

现在，当您序列化此结构时， my_message 应该自动变成 myMessage ！非常适合使用以其他语言或不同约定编写的 API。

如果您不想将字段包装在 Option 中，您还可以使用 #[serde(default)] 实现默认值。这只是允许用默认值填充字段，而不是 报错。您还可以使用 #[serde(default = "path")] 来指向提供自动默认值的函数。例如，这个结构体和函数：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
pub struct MyStruct {
    #[serde(path = "my_function")]
    my_message: String,
}

fn my_function() -> String {
    "Hello world!".to_string()
}

serde 还提供其他有用的属性，例如能够在结构顶部使用 #[serde(deny_unknown_fields)] 拒绝未知字段。这使您可以确保序列化和反序列化时结构完全按原样。

Deserializing and Serializing enums

让我们看一下这个枚举类型：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
enum MyEnum {
    Data { id: String, data: Value },
    SomeOtherData { id: i32, name: String }
}

请注意，在与此枚举进行转换时，可以采用两个选项：

  • 名为 id 的字符串字段和 data 这是一个 JSON 值（可以是map、值或 Json 值可以保存的任何内容）
  • 名为 id 的 i32 字段和名为 name 的 String 字段

然后，您可以匹配枚举变量以进行进一步处理。

当第一个枚举变体用 JSON 编写时，您可以看到它应该与此对应：

json 复制代码 
{
    "Data": {
        "id": "your_id_here",
        "data": { .. }
    }
}

这种类型的数据是"外部标记的"------这意味着数据的特征是标识符位于 JSON 对象的外部。我们可以添加内联标记，以便标识符位于crate的内部 - 让我们看看它会是什么样子：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
#[serde(tag = "type")]
enum MyEnum {
    Data { id: String, data: Value },
    SomeOtherData { id: i32, name: String }
}

现在 JSON 表示如下所示：

json 复制代码 
{
    "type": "Data",
    "id": "your_id_here",
    "data": { .. }
}

有兴趣阅读更多内容吗？ serde 文档有一个关于tag 的页面，您可以在此处Enum representations · Serde找到。

Crates that work well with Serde

serde_with

serde_with 是一个提供自定义反/序列化 帮助程序的包，可与 serde 的 with 注释一起使用。通常，您可以定义一个模块供（反）序列化器使用，该模块位于用于自定义（反）序列化的自定义模块之后：

rust 复制代码 
#[derive(Deserialize, Serialize)]
pub struct MyStruct {
    #[serde(with = "my_module")]
    my_message: String
}

使用 serde_with 时，它的工作原理是用名为 serde_as 的新注释替换 with 注释。使用这个新的属性宏，您可以做很多事情：

  • 使用 Display 和 FromStr traits反序列化类型。
  • 支持大于 32 个元素的数组。
  • 跳过序列化空选项类型。
  • 将逗号分隔的列表反序列化为 Vec<String> 。

要使用 serde_with ，您需要手动或使用以下命令将其添加到 Cargo.toml 中：

bash 复制代码 
cargo add serde_with

然后您需要将 serde_as 添加到您想要使用它的类型，如下所示：

rust 复制代码 
use serde_with::{serde_as, DisplayFromStr};
#[serde_as]
#[derive(Deserialize, Serialize)]
struct MyStruct {
    // Serialize with Display, deserialize with FromStr
    #[serde_as(as = "DisplayFromStr")]
    my_number: u8,
}

该结构允许您与字符串相互转换，但 Rust 结构中的类型本身为 u8 ！非常有用，对吧？

这个crate还附带了一个指南，您可以使用它来充分利用 serde_with 。总的来说，这是 serde 的一个强大的伴侣crate。

serde_bytes

serde_bytes 是一个允许优化处理 &[u8] 和 Vec<u8> 类型的包 - 而 serde 本身能够处理这些类型，某些格式可以更有效地反/序列化。使用起来非常简单 - 您只需将其添加到 Cargo.toml 中，然后通过 #[serde(with = "serde_bytes")] 注释添加它，如下所示：

rust 复制代码 
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct MyStruct {
    #[serde(with = "serde_bytes")]
    byte_buf: Vec<u8>,
}

总的来说，这是一个易于使用且简单的 crate，无需太多知识即可提高性能。

尾声

我希望您喜欢阅读有关 Serde 的文章！它是一个非常强大的 Rust 包，构成了大多数 Rust 应用程序的基础。

Using Serde in Rust

相关推荐
萧瑟余晖1 小时前
JDK 26 新特性详解
java·开发语言
马优晨1 小时前
Freemarker 完整讲解（后端 Java 模板引擎）
java·开发语言·freemarker·freemarker 完整讲解·freemarker模板引擎
doiito3 小时前
【AI 应用】从“外国人味”到地道中文：kokoroi-rs v0.1.2 架构升级深度解析
ai·rust·系统设计
人邮异步社区3 小时前
怎么把C语言学到精通？
c语言·开发语言
心平气和量大福大4 小时前
C#-WPF-控件-TextBox 数据绑定
开发语言·c#·wpf
ttwuai4 小时前
Cursor 生成 CRUD 后，Go 后台接口别只测 200：JWT、RBAC 和 tenant_id 怎么验
开发语言·后端·golang
维天说4 小时前
CLI-Switch 2026年3月版历史设计：Hook、TTY 隔离与 JSON 状态
java·服务器·json
এ慕ོ冬℘゜4 小时前
前端基础：什么是时间戳？JS获取时间戳三种方法与实战用途
开发语言·前端·javascript
执明wa4 小时前
LayoutInflater详解: XML是如何变成View的？
android·xml·开发语言·android studio
一次旅行4 小时前
Python+大模型端到端自动化日报系统
开发语言·python·自动化
热门推荐
01GitHub 镜像站点022026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片03如何新建文件夹？ 电脑新建文件夹的4种方法04国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）05AI科技热点日报 | 2026年07月01日06幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路08微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新09【解构】DeepSeek V4 发布：技术报告深度解读 + 横向对比六大开源模型，我们的判断是……102026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？