罗罗编程学习记录
本页内容 展开查看

11.8 阶段 7 Web 服务全链路

所属:全栈开发面试题库 / 学习路径 / 11 Rust 全栈

本页目录

一、阶段定位

阶段 6 让工程能在 CI 里跑起来,本阶段要把它变成一个真正能接流量的 Web 服务:axum 路由与提取器、State 共享、tower 中间件、统一错误处理、SQLx 编译期 SQL 校验、JWT 认证、OpenAPI、SSE/WebSocket、tracing 与 OpenTelemetry、优雅关闭与健康检查。这一阶段是 Rust 后端岗位最直接考察的部分,也是「Rust 全栈」里「全栈」二字的落点。

与前后阶段的衔接:往上承接阶段 5 的异步与 Tokio——axum 的 handler 是 async fn,提取器、中间件、连接池全部跑在 Tokio 上;不会 spawn_blocking、取消安全、JoinSet,本阶段写出来的服务要么阻塞执行器、要么超时丢数据。往上也承接阶段 6 的工程化——SQLx 的离线模式、testcontainers 集成测试、cargo-chef 镜像都要在这里用起来。往下接阶段 8 的生态延伸与架构收敛——CLI、Tauri、WASM、嵌入式、FFI 都是从这个服务往外长。

「怎么判断自己卡住了」:写了一个 handler 但提取器顺序报错看不懂;错误直接 unwrap() 抛 500;SQL 拼字符串没类型校验;中间件加了但没生效;优雅关闭靠 process::exit。这些都是本阶段要解决的。

二、阶段目标与投入

能力目标(可验证的行为) 验证方式
能用 axum 写出带路由、State、中间件的服务骨架 curl 命中各路由,State 全局可见
能解释提取器顺序与 FromRequestParts/FromRequest 区别 自定义提取器能正确解析请求并返回结构化错误
能用 tower-http 加 Trace/Timeout/CORS/压缩中间件 响应头有 server-timing 与压缩标识
能写统一错误结构实现 IntoResponse 业务错误返回结构化 JSON 而非裸 500
能用 SQLx query! 写编译期校验 SQL,用 PgPool 与 Transaction 改 SQL 字段名编译期就报错
能加 JWT 认证、OpenAPI 文档、SSE/WebSocket 带 token 访问受控路由通过;Swagger UI 可打开
能接 tracing + OpenTelemetry 并实现优雅关闭与健康检查 收到 SIGTERM 后在连接处理完后退出;/health 返回 200

建议学时:

  • 全职(每天 4–6 小时):2.5 周,约 70–80 小时。
  • 在职(每天 2 小时):6–8 周。

学时分配:axum 路由与 State 15%、提取器与中间件 20%、错误处理 10%、SQLx 20%、Serde/validator/JWT/OpenAPI 15%、SSE/WS/tracing/优雅关闭 20%。

三、先修自检

先修项 合格标准 不合格时回到
async/await 与 Tokio 能写 #[tokio::main]、spawn、timeout 阶段 5 并发与异步
Cargo Workspace 与 feature 能搭多 crate、开 feature 阶段 6 Cargo 工程化与质量体系
HTTP 与 JSON 知道 method/status/header/body 01 计算机基础与通用工程
SQL 基本概念 知道连接池、事务、索引 05 数据库与存储
错误处理 知道 thiserror/anyhow 分工 阶段 3 trait 与抽象设计

四、知识地图

模块 知识点 掌握程度 对应题库章节
axum 路由 Router、route、merge、nest、State 会用 04.4.3 Axum
提取器 Json/Path/Query/Extension、FromRequestParts/FromRequest 能讲清原理 06.7.1.2 提取器中间件与错误处理
中间件 tower::ServiceBuilder、TraceLayer、TimeoutLayer、CorsLayer 会用 06.7.1.2 提取器中间件与错误处理
错误处理 IntoResponse、统一错误结构、thiserror 能讲清原理 06.7.1.2 提取器中间件与错误处理
SQLx query!、PgPool、Transaction、migrate! 能讲清原理 04.4.8 数据访问
序列化与校验 serde、validator、JWT、cookie、utoipa 会用 04.4.9 序列化校验与 API 契约
认证授权 JWT、axum-extra cookie、中间件鉴权 会用 04.4.11 认证授权与 Web 安全
可观测与关闭 tracing、OpenTelemetry、SSE/WS、优雅关闭、健康检查 会用 04.4.12 可观测性与测试工程化

进度管理建议:提取器与 SQLx 编译期校验务必到「能讲清原理」。《知识点全清单》是本篇更细的全量清单。

五、分模块精讲

5.1 axum 路由、Router 合并与 State

为什么需要它:axum 是 Tokio 团队维护的 axum 框架,基于 tower,路由与状态共享是它的核心。不会 Router::merge 与 State 类型,就写不出多模块服务。

核心机制:

  • Router::new().route("/users", get(list_users).post(create_user))。
  • Router::merge(other) 合并两个路由树;nest("/api", sub) 子路由挂载。
  • State<T> 提取器:用 Router::new().with_state(app_state) 注入,handler 里写 State(state) 拿。
  • State 类型必须一致:所有子路由的 State 类型要与 with_state 的类型一致,否则编译错。
  • 路径参数:/users/:id,handler 用 Path(id): Path<u64>。
  • MethodRouter 按 method 组合:get(...).post(...)。

最小可运行示例:

// Cargo.toml: axum = "0.7", tokio = { version = "1", features=["full"] }
use axum::{routing::{get, post}, Router, extract::State, Json};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    db_url: String,
}

async fn list_users(State(state): State<AppState>) -> String {
    format!("users from {}", state.db_url)
}

async fn create_user(State(_): State<AppState>, Json(body): Json<serde_json::Value>) -> Json<serde_json::Value> {
    Json(body)
}

#[tokio::main]
async fn main() {
    let state = AppState { db_url: "postgres://localhost".into() };
    let app = Router::new()
        .route("/users", get(list_users).post(create_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

常见坑:

现象 原因 修法
State<AppState> 类型不匹配 子路由 with_state 类型不同 统一类型;复杂场景包 Arc<AppState>
路由冲突 两个 route 同路径同 method 用 merge 或拆分
MissingState 忘了 with_state 启动前调 with_state

面试考法:「axum 的 State 怎么注入」「为什么 State 要 Clone」。答到:with_state 注入,handler 用 State<T> 提取;Clone 是因为 axum 在每个请求里克隆一份(或内部 Arc 共享)。

5.2 提取器顺序与 FromRequestParts/FromRequest

为什么需要它:axum 的 handler 是「提取器」列表,提取器顺序错了就编译失败。搞懂 FromRequestParts 与 FromRequest 的边界,才能写自定义提取器。

核心机制:

  • 提取器是 handler 函数参数,按顺序从请求里提取。
  • 顺序规则:会消费请求 body 的提取器(Json<T>、String、Bytes、Request)必须放最后;只看 parts 的(Path、Query、HeaderMap、State、Extension)放前面。
  • FromRequestParts:只从 parts(路径、header、query)提取,不消费 body。
  • FromRequest:从完整请求(含 body)提取。
  • 自定义提取器:impl<S> FromRequestParts<S> for MyAuth,或 impl<S> FromRequest<S> for MyBody。
  • Json<T> 提取时要 Content-Type: application/json,否则 415。

最小可运行示例:

use axum::{extract::FromRequestParts, http::request::Parts, Request, response::IntoResponse, Json};

struct UserId(String);

// 自定义提取器:从 Authorization 头取 user id
impl<S> FromRequestParts<S> for UserId
where S: Send + Sync,
{
    type Rejection = axum::response::Response;
    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
        let header = parts.headers.get("authorization")
            .ok_or_else(|| (axum::http::StatusCode::UNAUTHORIZED, "missing auth").into_response())?;
        Ok(UserId(header.to_str().unwrap_or("").to_string()))
    }
}

// body 提取器必须放最后
async fn handler(
    UserId(uid): UserId,
    Json(body): Json<serde_json::Value>,
) -> Json<serde_json::Value> {
    Json(serde_json::json!({"user": uid, "body": body}))
}

常见坑:

现象 原因 修法
Json 提取器编译失败说它必须是最后一个参数 后面还有 Path/Query 把 body 提取器挪到最后
415 Unsupported Media Type 请求没带 Content-Type: application/json 客户端补 header;或用 Bytes 自定义
自定义提取器报 not implement FromRequest 实现错了 trait 只看 parts 用 FromRequestParts

面试考法:「提取器顺序为什么有讲究」「FromRequestParts 与 FromRequest 区别」。答到:body 只能消费一次,会消费的必须放最后;parts 不消费 body,可放前面。

5.3 中间件:tower::ServiceBuilder 与 tower-http

为什么需要它:日志、超时、CORS、压缩、追踪这些横切关注点不能写在每个 handler 里,要用中间件。tower 是 Rust 异步中间件生态的核心。

核心机制:

  • tower::ServiceBuilder::new().layer(...) 组合中间件。
  • tower-http 常用 layer:
    • TraceLayer::new_for_http():请求日志、耗时、状态码。
    • TimeoutLayer::new(Duration::from_secs(30)):全局超时。
    • CorsLayer::new():跨域。
    • CompressionLayer::new():gzip/br 压缩。
    • ServeDir/ServeFile:静态文件。
  • Router::layer(...) 把 layer 应用到整个路由;route_layer(...) 只应用到部分路由。
  • 顺序:ServiceBuilder 里写的顺序是「外层到内层」,第一个 layer 最先看到请求。

最小可运行示例:

use axum::{routing::get, Router};
use tower_http::{trace::TraceLayer, cors::CorsLayer, compression::CompressionLayer};
use tower::ServiceBuilder;
use std::time::Duration;

let app = Router::new()
    .route("/", get(|| async { "hello" }))
    .layer(
        ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(CompressionLayer::new())
            .layer(CorsLayer::permissive())
            .timeout(Duration::from_secs(30)),
    );

常见坑:

现象 原因 修法
CORS 预检失败 CorsLayer 配置太严 开发用 permissive(),生产收紧 origin
超时后 handler 还在跑 TimeoutLayer 只断连接,任务被 drop handler 内部用 tokio::time::timeout 也加
压缩没生效 响应没设 Content-Type 用 CompressionLayer 自动处理

面试考法:「tower 中间件模型」「layer 的执行顺序」。答到:Service 套 Service,layer 是装饰器;ServiceBuilder 里第一个 layer 是最外层。

5.4 错误处理:IntoResponse 与统一错误结构

为什么需要它:handler 直接 unwrap() 会返回 500 且 body 是 Rust debug 格式,前端没法处理。要把错误统一成结构化 JSON。

核心机制:

  • handler 返回 Result<T, AppError>,AppError 实现 IntoResponse。
  • thiserror 定义错误枚举;IntoResponse 把变体映射到 status code + JSON body。
  • 统一 body:{"error": {"code": "...", "message": "..."}}。
  • 错误日志:在 IntoResponse 里 tracing::error!(...),但不要把内部错误信息暴露给客户端。

最小可运行示例:

use axum::{http::StatusCode, response::IntoResponse, Json};
use serde_json::json;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum AppError {
    #[error("not found: {0}")]
    NotFound(String),
    #[error("unauthorized")]
    Unauthorized,
    #[error("db error: {0}")]
    Database(#[from] sqlx::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        let (status, code) = match &self {
            AppError::NotFound(_) => (StatusCode::NOT_FOUND, "not_found"),
            AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized"),
            AppError::Database(_) => (StatusCode::INTERNAL_SERVER_ERROR, "internal"),
        };
        (status, Json(json!({"error": {"code": code, "message": self.to_string()}}))).into_response()
    }
}

常见坑:

现象 原因 修法
客户端收到 500 且 body 是 Rust debug 直接 unwrap 了 用 Result<T, AppError> 与 ?
内部错误信息暴露给前端 self.to_string() 含 db 细节 对外用固定 message,详细错误走日志
sqlx::Error 直接返回 没实现 From #[from] sqlx::Error 自动转换

面试考法:「Rust Web 服务怎么做统一错误」。答到:thiserror 枚举 + IntoResponse impl,映射 status code 与对外 JSON;内部细节记日志。

5.5 SQLx:query! 编译期校验、PgPool、Transaction、migrate!

为什么需要它:字符串拼 SQL 在运行时才暴露错误。SQLx 用宏在编译期连数据库(或离线缓存)校验 SQL 与类型映射,是 Rust 后端的杀手锏。

核心机制:

  • sqlx::query!("SELECT id, name FROM users WHERE id = $1", user_id):宏在编译期连接数据库(或读 .sqlx 离线缓存)校验 SQL。
  • PgPool:连接池,PgPoolOptions::new().max_connections(20).connect(&url).await?。
  • query_as!(User, ...):直接映射到结构体。
  • Transaction:pool.begin().await?,tx.commit().await?,tx.rollback() 自动 drop。
  • sqlx::migrate!("./migrations"):在启动时跑迁移文件。
  • 离线模式:cargo sqlx prepare -- --lib 生成 .sqlx 目录,CI 不需要连数据库;DATABASE_URL 在开发时本机连。

最小可运行示例:

// Cargo.toml: sqlx = { version = "0.8", features = ["postgres", "runtime-tokio-rustls", "macros", "chrono"] }
use sqlx::{PgPool, FromRow};

#[derive(Debug, FromRow)]
struct User {
    id: i64,
    name: String,
}

async fn get_user(pool: &PgPool, id: i64) -> Result<Option<User>, sqlx::Error> {
    let row = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
        .fetch_optional(pool)
        .await?;
    Ok(row)
}

async fn create_user(pool: &PgPool, name: &str) -> Result<i64, sqlx::Error> {
    let mut tx = pool.begin().await?;
    let id = sqlx::query!("INSERT INTO users (name) VALUES ($1) RETURNING id", name)
        .fetch_one(&mut *tx)
        .await??;
    tx.commit().await?;
    Ok(id.id)
}
# 开发:本机起 postgres,DATABASE_URL 指向它
# CI:用离线缓存
cargo sqlx prepare --check

常见坑:

现象 原因 修法
error: error: failed to connect to database 编译期宏找不到数据库 设 DATABASE_URL 或 cargo sqlx prepare 离线
mismatched types 指向 SQL 字段 SQL 字段类型与 Rust 类型不一致 改 Rust 类型或 SQL 用 ::text 强转
事务没 commit 也没 rollback tx drop 默认 rollback 显式 tx.commit().await?
连接池打满 max_connections 太小或泄漏 调大;检查 spawn 里没 drop pool

面试考法:「SQLx 的编译期校验怎么工作」「事务边界怎么划」。答到:宏在编译期连数据库(或离线缓存)校验 SQL 与类型映射;事务用 pool.begin(),commit 显式调,drop 默认 rollback。

5.6 Serde、validator、JWT、cookie 与 OpenAPI

为什么需要它:请求校验、认证、API 文档是 Web 服务的标配。Rust 的 serde 生态把序列化与校验解耦,JWT 用 jsonwebtoken,OpenAPI 用 utoipa。

核心机制:

  • serde:#[derive(Serialize, Deserialize)],#[serde(rename_all = "camelCase")]。
  • validator:#[derive(Validate)],字段加 #[validate(length(min=1, max=50))],handler 里 body.validate()?。
  • JWT:jsonwebtoken::{encode, decode, Header, Validation},登录时签 token,中间件解码校验。
  • axum-extra cookie:CookieJar 提取器,jar.add(Cookie::new(...))。
  • utoipa:#[derive(ToSchema)],handler 加 #[utoipa::path(...)],OpenApi struct 注册路由,SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", doc)。

最小可运行示例:

use serde::Deserialize;
use validator::Validate;

#[derive(Debug, Deserialize, Validate)]
pub struct CreateUserRequest {
    #[validate(length(min = 1, max = 50))]
    pub name: String,
    #[validate(email)]
    pub email: String,
}

async fn create_user(
    Json(req): Json<CreateUserRequest>,
) -> Result<axum::Json<serde_json::Value>, axum::http::StatusCode> {
    req.validate().map_err(|_| axum::http::StatusCode::BAD_REQUEST)?;
    Ok(axum::Json(serde_json::json!({"id": 1})))
}
// JWT 签发
use jsonwebtoken::{encode, Header, EncodingKey};
let claims = serde_json::json!({"sub": "1", "exp": 1735689600});
let token = encode(&Header::default(), &claims, &EncodingKey::from_secret(b"secret"))?;

常见坑:

现象 原因 修法
校验错误没结构化 直接 validate() 抛 Err 把 ValidationErrors 转成 AppError::BadRequest
JWT 过期不生效 exp 没设或时钟偏差 Validation::default() 默认校验 exp
OpenAPI 文档与 handler 不同步 改 handler 没改 #[utoipa::path] 用 utoipa 自动生成;CI 校验

面试考法:「Rust 怎么做请求校验」「JWT 怎么存」。答到:serde 反序列化 + validator 字段校验;JWT 放 Authorization header 或 HttpOnly cookie。

5.7 SSE、WebSocket、tracing、OpenTelemetry 与优雅关闭

为什么需要它:实时推送、全链路追踪、优雅关闭是生产服务的最后一公里。不会 SSE/WS 写不了实时接口,不会优雅关闭 K8s 滚动更新时会丢请求。

核心机制:

  • SSE:axum::response::sse::{Sse, Event},handler 返回 Sse::new(stream),用 async_stream 或 tokio::select! 推事件。
  • WebSocket:axum::extract::ws::{WebSocketUpgrade, WebSocket},handler 用 ws.on_upgrade(handle_socket)。
  • tracing:tracing_subscriber::fmt(), #[tracing::instrument];tracing-opentelemetry 接 OTLP。
  • OpenTelemetry:opentelemetry crate + OTLP exporter,把 trace 发到 Jaeger/Tempo。
  • 优雅关闭:axum::serve(listener, app).with_graceful_shutdown(shutdown_signal());shutdown_signal 里 tokio::signal::ctrl_c() 与 SIGTERM。
  • 健康检查:/health/live(存活,永远 200)、/health/ready(就绪,检查 db 连接池可用)。

最小可运行示例:

use axum::response::sse::{Sse, Event};
use futures::stream::Stream;
use std::time::Duration;
use tokio_stream::wrappers::IntervalStream;

async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, std::io::Error>>> {
    let stream = IntervalStream::new(tokio::time::interval(Duration::from_secs(1)))
        .map(|_| Ok(Event::default().data("ping")));
    Sse::new(stream)
}

async fn shutdown_signal() {
    tokio::signal::ctrl_c().await.expect("install ctrl_c");
}

// 启动
axum::serve(listener, app)
    .with_graceful_shutdown(shutdown_signal())
    .await
    .unwrap();

常见坑:

现象 原因 修法
SSE 被中间件缓冲 CompressionLayer 缓冲了流 SSE 路由 route_layer 排除压缩
WebSocket 升级失败 没带 Connection: Upgrade 头 axum 自动处理;检查反向代理配置
优雅关闭时在途请求丢了 没用 with_graceful_shutdown 加上;等待连接处理完
trace 跨线程断了 没装 tracing-opentelemetry 用 tracing 的 tokio 特性与 OpenTelemetryLayer

面试考法:「SSE 与 WebSocket 的区别」「K8s 里怎么做优雅关闭」。答到:SSE 是单向 HTTP 长连接,WS 是双向;收到 SIGTERM 后先摘流量(/ready 返回 503),等在途请求处理完再退出。

六、分层练习

6.1 复现型

练习 要求 验收标准 预计耗时
搭 axum 骨架 路由 + State + 一个 GET 一个 POST curl 都能命中 1.5 小时
加中间件 Trace + CORS + Timeout 响应头可见;30s 超时生效 1.5 小时
统一错误 写 AppError + IntoResponse 404/401/500 返回结构化 JSON 1.5 小时
SQLx 查询 连本机 postgres,写 query! 查 users 改字段名编译期报错 2 小时
SSE 推送 每秒推一个 ping 浏览器 EventSource 能收到 2 小时

6.2 改造型

练习 要求 验收标准 预计耗时
修提取器顺序 给定 Json 在前、Path 在后的 handler 调整顺序编译通过 0.5 小时
加 JWT 中间件 给受控路由加 Authorization 校验 不带 token 401;带 token 200 3 小时
加 validator 给 CreateUserRequest 加 length/email 校验 非法请求 400 1.5 小时
接入 OpenAPI 用 utoipa 给路由生成 Swagger /swagger-ui 可访问 3 小时
优雅关闭 用 with_graceful_shutdown 收到 SIGTERM 后在途请求完成才退出 2 小时

6.3 设计型

练习 要求 验收标准 预计耗时
用户服务全链路 注册/登录/JWT/查询用户 + PostgreSQL + 迁移 testcontainers 跑集成测试;/docs 有 Swagger 8 小时
实时通知服务 SSE 推送 + 内存广播 + 多连接 多客户端同时收到同一条 5 小时
可观测栈 tracing + OTLP + 健康检查 Jaeger 看到 trace;/health/ready 检查 db 5 小时
部署清单 Dockerfile(cargo-chef)+ K8s manifest(探针+资源限制) kubectl apply 后滚动更新不丢请求 5 小时

七、排障表

现象 可能原因 排查步骤 解决办法
Json 提取器编译错说它必须最后 body 提取器后还有别的提取器 看 handler 参数顺序 把 body 提取器挪到最后
MissingState 没 with_state 看启动代码 启动前 with_state(state)
failed to connect to database 编译期 SQLx 宏找不到 DB 看 DATABASE_URL 设 DATABASE_URL 或 cargo sqlx prepare
415 Unsupported Media Type 客户端没带 Content-Type: application/json 看请求头 客户端补 header
CORS 预检失败 CorsLayer 太严 看 OPTIONS 响应 开发 permissive(),生产收紧
优雅关闭丢请求 没用 with_graceful_shutdown 看启动代码 加上;就绪探针先返回 503
SSE 被缓冲 压缩层缓冲了流 看响应头 SSE 路由排除压缩
事务没生效 没 commit 看代码 显式 tx.commit().await?

八、出口条件

全部勾选后再进入 阶段 8 生态延伸与架构收敛。

  • [ ] 能用 axum 写出带路由、State、中间件的服务
  • [ ] 能解释提取器顺序与 FromRequestParts/FromRequest 区别
  • [ ] 能写统一错误结构并实现 IntoResponse
  • [ ] 能用 SQLx query! 做编译期 SQL 校验,写 Transaction 与 migrate!
  • [ ] 能加 JWT 认证、validator 校验、utoipa OpenAPI
  • [ ] 能写 SSE 或 WebSocket,接 tracing 与 OTLP
  • [ ] 能实现优雅关闭与健康检查
  • [ ] 排障表里随机抽三个现象,5 分钟内给出排查路径

自测题(先自己想,再看要点):

  1. axum 的提取器顺序为什么有讲究?Json 为什么必须放最后?
    • 要点:body 只能消费一次;Json 消费 body,放最后避免其它提取器再读 body 失败。
  2. FromRequestParts 与 FromRequest 的区别?
    • 要点:前者只看 parts(路径、header、query),后者消费完整请求含 body。
  3. SQLx 的 query! 编译期校验怎么工作?
    • 要点:宏在编译期连数据库(或读 .sqlx 离线缓存)校验 SQL 语法与类型映射。
  4. 事务怎么提交与回滚?
    • 要点:pool.begin() 拿 Transaction,commit() 显式提交;drop 默认 rollback。
  5. with_graceful_shutdown 解决什么问题?
    • 要点:收到 SIGTERM 后先停止接受新连接,等在途请求处理完再退出,避免 K8s 滚动更新丢请求。
  6. SSE 与 WebSocket 的区别?
    • 要点:SSE 单向 HTTP 长连接、基于文本;WebSocket 双向、基于帧协议,适合实时双向交互。
  7. 统一错误处理为什么要实现 IntoResponse?
    • 要点:handler 返回 Result<T, AppError>,AppError 自己决定 status code 与对外 JSON body,避免 unwrap 抛裸 500。