use axum::{
Json,
http::StatusCode,
response::{IntoResponse, Response},
};
use serde_json::{Value, json};
/// 吃 JSON body 的 extractor,但**拒絕時也回 JSON**。
///
/// axum 內建的 `Json<T>` 在四種情況下回的是 `text/plain`:
///
/// 壞掉的 JSON 400 "Failed to parse the request body as JSON: …"
/// 沒有 content-type 415 "Expected request with `Content-Type: application/json`"
/// content-type 錯 415 同上
/// 型別不符 422 "Failed to deserialize the JSON body into the target type: …"
///
/// 這對一個宣告「回應是 application/json」的 API 是不一致的:前端若一律 `JSON.parse()`
/// 就會拿到解析例外而不是結構化錯誤,錯誤處理只能靠 try/catch 猜。
///
/// 這不是理論問題——Schemathesis 的 stateful 測試在 `POST /api/admin/tags` 上實際
/// 抓到「Undocumented Content-Type: received text/plain, documented application/json」。
/// 手寫測試沒抓到,因為沒有人會想到去測「送壞掉的 body 時 content-type 是什麼」。
///
/// 用法:把 handler 的 `Json(body): Json<T>` 換成 `JsonBody(body): JsonBody<T>`。
pub struct JsonBody<T>(pub T);
impl<S, T> axum::extract::FromRequest<S> for JsonBody<T>
where
T: serde::de::DeserializeOwned,
S: Send + Sync,
{
type Rejection = Response;
async fn from_request(req: axum::extract::Request, state: &S) -> Result<Self, Self::Rejection> {
match Json::<T>::from_request(req, state).await {
Ok(Json(v)) => Ok(Self(v)),
// 狀態碼原樣保留(400/415/422 各有意義),只把 body 換成 JSON。
Err(rej) => {
let status = rej.status();
Err((status, Json(json!({ "error": rej.body_text() }))).into_response())
}
}
}
}
/// 吃路徑參數的 extractor,但**拒絕時也回 JSON**——與 [`JsonBody`] 同一個理由。
///
/// axum 的 `Path<T>` 在型別對不上(`/api/admin/tags/abc` 而 `T = i64`)時回 400 + `text/plain`。
///
/// 為什麼要把 `Path<String>` 換成 `PathParam<i64>`:這幾張表的 id 都是
/// `INTEGER PRIMARY KEY`,宣告成 String 是把「任何字串都是合法 id」寫進了 spec。
/// 後果不只是文件不準——Schemathesis 的 fuzzing 階段會依 spec 生隨機字串,
/// 其中大半(含 `/`、控制字元、空字串)根本放不進 URL 而被過濾掉,
/// 四支 DELETE 因此觸發 `filter_too_much` health check,整個階段被跳過。
pub struct PathParam<T>(pub T);
impl<S, T> axum::extract::FromRequestParts<S> for PathParam<T>
where
T: serde::de::DeserializeOwned + Send,
S: Send + Sync,
{
type Rejection = Response;
async fn from_request_parts(
parts: &mut axum::http::request::Parts,
state: &S,
) -> Result<Self, Self::Rejection> {
match axum::extract::Path::<T>::from_request_parts(parts, state).await {
Ok(axum::extract::Path(v)) => Ok(Self(v)),
Err(rej) => {
let status = rej.status();
Err((status, Json(json!({ "error": rej.body_text() }))).into_response())
}
}
}
}
/// 服務層錯誤。回應形狀刻意對齊 Express:多數端點 `{ "error": ... }`,
/// 但 auth(requireAdmin)用 `{ "message": ... }`,故分變體決定 body key。
#[derive(Debug)]
pub enum AppError {
Database(sqlx::Error),
/// 代理回 Express 時的上游錯誤(連線失敗等)。
Upstream(reqwest::Error),
/// 404,回應 `{"error": "<msg>"}`,對齊 Express 的 `res.status(404).json({error})`。
NotFound(String),
/// 401,回應 `{"message": "<msg>"}`,對齊 Express requireAdmin。
Unauthorized(String),
/// 403,回應 `{"message": "<msg>"}`,對齊 Express requireAdmin。
Forbidden(String),
Anyhow(anyhow::Error),
}
impl AppError {
pub fn not_found(msg: impl Into<String>) -> Self {
Self::NotFound(msg.into())
}
pub fn unauthorized(msg: impl Into<String>) -> Self {
Self::Unauthorized(msg.into())
}
pub fn forbidden(msg: impl Into<String>) -> Self {
Self::Forbidden(msg.into())
}
}
impl From<sqlx::Error> for AppError {
fn from(err: sqlx::Error) -> Self {
Self::Database(err)
}
}
impl From<reqwest::Error> for AppError {
fn from(err: reqwest::Error) -> Self {
Self::Upstream(err)
}
}
impl From<anyhow::Error> for AppError {
fn from(err: anyhow::Error) -> Self {
Self::Anyhow(err)
}
}
impl IntoResponse for AppError {
fn into_response(self) -> Response {
// (狀態碼, 對外 body, log 用細節):auth 用 message key、其餘用 error key。
// Database/Upstream/Anyhow 的原文只進 log——SQLite/reqwest 錯誤字串可能含
// 資料表、欄位、內部 URL 等細節,不外洩給客戶端(刻意偏離 Express 的舊行為)。
let (status, body, detail): (StatusCode, Value, Option<String>) = match self {
Self::Database(e) => (
StatusCode::INTERNAL_SERVER_ERROR,
json!({ "error": "Internal server error" }),
Some(e.to_string()),
),
Self::Upstream(e) => {
(StatusCode::BAD_GATEWAY, json!({ "error": "Upstream error" }), Some(e.to_string()))
}
Self::NotFound(msg) => (StatusCode::NOT_FOUND, json!({ "error": msg }), None),
Self::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, json!({ "message": msg }), None),
Self::Forbidden(msg) => (StatusCode::FORBIDDEN, json!({ "message": msg }), None),
Self::Anyhow(e) => (
StatusCode::INTERNAL_SERVER_ERROR,
json!({ "error": "Internal server error" }),
Some(format!("{e:#}")),
),
};
if status.is_server_error() {
tracing::error!(%status, %body, detail = detail.as_deref().unwrap_or(""), "request failed");
} else {
tracing::debug!(%status, %body, "request rejected");
}
(status, Json(body)).into_response()
}
}
/// 手排錯誤分支用(match Err(e) 直接組 Response 的 handler):
/// 原文+呼叫點進 log,客戶端只拿泛用訊息(同 IntoResponse 的 Database 分支)。
/// 狀態碼由呼叫端決定——部分舊端點對齊 Express 用 400 回 DB 錯誤,維持不變。
#[track_caller]
pub fn internal_error(status: StatusCode, e: impl std::fmt::Display) -> Response {
let loc = std::panic::Location::caller();
tracing::error!("internal error at {}:{}: {e}", loc.file(), loc.line());
(status, Json(json!({ "error": "Internal server error" }))).into_response()
}
#[cfg(test)]
mod tests {
use super::*;
use axum::extract::{FromRequest, FromRequestParts};
use axum::http::header;
async fn parts_of(resp: Response) -> (StatusCode, String, Value) {
let status = resp.status();
let ct =
resp.headers().get(header::CONTENT_TYPE).and_then(|v| v.to_str().ok()).unwrap_or("").to_string();
let bytes = http_body_util::BodyExt::collect(resp.into_body()).await.unwrap().to_bytes();
let v = serde_json::from_slice(&bytes)
.unwrap_or_else(|_| Value::String(String::from_utf8_lossy(&bytes).into_owned()));
(status, ct, v)
}
/// **底層錯誤的原文不能外洩。**
///
/// SQLite 與 reqwest 的錯誤字串會帶資料表名、欄位名、內部 URL。這一條是刻意
/// 偏離 Express 舊行為的地方(舊版直接把 `err.message` 丟給客戶端),
/// 而「偏離」正是最容易在日後某次重構被人「修回去」的東西——沒有測試釘住的話。
#[tokio::test]
async fn 資料庫與上游的錯誤原文只進_log_不進回應() {
let secret = "no such column: users.password_hash";
let (status, ct, body) =
parts_of(AppError::Database(sqlx::Error::Protocol(secret.into())).into_response()).await;
assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
assert!(ct.starts_with("application/json"));
assert_eq!(body["error"], "Internal server error");
assert!(!body.to_string().contains("password_hash"), "內部細節外洩了:{body}");
let (status, _, body) = parts_of(
AppError::Anyhow(anyhow::anyhow!("internal path /srv/secret/db.sqlite")).into_response(),
)
.await;
assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
assert_eq!(body["error"], "Internal server error");
assert!(!body.to_string().contains("secret"), "anyhow 的內容外洩了:{body}");
}
/// 我們自己寫的訊息**要**顯示(那是給使用者看的),而且 auth 那兩個用的是
/// `message` key 不是 `error`——前端的錯誤處理靠這個分辨。
#[tokio::test]
async fn 自己的訊息要顯示_而且_auth_用_message_key() {
let (status, _, body) = parts_of(AppError::not_found("找不到文章").into_response()).await;
assert_eq!(status, StatusCode::NOT_FOUND);
assert_eq!(body["error"], "找不到文章", "404 用 error key");
assert!(body.get("message").is_none());
let (status, _, body) = parts_of(AppError::unauthorized("需要登入").into_response()).await;
assert_eq!(status, StatusCode::UNAUTHORIZED);
assert_eq!(body["message"], "需要登入", "401 用 message key(對齊 Express requireAdmin)");
assert!(body.get("error").is_none());
let (status, _, body) = parts_of(AppError::forbidden("權限不足").into_response()).await;
assert_eq!(status, StatusCode::FORBIDDEN);
assert_eq!(body["message"], "權限不足");
}
#[tokio::test]
async fn 上游錯誤是_502_不是_500() {
// 502 讓監控分得出「我們壞了」與「別人壞了」;一律 500 的話這個區別就沒了。
let e = reqwest::get("http://127.0.0.1:1/不存在").await.unwrap_err();
let (status, _, body) = parts_of(AppError::Upstream(e).into_response()).await;
assert_eq!(status, StatusCode::BAD_GATEWAY);
assert_eq!(body["error"], "Upstream error");
}
#[tokio::test]
async fn internal_error_由呼叫端決定狀態碼但_body_一律泛用() {
// 部分舊端點對齊 Express 用 400 回 DB 錯誤——狀態碼可變,訊息不可變。
for st in [StatusCode::INTERNAL_SERVER_ERROR, StatusCode::BAD_REQUEST] {
let (status, ct, body) =
parts_of(internal_error(st, "table posts has no column named xyz")).await;
assert_eq!(status, st);
assert!(ct.starts_with("application/json"));
assert_eq!(body["error"], "Internal server error");
assert!(!body.to_string().contains("xyz"), "細節外洩:{body}");
}
}
fn req(ct: Option<&str>, body: &str) -> axum::extract::Request {
let mut b = axum::http::Request::builder().method("POST").uri("/");
if let Some(c) = ct {
b = b.header(header::CONTENT_TYPE, c);
}
b.body(axum::body::Body::from(body.to_string())).unwrap()
}
/// `JsonBody` 存在的唯一理由:**拒絕時也要回 JSON**。
/// axum 內建的 `Json<T>` 這四種情況回的是 text/plain,前端一律 `JSON.parse()`
/// 就會拿到解析例外而不是結構化錯誤。
#[tokio::test]
async fn jsonbody_的四種拒絕都回_json_而不是_text_plain() {
let cases: [(&str, Option<&str>, &str, StatusCode); 4] = [
("壞掉的 JSON", Some("application/json"), "{ 不是合法 json", StatusCode::BAD_REQUEST),
("沒有 content-type", None, r#"{"a":1}"#, StatusCode::UNSUPPORTED_MEDIA_TYPE),
("content-type 錯", Some("text/plain"), r#"{"a":1}"#, StatusCode::UNSUPPORTED_MEDIA_TYPE),
("型別不符", Some("application/json"), r#"{"a":1}"#, StatusCode::UNPROCESSABLE_ENTITY),
];
for (why, ct, body, want) in cases {
// 型別不符那條要一個「不可能從 {a:1} 解出來」的目標型別
let resp = if why == "型別不符" {
JsonBody::<Vec<i32>>::from_request(req(ct, body), &()).await.err()
} else {
JsonBody::<serde_json::Map<String, Value>>::from_request(req(ct, body), &()).await.err()
};
let resp = resp.unwrap_or_else(|| panic!("{why} 應該被拒絕"));
let (status, ct_out, v) = parts_of(resp).await;
assert_eq!(status, want, "{why} 的狀態碼要原樣保留(每個碼各有意義)");
assert!(ct_out.starts_with("application/json"), "{why} 回的是 {ct_out}");
assert!(v["error"].is_string(), "{why} 要有結構化的 error 欄位:{v}");
}
}
#[tokio::test]
async fn jsonbody_成功時原樣解出來() {
let JsonBody(v) = JsonBody::<serde_json::Map<String, Value>>::from_request(
req(Some("application/json"), r#"{"a":1}"#),
&(),
)
.await
.expect("合法 body 應該通過");
assert_eq!(v["a"], 1);
}
/// `PathParam<i64>` 在型別對不上時同樣要回 JSON。
/// 宣告成 `Path<String>` 會把「任何字串都是合法 id」寫進 OpenAPI spec,
/// 讓 Schemathesis 的 fuzzing 生出一堆放不進 URL 的字串而整個階段被跳過。
#[tokio::test]
async fn pathparam_型別不符時回_json() {
let mut parts = axum::http::Request::builder().uri("/").body(()).unwrap().into_parts().0;
// 沒有路徑參數可抽 → 一樣走拒絕分支
let err = PathParam::<i64>::from_request_parts(&mut parts, &()).await.err().expect("應該被拒絕");
let (status, ct, v) = parts_of(err).await;
assert!(status.is_client_error() || status.is_server_error());
assert!(ct.starts_with("application/json"), "回的是 {ct}");
assert!(v["error"].is_string(), "要有結構化的 error 欄位:{v}");
}
#[test]
fn from_轉換把三種底層錯誤各自歸位() {
let e: AppError = sqlx::Error::RowNotFound.into();
assert!(matches!(e, AppError::Database(_)));
let e: AppError = anyhow::anyhow!("boom").into();
assert!(matches!(e, AppError::Anyhow(_)));
}
}