用 APIRouter 组织多文件项目
为什么要拆分
一个文件可以帮助你入门，但接口逐渐变多后，用户、任务、认证全部混在一起会越来越难维护。
初学阶段先分“入口、路由、数据模型、数据库”即可；业务复杂之后再引入服务层与数据访问层。
最小可运行结构
text
project/
├── app/
│ ├── __init__.py
│ ├── main.py
│ └── routers/
│ ├── __init__.py
│ └── books.py
└── requirements.txt两个 __init__.py 文件保持为空即可，帮助明确包结构。
文件 app/routers/books.py：
python
from fastapi import APIRouter
router = APIRouter(prefix="/books", tags=["图书"])
@router.get("")
def list_books():
return [{"id": 1, "title": "Python 基础"}]
@router.get("/{book_id}")
def read_book(book_id: int):
return {"id": book_id}文件 app/main.py：
python
from fastapi import FastAPI
from app.routers import books
app = FastAPI(title="图书管理 API")
app.include_router(books.router, prefix="/api/v1")在 project 目录运行：
powershell
python -m uvicorn app.main:app --reload最终路由是 /api/v1/books 与 /api/v1/books/{book_id}。tags 用来在文档中分组；只有执行 include_router 后，这些路由才进入应用。官方多文件项目说明
项目扩大后的职责
| 文件或目录 | 适合放什么 |
|---|---|
main.py | 创建应用、注册路由、中间件、生命周期 |
routers/ | 参数接收、调用业务逻辑、返回结果 |
schemas.py 或 schemas/ | 请求与响应模型 |
models.py 或 models/ | 数据库表模型 |
db.py | 数据库连接配置、初始化与相关依赖 |
services/ | 多步骤业务处理 |
tests/ | 自动化测试 |
schemas 与数据库 models 的命名是常见约定，不是 FastAPI 强制要求。重要的是职责清楚。
避免循环导入
如果 main.py 导入路由，而路由又从 main.py 导入 app，就容易形成循环。路由使用自己的 APIRouter，公共配置与依赖放到独立模块，可以减少这种问题。
本章练习
把图书与商品接口放到两个路由文件中，在入口统一加上 /api/v1 前缀。
过关标准：能找到项目入口、路由登记位置和最终完整请求路径。