说起来，

如果你刚接触 FastAPI，或者想把一个零散的项目整理成可维护、可 的结构。你会遇到以下痛点：

• 业务代码分散在多个文件夹，修改时要跳来跳去。
• 公共配置、异常、日志等能力混在业务里导致团队协作困难。
• 数据库模型和 Pydantic 模型混用，导致数据层与接口层耦合。
• 缺少统一响应格式和分页实现，让前端消耗更多时间。
• 没有自动化迁移、日志、测试，部署后难以排查问题。

下面给出一个“Todo List”项目示例。从目录结构到完整接口，全流程解决上述痛点。话说回来，

一、目录结构

主要原则: 公共能力放全局；业务能力放局部，

todo-api/
├── app/
│ ├── __init__.py
│ ├── main.py # 应用入口
│ ├── api/
│ │ └── v1/
│ │ └── router.py # 聚合所有业务 router
│ ├── core/ # 程序级公共能力
│ │ ├── config.py # 配置读取
│ │ ├── exceptions.py # 全局异常
│ │ ├── logging.py # 日志配置
│ │ └── security.py # 密码、Token 工具
│ ├── db/ # 数据库基础设施
│ │ ├── base.py # ORM Base
│ │ ├── models.py # 统一导入所有 ORM 模型
│ │ └── session.py # engine & SessionLocal
│ ├── schemas/ # 跨模块公共 schema
│ │   └── common.py # ApiResponse、PageResponse 等通用模型
│   ├── dependencies/ # 跨模块公共 Depends
│   └── modules/ # 业务模块
└───── migrations/ # Alembic 迁移目录

二、项目初始化

统一依赖管理与启动方式：

uv init todo-api # 创建项目文件夹
uv add "fastapi"
uv add sqlalchemy alembic pydantic-settings
uv add --dev pytest 

启动命令

uv run fastapi dev app/main.py

三、应用入口

from fastapi import FastAPI
from app.api.v1.router import api_router
from app.core.exceptions import register_exception_handlers
from app.core.logging import setup_logging
def create_app -> FastAPI:
app = FastAPI
setup_logging
register_exception_handlers
app.include_router
return app
app = create_app

四、路由分层

# app/api/v1/router.py
from fastapi import APIRouter
from app.modules.todos.router import router as todos_router
api_router = APIRouter
api_router.include_router
# app/modules/todos/router.py
from fastapi import APIRouter,status
from app.modules.todos.schemas import TodoCreate,TodoResponse
router = APIRouter
@router.post("",response_model=TodoResponse。status_code=status.HTTP_201_CREATED)
def create_todo -> TodoResponse:
return TodoResponse(id=0,title=payload.title,description=payload.description,is_completed=False)

五、请求与响应模型

# app/modules/todos/schemas.py
from pydantic import BaseModel,Field
class TodoCreate:
title这方面，str = Field
description: str | None = Field
class TodoUpdate:
至于title，str | None = Field
description: str | None = Field
is_completed: bool | None = None
class TodoResponse:
再看id，int
至于title，str
description: str | None = None
is_completed: bool

六、ORM 数据库映射

# app/db/base.py
from sqlalchemy.orm import DeclarativeBase
class Base: pass
# app/modules/todos/models.py
from datetime import datetime
from sqlalchemy import Boolean,DateTime,String
from sqlalchemy.orm import Mapped,mapped_column
from app.db.base import Base
class Todo:
__tablename__ = "todos"
再看id，Mapped = mapped_column
至于title，Mapped = mapped_column,nullable=False)
description: Mapped = mapped_column,nullable=True)
is_completed: Mapped = mapped_column,default=False)
created_at: Mapped = mapped_column,default=datetime.utcnow)
updated_at: Mapped = mapped_column,default=datetime.utcnow,onupdate=datetime.utcnow)

七、配置管理

# .env
APP_ENV=development
DEBUG=true
DATABASE_URL=sqlite:///./todo.db
# app/core/config.py
from pydantic_settings import BaseSettings,SettingsConfigDict
class Settings:
app_env: str ="development"
debug这方面，bool ="false"
database_url:str
model_config=SettingsConfigDict(
env_file=".env",env_file_encoding="utf-8",extra="ignore"
)
settings=Settings

多环境支持

.env.development / .env.production 等文件即可；话说回来，通过 `Settings` 或者 `env_file=` 来切换。

八、数据库连接池

# app/db/session.py
import sqlalchemy as sa
from sqlalchemy.orm import sessionmaker
from app.core.config import settings
engine=sa.create_engine
SessionLocal=sessionmaker(bind=engine,autoflush=False,autocommit=False)
# app/dependencies/database.py
import collections.abc as abc
import typing as t
from fastapi import Depends
from sqlalchemy.orm import Session
from app.db.session import SessionLocal
DbSession=t.Annotated
def get_db -> abc.Generator:
db=SessionLocal
try这方面。yield db
finally:
db.close

九、数据访问层

# repo/todo_repository.py
import sqlachemy as sa
import typing as t
from sqlalchemy.orm import Session
from ..models import Todo
from ..schemas import TodoCreate,Todoupdate
class TodoRepository:
def __init__: self.db=db
def create->Todo:
todo=(title=payload.title,description=payload.description)
self.db.add;self.db.commit;self.db.refresh
return todo
def list->list:
stmt=.offset.limit
return list.all)
def get_by_id->Todo|None:
return self.db.get
def update->Todo:
data=payload.model_dump
for k,v in data.items: setattr
self.db.commit;self.db.refresh;return todo
def delete ->None :
self.db.delete;self.db.commit

*痛点解决*

• 所有 DB 操作集中在 Repository，避免了服务层写 SQL 的碎片化代码。

*业务层*

# service/todoservice.py
import typing as t
import sqlachemy as sa
from ..models.totoos.models from ..repo.todorepository from ..schemas.totoos.schemas from ...core.exceptions NotFoundError 

def create_todo -> repo=RepoType;return repo.create

def list_todos: repo=RepoType;  ，offset=*size; ，return repo.list

def gettodo-> repo=&l， totooorpo.getby_id“;if not t，不过，raise NotFoundError

def update_todo->...etc......... 再看**注**。这里简化了错误处理，只演示主要原因。

---

*异常统一处理*

html+python

python

主要所有自定义错误继承 。FastAPI 自动捕获并返回统一 JSON。其实，

---

分页 & 通用响应壳

• : 包装任何类型的数据。
• : 分页包装器。
• 函数统一构造成功响应。

---

完整接口实现

---

数据库迁移

• 初始化这方面，uv run alembic init migrations
• 自动生成这方面。uv run alembic revision --autogenerate -m "create todos table"
• 再看执行迁移，uv run alembic upgrade head
• 必须在 migrations/env.py 中 target_metadata= 指向 Base.metadata。

---

日志

设置全局日志格式；在 Service 层记录关键操作。其实，

---

测试

至于运行测试，uv run pytest

---

小结

通过上面组织方式。你可以：

1. 快速定位改动范围 – 所有业务相关代码都聚集在对应模块内；
2. 共享全局功能 – 日志、异常、安全等只需写一次；
3. 易于 – 新增模块只需创建一个文件夹并按约定添加文件；
4. 保证质量 – 单元测试覆盖主要功能，避免回归；
5. 生产友好 – 自动化迁移和日志让上线后运维更顺畅。

祝你开发愉快 🚀

---