一个标准的 FastAPI 项目
项目结构、路由拆分、参数、依赖注入、鉴权与分层边界
信息
项目结构
.
├── 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:
passPath 接收常用参数如下,同样的规则也适应于后续的 Query
| 参数 | 说明 |
|---|---|
default | Path 不可用, 默认值 |
alias | 给对外的接口起个别名,内部正常使用该值 |
title | 不知道 |
description | swagger 字段的描述 |
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()]):
passData 参数
接收到非结构性的参数或者没有显示注入 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)]):
passForm 参数
表单以及文件需要
Header 和 Cookie 参数
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_userHeader 默认会把参数名中的 _ 转成 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_userAPIRouter(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 userHTTPBearer 会从请求头里读取 Bearer token:
Authorization: Bearer <access_token>它只负责“从请求里取 token”,真正的解析、过期校验、查用户仍然在 get_current_user() 里完成。
几个对象的作用:
| 对象 / 方法 | 作用 |
|---|---|
HTTPBearer() | FastAPI security 依赖,从 Authorization 请求头解析 Bearer token |
HTTPAuthorizationCredentials | HTTPBearer 的解析结果,包含 scheme 和 credentials |
credentials.scheme | 通常是 Bearer |
credentials.credentials | 真正的 token 字符串 |
jwt.encode(payload, secret, algorithm=...) | 签发 JWT |
jwt.decode(token, secret, algorithms=[...]) | 解析 JWT,并校验签名、算法、过期时间 |
ExpiredSignatureError | token 已过期 |
InvalidTokenError | token 格式错误、签名错误、算法不匹配等无效 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 token | 15-30 分钟 | 调业务接口 |
| refresh token | 7-30 天 | 换新的 access token |
本文示例只展示 access token。实际项目如果需要长期登录态,通常会再引入 refresh token、token 黑名单或服务端 session 版本号。
Models 和 Schemas
数据库对象、接口入参、接口返回值不能混成一个模型。SQLModel 官方也推荐按创建、表模型、响应模型拆成多个模型,本质上就是把“内部存储”和“外部契约”分开。
分层边界
| 类型 | 核心角色 | 是否映射数据库 | 常用位置 | 典型用途 |
|---|---|---|---|---|
SQLModel(table=True) | ORM 表模型 | 是 | models | 表结构、索引、外键、数据库字段 |
SQLModel 无 table=True | 可复用数据模型 | 否 | models 或 schemas | 抽公共字段,减少重复 |
BaseModel | API / 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 | 序列化时默认使用 alias | model_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': '...'}是传给底层 SQLAlchemyColumn的额外参数,适合只补充注释、nullable 这类简单配置。 - 自定义 Column:
sa_column=Column(..., comment='...')也是 SQLModelField()的参数,表示直接交给你自己定义完整的 SQLAlchemyColumn,控制力更强。
这里的 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)
yieldsettings.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 8000BaseSettings 会按字段名读取环境变量,大小写通常不敏感;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=trueDATABASE_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
└── versionsalembic.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,生产环境只执行迁移,不现场生成迁移。