1. 从零到一一个完整的 FastAPI 项目实战复盘最近在社区里看到一个挺有意思的葡萄牙语开源教程项目叫“FastAPI do Zero”。虽然页面是葡萄牙语但技术栈和路径对我们来说再熟悉不过了FastAPI、Pydantic、SQLAlchemy、Alembic最后用 Docker 打包通过 CI/CD 部署到 fly.io。这本质上就是一个非常标准的现代 Python Web API 开发与部署的“全家桶”实践。我自己也带过不少新人团队发现很多朋友学 FastAPI容易陷入“只会写单个接口”的困境。知道怎么用app.get但一说到项目结构、数据库迁移、认证授权、容器化部署就有点发懵。这个“从零开始”的项目路线图恰好提供了一个绝佳的、可复现的练手路径。今天我就结合自己多年的实战经验把这个路线图“翻译”并扩展成一篇详尽的实战指南不仅告诉你每一步怎么做更会拆解背后的“为什么”并附上我踩过的坑和总结的技巧。无论你是想系统学习 FastAPI还是手头有个新项目需要技术选型参考这篇文章都能给你一个清晰的蓝图。2. 项目蓝图与核心架构设计解析2.1 为什么是这套技术栈看到 FastAPI Pydantic SQLAlchemy Alembic 的组合老 Python 开发者会心一笑。这不是随意拼凑而是一套经过市场检验、优势互补的“黄金组合”。FastAPI作为核心框架其优势在于极致的开发体验和性能。基于 Python 类型提示Type Hints的自动 API 文档生成Swagger UI / ReDoc是它最大的卖点之一这极大地减少了前后端沟通成本。其底层基于 Starlette用于 Web和 Pydantic用于数据验证保证了异步支持和数据处理的效率。Pydantic在这里扮演了双重角色。一是作为 FastAPI 的依赖用于请求和响应数据的验证与序列化。二是我们可以在项目内部用它来定义纯粹的数据模型DTO确保在业务逻辑层流转的数据结构是明确且安全的。它的验证逻辑运行在编译时通过类型提示和运行时比手动写一堆if...else判断优雅且可靠得多。SQLAlchemy是 Python 生态里最强大、最流行的 ORM对象关系映射工具。它提供了高度的灵活性和表达能力。“用 Python 对象的方式操作数据库”这个理念大大提升了开发效率和代码可读性。虽然学习曲线稍陡但一旦掌握应对复杂查询和数据库操作会游刃有余。Alembic是 SQLAlchemy 作者编写的数据库迁移工具。它解决了数据库模式Schema版本化管理这个核心痛点。没有它团队协作和线上部署时数据库结构的同步将是噩梦。Alembic 可以自动生成迁移脚本、支持升级和回滚是任何严肃项目不可或缺的一环。这套组合拳打下来覆盖了现代 Web API 开发的几乎所有核心需求路由、验证、序列化、数据库操作、模式迁移。而且它们之间的集成度非常高社区支持也好避免了“踩雷”第三方兼容性问题的风险。2.2 项目阶段划分与学习路径设计原教程的 14 节课加一个最终项目可以清晰地划分为四个大阶段这非常符合认知规律和项目推进的节奏基础入门与环境搭建第 0-2 课解决“从哪开始”的问题。配置 Python 环境、理解 HTTP 和 Web 开发基础概念、创建第一个 FastAPI 应用。这一步的目标是让开发环境跑起来并消除对 Web 开发的陌生感。核心功能开发与集成第 3-6 课这是项目的“躯干”。从定义数据模型Pydantic、创建 CRUD 路由到引入数据库SQLAlchemy、管理迁移Alembic最后实现用户认证与授权JWT。至此一个具备基本功能的、有数据持久化的 API 就完成了。架构优化与进阶特性第 7-10 课这是让项目从“能用”到“好用”的关键。重构项目结构使其更清晰、引入异步编程提升性能、加固认证系统、实现更复杂的业务逻辑如任务管理。这一步关注代码质量和系统能力。部署上线与工程化第 11-13 课这是临门一脚。用 Docker 容器化应用保证环境一致性用 CI/CD 自动化测试和部署流程最终部署到云平台fly.io让服务对外可用。这一步将开发成果转化为真正的产品。这个路径设计得非常务实它模拟了一个真实项目的完整生命周期。我建议学习者严格按照这个顺序进行不要跳步。比如不要在还没弄懂同步数据库操作时就急着去搞异步那样只会增加理解负担。3. 环境配置与项目初始化实操要点3.1 开发环境搭建不止于pip install很多教程让你直接pip install fastapi uvicorn就结束了。但对于一个长期项目我们需要一个更可控、更干净的环境。首选方案使用uv工具强烈推荐uv是一个用 Rust 写的、极速的 Python 包安装器和项目管理器。它比传统的pipvenv组合快一个数量级并且内置了虚拟环境管理。# 安装 uv (macOS/Linux) curl -LsSf https://astral.sh/uv/install.sh | sh # 进入你的项目目录 cd my_fastapi_project # 使用 uv 初始化项目这会创建 pyproject.toml 和虚拟环境 uv init # 使用 uv 添加依赖它会自动处理版本兼容并更新 pyproject.toml uv add fastapi uvicorn sqlalchemy pydantic-settings为什么推荐 uv速度极快依赖解析和下载安装过程比 pip 快很多。一体化一个工具替代了pip、venv、pip-tools等多个工具。可复现性它生成的pyproject.toml和uv.lock锁文件能完美锁定依赖版本确保所有开发者和生产环境的一致性。备选方案传统的venvpip如果你更习惯传统方式务必使用pyproject.toml来管理依赖。python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 将依赖写入 pyproject.toml 的 [project] 部分 # 然后使用 pip 安装 pip install -e .注意无论用哪种方式永远不要将虚拟环境目录.venv提交到 Git 中。务必在.gitignore文件中添加.venv/和__pycache__/。3.2 项目结构雏形为未来打好地基在写第一行业务代码前花几分钟规划一下目录结构能省去后期大量重构的麻烦。一个清晰的初始结构可以这样安排my_fastapi_project/ ├── .gitignore ├── pyproject.toml # 项目配置与依赖声明 ├── uv.lock # 锁文件 (如果使用 uv) ├── README.md ├── app/ # 主应用包 │ ├── __init__.py │ ├── main.py # FastAPI 应用实例和根路由 │ ├── core/ # 核心配置、安全、工具函数 │ │ ├── __init__.py │ │ ├── config.py # 配置管理 (使用 Pydantic Settings) │ │ └── security.py # 认证授权相关工具 │ ├── api/ # 路由层 │ │ ├── __init__.py │ │ └── v1/ # API 版本1 │ │ ├── __init__.py │ │ ├── endpoints/ # 各个端点的路由文件 │ │ │ ├── __init__.py │ │ │ ├── items.py │ │ │ └── users.py │ │ └── deps.py # 依赖注入项 │ ├── models/ # SQLAlchemy 数据模型 (ORM) │ │ ├── __init__.py │ │ └── user.py │ ├── schemas/ # Pydantic 数据模型 (请求/响应) │ │ ├── __init__.py │ │ └── user.py │ ├── crud/ # 数据库 CRUD 操作层 │ │ ├── __init__.py │ │ └── user.py │ └── db/ # 数据库会话和引擎 │ ├── __init__.py │ └── session.py ├── alembic/ # Alembic 迁移目录 │ ├── versions/ │ └── env.py ├── tests/ # 测试目录 │ ├── __init__.py │ └── test_main.py └── scripts/ # 自定义脚本可选这个结构遵循了“关注点分离”原则。api只处理 HTTP 和路由crud处理数据库交互models和schemas定义数据结构core放全局配置和工具。一开始可能觉得有点“过度设计”但随着功能增加你会发现代码依然清晰可维护。4. 数据库集成与迁移管理深度实践4.1 SQLAlchemy 模型定义不仅仅是字段映射定义 SQLAlchemy 模型时很多人只写字段名和类型。其实这里有很多细节可以优化。# app/models/user.py from sqlalchemy import String, Boolean from sqlalchemy.orm import Mapped, mapped_column, relationship from app.db.session import Base # 假设 Base 在 session.py 中定义 class User(Base): __tablename__ users id: Mapped[int] mapped_column(primary_keyTrue, indexTrue) email: Mapped[str] mapped_column(String(255), uniqueTrue, indexTrue, nullableFalse) username: Mapped[str] mapped_column(String(50), uniqueTrue, indexTrue, nullableFalse) hashed_password: Mapped[str] mapped_column(String(255), nullableFalse) is_active: Mapped[bool] mapped_column(Boolean, defaultTrue) is_superuser: Mapped[bool] mapped_column(Boolean, defaultFalse) # 定义关系例如一个用户有多篇文章 # articles: Mapped[list[Article]] relationship(back_populatesauthor, cascadeall, delete-orphan)关键点解析使用Mapped类型注解这是 SQLAlchemy 2.0 的风格能提供更好的类型提示支持让 IDE 更智能。合理使用索引对email、username这种常用于查询和唯一性约束的字段添加indexTrue能大幅提升查询速度。但索引不是越多越好它会影响写入性能。设置字段长度对String类型指定长度如String(255)既是良好的数据库设计习惯也能避免存储空间浪费。明确空值约束使用nullableFalse明确哪些字段不能为空让数据完整性由数据库层面保障。关系定义使用relationship定义模型间的关联。back_populates参数用于建立双向关系cascade参数定义了当父对象被删除或更新时子对象该如何处理如delete-orphan表示删除与父对象脱离关系的子对象。4.2 Alembic 迁移不仅仅是alembic revisionAlembic 的核心是生成和应用迁移脚本。但实战中我们更需要一个可靠的工作流。初始化 Alembic通常只需一次alembic init alembic这会在项目根目录创建alembic.ini配置文件和alembic/目录。配置alembic.ini和env.py这是最容易出错的地方。关键是要让 Alembic 能找到你的模型和数据库 URL。在alembic.ini中修改sqlalchemy.url。但注意更好的做法是不在这里写死而是从环境变量或你的配置文件中读取。所以我们可以先注释掉它# sqlalchemy.url driver://user:passlocalhost/dbname修改alembic/env.py使其从你的应用配置中获取元数据和数据库 URL# alembic/env.py import sys from logging.config import fileConfig from sqlalchemy import engine_from_config, pool from alembic import context # 将项目根目录添加到 Python 路径以便导入 app sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from app.core.config import settings # 你的配置模块 from app.models import Base # 导入包含所有模型的 Base 元数据 # 从配置中获取数据库 URL config context.config config.set_main_option(sqlalchemy.url, settings.DATABASE_URL) target_metadata Base.metadata # ... 文件其余部分保持不变生成迁移脚本# 自动检测模型变化并生成迁移脚本 alembic revision --autogenerate -m 创建用户表重要警告自动生成--autogenerate非常方便但不是万能的。它无法检测到所有变化比如重命名列、某些复杂的约束变化。生成脚本后务必仔细检查alembic/versions/下的新脚本文件确认 SQL 语句符合你的预期。应用迁移# 升级到最新版本 alembic upgrade head # 降级一个版本 alembic downgrade -1 # 查看当前版本 alembic current # 查看历史 alembic history --verbose实战心得迁移脚本是代码的一部分生成的迁移脚本应该被提交到版本控制系统如 Git。这样任何克隆项目的人都能通过alembic upgrade head将数据库同步到正确状态。测试迁移在本地或测试环境尝试alembic downgrade -1然后再alembic upgrade head确保回滚和升级都能正常工作。不要在生产环境直接运行alembic命令生产环境的数据库迁移应该通过 CI/CD 流程或经过严格评审的部署脚本进行并且一定要先备份数据。5. 认证授权与项目结构优化实战5.1 JWT 认证实现安全是第一位使用 JWTJSON Web Token进行无状态认证是 API 的常见选择。但实现时安全细节决定成败。核心步骤用户登录验证用户名密码后生成一个包含用户标识如user_id和过期时间exp的 JWT。返回 Token将 JWT 返回给客户端客户端通常在后续请求的Authorization头中携带Bearer token。保护路由创建一个 FastAPI 依赖项用于解析和验证 JWT并提取当前用户信息。一个更健壮的安全工具模块示例# app/core/security.py from datetime import datetime, timedelta, timezone from typing import Any, Union from jose import JWTError, jwt from passlib.context import CryptContext from app.core.config import settings pwd_context CryptContext(schemes[bcrypt], deprecatedauto) def verify_password(plain_password: str, hashed_password: str) - bool: 验证密码 return pwd_context.verify(plain_password, hashed_password) def get_password_hash(password: str) - str: 生成密码哈希 return pwd_context.hash(password) def create_access_token(subject: Union[str, Any], expires_delta: timedelta None) - str: 创建 JWT Token if expires_delta: expire datetime.now(timezone.utc) expires_delta else: expire datetime.now(timezone.utc) timedelta(minutessettings.ACCESS_TOKEN_EXPIRE_MINUTES) to_encode {exp: expire, sub: str(subject)} encoded_jwt jwt.encode(to_encode, settings.SECRET_KEY, algorithmsettings.ALGORITHM) return encoded_jwt def verify_token(token: str) - Union[str, None]: 验证并解析 JWT Token返回用户标识subject try: payload jwt.decode(token, settings.SECRET_KEY, algorithms[settings.ALGORITHM]) sub: str payload.get(sub) if sub is None: return None return sub except JWTError: # 捕获所有 JWT 异常过期、无效签名等 return None创建依赖项以获取当前用户# app/api/v1/deps.py from fastapi import Depends, HTTPException, status from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials from app.core.security import verify_token from app.crud import user as crud_user from app.db.session import SessionLocal security HTTPBearer() async def get_current_user( credentials: HTTPAuthorizationCredentials Depends(security), db: SessionLocal Depends(get_db) # 假设你有获取数据库会话的依赖 ): token credentials.credentials user_id verify_token(token) if user_id is None: raise HTTPException( status_codestatus.HTTP_401_UNAUTHORIZED, detail无效或过期的令牌, headers{WWW-Authenticate: Bearer}, ) user crud_user.get(db, user_id) if user is None or not user.is_active: raise HTTPException(status_codestatus.HTTP_404_NOT_FOUND, detail用户未找到或未激活) return user async def get_current_active_superuser(current_user: User Depends(get_current_user)): 依赖项检查当前用户是否是超级用户 if not current_user.is_superuser: raise HTTPException(status_codestatus.HTTP_403_FORBIDDEN, detail权限不足) return current_user在路由中使用# app/api/v1/endpoints/items.py from fastapi import APIRouter, Depends from app.api.v1.deps import get_current_user, get_current_active_superuser from app.models.user import User router APIRouter() router.get(/me/items) async def read_my_items(current_user: User Depends(get_current_user)): 需要登录才能访问的路由 return {items: [{item_id: 1, owner: current_user.username}]} router.delete(/items/{item_id}) async def delete_item(item_id: int, current_user: User Depends(get_current_active_superuser)): 需要超级用户权限才能访问的路由 # ... 删除逻辑 return {message: Item deleted}安全注意事项SECRET_KEY必须使用强随机字符串并通过环境变量注入绝不能硬编码在代码中。ALGORITHM推荐使用HS256。对于更高安全要求可以考虑RS256非对称加密。Token 过期时间ACCESS_TOKEN_EXPIRE_MINUTES不宜过长通常 15-30 分钟。可以考虑结合 Refresh Token 机制。密码哈希务必使用bcrypt等抗破解的哈希算法绝对不要明文存储或使用 MD5、SHA1 等弱哈希。HTTPS在生产环境必须使用 HTTPS 来传输 Token防止中间人攻击。5.2 项目结构重构从“能跑”到“优雅”当功能越来越多把所有代码堆在main.py里会变得难以维护。重构的目标是让每个文件职责单一依赖关系清晰。重构后的核心变化依赖注入集中管理将创建数据库会话、获取配置等依赖项放在app/api/v1/deps.py中。路由分模块按照业务域如usersitemstasks拆分路由文件放在app/api/v1/endpoints/下。每个文件定义一个APIRouter实例。主文件简化app/main.py只负责创建 FastAPI 应用实例、包含路由、配置中间件和生命周期事件。配置管理使用pydantic-settings从环境变量和.env文件加载配置集中在app/core/config.py。一个典型的app/main.py重构后# app/main.py from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.core.config import settings from app.api.v1.api import api_router # 导入聚合了所有子路由的总路由 from app.db.session import engine from app.models import Base # 导入所有模型确保元数据被加载 # 可选的如果需要在这里创建数据库表通常由 Alembic 管理 # Base.metadata.create_all(bindengine) app FastAPI( titlesettings.PROJECT_NAME, openapi_urlf{settings.API_V1_STR}/openapi.json ) # 设置 CORS 中间件 if settings.BACKEND_CORS_ORIGINS: app.add_middleware( CORSMiddleware, allow_origins[str(origin) for origin in settings.BACKEND_CORS_ORIGINS], allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 包含 API 路由 app.include_router(api_router, prefixsettings.API_V1_STR) app.get(/) async def root(): return {message: 欢迎使用 FastAPI 项目} # 可以在这里添加启动、关闭事件 app.on_event(startup) async def startup_event(): # 例如初始化数据库连接池、加载缓存等 passapp/api/v1/api.py负责聚合路由# app/api/v1/api.py from fastapi import APIRouter from app.api.v1.endpoints import items, users, tasks # 导入各个端点模块 api_router APIRouter() api_router.include_router(users.router, prefix/users, tags[users]) api_router.include_router(items.router, prefix/items, tags[items]) api_router.include_router(tasks.router, prefix/tasks, tags[tasks])这样的结构当需要添加一个新的业务模块如payments时只需要在endpoints/下新建文件并在api.py中加一行include_router即可扩展性非常好。6. 异步化改造与性能考量6.1 为什么需要异步理解 I/O 密集型场景FastAPI 天生支持异步基于 Starlette。当你的应用主要受限于 I/O 操作如网络请求、数据库查询、文件读写时异步可以显著提升并发处理能力用更少的资源服务更多的请求。关键决策点你的数据库驱动支持异步吗这是异步改造的前提。对于 SQLAlchemy你需要使用asyncpgPostgreSQL或aiomysqlMySQL等异步驱动并配合sqlalchemy.ext.asyncio异步引擎。你的其他依赖如 Redis 客户端、HTTP 客户端支持异步吗如果链路上有一个关键库是同步的它可能会阻塞整个事件循环抵消异步的优势。同步 vs 异步数据库会话示例同步改造前# app/db/session.py (同步) from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker, Session engine create_engine(SQLALCHEMY_DATABASE_URL) SessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) def get_db(): db SessionLocal() try: yield db finally: db.close()异步改造后# app/db/session.py (异步) from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker from app.core.config import settings # 注意数据库 URL 格式变化postgresqlasyncpg://... engine create_async_engine(settings.ASYNC_DATABASE_URL, echoTrue) AsyncSessionLocal async_sessionmaker(engine, class_AsyncSession, expire_on_commitFalse) async def get_db() - AsyncSession: async with AsyncSessionLocal() as session: try: yield session finally: await session.close()对应的 CRUD 操作也需要改为异步# app/crud/user.py (异步示例) from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy import select from app.models.user import User async def get_user_by_email(db: AsyncSession, email: str): result await db.execute(select(User).where(User.email email)) return result.scalar_one_or_none() # 使用异步执行路由处理函数也需要使用async def# app/api/v1/endpoints/users.py router.get(/{user_id}, response_modelschemas.User) async def read_user(user_id: int, db: AsyncSession Depends(get_db)): user await crud_user.get(db, user_id) # ...重要提醒异步改造不是银弹。如果应用是 CPU 密集型的如图像处理、复杂计算异步可能不会带来性能提升甚至可能因为事件循环管理而增加复杂度。改造前请先分析你的应用瓶颈所在。6.2 异步化过程中的常见陷阱阻塞操作在异步函数中绝对不要调用同步的、可能耗时的 I/O 操作如time.sleep(5)、同步的数据库查询、同步的文件读写。这会阻塞整个事件循环导致所有其他请求都被卡住。对于无法避免的阻塞操作应该使用asyncio.to_thread或run_in_executor将其放到线程池中运行。会话管理异步会话 (AsyncSession) 的生命周期管理比同步会话更需要注意。确保使用async with上下文管理器或在依赖项中正确地进行await session.close()。测试测试异步代码需要使用pytest-asyncio等插件。测试函数也需要定义为async def并使用await调用被测试的异步函数。7. 容器化、测试与部署全流程7.1 Docker 容器化构建可复现的环境Docker 的目标是“一次构建处处运行”。一个优化的Dockerfile能减少镜像体积加快构建速度。# 使用官方 Python 精简版镜像作为构建和运行环境 FROM python:3.12-slim AS builder # 安装构建依赖如编译器等并在完成后清理以减小镜像 RUN apt-get update apt-get install -y --no-install-recommends \ gcc \ rm -rf /var/lib/apt/lists/* # 设置工作目录 WORKDIR /app # 使用 uv 安装依赖如果使用 uv COPY pyproject.toml uv.lock ./ RUN pip install uv uv pip install --system -r pyproject.toml # 或者使用 pip 安装依赖 # COPY requirements.txt . # RUN pip install --no-cache-dir --upgrade -r requirements.txt # 复制应用代码 COPY . . # 多阶段构建创建更小的运行时镜像 FROM python:3.12-slim AS runtime WORKDIR /app # 从构建阶段复制已安装的 Python 包 COPY --frombuilder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages COPY --frombuilder /app /app # 创建一个非 root 用户运行应用提高安全性 RUN useradd -m -u 1000 appuser chown -R appuser:appuser /app USER appuser # 暴露端口与 FastAPI 应用启动端口一致 EXPOSE 8000 # 启动命令使用 uvicorn CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]优化点多阶段构建第一阶段安装依赖和编译第二阶段只复制运行所需的最小文件大大减小了最终镜像体积。使用slim镜像比完整版python:3.12镜像小很多。清理 apt 缓存在RUN apt-get install后立即清理避免缓存占用镜像空间。使用非 root 用户避免容器以 root 权限运行遵循最小权限原则提升安全性。.dockerignore文件在项目根目录创建.dockerignore排除.git__pycache__.venv等不需要复制到镜像中的文件加速构建过程。7.2 自动化测试与 CI/CD质量守护神没有自动化测试和持续集成的项目就像没有刹车的汽车。原教程第 12 课提到了“使用持续集成自动化测试”。基本的 Pytest 测试示例# tests/test_users.py import pytest from fastapi.testclient import TestClient from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker from app.main import app from app.db.session import Base, get_db # 为测试创建独立的数据库如 SQLite 内存数据库 SQLALCHEMY_DATABASE_URL sqlite:///./test.db engine create_engine(SQLALCHEMY_DATABASE_URL, connect_args{check_same_thread: False}) TestingSessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) # 覆盖原依赖使测试使用我们创建的会话 def override_get_db(): try: db TestingSessionLocal() yield db finally: db.close() app.dependency_overrides[get_db] override_get_db client TestClient(app) def test_create_user(): response client.post( /api/v1/users/, json{email: testexample.com, password: secret, username: testuser} ) assert response.status_code 200 data response.json() assert data[email] testexample.com assert id in data # 测试前创建表测试后删除表 pytest.fixture(scopesession, autouseTrue) def create_test_tables(): Base.metadata.create_all(bindengine) yield Base.metadata.drop_all(bindengine)使用 GitHub Actions 的 CI 配置示例# .github/workflows/test.yml name: Run Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest services: postgres: image: postgres:16 env: POSTGRES_PASSWORD: postgres options: - --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 ports: - 5432:5432 steps: - uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv5 with: python-version: 3.12 - name: Install uv run: | curl -LsSf https://astral.sh/uv/install.sh | sh echo $HOME/.cargo/bin $GITHUB_PATH - name: Install dependencies run: uv pip install -e .[test] # 假设你的 pyproject.toml 中有 test 额外依赖组 - name: Run tests with pytest env: DATABASE_URL: postgresql://postgres:postgreslocalhost:5432/test_db run: | pytest -v --covapp --cov-reportxml这个工作流会在每次推送代码或创建拉取请求时自动运行它会启动一个 PostgreSQL 容器安装依赖然后运行测试并生成测试覆盖率报告。7.3 部署到 fly.io让应用上线fly.io 是一个非常适合部署容器化应用的平台对小型项目有免费额度。部署流程通常与 CI/CD 结合。核心步骤安装 flyctl 并登录在本地或 CI 环境中安装 flyctl 命令行工具并进行认证。创建 fly.toml 配置文件这是 fly.io 的应用配置定义了应用名称、构建方式、环境变量、资源限制等。# fly.toml app your-fastapi-app-name primary_region iad # 例如美国弗吉尼亚 [build] dockerfile Dockerfile [http_service] internal_port 8000 force_https true auto_stop_machines true auto_start_machines true min_machines 1 max_machines 1 [[http_service.checks]] interval 10s timeout 2s grace_period 5s method GET path /设置 Secrets将数据库连接字符串、JWT 密钥等敏感信息通过flyctl secrets set命令设置为环境变量而不是写在配置文件中。部署运行flyctl deploy。它会根据Dockerfile构建镜像并推送到 fly.io 平台运行。将部署集成到 CI/CD你可以在 GitHub Actions 工作流中添加一个部署步骤通常在测试通过后且是推送到主分支时触发。# 在 test job 之后添加 deploy: needs: test if: github.ref refs/heads/main success() runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: superfly/flyctl-actions/setup-flyctlmaster - run: flyctl deploy --remote-only env: FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}8. 常见问题与排查技巧实录在实际开发和部署中你几乎一定会遇到下面这些问题。这里是我总结的一些排查思路和解决方案。8.1 数据库连接与迁移问题问题1Alembic 无法检测到模型变化--autogenerate不生成迁移脚本。可能原因1alembic/env.py中的target_metadata没有正确指向包含所有模型的Base.metadata。确保你从正确的模块导入了Base。可能原因2模型文件没有被 Python 解释器导入。Alembic 需要能“看到”你的模型类。检查env.py中是否通过from app.models import Base导入了所有模型确保app/models/__init__.py中导入了所有模型类。排查命令在 Python 交互环境中手动导入你的模型和 Base检查Base.metadata.tables是否包含了你的表。问题2数据库连接失败特别是部署后。可能原因1数据库 URL 错误。本地开发常用localhost但部署后数据库可能在其他主机。确保生产环境的环境变量DATABASE_URL已正确设置。可能原因2网络或防火墙问题。在 fly.io 等云平台你的应用可能在一个内部网络中需要确保数据库服务允许来自该网络的连接例如在 fly.io 上可能需要将应用和数据库放在同一个私有网络flycast中。可能原因3连接池耗尽。在高并发下默认的连接池设置可能不够。可以调整 SQLAlchemy 引擎的pool_size和max_overflow参数。排查步骤在应用启动时打印出数据库 URL隐藏密码确认配置被正确加载。尝试在应用运行的容器内使用psql或mysql客户端手动连接数据库验证网络连通性。查看数据库日志看是否有连接尝试被拒绝。8.2 依赖与环境问题问题本地运行正常部署后出现ModuleNotFoundError。可能原因pyproject.toml或requirements.txt没有包含所有必要的依赖或者生产环境使用了不同的 Python 版本。解决方案使用uv pip freeze requirements.txt生成完整的依赖列表如果使用 uv。在Dockerfile中明确指定 Python 版本如FROM python:3.12-slim。在本地使用与生产环境相同的 Python 版本进行测试可以使用pyenv等工具切换版本。确保pyproject.toml中的dependencies部分列出了所有直接依赖。对于开发依赖如测试框架、代码格式化工具可以放在[project.optional-dependencies]下如dev或test组。8.3 异步代码中的疑难杂症问题在异步路由中调用了一个同步的第三方库如requests导致应用响应变慢甚至卡死。原因同步的 I/O 操作会阻塞整个 asyncio 事件循环。解决方案寻找异步替代品用httpx替代requests用aiofiles替代同步文件操作。使用线程池执行如果找不到异步替代品使用asyncio.to_thread()将同步函数放到后台线程中运行避免阻塞事件循环。import asyncio import requests async def async_fetch(url): loop asyncio.get_event_loop() # 将 requests.get 放到线程池中执行 response await loop.run_in_executor(None, requests.get, url) return response.json()评估必要性如果这个同步调用是性能瓶颈且无法替代可能需要重新考虑这部分逻辑是否适合放在异步上下文中。8.4 部署与运行问题问题应用在 fly.io 上启动成功但访问返回 502 Bad Gateway 或连接超时。可能原因1应用进程没有在fly.toml中internal_port指定的端口上监听。检查你的 FastAPI 应用启动命令如uvicorn是否绑定到了0.0.0.0:8000。可能原因2健康检查失败。fly.io 会根据fly.toml中配置的[[http_service.checks]]定期访问你的应用。如果健康检查路径如path /返回非 2xx 状态码或超时fly.io 会认为应用不健康并停止路由流量。确保你的根路径或健康检查端点能快速返回成功响应。排查命令flyctl logs查看应用容器的实时日志看是否有启动错误或异常。flyctl status检查应用状态。在fly.toml中暂时调大健康检查的timeout和grace_period看看是否是应用启动较慢导致的。问题静态文件如图片、CSS无法访问。原因FastAPI 本身不专门用于服务静态文件虽然可以通过StaticFiles实现但在生产环境这通常不是最佳实践。建议方案使用专业静态文件服务将静态文件上传到对象存储服务如 AWS S3、Cloudflare R2、或 fly.io 自带的volumes并通过 CDN 分发。前端直接引用这些服务的 URL。使用前端框架处理如果是前后端分离项目静态文件应由前端构建工具如 Vite、Webpack处理并通过 Nginx 等服务。仅在开发时使用 StaticFiles在 FastAPI 中可以仅在开发环境配置StaticFiles用于便利。from fastapi.staticfiles import StaticFiles if settings.ENV development: app.mount(/static, StaticFiles(directorystatic), namestatic)走完从环境搭建、功能开发、结构优化、异步改造到容器化部署的完整闭环你对如何使用 FastAPI 构建一个健壮的、可维护的、可部署的 Web API 应该有了扎实的理解。这套流程和工具链不仅适用于这个教程项目完全可以作为你未来任何 FastAPI 新项目的起点模板。最重要的不是记住每一个命令而是理解每个环节解决的问题和背后的设计思想。当你下次再启动一个 FastAPI 项目时不妨直接从这个结构开始然后根据实际需求进行增删改这会让你事半功倍。