Leptos SSR 模式：Server Function 对外 API 调用说明

核心认知

#[server] 函数在 SSR 模式下会自动生成 HTTP API 端点，格式为 POST /api/函数名。外部系统可以直接用 HTTP 客户端调用，不需要手动注册路由。

默认编码：CBOR

Leptos 服务端和客户端之间默认使用 CBOR（二进制序列化格式，类似 JSON 的压缩版）通信
优点：体积小、解析快、两端都是 Rust 时零额外成本
缺点：非 Rust 调用方需要额外引入 CBOR 解析库

调用方 CBOR 解析方案

语言	库	用法示例
Rust	`ciborium` / `serde_cbor`	`ciborium::de::from_reader(resp)`
Python	`cbor2`	`pip install cbor2` → `cbor2.loads(resp.content)`
Go	`fxamacker/cbor`	`cbor.Unmarshal(body, &result)`

JSON 编码方案

#[server(GetUser, "/api", "GetJson")]
pub async fn get_user(user_id: i32) -> Result<User, ServerFnError> {
    // ...
}

注意：使用 "GetJson" 后，服务端强制返回 JSON，不会根据 Accept 头协商。若客户端未同步修改编码，会导致解析失败。不推荐此方式。

推荐方案：利用 Accept 头自动协商（Leptos 0.7+）

不使用第三个参数，保持默认（即编码由 Accept 头决定）：

#[server(GetUser, "/api")]
pub async fn get_user(user_id: i32) -> Result<User, ServerFnError> {
    // ...
}

内部 Leptos 前端调用

无需任何改动，客户端自动带 Accept: application/cbor，服务端返回 CBOR。

外部系统调用

请求时带上 Accept: application/json，服务端自动切回 JSON：

Rust (reqwest)

let resp = reqwest::Client::new()
    .post("https://你的域名/api/GetUser")
    .header("Accept", "application/json")
    .json(&serde_json::json!({"user_id": 42}))
    .send()
    .await?;
let data = resp.json::<serde_json::Value>().await?;

Python (requests)

resp = requests.post(
    "https://你的域名/api/GetUser",
    json={"user_id": 42},
    headers={"Accept": "application/json"}
)
data = resp.json()

总结

方案	服务端改动	客户端改动	外部调用
默认 CBOR + 外部装 CBOR 库	无	无	各语言装库解析
强制 JSON (`"GetJson"`)	有	必须同步改	直接用 JSON
Accept 头协商（推荐）	无	无	加 `Accept: application/json`

本文由萧兮的博客原创发布，欢迎转载，转载务必保留原文链接。

萧兮的博客：https://www.20010515.xyz · 原文：https://www.20010515.xyz/posts/019fc5b9-6903-79d0-826a-61ffe51cf1a3