Làm thế nào để cấu trúc một ứng dụng lớn với APIRouter?

Question

Accepted Answer

**`APIRouter`** cho phép bạn chia một ứng dụng FastAPI lớn thành nhiều module — mỗi router nhóm các endpoint liên quan (ví dụ tất cả route `/users`), và app chính include chúng. Điều này giữ một codebase đang phát triển có tổ chức và dễ bảo trì.

## Định nghĩa một router trong module riêng

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

router = APIRouter(
    prefix="/users",          # tất cả route ở đây bắt đầu bằng /users
    tags=["users"],           # gom nhóm dưới "users" trong tài liệu
)

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

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

Một `APIRouter` hoạt động như một mini-app — bạn định nghĩa path operation trên nó bằng các decorator tương tự, và một `prefix` áp dụng cho tất cả chúng.

## Include router vào app chính

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

app = FastAPI()
app.include_router(users.router)     # mount các endpoint /users/*
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()` mount các endpoint của mỗi router vào app chính — lắp ráp API đầy đủ từ các mảnh module hóa.

## Một cấu trúc dự án điển hình

```text
app/
  main.py              # tạo app, include router
  routers/
    users.py           # APIRouter cho /users
    items.py           # APIRouter cho /items
    auth.py            # APIRouter cho /auth
  models.py            # Pydantic model
  database.py          # thiết lập DB
  dependencies.py      # dependency dùng chung
```

Mỗi tính năng/domain có module router riêng — giữ các route liên quan, và codebase, có tổ chức tốt.

## Dependency và cấu hình cấp router

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # áp dụng một dependency cho TẤT CẢ route trong router
)
# bạn cũng có thể lồng router qua include_router trên một router
```

Router có thể mang dependency dùng chung (ví dụ yêu cầu admin auth cho cả một nhóm route) — áp dụng cho tất cả endpoint của chúng cùng một lúc.

## Tại sao điều này quan trọng

`APIRouter` thiết yếu để xây dựng bất cứ thứ gì vượt ra ngoài một app FastAPI tầm thường — không có nó, tất cả endpoint sẽ nằm trong một file, điều trở nên không quản lý nổi khi API phát triển.

Hiểu nó quan trọng cho **tổ chức code và khả năng bảo trì**: chia endpoint thành các module router theo tính năng (users, items, auth) giữ code liên quan với nhau, khiến dự án dễ điều hướng, và cho phép các team làm việc trên các khu vực khác nhau độc lập. `prefix` và `tags` giữ route và tài liệu có tổ chức, và **dependency cấp router** (như yêu cầu admin auth cho cả một nhóm) cung cấp hành vi cả-nhóm gọn gàng.

Cấu trúc module hóa này là thực hành chuẩn cho ứng dụng FastAPI thực, biến `APIRouter` và các pattern tổ chức dự án quanh nó thành kiến thức quan trọng, thực sự thiết yếu để xây dựng API mở rộng được, dễ bảo trì.