FastAPI如何自定义URL缺失参数时的404错误内容？

问题描述 #

有一个API端点/devices/{id}，当调用时未在URL中传入id参数（即访问/devices），会返回默认的404错误，响应体提示为{"detail": "Not Found"}，需要自定义该场景下的错误提示内容。

解决方案 #

FastAPI支持两种方式实现需求：

方式一：添加无参数路径路由，主动抛出自定义错误 #

直接为/devices路径添加路由，在其中抛出带有自定义提示的404异常，精准针对缺失id的场景：

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/devices")
async def devices_missing_id():
    raise HTTPException(
        status_code=404,
        detail="请求路径缺失设备ID参数，请在/devices后添加设备ID，例如：/devices/12345"
    )

@app.get("/devices/{id}")
async def get_cellular_data_for_device_id(id: str):
     print("处理设备数据逻辑")
     return {"device_id": id, "status": "success"}

方式二：全局404异常处理器 #

通过全局异常处理器捕获所有404错误，判断请求路径后返回对应自定义提示，适合统一管理所有404场景：

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse
import re

app = FastAPI()

@app.exception_handler(404)
async def custom_404_handler(request: Request, exc: HTTPException):
    # 匹配/devices或/devices/路径（未带id参数的情况）
    if re.match(r"^/devices/?$", str(request.url.path)):
        return JSONResponse(
            status_code=404,
            content={"detail": "请求路径缺失设备ID参数，请在/devices后添加设备ID，例如：/devices/12345"}
        )
    # 其他404场景返回通用提示
    return JSONResponse(
        status_code=404,
        content={"detail": "请求的资源不存在"}
    )

@app.get("/devices/{id}")
async def get_cellular_data_for_device_id(id: str):
     print("处理设备数据逻辑")
     return {"device_id": id, "status": "success"}

效果验证 #

当访问/devices时，会返回自定义的404响应：

{
    "detail": "请求路径缺失设备ID参数，请在/devices后添加设备ID，例如：/devices/12345"
}

内容的提问来源于stack exchange，提问作者Cribber