Rust 后端开发

是什么，为什么存在

Rust 后端开发是用 Rust 实现长期运行的网络服务，而不是某一个框架的别名。典型程序监听连接，把 HTTP 请求路由到处理器，访问数据库或其他服务，再返回带状态码和正文的响应。Axum 提供 HTTP 层，Tokio 提供异步执行基础，业务模型仍由应用自己定义。

Rust 的 所有权（ownership） 和 借用（borrowing） 规则让许多资源生命周期错误在编译期暴露。服务可以在没有垃圾回收停顿的情况下管理内存，也能用类型区分已验证输入、领域错误和公开响应。不过，编译通过不代表授权正确、查询有界或操作可安全重试。

当尾延迟、资源占用、长期稳定性或安全并发值得额外工程成本时，你会遇到 Rust 服务。它也适合基础设施组件，以及需要与现有 Rust 库共享类型和内存布局的 API。若工作主要是常规 CRUD，团队又缺少 Rust 经验，成熟度更高的现有技术栈可能交付得更快。

本页选择 Axum 而不重复展示多个框架。它的处理器直接使用普通异步函数，并复用 Tower 的服务与中间件模型，因此请求边界、状态和错误都容易单独测试。数据库、认证和部署分别由相关专题负责，这里只说明它们接入 HTTP 层时必须保留的边界。

文中的版本组合是 Rust 1.98、Axum 0.8.9、Tokio 1.53.1 和 Tower 0.5。版本号很重要：Axum 0.8 的动态路由写作 /{order_id}，旧资料中的 /:order_id 不能当作当前语法复制。

工作原理

Tokio 是一个 异步运行时（async runtime） 。Rust 的 async fn 产生惰性的 Future；只有运行时持续轮询它，内部工作才会推进。等待套接字或计时器时，任务把执行线程还给运行时，而不是为每个请求占住一个操作系统线程。

Axum 的 Router 实现 Tower Service 抽象。路由先按 HTTP 方法与路径选择处理器，然后 请求提取器（request extractor） 从路径、查询、请求头、扩展、状态或正文构造带类型的参数。处理器返回实现 IntoResponse 的值，Axum 再把它转换为 HTTP 响应。

所有权仍然贯穿这条异步路径。处理器取得的路径值和 JSON 值通常由当前请求拥有，共享服务则常放在 Arc 中并通过 State 克隆轻量句柄。编译器会拒绝悬垂引用，却不会替你决定状态应该属于一次请求、一个租户还是整个进程。

一次请求的路径

请求按下面的顺序穿过应用：

1. 监听器接受连接，HTTP 实现解析请求头和正文帧。
2. Router 按方法和路径匹配路由。
3. 外层 Tower 层（Tower layer） 执行超时、追踪或认证等横切逻辑。
4. 提取器按参数声明读取请求部件；失败时可直接生成拒绝响应。
5. 处理器调用领域服务和 I/O 适配器。
6. 返回值或带类型的错误经 IntoResponse 转为状态码、响应头和正文。
7. 中间件完成返回路径，HTTP 实现发送响应。

提取器不是字段注解的装饰语法。实现 FromRequestParts 的提取器只读取请求部件，可以组合多个；消费正文的 FromRequest 提取器必须是处理器的最后一个参数。把 Json<T> 放在仍需读取请求部件的参数之前，通常会得到处理器 trait 错误，而不是运行时自动调整顺序。

路径和查询字符串到整数的转换可能失败，JSON 也可能格式错误或不符合 Serde 模型。此时处理器根本不会执行。公开 API 应决定是保留框架默认拒绝格式，还是在边界统一映射为自己的错误契约。

状态、错误与中间件

应用状态必须满足路由在并发任务间共享它的要求，常见形态是包含连接池客户端的可克隆结构。Arc 只提供共享所有权；内部数据是否需要 Mutex、RwLock、通道或单一任务所有者，取决于更新方式。不要因为编译器接受 Arc<Mutex<_>> 就把整个服务状态塞进一把锁。

业务错误应映射为稳定且有意选择的 HTTP 状态。资源不存在、输入无效、版本冲突和内部依赖失败不是同一种错误；将它们全部变成 500 会破坏客户端契约，将内部错误文本原样返回又可能泄漏实现细节。

中间件适合处理多个路由共享的横切行为，例如请求 ID、追踪、正文上限和认证入口。资源级授权仍需要知道正在访问哪个对象，通常应放在带租户范围的查询或领域服务中。中间件的嵌套顺序会改变哪些响应被记录、哪些错误受超时约束，必须用请求级测试固定下来。

示例

三个示例共用下面的清单，并分别保存为 src/bin/typed_get.rs、src/bin/create_order.rs 与 src/bin/blocking_timeout.rs。所有输出均由本地 cargo +1.98.0 run --quiet --bin <name> 实际生成。

[package]
name = "codewiki-rust-backend"
version = "0.1.0"
edition = "2024"

[dependencies]
axum = "=0.8.9"
serde = { version = "1", features = ["derive"] }
tokio = { version = "=1.53.1", features = ["macros", "rt-multi-thread", "sync", "time"] }
tower = { version = "0.5", features = ["util"] }

测试带类型的 GET 路由

第一个程序不绑定端口，而是把请求直接交给 Router。这样仍会执行真实的路由、提取与响应转换，同时输出保持确定，测试也不依赖可用端口。

Path<u64> 同时声明数据来源和转换目标。若片段不是合法的 u64，提取器在调用 get_order 前拒绝请求；处理器因此只接收已经完成这一步结构转换的值。

示例限制响应读取为 1024 字节，避免测试工具无界收集正文。真实客户端与服务端同样需要大小限制，但上限必须来自自己的消息契约，而不是复制示例数字。

验证 JSON 并注入状态

第二个程序加入 State 与 Json。AtomicU64 只是可克隆状态中的最小示例；它生成进程内编号，不是跨重启或多副本可用的数据库 ID 策略。

use axum::{body::{Body, to_bytes}, extract::State, http::{Request, StatusCode}, routing::post, Json, Router};
use serde::{Deserialize, Serialize};
use std::sync::{atomic::{AtomicU64, Ordering}, Arc};
use tower::ServiceExt;

type NextId = Arc<AtomicU64>;

#[derive(Deserialize)]
struct NewOrder { sku: String, quantity: u32 }

#[derive(Serialize)]
struct Order { id: u64, sku: String, quantity: u32 }

async fn create_order(State(next_id): State<NextId>, Json(input): Json<NewOrder>)
    -> Result<(StatusCode, Json<Order>), (StatusCode, &'static str)>
{
    if input.quantity == 0 {
        return Err((StatusCode::UNPROCESSABLE_ENTITY, "quantity must be positive"));
    }
    let order = Order {
        id: next_id.fetch_add(1, Ordering::Relaxed),
        sku: input.sku,
        quantity: input.quantity,
    };
    Ok((StatusCode::CREATED, Json(order)))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/orders", post(create_order))
        .with_state(Arc::new(AtomicU64::new(1)));
    for payload in [r#"{"sku":"KB-87","quantity":0}"#, r#"{"sku":"KB-87","quantity":2}"#] {
        let request = Request::post("/orders").header("content-type", "application/json")
            .body(Body::from(payload)).unwrap();
        let response = app.clone().oneshot(request).await.unwrap();
        let status = response.status();
        let body = to_bytes(response.into_body(), 1024).await.unwrap();
        println!("{} {}", status, String::from_utf8(body.to_vec()).unwrap());
    }
}

422 Unprocessable Entity quantity must be positive
201 Created {"id":1,"sku":"KB-87","quantity":2}

Json<NewOrder> 负责 JSON 语法和字段类型，处理器再执行 quantity > 0 这条业务边界。生产代码还应限制 SKU 格式和数量上限，并把验证失败转换为统一错误结构；类型为 u32 只排除了负数。

成功分支显式返回 201 Created，错误分支显式返回 422 Unprocessable Entity。这比所有分支都返回一个 JSON 对象更准确，因为客户端首先依赖状态码判断 HTTP 结果类别。

看清阻塞任务的超时

第三个程序展示一个容易被误解的边界。对 spawn_blocking 的 JoinHandle 等待超时，只表示等待者超过截止时间；已经开始的阻塞闭包不会因此停止。

use std::{
    sync::{
        Arc,
        atomic::{AtomicBool, Ordering},
    },
    time::Duration,
};
use tokio::{task, time::{sleep, timeout}};

#[tokio::main]
async fn main() {
    let finished = Arc::new(AtomicBool::new(false));
    let worker_flag = Arc::clone(&finished);

    let blocking_job = task::spawn_blocking(move || {
        std::thread::sleep(Duration::from_millis(100));
        worker_flag.store(true, Ordering::SeqCst);
    });

    if timeout(Duration::from_millis(5), blocking_job).await.is_err() {
        println!("deadline exceeded");
    }
    sleep(Duration::from_millis(150)).await;
    println!("blocking job finished: {}", finished.load(Ordering::SeqCst));
}

deadline exceeded
blocking job finished: true

真实阻塞工作应支持协作式停止，例如定期检查取消标志，或由外部进程提供可终止边界。若工作会修改外部系统，还要定义超时后的结果未知状态；不能因为调用方已返回超时，就假设副作用没有发生。

spawn_blocking 适合短而有界、无法异步化的阻塞调用。大量 CPU 工作需要单独限制并行度，持续循环则更适合专用线程或进程；Tokio 的阻塞线程池不是无界任务队列的容量规划方案。

陷阱

在异步处理器中直接阻塞

修复方法： 优先使用异步 API。短而有界的遗留阻塞调用可交给 spawn_blocking，同时限制并发、设置上层截止时间，并明确阻塞闭包开始后无法靠丢弃句柄停止。

跨越 .await 持有不合适的锁

修复方法： 在 .await 前缩小锁作用域并复制所需数据，完成 I/O 后再短暂加锁提交结果。确实需要跨等待持锁时才使用 Tokio 的异步锁，并检查锁顺序、争用与取消路径。

把类型安全当成输入与授权安全

修复方法： 分开定义传输模型、已验证领域输入和公开响应模型。让认证建立主体，让带主体或租户范围的查询执行授权，并对边界值、第二个租户和额外字段写测试。

把超时当成回滚

修复方法： 为写操作设计幂等键、事务或可查询操作状态，并把结果未知当作显式状态。需要停止本地异步任务时保存句柄并协调取消；不要只丢弃 JoinHandle，因为丢弃会让任务分离运行。

让队列、正文与扇出无界增长

修复方法： 在入口限制正文和并发，用有界通道或信号量把容量反馈给生产者，并为溢出选择明确行为。负载测试应覆盖慢下游和取消，而不只测正常吞吐。

复制过期的 Axum 接口

修复方法： 先确认 Cargo.lock 和当前版本文档，再把错误缩减为最小处理器。Axum 0.8 使用 /{id} 路径语法；为复杂处理器启用 Axum 的 debug_handler 可得到更直接的诊断，但最终仍要理解缺失的 trait 约束。

延伸阅读

• Rust 1.98 所有权章节
• Axum 0.8.9 文档
• Axum 请求提取模块
• Tokio 1.53.1 文档
• Tokio spawn_blocking 文档
• Tokio 优雅关闭指南