loveyu-kit 0.2.0

面向 Axum 项目的可组合 API 工具库
Documentation
#![cfg(all(feature = "response", feature = "validation"))]

#[cfg(feature = "logging")]
use axum::Extension;
#[cfg(feature = "multipart")]
use axum::body::Bytes;
use axum::{
    Form, Json, Router,
    body::Body,
    extract::{Path, Query},
    http::{Request, StatusCode, header::CONTENT_TYPE},
    response::IntoResponse,
    routing::{get, post},
};
#[cfg(feature = "multipart")]
use axum_typed_multipart::{FieldData, TryFromMultipart};
use http_body_util::BodyExt;
use loveyu_kit::prelude::*;
use serde::Deserialize;
use tower::ServiceExt;
use validify::{Payload, Validify};

#[derive(Deserialize, Payload, Validify)]
struct CreatePayload {
    #[modify(trim)]
    #[validate(length(min = 3, code = "42001", message = "名称长度不能少于 3 个字符"))]
    name: String,
}

async fn create(Validated(Json(payload)): ValidatedJson<CreatePayload>) -> ApiResult<String> {
    Ok(ApiResponse::new(payload.name))
}

async fn query(Validated(Query(payload)): ValidatedQuery<CreatePayload>) -> ApiResult<String> {
    Ok(ApiResponse::new(payload.name))
}

async fn path(Validated(Path(payload)): ValidatedPath<CreatePayload>) -> ApiResult<String> {
    Ok(ApiResponse::new(payload.name))
}

async fn form_url(Validated(Form(payload)): ValidatedFormUrl<CreatePayload>) -> ApiResult<String> {
    Ok(ApiResponse::new(payload.name))
}

async fn system_failure() -> ApiResult<()> {
    Err(ApiError::err_database("查询失败")
        .with_error("数据库连接被拒绝")
        .with_context("user_id", 1001))
}

#[cfg(feature = "logging")]
async fn logged(Extension(request_log): Extension<RequestLogContext>) -> ApiResult<&'static str> {
    request_log.insert("operation", "读取数据");
    request_log.insert("user_id", 1001);
    Ok(ApiResponse::new("完成"))
}

#[cfg(feature = "multipart")]
#[derive(TryFromMultipart, Validify)]
struct UploadPayload {
    #[modify(trim)]
    #[validate(length(min = 1, code = "42002", message = "标题不能为空"))]
    title: String,

    #[form_data(limit = "1KiB")]
    file: FieldData<Bytes>,
}

#[cfg(feature = "multipart")]
async fn upload(ValidatedFormData(payload): ValidatedFormData<UploadPayload>) -> ApiResult<String> {
    let file_name = payload.file.metadata.file_name.unwrap_or_default();
    Ok(ApiResponse::new(format!("{}:{file_name}", payload.title)))
}

fn app() -> Router {
    let app = Router::new()
        .route("/create", post(create))
        .route("/query", get(query))
        .route("/path/{name}", get(path))
        .route("/form-url", post(form_url))
        .route("/failure", get(system_failure));

    #[cfg(feature = "multipart")]
    let app = app.route("/upload", post(upload));

    #[cfg(feature = "logging")]
    let app = app
        .route("/logged", get(logged))
        .with_request_logging_config(RequestLoggingConfig::new().expose_context_in_response(true));

    app
}

async fn response_json(response: axum::response::Response) -> serde_json::Value {
    let body = response.into_body().collect().await.unwrap().to_bytes();
    serde_json::from_slice(&body).unwrap()
}

#[tokio::test]
async fn json_payload_is_trimmed_before_handler() {
    let response = app()
        .oneshot(
            Request::post("/create")
                .header(CONTENT_TYPE, "application/json")
                .body(Body::from(r#"{"name":"  ferris  "}"#))
                .unwrap(),
        )
        .await
        .unwrap();

    assert_eq!(response.status(), StatusCode::OK);
    let value = response_json(response).await;
    assert_eq!(value["data"], "ferris");
}

#[tokio::test]
async fn validation_error_uses_invalid_param_code_and_declared_message() {
    let response = app()
        .oneshot(
            Request::post("/create")
                .header(CONTENT_TYPE, "application/json")
                .body(Body::from(r#"{"name":" x "}"#))
                .unwrap(),
        )
        .await
        .unwrap();

    let value = response_json(response).await;
    assert_eq!(value["code"], 400_001);
    assert_eq!(value["msg"], "名称长度不能少于 3 个字符");
}

#[tokio::test]
async fn malformed_json_uses_invalid_param_code() {
    let response = app()
        .oneshot(
            Request::post("/create")
                .header(CONTENT_TYPE, "application/json")
                .body(Body::from(r#"{"name":}"#))
                .unwrap(),
        )
        .await
        .unwrap();

    let value = response_json(response).await;
    assert_eq!(value["code"], 400_001);
    assert!(
        value["msg"]
            .as_str()
            .is_some_and(|message| !message.is_empty())
    );
}

#[tokio::test]
async fn query_path_and_form_url_are_trimmed_before_handler() {
    let cases = [
        ("GET", "/query?name=%20ferris%20", Body::empty(), None),
        ("GET", "/path/%20ferris%20", Body::empty(), None),
        (
            "POST",
            "/form-url",
            Body::from("name=%20ferris%20"),
            Some("application/x-www-form-urlencoded"),
        ),
    ];

    for (method, uri, body, content_type) in cases {
        let mut request = Request::builder().method(method).uri(uri);
        if let Some(content_type) = content_type {
            request = request.header(CONTENT_TYPE, content_type);
        }
        let response = app().oneshot(request.body(body).unwrap()).await.unwrap();

        assert_eq!(response.status(), StatusCode::OK, "请求 {uri} 失败");
        let value = response_json(response).await;
        assert_eq!(value["data"], "ferris", "请求 {uri} 未完成 trim");
    }
}

#[tokio::test]
async fn system_error_does_not_expose_internal_details() {
    let response = app()
        .oneshot(Request::get("/failure").body(Body::empty()).unwrap())
        .await
        .unwrap();

    let value = response_json(response).await;
    assert_eq!(value["msg"], "查询失败");
    assert!(!value.to_string().contains("数据库连接被拒绝"));
    assert!(!value.to_string().contains("user_id"));
}

#[cfg(feature = "logging")]
#[tokio::test]
async fn request_log_context_is_shared_with_handler() {
    let response = app()
        .oneshot(Request::get("/logged").body(Body::empty()).unwrap())
        .await
        .unwrap();

    let context = response.extensions().get::<RequestLogContext>().unwrap();
    let fields = context.snapshot();
    assert_eq!(
        fields.get("operation").map(String::as_str),
        Some("读取数据")
    );
    assert_eq!(fields.get("user_id").map(String::as_str), Some("1001"));
}

#[cfg(feature = "multipart")]
#[tokio::test]
async fn multipart_fields_and_file_are_extracted() {
    let boundary = "loveyu-kit-boundary";
    let body = format!(
        "--{boundary}\r\n\
         Content-Disposition: form-data; name=\"title\"\r\n\r\n\
           头像  \r\n\
         --{boundary}\r\n\
         Content-Disposition: form-data; name=\"file\"; filename=\"icon.txt\"\r\n\
         Content-Type: text/plain\r\n\r\n\
         content\r\n\
         --{boundary}--\r\n"
    );

    let response = app()
        .oneshot(
            Request::post("/upload")
                .header(
                    CONTENT_TYPE,
                    format!("multipart/form-data; boundary={boundary}"),
                )
                .body(Body::from(body))
                .unwrap(),
        )
        .await
        .unwrap();

    let value = response_json(response).await;
    assert_eq!(value["data"], "头像:icon.txt");
}

#[cfg(feature = "multipart")]
#[tokio::test]
async fn invalid_multipart_uses_invalid_param_code() {
    let boundary = "loveyu-kit-boundary";
    let body = format!(
        "--{boundary}\r\n\
         Content-Disposition: form-data; name=\"title\"\r\n\r\n\
         头像\r\n\
         --{boundary}--\r\n"
    );

    let response = app()
        .oneshot(
            Request::post("/upload")
                .header(
                    CONTENT_TYPE,
                    format!("multipart/form-data; boundary={boundary}"),
                )
                .body(Body::from(body))
                .unwrap(),
        )
        .await
        .unwrap();

    let value = response_json(response).await;
    assert_eq!(value["code"], 400_001);
    assert!(
        value["msg"]
            .as_str()
            .is_some_and(|message| !message.is_empty())
    );
}

#[test]
fn semantic_http_status_can_be_selected() {
    let response = ApiError::err_unauthorized("请先登录")
        .with_http_status(StatusCode::UNAUTHORIZED)
        .into_response();
    assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
}