一、问题背景
去年年底接手了一个内部商品服务,技术栈是 FastAPI + SQLAlchemy + PostgreSQL,接口不多,但有一个 /api/v1/products/search 被前端和另外两个服务频繁调用。上线初期量小,没人管它;等到日调用量涨到百万级,监控上这个接口的 P99 一直在 1.2s 上下浮动,Locust 压到 150 并发就开始出现 504。
运维那边先甩锅给"Python 太慢",我是不信的。FastAPI 再怎么说也是 Starlette + uvicorn 的异步栈,一个查询接口跑出 1.2s,八成是 IO 或者查询写法的问题。于是花了一个下午做 profiling,本文就是把整个过程和优化落地记录下来。
二、环境与版本
先把环境交代清楚,不同版本行为差异挺大的:
- Python 3.11.6
- FastAPI 0.109.2
- Starlette 0.36.3
- uvicorn 0.27.1(生产用
--workers 4,gunicorn + UvicornWorker) - SQLAlchemy 2.0.25(注意是 2.0,
select()风格) - asyncpg 0.29.0
- PostgreSQL 15.4
- Redis 7.2.4,客户端 redis-py 5.0.1
- 压测工具 Locust 2.20.1
服务器配置:4C8G 容器,数据库单独一台 8C16G。
三、定位瓶颈:py-spy + cProfile
第一步先确认瓶颈在哪一层。线上进程不方便直接挂 cProfile,我用 py-spy 做采样:
py-spy record -o profile.svg --pid --duration 60 --rate 100
同时用 Locust 打 100 并发,跑 60 秒。生成的火焰图很说明问题:大约 70% 的采样落在 asyncpg 的 fetch 等待上,剩下的大部分在 SQLAlchemy 的 ORM 对象构造(_instance 相关调用)。框架本身(路由匹配、Pydantic 序列化)占比不到 5%。
结论很清楚:时间花在数据库上,而且是"很多次小查询"。
为了拿到更精确的调用次数,我又在测试环境用 cProfile 跑单请求:
import cProfile, pstats, io
from app.main import app
from fastapi.testclient import TestClient
client = TestClient(app)
pr = cProfile.Profile()
pr.enable()
for _ in range(20):
client.get("/api/v1/products/search", params={"keyword": "手机", "page": 1})
pr.disable()
s = io.StringIO()
ps = pstats.Stats(pr, stream=s).sort_stats("cumulative")
ps.print_stats(30)
print(s.getvalue())
输出里 cursor.execute 被调用了 20 次请求 × 平均 47 次 = 940 次。一个搜索接口,一次请求打了 47 条 SQL,这就是典型的 N+1。
回头看代码,问题一目了然:
# 优化前:典型的 N+1
@router.get("/search")
async def search_products(keyword: str, page: int = 1, size: int = 20, db: AsyncSession = Depends(get_db)):
stmt = select(Product).where(Product.name.ilike(f"%{keyword}%")).offset((page-1)*size).limit(size)
result = await db.execute(stmt)
products = result.scalars().all()
items = []
for p in products: # 每个商品触发 2 次懒加载查询
category = await db.get(Category, p.category_id)
tags = await db.execute(select(Tag).join(ProductTag).where(ProductTag.product_id == p.id))
items.append({
"id": p.id, "name": p.name,
"category": category.name if category else None,
"tags": [t.name for t in tags.scalars().all()],
})
return {"items": items, "total": len(items)}
20 条商品,每条 2 次额外查询,加上主查询和 count,一次请求 40+ 条 SQL。而且 ilike '%keyword%' 这种前置模糊匹配在 PostgreSQL 上根本走不了普通 B-tree 索引。
四、方案设计与核心实现
优化分三步走,按收益排序:
4.1 消除 N+1:selectinload 预加载
SQLAlchemy 2.0 的 async 模式下,selectinload 是最稳的预加载方式(joinedload 在多对多场景下会产生笛卡尔积,subqueryload 在 async 里兼容性有坑)。
# 优化后:预加载 + 显式 join
from sqlalchemy.orm import selectinload
@router.get("/search")
async def search_products(
keyword: str,
page: int = 1,
size: int = 20,
db: AsyncSession = Depends(get_db),
):
base = select(Product).where(Product.name.ilike(f"%{keyword}%"))
# count 单独走,避免带 join 的 count 变慢
total = await db.scalar(select(func.count()).select_from(base.subquery()))
stmt = (
base.options(
selectinload(Product.category),
selectinload(Product.tags),
)
.order_by(Product.created_at.desc())
.offset((page - 1) * size)
.limit(size)
)
products = (await db.execute(stmt)).scalars().all()
return {
"items": [
{
"id": p.id,
"name": p.name,
"category": p.category.name if p.category else None,
"tags": [t.name for t in p.tags],
}
for p in products
],
"total": total,
}
一次请求的 SQL 从 47 条降到 3 条(count、主查询、tags 的 selectin 查询;category 走 selectin 又是一条,实际是 4 条,但都是批量查询)。
4.2 索引:pg_trgm 解决前置模糊
ilike '%手机%' 走不了 B-tree,PostgreSQL 的原生方案是 pg_trgm + GIN 索引:
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX idx_products_name_trgm ON products USING gin (name gin_trgm_ops);
CREATE INDEX idx_products_created_at ON products (created_at DESC);
pg_trgm 对中文的支持取决于分词粒度,实测三字以上关键词效果不错,单字查询仍然会退化成全表扫描——所以接口层加了个约束:关键词长度 str:
raw = f"{keyword}|{page}|{size}"
return "prod:search:" + hashlib.md5(raw.encode()).hexdigest()
@router.get("/search")
async def search_products(...):
key = _cache_key(keyword, page, size)
if cached := await redis.get(key):
return json.loads(cached)
# ... 数据库查询逻辑 ...
payload = {"items": items, "total": total}
await redis.setex(key, CACHE_TTL, json.dumps(payload, ensure_ascii=False))
return payload
注意 `json.dumps` 用了 `ensure_ascii=False`,否则中文会被转义成 `\uXXXX`,序列化体积大 3 倍左右。
## 五、踩坑与优化细节
**坑 1:selectinload 与 limit 的顺序**。一开始我把 `selectinload` 加在了带 `limit` 的查询上,结果 SQLAlchemy 生成的是先 join 再 limit,实际返回条数不对。正确做法是主查询只查 Product,预加载由 selectin 单独发 `WHERE id IN (...)`,也就是上面代码的写法——`selectinload` 本身就是这个机制,但前提是不要在同一个 select 里再手动 join 关联表。
**坑 2:连接池配置**。压测到 300 并发时出现 `TimeoutError: connection pool exhausted`。默认 `pool_size=5, max_overflow=10` 完全不够。改成:
```python
engine = create_async_engine(
DATABASE_URL,
pool_size=20,
max_overflow=10,
pool_timeout=5,
pool_recycle=1800,
pool_pre_ping=True,
)
4 个 worker × 30 = 120 个潜在连接,PostgreSQL 那边 max_connections=200,刚好留余量。pool_pre_ping 是为了应对数据库侧的 idle 连接被防火墙掐断。
坑 3:缓存击穿。热点关键词过期瞬间,几十个请求同时打到数据库。加了个简单的互斥:用 SET key value NX EX 5 抢锁,抢不到就短暂 sleep 后重试读缓存。没有上完整的 singleflight,因为量级不大,这个够用。
坑 4:count 查询。SELECT count(*) 在百万级表上即使有索引也要几百毫秒。业务上其实不需要精确总数,前端只展示"约 N 条"。改成 EXPLAIN 估算或者直接封顶(超过 10000 就返回 10000),count 耗时从 300ms 降到 20ms 以内。最后我用的是 count(*) 加 WHERE 条件命中索引的方案,配合缓存,实际影响不大——但如果你的表更大,建议直接砍掉精确 count。
六、效果数据
压测条件统一:Locust,200 并发用户,持续 5 分钟,关键词从 Top 100 里随机取(模拟真实分布,缓存命中率约 58%)。
| 指标 | 优化前 | 优化后 |
|---|---|---|
| P50 | 680 ms | 21 ms |
| P95 | 1100 ms | 62 ms |
| P99 | 1240 ms | 78 ms |
| QPS | 148 | 1430 |
| 单请求 SQL 数 | 47 | 4(缓存未命中)/ 0(命中) |
| DB CPU | 78% | 27% |
| 错误率 | 3.1%(超时) | 0% |
缓存命中时的 P99 是 12ms,未命中时约 95ms。数据库侧最明显的变化是 pg_stat_statements 里那条主查询的 mean_time 从 41ms 降到 6ms。
七、总结
这次优化没有用什么高深的东西,核心就三件事:用 py-spy 确认瓶颈不在框架、用 selectinload 干掉 N+1、用 pg_trgm 让模糊查询能走索引。缓存是锦上添花,真正把 1.2s 打到 100ms 以内的是前两步。
几点经验:
- 先 profiling 再动手。我见过太多人一上来就加缓存,结果缓存没命中时照样慢,问题被掩盖了而已。
- FastAPI 本身很少是瓶颈,火焰图里框架占比超过 20% 才需要怀疑它。
- SQLAlchemy 2.0 的 async 模式下,懒加载是隐形的性能杀手,建议全局配置
lazy="raise",强制显式预加载,早暴露早修。 - 缓存 TTL 和一致性要做业务上的取舍,60 秒对我们够用,对你不一定。
如果这个接口后面 QPS 再涨一个量级,下一步会上 ES 做搜索,PostgreSQL 的 ilike 终究不是长久之计。但那是另一个故事了。