AxumStatusCode细化Rust Web标准格式响应

news2025/6/2 3:43:11

1. Axum 中的 `StatusCode` 概述

axum::http::StatusCode 提供了 HTTP 状态码的枚举，涵盖了从 100 到 599 的所有标准状态码。

通过使用这些状态码，您可以精确地控制 HTTP 响应的语义，例如成功、客户端错误、服务器错误等。

1.1 常用状态码

2xx 系列：成功
- 200 OK
- 201 Created
- 204 No Content
3xx 系列：重定向
- 301 Moved Permanently
- 302 Found
- 304 Not Modified
4xx 系列：客户端错误
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 409 Conflict
5xx 系列：服务器错误
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable

2. 在 Axum 中使用 `StatusCode`

2.1 基本用法

在 Axum 中，您可以在处理函数中返回 Result 类型，其中 Ok 包含 Response 或 axum::response::Response，而 Err 包含 StatusCode 或自定义错误类型。

rust

use axum::{
    Router,
    routing::get,
    http::StatusCode,
    response::Response,
};
use std::net::SocketAddr;

async fn handler() -> Result<Response, StatusCode> {
    // 业务逻辑
    Ok((
        StatusCode::OK,
        "Hello, World!".to_string(),
    ).into_response())
}

#[tokio::main]
async fn main() {
    // 构建路由
    let app = Router::new().route("/", get(handler));

    // 绑定地址并运行
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

2.2 使用 `IntoResponse` 特性

Axum 的 IntoResponse 特性允许您将任何实现了该特性的类型转换为 HTTP 响应。

通过实现 IntoResponse，您可以自定义更复杂的响应结构。

rust

use axum::{
    response::{IntoResponse, Response},
    http::StatusCode,
};
use serde::Serialize;

#[derive(Serialize)]
struct ApiResponse<T> {
    data: Option<T>,
    message: String,
}

impl<T> IntoResponse for ApiResponse<T>
where
    T: Serialize,
{
    fn into_response(self) -> Response {
        let body = serde_json::to_string(&self).unwrap();
        let status = match self.message.as_str() {
            "success" => StatusCode::OK,
            "created" => StatusCode::CREATED,
            "not_found" => StatusCode::NOT_FOUND,
            _ => StatusCode::INTERNAL_SERVER_ERROR,
        };
        (status, body).into_response()
    }
}

async fn get_user() -> impl IntoResponse {
    let user = fetch_user().await;
    if user.is_some() {
        ApiResponse {
            data: user,
            message: "success".to_string(),
        }
    } else {
        ApiResponse {
            data: None,
            message: "not_found".to_string(),
        }
    }
}

2.3 错误处理

使用 StatusCode 进行错误处理，可以使错误响应更加语义化。例如：

rust

use axum::{
    response::{IntoResponse, Response},
    http::StatusCode,
    Json,
};
use serde::Serialize;

#[derive(Serialize)]
struct ErrorResponse {
    error: String,
}

impl IntoResponse for ErrorResponse {
    fn into_response(self) -> Response {
        let body = serde_json::to_string(&self).unwrap();
        (StatusCode::BAD_REQUEST, Json(self)).into_response()
    }
}

async fn create_user() -> Result<impl IntoResponse, ErrorResponse> {
    // 假设创建用户失败
    Err(ErrorResponse {
        error: "User already exists".to_string(),
    })
}

3. 最佳实践

3.1 语义化状态码

选择合适的状态码：确保每个响应使用最合适的状态码。例如，201 Created 用于成功创建资源，204 No Content 用于成功但无返回内容，400 Bad Request 用于客户端请求错误等。
避免滥用：不要滥用 200 OK 或 500 Internal Server Error，确保每个状态码都有明确的语义。

3.2 统一响应格式

一致的响应结构：使用统一的响应格式，如 ApiResponse，确保所有 API 端点的响应结构一致。
错误处理：设计统一的错误响应格式，包含错误代码、错误消息等，方便客户端处理。

3.3 安全性

不要暴露敏感信息：在错误响应中，避免暴露敏感信息，如堆栈跟踪、内部错误消息等。
限制返回的信息：根据需要，返回必要的信息，避免过多或不必要的数据泄露。

3.4 性能优化

缓存静态资源：使用合适的状态码（如 304 Not Modified）和缓存策略，提高性能。
减少不必要的重定向：避免过多的重定向请求，提高响应速度。

4. 示例：完整的 Axum 应用

以下是一个完整的 Axum 应用示例，展示了如何使用 StatusCode 来处理不同的 HTTP 请求和响应。

rust

use axum::{
    routing::{get, post},
    Router,
    response::{IntoResponse, Response},
    http::StatusCode,
    Json,
};
use serde::Serialize;
use std::net::SocketAddr;

#[derive(Serialize)]
struct ApiResponse<T> {
    data: Option<T>,
    message: String,
}

impl<T> IntoResponse for ApiResponse<T>
where
    T: Serialize,
{
    fn into_response(self) -> Response {
        let body = serde_json::to_string(&self).unwrap();
        let status = match self.message.as_str() {
            "success" => StatusCode::OK,
            "created" => StatusCode::CREATED,
            "not_found" => StatusCode::NOT_FOUND,
            _ => StatusCode::INTERNAL_SERVER_ERROR,
        };
        (status, body).into_response()
    }
}

#[derive(Serialize)]
struct User {
    id: u32,
    name: String,
}

async fn get_user() -> impl IntoResponse {
    let user = fetch_user().await;
    if user.is_some() {
        ApiResponse {
            data: user,
            message: "success".to_string(),
        }
    } else {
        ApiResponse {
            data: None,
            message: "not_found".to_string(),
        }
    }
}

async fn create_user(Json(payload): Json<User>) -> impl IntoResponse {
    // 假设用户创建成功
    let user = payload;
    // 实际应用中，这里应将用户信息保存到数据库
    ApiResponse {
        data: Some(user),
        message: "created".to_string(),
    }
}

async fn fetch_user() -> Option<User> {
    // 从数据库或其他数据源获取用户信息
    Some(User {
        id: 1,
        name: "Alice".to_string(),
    })
}

#[tokio::main]
async fn main() {
    // 构建路由
    let app = Router::new()
        .route("/", get(get_user))
        .route("/users", post(create_user));

    // 绑定地址并运行
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}