如何使用 APIRouter 组织一个大型应用？

Question

Accepted Answer

**`APIRouter`** 让您将一个大型 FastAPI 应用分割成多个模块 — 每个 router 对相关的 endpoints 进行分组（例如所有 `/users` 路由），主应用将它们包含进来。这样可以保持不断增长的代码库井井有条且易于维护。

## 在单独的模块中定义 router

```python
# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # all routes here start with /users
    tags=["users"],           # grouped under "users" in the docs
)

@router.get("/")              # GET /users/
def list_users(): ...

@router.get("/{user_id}")     # GET /users/{user_id}
def get_user(user_id: int): ...
```

`APIRouter` 的工作方式类似于一个小型应用 — 你在它上面用相同的 decorators 定义 path operations，`prefix` 适用于所有这些操作。

## 在主应用中包含 routers

```python
# main.py
from fastapi import FastAPI
from routers import users, items, auth

app = FastAPI()
app.include_router(users.router)     # mounts /users/* endpoints
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()` 将每个 router 的 endpoints 挂载到主应用中 — 从模块化的各部分组装完整的 API。

## 一个典型的项目结构

```text
app/
  main.py              # creates the app, includes routers
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
    auth.py            # APIRouter for /auth
  models.py            # Pydantic models
  database.py          # DB setup
  dependencies.py      # shared dependencies
```

每个功能/领域都有自己的 router 模块 — 使相关的路由和代码库保持井井有条。

## Router 级别的依赖项和配置

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # apply a dependency to ALL routes in the router
)
# you can also nest routers via include_router on a router
```

Routers 可以携带共享的依赖项（例如为整组路由要求 admin 认证）— 一次性应用于所有 endpoints。

## 为什么这很重要

`APIRouter` 对于构建任何超出平凡 FastAPI 应用的东西都是必不可少的 — 没有它，所有 endpoints 会存在一个文件中，随着 API 的增长会变得难以管理。

理解它对于**代码组织和可维护性**很重要：将 endpoints 拆分到基于功能的 router 模块（users、items、auth）中使相关代码保持在一起，使项目更容易导航，并让团队能够独立地在不同区域工作。

`prefix` 和 `tags` 保持路由和文档的组织有序，**router 级别的依赖项**（如为整组路由要求 admin 认证）提供了干净的、整体的行为。

这种模块化结构是真实 FastAPI 应用的标准实践，使 `APIRouter` 和围绕它的项目组织模式成为构建可扩展、可维护 API 的重要、实际上必不可少的知识。