使用FastAPI的APIRouter出现Detail not found错误，如何解决？

场景还原 #

目录结构：

app
  >routers
   >items.py
  __init__.py
  main.py

main.py 代码：

from typing import Union
import uvicorn
from fastapi import FastAPI, APIRouter
from routers import items


app = FastAPI()
app.include_router(items.router, prefix='/items', tags=['items'])

@app.get("/")
async def root():
    return {"message": "World World"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

items.py 代码：

from fastapi import APIRouter

router = APIRouter(
    prefix="/items",
    tags=["items"]
)

@router.api_route("/items")
async def items():
    return {"test": "items"}

运行后访问根路径 http://127.0.0.1:8000/ 正常返回，但访问 http://127.0.0.1:8000/items 时返回 {"detail": "not found"}，导入路径已确认无误。

问题原因 #

路由前缀重复叠加了：

• main.py 给子路由加了 /items 前缀
• items.py 里的 APIRouter 又自带了 /items 前缀
• 路由函数的路径又是 /items

最终实际生效的路径是 /items/items/items，和你访问的 /items 完全不匹配，所以返回404。

两种修复方案 #

方案一（推荐）：调整子路由配置 #

修改 items.py，移除 APIRouter 的 prefix，并把路由路径改为 /：

from fastapi import APIRouter

router = APIRouter(
    tags=["items"]  # 删掉prefix="/items"
)

@router.api_route("/")  # 路径改为根路径
async def items():
    return {"test": "items"}

修改后访问 http://127.0.0.1:8000/items 就能正常返回结果。

方案二：调整主应用的路由导入 #

修改 main.py，去掉 include_router 时的 prefix 参数：

# 把这一行的prefix='/items'删掉
app.include_router(items.router, tags=['items'])

此时接口的实际路径是 /items/items，访问这个地址就能得到正确响应。

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