Rust reqwest .json(&json!({ "key": "value" })) 语法讲解

在 Rust 的 reqwest 库中，.json(&json!({ "key": "value" })) 这一写法涉及两个关键点：json! 宏和借用操作符 &。以下是详细解释：

1. json! 宏的作用

json! 是 serde_json 库提供的宏，用于在编译时快速构造 JSON 数据（类型为 serde_json::Value）。它的优势包括：

• 语法简洁：直接写类似 JavaScript 的 JSON 结构，无需手动构建 serde_json::Value 或序列化结构体。
• 编译时检查：如果 JSON 格式无效（如尾随逗号），编译会报错。

示例对比：

// 使用 json! 宏（推荐）
let data = json!({ "key": "value", "num": 42 });

// 手动构建（等价但冗长）
use serde_json::{Map, Number, Value};
let mut data = Map::new();
data.insert("key".to_string(), Value::String("value".to_string()));
data.insert("num".to_string(), Value::Number(Number::from(42)));
let data = Value::Object(data);

2. 为什么需要 & 借用？

reqwest 的 .json() 方法签名如下：

pub fn json<T: Serialize + ?Sized>(self, json: &T) -> RequestBuilder

• 参数类型是 &T（通用引用），要求传入一个实现了 Serialize trait 的值的引用。
• json! 宏返回的是 serde_json::Value（已实现 Serialize），但它是临时值，直接传入会因生命周期问题被丢弃。

关键点：

• 临时值问题：如果不加 &，json! 生成的 Value 会在语句结束后被丢弃，导致悬垂引用。
• 借用延长生命周期：通过 & 借用，Value 的生命周期会延长到当前作用域结束。

错误示例（不加 &）：

// 错误！临时值被丢弃
let response = client.post(url)
    .json(json!({ "key": "value" })) // 返回的 Value 在这里被丢弃
    .send()
    .await?; // 编译错误：临时值生命周期不足

正确做法：

// 方式1：直接借用 json! 的结果
.json(&json!({ "key": "value" }))

// 方式2：显式绑定到变量（更清晰）
let payload = json!({ "key": "value" });
.json(&payload)

3. 底层原理

1. 序列化时机：
   reqwest 会在发送请求时（调用 .send().await 时）将 &T 序列化为 JSON 字节流，而非在 .json() 调用时。因此需要保证引用的数据在异步操作完成前有效。

2. 性能优化：
   借用（&）避免了不必要的内存分配，直接传递引用而非所有权。

4. 替代方案

如果不想用 json!，可以通过以下方式实现相同效果：

方案1：使用结构体 + serde

use serde::Serialize;

#[derive(Serialize)]
struct Payload {
    key: String,
    num: i32,
}

let payload = Payload { 
    key: "value".to_string(), 
    num: 42 
};
client.post(url).json(&payload).send().await?;

方案2：手动构造 Value

use serde_json::Value;

let payload: Value = serde_json::json!({ "key": "value" });
client.post(url).json(&payload).send().await?;

总结

• json!：简化 JSON 数据的构造，编译时生成 serde_json::Value。
• &：借用数据以确保生命周期覆盖异步请求的整个过程。
• 最佳实践：推荐使用 json! + 借用的组合，或定义明确的 Serialize 结构体。

这种设计体现了 Rust 对所有权和生命周期的严格管理，虽然比 JavaScript 的 fetch 更繁琐，但避免了运行时内存安全问题。