异步接口、后台任务与超时控制的组合方式
在 Python Web 项目里，“异步”这个词很容易被误用。真正需要关心的不是函数有没有写成 async，而是请求路径上哪些操作会阻塞，哪些工作应该在请求返回后继续执行。
一、先区分三类任务
- 短时间内必须返回结果的请求，如表单校验、用户认证。
- 可以接受稍后完成的任务，如文件转换、报告生成。
- 需要重试、容错和状态跟踪的任务，如通知下发、第三方同步。
只有第一类任务必须强依赖接口响应周期，后两类更适合进入后台任务系统。
二、异步并不自动提升吞吐
如果代码内部仍然调用阻塞式数据库驱动、同步 HTTP 请求或文件 I/O，接口即使写成异步风格，也不会自动变快。真正有效的优化通常来自以下几点：
- 减少请求链路上的串行外部调用。
- 把长耗时逻辑移出接口响应路径。
- 设置清晰的超时值和回退策略。
三、后台任务要有状态设计
class TaskStatus(str, Enum):
queued = "queued"
running = "running"
succeeded = "succeeded"
failed = "failed"只把任务丢给队列还不够。前端或调用方通常需要知道它现在排队、执行还是失败，所以任务状态至少要能查，也要能带上失败原因和重试次数。
四、超时设置应该和业务目标一致
接口超时不是越大越安全。超时过大只会让调用方更慢地失败。更好的方式是按业务容忍度设置：能快速失败的请求就尽快失败，能异步的任务就异步化。