使用异步
（榨干 FastAPI 性能）
属于网络IO、数据库IO，天生异步、不写浪费性能：
- 异步 SQLAlchemy 数据库增删改查
- 异步 Redis（aioredis）
- 异步 HTTP 请求（httpx.AsyncClient）
- 异步 MQ、消息队列、异步三方接口调用
- FastAPI 内部依赖、异步生命周期事件
规则：接口用 async def，调用全加 await。
可以在 async 函数里随便写
（无坑、阻塞可忽略）
都是极快、毫秒级以内小操作：
- 控制台
print()普通打印 - 读取小文件（几KB～几MB 配置/文本/JSON/YAML）
- 简单字符串处理、字典列表遍历、逻辑判断
- Pydantic 模型解析、参数校验
- 简单时间运算、加密小算法
规则：直接写在 async def 里，不用顾虑，不会卡事件循环。
使用同步情况
同步阻塞耗时久、CPU重、文件重操作，放 async 会拖垮整个服务：
- 读写大文件、大文件上传下载、分片处理
- 生成/解析 Word、PPT、Excel、PDF（python-docx / python-pptx / openpyxl）
- Pandas、NumPy 复杂数据处理
- 图片处理：PIL、OpenCV、裁剪合成
- 串口/网口硬件打印、小票机、硬件交互
- 文件压缩、解压、批量遍历目录
- 复杂循环计算、耗时业务逻辑
- 调用老旧纯同步第三方库无异步版本
规则：这类接口一律用普通 def，不要加 async，FastAPI 自动丢线程池，互不影响。
从耗时的角度使用异步、同步
1. 耗时 ＜ 0.1s
小文件读取、简单参数处理、普通循环、简单校验
👉 可以写在 async 路由里，毫无感知，不影响事件循环。
2. 耗时 ≥ 0.1s ～ 10s
文件读写、生成Word/PPT/Excel、图片处理、小票打印、复杂业务计算、慢第三方接口
👉 一律用同步 def 接口
3. 耗时 ＞ 10s
批量任务、大数据导出、复杂报表、长时间运算
👉 不要用普通接口了，直接上任务队列 Celery/后台异步任务，前端轮询查进度。
为什么定 0.1 秒？
事件循环容忍的安全阻塞红线就是 100ms
超过这个时间：
- 并发一上来就开始卡顿
- 接口响应抖动
- 异步接口整体变慢
低于 0.1s，人感知不到、事件循环也感知不到。
实际开发怎么用？
不用精确计时，凭肉眼业务判断就行：
- 只是查个库、简单逻辑 → async 没问题
- 只要涉及 文件、Office、图片、打印、批量处理
直接默认 ≥0.1s，无脑写同步接口，永远不会踩坑。
最简一句口诀
网络数据库用异步，小文件打印随便混；
大文件Office重计算，全部老老实实写同步。
落地开发规范
- IO 密集业务 →
async def + await - 轻量小文件/打印 → 放 async 里无所谓
- 重文件/Office/图片/打印/计算 → 全部同步
def - 绝不：在 async 路由里跑耗时同步阻塞代码