栈记
PythonFastAPI

一个标准的 FastAPI 项目

项目结构、路由拆分、参数、依赖注入、鉴权与分层边界

信息

这是看完官网后仍然不理解部分的总结和补充,顺便自己也做个项目模板;

FastAPI

SQLModel 基于 Pydantic 和 SQLAlchemy 开发;

项目启动使用 uvicorn

项目结构

.
├── app
│   ├── api
│   │   ├── router.py       # 路由汇总
│   │   ├── deps.py         # 依赖注入
│   │   └── v1
│   │       └── users.py    # 模块路由
│   ├── common
│   │   ├── constants.py           # 常量
│   │   ├── datetime.py            # 时间工具
│   │   ├── apis.py                # [可选] 示例:第三方接口维护
│   │   └── enums.py               # API 枚举和数据库值映射
│   ├── core
│   │   ├── config.py              # 环境变量配置
│   │   ├── database.py            # 数据库 engine/session/init
│   │   ├── exception_handlers.py  # 全局异常处理
│   │   ├── lifespan.py            # 应用生命周期
│   │   ├── middlewares.py         # 全局中间件 [如果内容比较多可以与 core 平级拆分出 middlewares/]
│   │   └── security.py            # 鉴权、加密、JWT
│   ├── infra
│   │   ├── http.py         # [可选] 示例:第三方 http 请求封装
│   │   └── lark.py         # [可选] 示例:第三方飞书 SDK 封装
│   ├── models
│   │   ├── base.py         # 表通用字段
│   │   └── users.py        # SQLModel 表模型
│   ├── services
│   │   ├── lark            # [可选] 示例:飞书相关业务编排
│   │   │   ├── tasks.py    # [可选] 示例:飞书任务创建、完成、同步
│   │   │   ├── events.py   # [可选] 示例:飞书事件订阅后的业务处理
│   │   │   └── messages.py # [可选] 示例:飞书消息、通知、机器人推送
│   │   ├── users.py        # [可选] 根据业务复杂度是否需要决定   
│   ├── schemas
│   │   ├── base.py         # API 字段命名规范
│   │   ├── common.py       # 分页、统一响应、错误响应等通用 schema
│   │   └── users.py        # 请求/响应模型
│   └── main.py             # 入口文件
├── alembic                 # Alembic 迁移脚本
├── alembic.ini             # Alembic 配置
├── logs                    # 本地运行日志,生产环境通常交给日志系统
├── static                  # 静态资源
│   ├── images
│   └── uploads
├── .env.example            # 环境变量示例
├── .env.test.example       # 测试环境变量示例
├── .env.prod.example       # 生产环境变量示例
├── pyproject.toml
└── uv.lock

路由文件拆分

# app/main.py
from fastapi import FastAPI
from app.api.main import api_router
from app.core.exception_handlers import register_exception_handlers
from app.core.lifespan import lifespan
from app.core.middlewares import register_middlewares

app = FastAPI(
  title="FastAPI Server Template",
  openapi_prefix="/api/v1/openapi.json",
  lifespan=lifespan
)
# 加载所有的路由
app.include_router(api_router, prefix="/api/v1")
# app/router.py
from fastapi import APIRouter
from app.api.v1 import users

api_router = APIRouter()
# 加载模块中的路由并且增加前缀和分类tag
api_router.include_router(users.router, prefix='/users', tags=['users'])
# app/v1/user.py
from fastapi import APIRouter

router = APIRouter()

@router.get('/{user_id}')
def get_user_by_id(): pass

@router.post('')
def create_user(): pass

@router.put('/{user_id}')
def set_user_by_id(): pass

@router.delete('/{user_id}')
def del_user_by_id(): pass

路径参数

与路径参数同名的函数参数会被自动识别成路径参数;

# http://localhost:8000/users/xxx
@router.get('users/{user_id}')
def get_user_detail(user_id: int) -> None:
    pass

# 框架进行类型的转换,声明了 int 类型就不能传递 str 类型

对于可选值可以使用枚举类定义参数,让 swagger 文档也具备这样的能力

from enum import Enum

class SwitchState(str, Enum):
    OPEN = 'OPEN'
    CLOSE = 'CLOSE'

@router.get('switch/{state}')
def get_switch_info(state: SwitchState):
    pass

当遇到多个参数的时候可以使用 Path 显示的声明路径参数,默认值参数和Annotated 注入两种方式

@router.get('switch/{state}')
def get_switch_state(q: str, state: int = Path()) -> None:
    pass

@router.get('switch/{state}') # 👍🏻 更推荐
def get_switch_state_1(state: Annotated[int, Path()], q: str) -> None:
    pass

Path 接收常用参数如下,同样的规则也适应于后续的 Query

参数说明
defaultPath 不可用, 默认值
alias给对外的接口起个别名,内部正常使用该值
title不知道
descriptionswagger 字段的描述
gt | ge | lt | le大于,小于,大于等于,小于等于
min_length | max_length最小长度,最大长度

Query 参数

除去路径参数的函数参数,或者使用 Query 显示声明的就是查询参数,设置默认值后表示该字段内容可以不传

from fastapi import Query
from typing import Annotated

@router.get('users')
def get_users(skip: int, limit: int, q: str) -> None:
    pass

@router.get('users')
def get_users(
    q: str | None = '',
    skip: Annotated[int, Query(lt=0, gt=1000)] = 0, 
    limit: int = 0
) -> None:
    pass

参数的校验可以使用 AfterValidator

from pydantic import AfterValidator

def check_query_str(id: str):
    if id.startswith('q'):
        return id
    raise ValueError('ID error')

@router.get('/users')
def get_users(id: Annotated[str, AfterValidator(check_query_str)]):
    pass

多个查询时,也可以使用一个参数去接受,不必要使用多个

from pydantic import BaseModel, Field

class FilterParams(BaseModel):
    # Field 同样是约束字段的类型并且设置默认值的
    limit: int = Field(0, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal['create_at', 'updated_at'] = 'create_at'
    tags: list[str] = []

@router.get('/users')
def get_users(filter_query: Annotated[FilterParams, Query()]):
    pass

Data 参数

接收到非结构性的参数或者没有显示注入 Query Path 的参数就是 data。同样支持两种方式。

不过由于 pydantic 的强大,反而更推荐直接使用,而不是通过 Annotated 增加元数据

class Image(BaseModel):
    path: HttpUrl
    name: str

class User(BaseModel):
    username: str = Field(min_length=4, max_length=20)
    password: str = Field(min_length=6, max_length=12)
    address: str = Field(0, max_length=1000)
    image: Image | None

@router.get('/users')
def get_users(user: User):
    pass

# embed 设置后接收到 json 外层会包裹 user: {} 
@router.get('/users')
def get_users(user: Annotated[User, Body(embed=True)]):
    pass

Form 参数

表单以及文件需要

Header 和 Cookie 本质上也是参数来源声明,和 Query、Path 的思路一致:把 HTTP 请求中的某一部分映射到函数参数上。

from typing import Annotated
from fastapi import Cookie, Depends, Header, HTTPException

def get_current_user(
    token: Annotated[str | None, Header(alias='X-Token')] = None,
    session_id: Annotated[str | None, Cookie()] = None
):
    if token is None and session_id is None:
        raise HTTPException(status_code=401, detail='Not authenticated')
    return {'token': token, 'session_id': session_id}

@router.get('/users/me')
def get_me(current_user: Annotated[dict, Depends(get_current_user)]):
    return current_user

Header 默认会把参数名中的 _ 转成 HTTP Header 常见的 -,例如 user_agent 对应 User-Agent;如果不想依赖这个规则,直接写 alias 更清晰。Cookie 一般按原名读取。

实际项目里很少在业务函数里到处散落 Header() 和 Cookie(),更常见的是把它们收口到依赖函数中,用来解析登录态、租户、灰度标记、trace id 等请求上下文。

Response 返回

响应模型是 API 的对外契约。FastAPI 可以直接把 dict、list、Pydantic Model 转成 JSON,但如果不声明响应结构,文档、字段过滤和响应校验都会变弱。

from pydantic import BaseModel

class UserOut(BaseModel):
    id: int
    username: str
    email: str

直接声明函数返回类型

如果函数真实返回值和对外响应结构一致,直接写返回类型最自然。

@router.get('/users/{user_id}')
def get_user(user_id: int) -> UserOut:
    return UserOut(id=user_id, username='Tom', email='tom@example.com')

@router.get('/users')
def get_users() -> list[UserOut]:
    return [UserOut(id=1, username='Tom', email='tom@example.com')]

这种写法让 Python 类型系统、编辑器提示、OpenAPI 文档保持一致,代码读起来也更像普通 Python 函数。

使用 response_model

response_model 更像“对外响应视图”。它不要求函数真实返回类型和响应模型完全一致,FastAPI 会按它做序列化、校验和字段过滤。

from typing import Any

@router.get('/users/{user_id}', response_model=UserOut)
def get_user(user_id: int) -> Any:
    return {
        'id': user_id,
        'username': 'Tom',
        'email': 'tom@example.com',
        'password': 'should-not-return'
    }

这里即使内部返回了 password,最终响应也会按 UserOut 过滤。

字段不完全一致时可以这样理解:

  • 返回字段多了:按 response_model 过滤,多余字段不会出现在响应里。
  • 少了必填字段:响应校验失败,这是后端返回不符合接口契约。
  • 少了可选字段或默认字段:按默认值或 None 处理。

两种方式怎么选

写法FastAPI 是否用于文档和过滤对类型检查是否友好推荐场景
def fn() -> UserOut是更友好函数真实返回值就是响应模型
@router.get(..., response_model=UserOut)是,且优先级更高需要配合 Any 或真实返回类型返回 ORM、dict、输入输出模型不同、需要过滤敏感字段

实践里可以简单判断:真实返回值就是对外 DTO,用函数返回类型;真实返回值是 ORM、内部对象、组合字典,或者需要过滤敏感字段,用 response_model。

直接返回 Response

需要控制状态码、响应头、Cookie、重定向、文件下载时,再直接操作 Response 或返回 Response 子类。

from fastapi import Response

@router.post('/login')
def login(response: Response):
    response.set_cookie(
        key='session_id',
        value='abc123',
        httponly=True
    )
    return {'message': 'ok'}

如果直接返回 JSONResponse、RedirectResponse 等响应对象,FastAPI 会把它当作最终响应,不再按 response_model 自动转换和过滤。普通业务接口优先声明响应模型,只有确实需要完全控制 HTTP 响应时再直接返回 Response。

依赖注入

FastAPI 的依赖注入不是传统后端框架里的容器注入,更像“请求处理前的函数编排”。一个依赖就是一个可复用函数,它可以声明自己需要哪些请求参数,也可以继续依赖其他函数。

from typing import Annotated
from fastapi import APIRouter, Depends, Header, HTTPException

def verify_token(x_token: Annotated[str | None, Header()] = None):
    if x_token != 'secret':
        raise HTTPException(status_code=401, detail='Invalid token')

def get_current_user(
    x_token: Annotated[str | None, Header()] = None
):
    if x_token != 'secret':
        raise HTTPException(status_code=401, detail='Invalid token')
    return {'id': 1, 'name': 'Tom'}

router = APIRouter(
    prefix='/users',
    tags=['users'],
    dependencies=[Depends(verify_token)]
)

@router.get('/me')
def get_me(current_user: Annotated[dict, Depends(get_current_user)]):
    return current_user

APIRouter(dependencies=...) 和路由装饰器里的 dependencies=[...] 更适合做只关心副作用的事情,比如鉴权、审计、限流;参数里的 Depends(...) 更适合拿到依赖函数的返回值,比如当前用户、数据库 session、分页条件。

注入位置作用范围是否接收返回值典型用途
APIRouter(dependencies=...) / include_router(dependencies=...)一组路由否模块级鉴权、统一请求头校验、租户校验
@router.get(..., dependencies=...)单个路由否单接口权限、特殊校验、日志、限流
路由方法参数 Depends(...)单个参数是当前用户、数据库连接、分页参数、业务上下文

如果依赖函数抛出 HTTPException,请求会中断;同一个请求中相同依赖默认会复用执行结果,必要时可以通过 Depends(dep, use_cache=False) 关闭缓存。

yield 依赖和资源释放

依赖函数不只能 return,也可以 yield。yield 前面的代码在接口执行前运行,yield 后面的代码会在请求结束后继续执行,适合做数据库 session、文件句柄、锁、临时资源这类需要释放的对象。

from typing import Generator
from sqlmodel import Session, create_engine

engine = create_engine('sqlite:///app.db')

def get_session() -> Generator[Session, None, None]:
    session = Session(engine)
    try:
        yield session
    finally:
        session.close()

使用时和普通依赖没有区别:

from typing import Annotated
from fastapi import Depends
from sqlmodel import Session

@router.get('/users')
def get_users(
    session: Annotated[Session, Depends(get_session)]
):
    return session.exec(...)

执行顺序可以理解为:

创建 session
  -> yield session 给路由函数
  -> 路由函数执行
  -> 响应处理完成
  -> finally 中关闭 session

这里不要把数据库连接放进全局变量里给所有请求共用。通常是 engine / pool 这种长生命周期对象放全局或 lifespan,每个请求自己的 session 用 yield 依赖创建和释放。

JWT Token 鉴权

JWT 更准确地说是“签名 token”,不是加密 token。服务端把用户标识、过期时间等信息放进 payload,用密钥签名;客户端拿到 token 后每次请求放到 Authorization: Bearer <token>。服务端验证签名和过期时间后,就能确认这个 token 是否可信。

平时说的“解密 token”,在 JWT 里通常指 decode + verify:解析 payload,同时校验签名、算法和过期时间。

因为 payload 可以被解码看到,所以不要把密码、手机号、身份证、内部权限明细这类敏感信息放进 JWT。常见做法是只放 sub、exp、少量稳定声明。

签发和解析

示例使用 PyJWT: uv add pyjwt

# app/core/security.py
from datetime import datetime, timedelta, timezone
from typing import Any
import jwt
from fastapi import HTTPException, status
from jwt.exceptions import ExpiredSignatureError, InvalidTokenError

SECRET_KEY = 'change-me'
ALGORITHM = 'HS256'
ACCESS_TOKEN_EXPIRE_MINUTES = 30

def create_access_token(
    subject: str,
    expires_delta: timedelta | None = None
) -> str:
    expire = datetime.now(timezone.utc) + (
        expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    )
    payload: dict[str, Any] = {
        'sub': subject,
        'exp': expire
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

def decode_access_token(token: str) -> dict[str, Any]:
    try:
        return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    except ExpiredSignatureError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail='Token expired'
        )
    except InvalidTokenError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail='Invalid token'
        )

exp 是 JWT 标准字段,用来表示过期时间。jwt.decode() 会自动校验 exp,过期后会抛 ExpiredSignatureError。

生产环境里 SECRET_KEY 不应该写死在代码里,应该来自环境变量或配置中心;换密钥会导致旧 token 全部失效。

登录时签发 token

from fastapi import HTTPException, status
from pydantic import BaseModel
from app.core.security import create_access_token

class LoginInput(BaseModel):
    username: str
    password: str

@router.post('/login')
def login(data: LoginInput):
    user = authenticate_user(data.username, data.password)
    # 创建 token
    access_token = create_access_token(subject=str(user.id))
    return {
        'accessToken': access_token,
        'tokenType': 'bearer'
    }

依赖中解析当前用户

from typing import Annotated
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from app.core.security import decode_access_token

bearer_scheme = HTTPBearer()

def get_current_user(credentials: Annotated[HTTPAuthorizationCredentials, Depends(bearer_scheme)]):
    token = credentials.credentials
    payload = decode_access_token(token)
    user_id = payload.get('sub')
    if user_id is None:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail='Invalid token'
        )

    user = get_user_by_id(int(user_id))
    return user

HTTPBearer 会从请求头里读取 Bearer token:

Authorization: Bearer <access_token>

它只负责“从请求里取 token”,真正的解析、过期校验、查用户仍然在 get_current_user() 里完成。

几个对象的作用:

对象 / 方法作用
HTTPBearer()FastAPI security 依赖,从 Authorization 请求头解析 Bearer token
HTTPAuthorizationCredentialsHTTPBearer 的解析结果,包含 scheme 和 credentials
credentials.scheme通常是 Bearer
credentials.credentials真正的 token 字符串
jwt.encode(payload, secret, algorithm=...)签发 JWT
jwt.decode(token, secret, algorithms=[...])解析 JWT,并校验签名、算法、过期时间
ExpiredSignatureErrortoken 已过期
InvalidTokenErrortoken 格式错误、签名错误、算法不匹配等无效 token

OAuth2PasswordBearer 也可以用,它更偏 OAuth2 password flow 和 OpenAPI 文档里的登录授权流程;如果只是做一个普通 Bearer JWT 鉴权,HTTPBearer 更直接。

保护接口

需要登录的接口直接依赖 get_current_user。

from typing import Annotated
from fastapi import Depends

@router.get('/users/me')
def get_me(current_user: Annotated[User, Depends(get_current_user)]):
    return current_user

如果整个 router 都需要登录,也可以放到 router 级别:

router = APIRouter(prefix='/users', tags=['users'], dependencies=[Depends(get_current_user)])

但 router 级别依赖拿不到返回值,适合只做鉴权;如果接口里需要当前用户对象,就用参数上的 Depends(get_current_user)。

常见策略:

Token时间用途
access token15-30 分钟调业务接口
refresh token7-30 天换新的 access token

本文示例只展示 access token。实际项目如果需要长期登录态,通常会再引入 refresh token、token 黑名单或服务端 session 版本号。

Models 和 Schemas

数据库对象、接口入参、接口返回值不能混成一个模型。SQLModel 官方也推荐按创建、表模型、响应模型拆成多个模型,本质上就是把“内部存储”和“外部契约”分开。

分层边界

类型核心角色是否映射数据库常用位置典型用途
SQLModel(table=True)ORM 表模型是models表结构、索引、外键、数据库字段
SQLModel 无 table=True可复用数据模型否models 或 schemas抽公共字段,减少重复
BaseModelAPI / DTO / VO 模型否schemas请求体、响应体、外部接口契约

简单规则:models 管数据库事实,schemas 管 API 承诺。表模型可以参与返回,但不要直接把表模型暴露成响应模型,尤其是包含 hashed_password、权限、状态、软删除、关联对象时。

聚合基类

一般实际情况使用场景下接口字段统一小驼峰,建议先做一个所有 schema 都继承的基类。这个基类主要负责别名、ORM 对象读取、默认序列化策略,不建议把所有业务字段转换都塞进去。

# app/schemas/base.py
from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel

class ApiSchema(BaseModel):
    model_config = ConfigDict(
        alias_generator=to_camel, # 下划线字段统一映射成小驼峰
        validate_by_alias=True, # 接收客户端小驼峰字段
        validate_by_name=True, # 内部代码继续用下划线构造 model
        serialize_by_alias=True, # `model_dump()` 默认输出小驼峰
        from_attributes=True, # ORM 对象转响应 schema
        extra='forbid' # 禁止输入未知字段
    )
属性含义常见用法
extra='forbid'禁止输入未知字段API 入参,避免客户端悄悄传无效字段
extra='ignore'忽略未知字段兼容外部系统脏数据
from_attributes=True从对象属性读取数据ORM 对象转响应 schema
alias_generator=to_camel自动生成字段别名下划线字段统一映射成小驼峰
validate_by_alias=True允许用 alias 输入接收客户端小驼峰字段
validate_by_name=True允许用字段名输入内部代码继续用下划线构造 model
serialize_by_alias=True序列化时默认使用 aliasmodel_dump() 默认输出小驼峰
populate_by_name=True旧配置,允许字段名填充 alias 字段Pydantic v2.11+ 更推荐 validate_by_name=True + validate_by_alias=True
str_strip_whitespace=True自动去掉字符串前后空格用户输入清洗
validate_assignment=True赋值时重新校验字段需要长期持有并修改 model 的场景
use_enum_values=True序列化时使用枚举的 value适合 API 枚举值本身就是字符串;不能替代数据库数字和 API 常量之间的映射

这些配置不要散落在每个 schema 里。通用规则放 ApiSchema,特殊规则只在具体 schema 覆盖。

时间处理

时间字段统一约定:库里存的和接口返回的都是带 Z 的 UTC ISO 字符串,比如 2026-01-01T00:00:00Z。不要存本地时间,也不要存没有时区的 naive datetime。

通过示例,展示通用字段如何统一处理

# app/common/datetime.py
from datetime import datetime, timezone

def to_utc(value: datetime) -> datetime:
    if value.tzinfo is None:
        raise ValueError('datetime must be timezone-aware')
    return value.astimezone(timezone.utc)

def datetime_to_z(value: datetime) -> str:
    return to_utc(value).strftime('%Y-%m-%dT%H:%M:%SZ')

def utc_now_z() -> str:
    return datetime_to_z(datetime.now(timezone.utc))

这里拆成两层:models.TimestampMixin 负责数据库字段和默认值,schemas.TimestampSchema 负责接口字段约束。不要把这些都塞进 ApiSchema,否则 API 通用配置、数据库字段定义、响应格式会混在一起。

表通用时间字段

表里的 created_at、updated_at 这类字段通常每张表都会有,可以抽到 models/base.py。

# app/models/base.py
from sqlalchemy import Column, String
from sqlmodel import Field, SQLModel
from app.common.datetime import utc_now_z

class TimestampMixin(SQLModel):
    created_at: str = Field(
        default_factory=utc_now_z,
        sa_column=Column(String(20), nullable=False, comment='创建时间')
    )
    updated_at: str = Field(
        default_factory=utc_now_z,
        sa_column=Column(String(20), nullable=False, comment='更新时间')
    )

响应通用时间字段

响应 schema 也可以抽时间字段,但不要直接复用上面的 TimestampMixin。API 响应只需要字段和序列化规则,不需要 sa_column 这类数据库定义。

# app/schemas/base.py
from pydantic import Field

class TimestampSchema:
    created_at: str = Field(description='创建时间,格式:2026-01-01T00:00:00Z')
    updated_at: str = Field(description='更新时间,格式:2026-01-01T00:00:00Z')

表模型

# app/models/users.py
from sqlmodel import Field, SQLModel
from app.models.base import TimestampMixin

class UserBase(SQLModel):
    username: str = Field(index=True, min_length=3, max_length=32, sa_column_kwargs={'comment': '用户名'})
    display_name: str | None = Field(default=None, max_length=64, sa_column_kwargs={'comment': '展示名称'})
    email: str = Field(index=True, max_length=255, sa_column_kwargs={'comment': '邮箱'})

# table=True 会创建数据表
class User(UserBase, TimestampMixin, table=True):
    id: int | None = Field(default=None, primary_key=True, description='用户 ID')
    hashed_password: str = Field(sa_column_kwargs={'comment': '密码哈希'})

sqlmodel.Field 同时服务 Pydantic 和 SQLAlchemy,常见属性可以按用途理解:

  • Pydantic 校验:min_length、max_length 这类规则会参与请求和模型校验。
  • OpenAPI 文档:description 会体现在 schema 描述里。
  • SQLModel 生成 Column:sa_column_kwargs={'comment': '...'} 是传给底层 SQLAlchemy Column 的额外参数,适合只补充注释、nullable 这类简单配置。
  • 自定义 Column:sa_column=Column(..., comment='...') 也是 SQLModel Field() 的参数,表示直接交给你自己定义完整的 SQLAlchemy Column,控制力更强。

这里的 created_at、updated_at 来自 TimestampMixin,默认值统一走 utc_now_z(),库内保存的就是 2026-01-01T00:00:00Z 这种字符串,避免不同表各自写 datetime.utcnow() 或混用本地时间。

API Schema

响应 schema 常见三种定义方式,不是所有场景都需要手动组装对象。只要路由声明了 response_model,FastAPI 会按响应 schema 做序列化和字段过滤,表模型里的 hashed_password 不会因为直接返回 ORM 对象就泄漏出去。

from pydantic import Field, field_validator
from app.schemas.base import ApiSchema, TimestampSchema
from app.common.enums import UserStatus, user_status_from_db

# 第一种:只继承 `ApiSchema`,适合字段和表模型语义一致的简单返回。
class UserSimpleRead(ApiSchema):
    id: int = Field(description='用户 ID')
    username: str = Field(description='用户名')
    display_name: str | None = Field(default=None, description='展示名称')
    email: str = Field(description='邮箱')

# 第二种:继承 TimestampSchema, ApiSchema
class UserRead(TimestampSchema, ApiSchema):
    id: int = Field(description='用户 ID')
    username: str = Field(description='用户名')
    display_name: str | None = Field(default=None, description='展示名称')
    email: str = Field(description='邮箱')

# 第三种:字段语义不一致时,在 schema 里集中做转换
class UserRead(TimestampSchema, ApiSchema):
    id: int = Field(description='用户 ID')
    username: str = Field(description='用户名')
    display_name: str | None = Field(default=None, description='展示名称')
    email: str = Field(description='邮箱')
    status: UserStatus = Field(description='用户状态')

    @field_validator('status', mode='before')
    @classmethod
    def validate_status(cls, value):
        if isinstance(value, int):
            return user_status_from_db(value)
        return value

请求和查询 schema 仍然按用途拆开:

from pydantic import Field
from app.common.enums import UserStatus
from app.schemas.base import ApiSchema
from app.schemas.common import PageQuery

class UserQuery(PageQuery):
    keyword: str | None = Field(default=None, description='按用户名或邮箱搜索')
    status: UserStatus | None = Field(default=None, description='用户状态')

class UserCreate(ApiSchema):
    username: str = Field(min_length=3, max_length=32, description='用户名')
    display_name: str | None = Field(default=None, max_length=64, description='展示名称')
    email: str = Field(max_length=255, description='邮箱')
    password: str = Field(min_length=8, max_length=72, description='密码')
    status: UserStatus = Field(default=UserStatus.ACTIVE, description='用户状态')

class UserUpdate(ApiSchema):
    display_name: str | None = Field(default=None, max_length=64, description='展示名称')
    email: str | None = Field(default=None, max_length=255, description='邮箱')

这里有三类字段:

  • UserQuery:Query 参数契约,外部是 pageSize。
  • UserCreate / UserUpdate:请求体契约,接收 displayName,但代码里用 display_name。
  • UserRead:响应契约,显式列出对外字段,不包含 hashed_password。

这套写法牺牲了一点字段重复,但边界最清楚:表模型怎么存、API 怎么暴露互不牵制。

需要注意:ApiSchema 只保证继承它的 schema 会拿到统一配置;不会影响没有继承它的 BaseModel,也不会影响你直接返回的裸 dict、JSONResponse。所以统一小驼峰、时间格式、枚举格式的前提是:接口返回走 response_model,或者手动用 schema 做 model_validate() 后再 model_dump(mode='json')。

枚举映射

实际项目里经常会遇到:数据库里存数字,前后端交互要用大写常量。比如用户状态:ACTIVE DISABLED

表模型继续存数字:

# app/models/users.py
class User(UserBase, TimestampMixin, table=True):
    id: int | None = Field(default=None, primary_key=True, description='用户 ID')
    status: int = Field(
        default=1,
        index=True,
        sa_column_kwargs={'comment': '用户状态'}
    )
    hashed_password: str = Field(sa_column_kwargs={'comment': '密码哈希'})

API 层定义字符串枚举,同时集中维护数字和常量之间的映射:

# app/common/enums.py
from enum import Enum

class UserStatus(str, Enum):
    ACTIVE = 'ACTIVE'
    DISABLED = 'DISABLED'

USER_STATUS_TO_DB = {
    UserStatus.ACTIVE: 1,
    UserStatus.DISABLED: 2
}

DB_TO_USER_STATUS = {
    1: UserStatus.ACTIVE,
    2: UserStatus.DISABLED
}

def user_status_to_db(status: UserStatus) -> int:
    return USER_STATUS_TO_DB[status]

def user_status_from_db(status: int) -> UserStatus:
    return DB_TO_USER_STATUS[status]

请求体里接收大写常量,再转成数据库数字:

from app.common.enums import UserStatus, user_status_to_db

class UserCreate(ApiSchema):
    username: str = Field(min_length=3, max_length=32)
    status: UserStatus = UserStatus.ACTIVE

def create_user(user: UserCreate):
    db_user = User(
        username=user.username,
        status=user_status_to_db(user.status),
        hashed_password='...'
    )
    return db_user

响应时可以在 schema 里把数据库数字转回大写常量:

from pydantic import field_validator

class UserRead(TimestampSchema, ApiSchema):
    id: int
    username: str
    status: UserStatus

    @field_validator('status', mode='before')
    @classmethod
    def validate_status(cls, value):
        if isinstance(value, int):
            return user_status_from_db(value)
        return value

@router.get('/users/{user_id}', response_model=UserRead)
def get_user(user_id: int):
    user = get_user_by_id(user_id)
    return user

这里不建议在业务代码里到处写 1、2,也不建议直接把数据库数字暴露给前端。数字是存储细节,大写常量才是 API 契约。

转成 dict 后再覆盖字段也会把转换逻辑散落在路由函数里。让 response_model 进入 UserRead,再由 schema validator 统一处理,更稳定。

model_config = ConfigDict(use_enum_values=True) 只能决定 Pydantic 序列化枚举时输出 ACTIVE 还是 UserStatus.ACTIVE 这类对象表示;它不能把数据库里的 1 自动理解成 ACTIVE。只要数据库值和 API 值不是同一种语义,就需要显式映射,位置可以放在 app/common/enums.py、领域 service,或者具体 schema 的 validator 里,但不要散落在路由函数里。

如果字段很多且稳定,schema 也可以继承 models 里的无 table=True 基类,但这应该是有意识的复用,而不是默认选择。

# 可选:复用 models.UserBase 的字段
from app.models.users import UserBase
from app.schemas.base import ApiSchema, TimestampSchema

class UserRead(UserBase, TimestampSchema, ApiSchema):
    id: int

这并不表示“继承了 ApiSchema 就不能继承 UserBase”。技术上可以,但要注意两个问题:

  • UserBase 来自 models,字段设计会受数据库影响;UserRead 是对外响应契约,不能把内部字段顺手暴露出去。
  • 多继承会让配置来源更隐含,小驼峰、from_attributes、字段过滤这些行为要确认最终仍然来自 ApiSchema。
  • 时间字段如果要复用,优先继承 schemas.TimestampSchema,不要直接继承 models.TimestampMixin。

所以默认推荐 UserRead(TimestampSchema, ApiSchema) 加显式业务字段;只有字段稳定、团队熟悉 SQLModel 多模型模式,并且确认不会泄漏内部字段时,再用 UserRead(UserBase, TimestampSchema, ApiSchema) 复用。

Query、Data、Response 聚合

from typing import Annotated
from fastapi import Depends, Query
from sqlmodel import Session, select

from app.db import get_session
from app.common.enums import user_status_to_db
from app.models.users import User
from app.schemas.users import UserCreate, UserQuery, UserRead, UserSimpleRead

@router.get('/users/simple', response_model=list[UserSimpleRead])
def get_simple_users(
    query: Annotated[UserQuery, Query()],
    session: Annotated[Session, Depends(get_session)]
):
    statement = (
        select(User)
        .offset((query.page - 1) * query.page_size)
        .limit(query.page_size)
    )
    return session.exec(statement).all()

@router.get('/users', response_model=list[UserRead])
def get_users(
    query: Annotated[UserQuery, Query()],
    session: Annotated[Session, Depends(get_session)]
):
    statement = (
        select(User)
        .offset((query.page - 1) * query.page_size)
        .limit(query.page_size)
    )
    return session.exec(statement).all()

@router.post('/users', response_model=UserRead)
def create_user(
    user: UserCreate,
    session: Annotated[Session, Depends(get_session)]
):
    db_user = User(
        username=user.username,
        display_name=user.display_name,
        email=user.email,
        status=user_status_to_db(user.status),
        hashed_password=hash_password(user.password)
    )
    session.add(db_user)
    session.commit()
    session.refresh(db_user)
    return db_user

手动序列化

使用 response_model=UserRead 时,FastAPI 会负责把 ORM 对象按响应模型转换并序列化。需要自己处理返回值的场景通常有三类:直接返回 JSONResponse、写缓存、记录发送给第三方的 payload。

db_user = session.get(User, user_id)

schema_user = UserRead.model_validate(db_user)
payload = schema_user.model_dump(mode='json')

如果 UserRead 继承了上面的 ApiSchema,payload 会使用小驼峰 key:

如果没有设置 serialize_by_alias=True,就需要显式写:

payload = UserRead.model_validate(db_user).model_dump(
    mode='json',
    by_alias=True
)

这几个 API 的职责:

  • model_validate(obj):把 ORM 对象、dict 或其他对象转换成 Pydantic model,并执行校验;schema 里的 validator 会在这个过程中处理状态映射。
  • model_dump():把 model 转成 Python dict。
  • model_dump(mode='json'):输出更接近 JSON 的结构,枚举、别名等序列化规则会在这里生效。
  • model_dump(by_alias=True):按别名输出字段,也就是小驼峰。

普通接口优先交给 response_model:字段一致就直接返回 ORM,让响应模型过滤敏感字段;需要统一时间格式就让响应 schema 继承 TimestampSchema;数据库值和 API 值语义不一致时,优先放到 schema validator 里;只有跳过 FastAPI 响应模型时,才手动 model_validate() 后再 model_dump()。

复用策略

策略写法优点缺点适合场景
表模型和 schema 完全分离User(SQLModel, table=True) + UserRead(TimestampSchema, ApiSchema)边界清晰,最不容易泄漏字段字段重复安全要求高、多人协作、字段差异大
SQLModel 基类复用字段UserBase(SQLModel) + User(UserBase, table=True) + UserRead(UserBase, TimestampSchema, ApiSchema)重复少,约束集中,仍能复用 ApiSchema 配置多继承更隐含,要确认不会泄漏内部字段字段稳定、团队熟悉 SQLModel
直接用表模型做响应response_model=User最省代码容易暴露内部字段,响应契约被数据库牵着走只适合内部 demo 或临时脚本

我的默认建议是第一种:对外 schema 继承 ApiSchema 和必要的 schema mixin,业务字段显式声明,保证小驼峰、ORM 转换、响应过滤都集中在 API 边界。只有字段稳定且团队熟悉 SQLModel 的继承模型时,再考虑用无 table=True 的 UserBase 复用字段。遇到密码、权限、状态、软删除、内部备注、关联对象时,不要复用,显式拆到不同 schema。

列表查询和统一返回

列表接口不要每个业务各写一套 page、pageSize、sortBy、sortOrder。更推荐先定义一套通用查询协议,业务查询 schema 再继承它补充自己的过滤条件。

# app/schemas/common.py
from typing import Generic, TypeVar
from pydantic import Field
from app.schemas.base import ApiSchema

T = TypeVar('T')

class PageQuery(ApiSchema):
    page: int = Field(default=1, ge=1, description='页码')
    page_size: int = Field(default=20, ge=1, le=100, description='每页数量')
    sort_by: str | None = Field(default=None, description='排序字段')
    sort_order: str = Field(default='desc', pattern='^(asc|desc)$', description='排序方向')

    @property
    def offset(self) -> int:
        return (self.page - 1) * self.page_size

class PageResult(ApiSchema, Generic[T]):
    total: int = Field(description='总条数')
    items: list[T] = Field(description='当前页数据')

class ErrorResponse(ApiSchema):
    code: str = Field(description='错误码')
    message: str = Field(description='错误信息')
    details: object | None = Field(default=None, description='错误详情')

因为继承了 ApiSchema,外部 Query 仍然是小驼峰:pageSize、sortBy、sortOrder;Python 代码里继续用 page_size、sort_by、sort_order。业务子类继续继承 PageQuery 时,子类里新增的下划线字段也会继承同一套 alias 规则。

业务查询只声明业务过滤条件:

# app/schemas/users.py
from pydantic import Field
from app.common.enums import UserStatus
from app.schemas.common import PageQuery

# 由于 PageQuery 继承了 ApiSchema 所以 user_name 仍然对外是小驼峰交互
class UserQuery(PageQuery):
    keyword: str | None = Field(default=None, description='按用户名或邮箱搜索')
    user_name: str | None = Field(default=None, description='用户名,外部参数是 userName')
    status: UserStatus | None = Field(default=None, description='用户状态')

正常返回可以分两类:

from typing import Annotated
from fastapi import HTTPException, Query, status
from app.schemas.common import PageResult
from app.schemas.users import UserQuery, UserRead

@router.get('/users', response_model=PageResult[UserRead])
def get_users(query: Annotated[UserQuery, Query()]):
    # 伪代码:真实项目里这里通常来自 repository/service
    total = count_users(query)
    users = query_users(query=query, offset=query.offset, limit=query.page_size)

    return PageResult[UserRead](
        total=total,
        items=users
    )

@router.get('/users/{user_id}', response_model=UserRead)
def get_user(user_id: int):
    user = get_user_by_id(user_id)
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail='User not found'
        )
    return user

列表返回用 PageResult[UserRead],详情返回仍然是标准对象 UserRead,不要为了统一而把所有接口都包一层 data。

PageResult[UserRead] 里的 PageResult 自己继承了 ApiSchema,所以 total、items 这些外层字段按 API 规则序列化;泛型参数 UserRead 如果也继承了 ApiSchema,那么 items 里的对象同样会按 UserRead 的规则处理,比如小驼峰、枚举转换、字段过滤、from_attributes。如果传进去的是没有继承 ApiSchema 的普通模型,那就只按那个模型自己的 Pydantic 配置处理。

错误处理

全局错误处理放在 core/exception_handlers.py 它不属于某个业务模块,而是应用级横切能力:统一错误响应、隐藏内部异常、记录日志、处理参数校验失败。

注册异常处理器

统一暴露一个注册函数,在 main.py 调用。这样入口文件只关心“注册”,不关心每一种异常怎么处理。

handler 本身建议拆成普通函数,最后通过 app.add_exception_handler() 注册;相比 @app.exception_handler(...) 装饰器嵌套在注册函数里,这种写法更容易测试、复用和拆文件。

from fastapi import status
from fastapi.responses import JSONResponse
from app.schemas.common import ErrorResponse

def error_response(
    code: str,
    message: str,
    status_code: int,
    details: object | None = None
) -> JSONResponse:
    payload = ErrorResponse(code=code, message=message, details=details)
    return JSONResponse(
        status_code=status_code,
        content=payload.model_dump(mode='json')
    )

async def http_exception_handler(request: Request, exc: HTTPException):
    # 这里可以记录 HTTP 异常日志,比如 404、403、业务里主动抛出的 HTTPException
    # 这里统一返回结构
    return error_response(
        code='HTTP_ERROR',
        message=str(exc.detail),
        status_code=exc.status_code
    )

async def validation_exception_handler(request: Request, exc: RequestValidationError):
    # 这里可以记录参数校验失败日志,必要时带上 request.url
    # 这里统一返回结构
    return error_response(
        code='VALIDATION_ERROR',
        message='Request validation failed',
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        details=exc.errors()
    )

async def unhandled_exception_handler(request: Request, exc: Exception):
    # 这里必须记录异常日志和堆栈
    # 这里统一返回结构,但不要把内部异常细节暴露给客户端
    return error_response(
        code='INTERNAL_SERVER_ERROR',
        message='Internal server error',
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR
    )

def register_exception_handlers(app: FastAPI) -> None:
    app.add_exception_handler(HTTPException, http_exception_handler)
    app.add_exception_handler(RequestValidationError, validation_exception_handler)
    app.add_exception_handler(Exception, unhandled_exception_handler)

几个处理器的定位:

  • HTTPException:HTTP 层异常,比如业务里主动抛出的 404,也包括框架产生的 404、405。
  • RequestValidationError:请求参数、Query、Body 校验失败。
  • Exception:最后兜底,防止未处理异常直接暴露堆栈信息。

@app.exception_handler(...) 和 app.add_exception_handler(...) 本质上都是注册异常处理器。写在 main.py 的小 demo 用装饰器很直观;抽到 core/exception_handlers.py 后,更推荐拆函数 + add_exception_handler(),因为注册关系集中在最后,handler 本身也更容易单测。

main.py 中注册

# app/main.py
app = FastAPI()
register_exception_handlers(app)

业务里需要主动中断请求时,继续抛 FastAPI 自带的 HTTPException 即可。

from fastapi import HTTPException, status

@router.get('/users/{user_id}')
def get_user(user_id: int):
    user = get_user_by_id(user_id)
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail='User not found'
        )
    return user

统一返回结构:

from app.schemas.common import ErrorResponse

@router.get(
    '/users/{user_id}',
    response_model=UserRead,
    responses={404: {'model': ErrorResponse}}
)
def get_user(user_id: int):
    ...

真正的错误响应仍然由全局异常处理器返回,responses={...} 只是补充 OpenAPI 文档,让调用方知道异常结构也是统一的。

Lifespan

lifespan 用来管理应用生命周期:服务启动时初始化资源,服务关闭时释放资源。它适合处理“整个应用共享”的对象,比如数据库连接池、HTTP client、缓存、模型加载、定时任务调度器等。

工作周期很简单:

应用启动
  -> 执行 yield 之前的代码
  -> 开始接收请求
  -> 应用关闭
  -> 执行 yield 之后的代码

使用 lifespan 后,就不要再混用旧的 @app.on_event('startup') / @app.on_event('shutdown'),否则生命周期入口会变得分散。

定义 lifespan

# app/core/lifespan.py
from contextlib import asynccontextmanager
from typing import Any

from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动阶段:初始化应用级共享资源
    app.state.cache: dict[str, Any] = {}
    app.state.config = {
        'appName': 'FastAPI Server Template'
    }

    yield
    # 关闭阶段:释放资源
    app.state.cache.clear()

app.state 是挂在 FastAPI app 上的状态容器,适合放应用级共享对象。它不是请求级状态;请求级数据仍然应该放在 request.state 或依赖函数的返回值里。

# main.py
app = FastAPI(lifespan=lifepsan)

lifespan 是创建 FastAPI 实例时传进去的;中间件、异常处理、路由仍然在 app 创建后注册。

在接口中读取共享状态

最直接的方式是通过 request.app.state 读取。

from fastapi import Request

@router.get('/config')
def get_config(request: Request):
    return request.app.state.config

如果多个地方都要用同一个资源,更推荐用依赖函数包一层,避免业务代码到处访问 request.app.state。

from typing import Any, Annotated
from fastapi import Depends, Request

def get_cache(request: Request) -> dict[str, Any]:
    return request.app.state.cache

@router.get('/cache/{key}')
def get_cache_value(
    key: str,
    cache: Annotated[dict[str, Any], Depends(get_cache)]
):
    return {'value': cache.get(key)}

这样路由函数只知道自己依赖了 cache,不关心 cache 存在 app.state 里还是其他地方。

管理需要关闭的资源

如果资源需要异步关闭,比如 HTTP client、消息队列连接、异步数据库连接池,就在 yield 之后释放。

from contextlib import asynccontextmanager
import httpx
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.http_client = httpx.AsyncClient(timeout=5)

    yield
    await app.state.http_client.aclose()

使用:

from typing import Annotated
from fastapi import Depends, Request
import httpx

def get_http_client(request: Request) -> httpx.AsyncClient:
    return request.app.state.http_client

@router.get('/remote-user/{user_id}')
async def get_remote_user(
    user_id: int,
    client: Annotated[httpx.AsyncClient, Depends(get_http_client)]
):
    response = await client.get(f'https://example.com/users/{user_id}')
    return response.json()

使用场景

场景是否适合 lifespan原因
初始化数据库连接池适合应用启动一次,关闭时释放
初始化 Redis / HTTP client适合连接对象可复用,避免每个请求重复创建
加载机器学习模型、词典、规则表适合加载成本高,全局只需要一份
每个请求的用户信息不适合这是请求级上下文,应该用依赖注入
每个请求的临时 trace id不适合应该放 request.state 或日志上下文

简单判断:生命周期和应用一致的资源,放 lifespan;生命周期和请求一致的数据,放依赖注入或 request.state。

中间件

中间件也是应用级横切能力,适合放在 core/middlewares.py。它和异常处理类似,不应该散落在业务 router 里。

常见用途:

  • CORS:处理浏览器跨域。
  • GZip:压缩响应体。
  • 自定义中间件:记录耗时、trace id、访问日志、统一 header。

多个中间件是嵌套执行的:请求进入时按注册链路一层层往里走,响应返回时再反向一层层往外走。

request
  -> middleware A before
    -> middleware B before
      -> router handler
    <- middleware B after
  <- middleware A after
response

所以中间件里 await call_next(request) 之前是“请求进入前”的逻辑,之后是“响应返回前”的逻辑。涉及日志、耗时、trace id 时要特别注意这个顺序。

CORS 和 GZip

# app/core/middlewares.py
import time
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

async def process_time_middleware(request: Request, call_next):
    start = time.perf_counter()
    # call_next 就是当前的请求
    response = await call_next(request)
    duration = time.perf_counter() - start
    response.headers['X-Process-Time'] = f'{duration:.4f}'
    return response

def register_middlewares(app: FastAPI) -> None:
    app.add_middleware(
        CORSMiddleware,
        allow_origins=[
            'http://localhost:3000',
            'http://localhost:5173'
        ],
        allow_credentials=True,
        allow_methods=['*'],
        allow_headers=['*'],
        expose_headers=['X-Process-Time']
    )

    app.add_middleware(
        GZipMiddleware,
        minimum_size=1000
    )

    app.middleware('http')(process_time_middleware)

CORSMiddleware 只解决浏览器跨域问题,服务端到服务端请求不受它影响。生产环境不要长期使用 allow_origins=['*'] 配合 allow_credentials=True,应该明确列出允许的前端域名。

GZipMiddleware 会在响应体超过 minimum_size 后压缩内容,适合 JSON 列表、大文本等响应;图片、压缩包这类已经压缩过的内容收益不大。

中间件的两种添加方式

FastAPI 有两种常见注册方式:

写法适合对象典型场景
app.add_middleware(SomeMiddleware, **options)ASGI 中间件类CORS、GZip、TrustedHost、HTTPSRedirect
@app.middleware('http') / app.middleware('http')(fn)普通函数记录耗时、trace id、访问日志、简单 header

add_middleware 注册的是中间件类。它更适合框架已经提供好的中间件,或者你自己实现的 ASGI middleware class。

app.add_middleware(
    GZipMiddleware,
    minimum_size=1000
)

app.middleware('http') 注册的是一个函数。函数接收 request 和 call_next,适合写轻量逻辑。

@app.middleware('http')
async def process_time_middleware(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    response.headers['X-Process-Time'] = f'{time.perf_counter() - start:.4f}'
    return response

如果像上面一样把函数放在 core/middlewares.py,为了统一注册,可以不用装饰器,改成:

app.middleware('http')(process_time_middleware)

简单判断:已有中间件类用 add_middleware;自己写请求前后的小逻辑,用 app.middleware('http')。

Uvicorn 启动

FastAPI 本身是 ASGI 框架,真正负责监听端口、接收 HTTP 请求、把请求交给应用处理的是 ASGI Server。最常用的 ASGI Server 是 uvicorn。

FastAPI CLI 的 fastapi dev、fastapi run 内部也是基于 Uvicorn 启动应用;所以实际项目里无论本地启动还是部署,都推荐直接写清楚 uvicorn 命令,参数更透明,也更容易被 Docker、systemd、Supervisor、Kubernetes 等运行环境接管。

安装: uv add uvicorn

本地开发:uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

部署时通常不加 --reload:uvicorn app.main:app --host 0.0.0.0 --port 8000

app.main:app 的含义:

  • app.main:Python 模块路径,对应 app/main.py。
  • app:模块里的 FastAPI 实例。

常用参数:

参数说明
--reload开发模式下监听文件变化并自动重启;生产环境不要开
--host监听地址,开发常用 127.0.0.1,容器或服务器里常用 0.0.0.0
--port监听端口,比如 8000
--log-config指定日志配置文件,适合接入统一日志格式

日志配置示例:

uvicorn app.main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --log-config logging.yaml

简单理解:fastapi dev/run 适合快速试跑;项目脚本、部署命令、容器启动命令里更推荐显式使用 uvicorn。

静态文件托管

FastAPI 可以通过 StaticFiles 托管静态资源,比如图片、导出的文件、临时公开下载文件。它适合小规模静态资源或开发环境使用;生产环境里更常见的是交给 Nginx、对象存储或 CDN。

# app/main.py
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()
app.mount(
    '/static',
    StaticFiles(directory='static'),
    name='static'
)

这样 static/images/logo.png 可以通过 /static/images/logo.png 访问。

如果项目启动时可能要写入上传目录,可以在 lifespan 里提前创建目录:

# app/core/lifespan.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from app.core.config import settings

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 确保静态资源目录存在;parents=True 会连同父目录一起创建,exist_ok=True 表示目录已存在时不报错。
    settings.static_dir_path.mkdir(parents=True, exist_ok=True)
    yield

settings.static_dir_path.mkdir(parents=True, exist_ok=True) 的作用就是保证 static/ 目录存在。比如配置的是 static/uploads,parents=True 会把中间不存在的 static 也一起创建;exist_ok=True 表示目录已经存在时直接跳过,不抛异常。

需要注意:

  • static/ 是对外公开目录,不要放配置文件、密钥、用户隐私数据。
  • 上传文件如果需要鉴权下载,不要直接放到公开的 static/,应该走业务接口校验权限后再返回文件。
  • logs/ 不应该被 StaticFiles 托管。

环境变量管理

配置不要写死在代码里,尤其是数据库地址、JWT 密钥、第三方服务 token。推荐用 pydantic-settings 统一读取环境变量,并在代码里通过 settings 使用。

安装:uv add pydantic-settings

# app/core/config.py
import os
from functools import lru_cache
from pathlib import Path
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_env: str = 'local'
    app_name: str = 'FastAPI Server Template'
    sqlalchemy_database_uri: str
    database_echo: bool = False
    create_db_tables: bool = False
    static_dir_path: Path = Path('static')
    secret_key: str
    lark_app_id: str | None = None
    lark_app_secret: str | None = None

    model_config = SettingsConfigDict(
        env_file_encoding='utf-8',
        extra='ignore'
    )

@lru_cache
def get_settings() -> Settings:
    env_file = os.getenv('ENV_FILE')
    if env_file:
        return Settings(_env_file=env_file)

    app_env = os.getenv('APP_ENV', 'local')
    env_map = {
        'local': '.env',
        'test': '.env.test',
        'production': '.env.prod'
    }
    return Settings(_env_file=env_map.get(app_env, '.env'))

settings = get_settings()

本地可以按环境组织三份文件:

.env        # 本地开发默认配置
.env.test   # 测试环境配置
.env.prod   # 生产环境配置模板或本地模拟生产配置
# .env 示例:
APP_ENV=local
APP_NAME=FastAPI Server Template
SQLALCHEMY_DATABASE_URI=postgresql+psycopg://user:password@localhost:5432/app
DATABASE_ECHO=false
CREATE_DB_TABLES=false
STATIC_DIR_PATH=static
SECRET_KEY=change-me
LARK_APP_ID=xxx
LARK_APP_SECRET=xxx

.env.test / .env.prod 保持同样的 key,只替换值。启动时可以通过 APP_ENV 选择环境,也可以用 ENV_FILE 直接指定配置文件:

APP_ENV=test uvicorn app.main:app --reload
APP_ENV=production uvicorn app.main:app --host 0.0.0.0 --port 8000
ENV_FILE=.env.prod uvicorn app.main:app --host 0.0.0.0 --port 8000

BaseSettings 会按字段名读取环境变量,大小写通常不敏感;app_name 会对应 APP_NAME。如果本地 GitLab、Docker 或部署机已经能挂载 .env.prod,CI/CD 不一定要注入所有变量,只注入 APP_ENV=production / ENV_FILE=.env.prod、密钥覆盖值或少量敏感配置即可。真正的线上密钥仍然建议由环境变量、Kubernetes Secret、Vault 或配置中心覆盖文件值。

SQLModel 迁移

SQLModel 负责定义表模型,但正式项目不要依赖 SQLModel.metadata.create_all() 管理表结构。create_all() 只会“没有表就创建”:通常不会主动删表或删除数据,但也不会可靠地把已有表同步成最新模型,比如加字段、改类型、删字段、建索引、回滚这些变更都不适合靠它处理。

实际项目里通常会先抽一个 core/database.py,集中创建 engine、session,并用环境变量控制本地是否允许自动建表:

# app/core/database.py
from typing import Generator
from sqlmodel import Session, SQLModel, create_engine
from app.core.config import Settings, settings

engine = create_engine(
    settings.sqlalchemy_database_uri,
    echo=settings.database_echo,
    pool_pre_ping=True
)

def import_model_modules() -> None:
    # 集中导入所有 SQLModel table,保证 metadata 和 Alembic 都能发现模型。
    import app.models.users  # noqa: F401

def get_session() -> Generator[Session, None, None]:
    with Session(engine, expire_on_commit=False) as db:
        yield db

def should_create_db_and_tables(app_settings: Settings = settings) -> bool:
    return app_settings.create_db_tables and app_settings.app_env != 'production'

def create_db_and_tables() -> None:
    import_model_modules()
    SQLModel.metadata.create_all(bind=engine)

create_engine() 是 SQLModel 对 SQLAlchemy create_engine() 的封装,常用参数主要是这些:

  • 连接地址:url,数据库连接地址,示例里是 settings.sqlalchemy_database_uri。
  • SQL 日志:echo,是否把 SQL 输出到控制台;本地排查 SQL 可以打开,线上通常关闭。
  • 连接可用性:pool_pre_ping,连接取出前先检查是否可用,适合避免数据库断开后的“坏连接”问题。
  • 连接池容量:pool_size 是常驻连接数,max_overflow 是连接池满了以后允许额外创建的连接数。
  • 连接池等待:pool_timeout,等待连接的最长时间,超过后直接报错。
  • 连接回收:pool_recycle,连接多久后回收,常用于规避数据库或代理主动断开长连接。
  • 事务隔离:isolation_level,需要明确控制隔离级别时使用,普通业务一般交给数据库默认值。
  • 驱动参数:connect_args,传给底层 DBAPI 的参数,比如 SQLite 的 {'check_same_thread': False}。
  • 连接池类型:poolclass,特殊场景才用,比如 Alembic 常见 NullPool,SQLite 测试可能用 StaticPool。

SQLModel.metadata.create_all() 是 SQLAlchemy MetaData.create_all(),常用参数很少:

  • bind:绑定的 engine 或 connection,通常就是 engine。
  • tables:只创建指定表;不传则创建 metadata 里所有表。
  • checkfirst:创建前是否先检查表是否存在,默认会检查。即使开启,它也只是避免重复建表,不负责同步已有表结构。

在 lifespan 启动阶段调用一次:

# app/core/lifespan.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from app.core.config import settings
from app.core.database import create_db_and_tables, should_create_db_and_tables

@asynccontextmanager
async def lifespan(app: FastAPI):
    if should_create_db_and_tables():
        create_db_and_tables()
    yield

.env 里可以这样控制:

DATABASE_ECHO=true
CREATE_DB_TABLES=true
  • DATABASE_ECHO=true:打开 SQLAlchemy 控制台 SQL 日志,本地排查 SQL 很有用。
  • CREATE_DB_TABLES=true:只建议本地空库首次初始化或 demo 使用;如果表已经存在,新增字段、改字段类型、建索引都不会靠它同步。
  • 开发、测试、生产环境应保持 CREATE_DB_TABLES=false,统一通过 Alembic 执行迁移。

如果想更明确地打开 SQLAlchemy 日志,也可以配合 Python logging:

import logging
logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)

也就是说,create_all() 只能解决“当前数据库还没有这些表”的问题,不能解决“模型变了,已有表也要跟着变”的问题。只要项目开始产生表结构变更,就应该生成 Alembic migration,并提交到 Git。

安装:uv add alembic

初始化:alembic init alembic 这会生成

.
├── alembic.ini
└── alembic
    ├── env.py
    ├── script.py.mako
    └── versions

alembic.ini 常用配置:

  • script_location:迁移脚本目录,通常是 alembic。
  • prepend_sys_path:把项目路径加入 Python import path,常见值是 .。
  • sqlalchemy.url:数据库连接地址;如果在 env.py 里用 settings 动态注入,这里可以留占位值。
  • file_template:生成 migration 文件名模板,团队想统一文件名时再改,比如带上年月日。
  • timezone:生成 migration 文件时使用的时区;团队有统一要求再配置。
  • version_locations:多目录管理 migration 时使用;普通项目不需要。
  • path_separator:多个路径配置的分隔符,保持默认即可。
  • output_encoding:生成 migration 文件的编码,通常是 utf-8。
  • [post_write_hooks]:生成 migration 后自动执行格式化工具,比如 ruff 或 black;不是必须。
  • [loggers] / [handlers] / [formatters]:Alembic 和 SQLAlchemy 执行迁移时的日志配置。

一个简化后的 alembic.ini 大概长这样:

[alembic]
script_location = alembic
prepend_sys_path = .
sqlalchemy.url = driver://user:pass@localhost/dbname
file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s_%%(slug)s
output_encoding = utf-8

[loggers]
keys = root,sqlalchemy,alembic

[handlers]
keys = console

[formatters]
keys = generic

如果项目已经用 pydantic-settings 管理环境变量,sqlalchemy.url 可以只是占位值,真实数据库地址由 alembic/env.py 里的 config.set_main_option('sqlalchemy.url', settings.sqlalchemy_database_uri) 注入。

在 alembic/env.py 里接入 SQLModel metadata 和数据库地址。Alembic 默认生成的文件会包含 run_migrations_offline() 和 run_migrations_online(),不要把它改成只有几行配置:

from logging.config import fileConfig

from alembic import context
from sqlalchemy import engine_from_config, pool
from sqlmodel import SQLModel

from app.core.config import settings
from app.core.database import import_model_modules

config = context.config
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

import_model_modules()
target_metadata = SQLModel.metadata
config.set_main_option('sqlalchemy.url', settings.sqlalchemy_database_uri)

def run_migrations_offline() -> None:
    context.configure(
        url=settings.sqlalchemy_database_uri,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={'paramstyle': 'named'}
    )

    with context.begin_transaction():
        context.run_migrations()

def run_migrations_online() -> None:
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix='sqlalchemy.',
        poolclass=pool.NullPool
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()

if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

生成迁移: alembic revision --autogenerate -m "create users table"

生成后的文件会放在 alembic/versions/ 里。这个目录存放每一次数据库结构变更的 migration 文件,文件里会记录:

  • revision:当前迁移版本号。
  • down_revision:上一个迁移版本号,用来串起迁移链路。
  • upgrade():升级逻辑,比如建表、加字段、建索引。
  • downgrade():回滚逻辑,比如删字段、删索引、删表。

执行迁移: alembic upgrade head

本地开发推荐同样执行迁移: APP_ENV=local alembic upgrade head

测试和生产同样执行迁移,只是读取的数据库地址不同:

APP_ENV=test alembic upgrade head
APP_ENV=production alembic upgrade head

如果生产环境由 GitLab CI/CD 发布,可以在发布流程里先执行 alembic upgrade head,再启动服务。这样本地、测试、生产使用同一批 migration 文件,数据库结构变化可追踪、可 review、可回滚。

简单规则:

  • create_all() 只用于空库首建或 demo,不用于同步已有表结构。
  • 本地开发也走 Alembic;否则新增字段后,本地已有表不会自动变化,环境会越来越不可信。
  • 每次改 models 后,生成 migration,并人工检查 upgrade() / downgrade()。
  • migration 文件要提交到 Git,生产环境只执行迁移,不现场生成迁移。

On this page