2026-09-06 20:48:50 +08:00
|
|
|
|
"""统一 API 响应外壳（B7 · 挂账④）。
|
|
|
|
|
|
|
|
|
|
|
|
成功响应：业务字段平铺不变（B5 评审 P2-2 口径「路由返回体不变」），trace_id
|
|
|
|
|
|
经 X-Trace-Id 响应头贯通（main 中间件）；错误响应统一 JWT 手册 §10 结构
|
|
|
|
|
|
{error_code, message, trace_id, request_id}（request_id 沿用 trace_id，
|
|
|
|
|
|
独立请求级标识尚未引入）。main 与测试 app 共用 register_error_handlers。
|
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
|
|
from __future__ import annotations
|
|
|
|
|
|
|
|
|
|
|
|
from fastapi import FastAPI, Request
|
|
|
|
|
|
from fastapi.responses import JSONResponse
|
|
|
|
|
|
|
|
|
|
|
|
from app.utils.exceptions import ApiError, PermissionDenied
|
|
|
|
|
|
from app.utils.trace import current_trace, new_trace
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def error_body(error_code: str, message: str) -> dict[str, str]:
|
|
|
|
|
|
"""手册 §10 错误体（trace 缺失时兜底生成，保证响应可归因）。"""
|
|
|
|
|
|
tid = current_trace() or new_trace()
|
|
|
|
|
|
return {"error_code": error_code, "message": message, "trace_id": tid, "request_id": tid}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def register_error_handlers(app: FastAPI) -> None:
|
|
|
|
|
|
"""注册统一错误体 handler（替代 FastAPI 默认 detail 结构）。"""
|
|
|
|
|
|
|
|
|
|
|
|
@app.exception_handler(ApiError)
|
|
|
|
|
|
async def _api_error_handler(request: Request, exc: ApiError) -> JSONResponse:
|
|
|
|
|
|
return JSONResponse(status_code=exc.status_code, content=error_body(exc.error_code, exc.message))
|
|
|
|
|
|
|
|
|
|
|
|
@app.exception_handler(PermissionDenied)
|
|
|
|
|
|
async def _permission_denied_handler(request: Request, exc: PermissionDenied) -> JSONResponse:
|
|
|
|
|
|
return JSONResponse(status_code=403, content=error_body(exc.code, str(exc)))
|
