FastAPI 中如何通过依赖项动态填充路径参数

本文介绍在 fastapi 中复用同一处理函数时，如何让路径参数 `wako_id` 在 `/outbound/{wako_id}` 路由中取自 url 路径，而在 `/inbound` 路由中由依赖项自动提供，避免 422 错误。

在 FastAPI 中，路径参数（如 {wako_id}）默认是强制性的，且不能被依赖项直接“覆盖”或“跳过”。当你为 /inbound 路由声明了依赖 Depends(middleware)，但 endpoint 函数签名仍包含非可选的 wako_id: str 参数时，FastAPI 会尝试从请求中解析该路径参数——而 /inbound 并无此段路径，导致校验失败，返回 422 Unprocessable Entity。

正确解法是：将 wako_id 的来源统一收口到一个依赖函数中，并根据当前请求路径动态决定其值。关键点包括：

• 依赖函数需接收 Request 对象以获取原始路由信息；
• 使用 Optional[str] 声明 wako_id 参数（允许路径未提供时为 None）；
• 通过 request.scope['route'].path 获取注册的路径模板（如 '/outbound/{wako_id}'），结合实际请求路径逻辑判断来源；
• 最终返回确定的 str 值，供 endpoint 消费。

以下是完整、可运行的示例：

from fastapi import FastAPI, Request, APIRouter, Depends
from typing import Optional

app = FastAPI()
router = APIRouter()

def get_wako_id(request: Request, wako_id: Optional[str] = None) -> str:
    # 获取已注册的路由路径模板（注意：含 {xxx} 占位符）
    route_path = request.scope.get("route", {}).get("path", "")

    # 匹配 /outbound/{wako_id}：优先使用路径中传入的值
    if route_path == "/outbound/{wako_id}" and wako_id is not None:
        return wako_id

    # 匹配 /inbound：返回默认生成值
    if route_path == "/inbound":
        return "123"

    # 兜底：若逻辑未覆盖，抛出明确错误（生产环境建议细化处理）
    raise ValueError(f"Unsupported route path: {route_path}")

@router.get("/inbound")
@router.get("/outbound/{wako_id}")
def endpoint(wako_id: str = Depends(get_wako_id)):
    return {"wako_id": wako_id}

app.include_router(router)

✅ 优势说明：

• ✅ 单一 endpoint 函数复用，逻辑集中；
• ✅ 无需重复定义路径参数，避免签名冲突；
• ✅ 依赖函数内可扩展任意业务逻辑（如鉴权、ID 解析、缓存查询等）；
• ✅ 完全兼容 FastAPI 的自动文档（Swagger UI / ReDoc）生成。

⚠️ 注意事项：

• request.scope['route'].path 返回的是路由定义时的模板路径（如 "/outbound/{wako_id}"），不是请求的实际 URL，因此适合做路由匹配；
• 不要依赖 request.url.path 做精确匹配（因可能含前缀、代理路径等），应以 route.path 为准；
• 若需支持更多路由变体（如 /legacy/{id} 映射到同个 wako_id），只需在 get_wako_id 中扩展 if/elif 分支即可；
• 此方案不适用于需对不同路径做差异化响应头、状态码等场景——此时建议拆分为独立 endpoint。

通过这种“路径感知型依赖”，你既能保持接口简洁性，又能灵活控制参数注入逻辑，是 FastAPI 高级依赖模式的典型实践。