ASGI是支持异步的服务器与应用通信协议，非Python语法或内置模块；其应用必须为async可调用对象，同步框架需桥接，启动时需注意--reload限制、uvicorn.run()多进程风险及HTTP/2的TLS依赖。
ASGI不是Python新语法，是服务器和应用之间的通信协议
ASGI（Asynchronous Server Gateway Interface）不是Python内置模块，也不是某个框架的私有机制，它是一套约定——类似WSGI但支持异步。你写async def app(scope, receive, send)，Uvicorn或Hypercorn才能正确调用它；如果用Flask这种纯同步框架直接扔给Uvicorn跑，会报TypeError: 'function' object is not async。
常见错误现象：启动Uvicorn后请求卡住、返回空响应、日志里反复出现RuntimeWarning: coroutine 'xxx' was never awaited。根本原因往往是把同步函数当ASGI应用传了。
- ASGI应用必须是可调用对象，且其
__call__方法是async的，或本身就是async def - FastAPI、Starlette原生符合ASGI；Django 3.1+需开启
ASGI_APPLICATION配置；Flask、Bottle默认不支持，得靠asgiref.WsgiToAsgi桥接（但会丢掉异步优势） - 协议版本影响行为：
scope["asgi"]["version"]为"3.0"时，receive可能返回{"type": "http.disconnect"}，不处理会导致长连接泄漏
Uvicorn启动时加--reload只监听.py文件，不监控模板或静态资源
开发时习惯加--reload，但默认它只检查Python源码改动。改了templates/index.html或static/css/app.css不会触发重启，容易误以为代码没生效。
使用场景：本地快速迭代带Jinja2模板的Starlette项目，或者前后端分离但后端要同步提供HTML页面。
立即学习“Python免费学习笔记（深入）”；
- 显式指定监控路径：
uvicorn main:app --reload --reload-dir templates --reload-dir static -
--reload依赖watchfiles库，Windows上偶尔因杀毒软件导致失效，可换用--reload-engine stat（轮询替代inotify） - 生产环境严禁用
--reload：它会启动多个进程监听同一端口，引发Address already in use或请求随机丢失
uvicorn.run()在脚本里直接调用，别和if __name__ == "__main__"混用
很多教程写if __name__ == "__main__": uvicorn.run("main:app")，看似合理，实则在Windows或某些IDE里会触发多进程重复加载——因为uvicorn.run()内部默认启用workers=1，但父进程和worker都会执行该脚本，导致数据库连接初始化两次、定时任务跑两遍。
正确做法是把启动逻辑隔离到单独入口，或强制单进程模式。
- 推荐方式：命令行启动
uvicorn main:app --host 0.0.0.0:8000，而非Python脚本里调用uvicorn.run() - 非要用
uvicorn.run()？加上loop="asyncio"和workers=1，并确保不在if __name__ == "__main__"外执行其他副作用代码 - 调试时发现日志重复打印、Redis连接数翻倍、SQLAlchemy报
QueuePool limit of size 5 overflow 10 reached，大概率是这个原因
HTTP/2支持需要额外配置TLS，Uvicorn本身不自动降级
Uvicorn宣称支持HTTP/2，但实际启动时不加--http http2参数，默认走HTTP/1.1；即使加了，若没配--ssl-keyfile和--ssl-certfile，会直接启动失败，报错hypercore.http2.H2Configuration requires ssl_context。
性能影响明显：HTTP/2的多路复用对API网关类服务有价值，但对简单CRUD接口收益极小，还增加证书维护成本。
- 本地测试可用
mkcert生成自签名证书：mkcert -install && mkcert localhost - 生产环境务必用Let’s Encrypt等可信CA，且Nginx前置时，Uvicorn只需处理HTTP/1.1，HTTP/2由Nginx终结
- Chrome对非HTTPS的HTTP/2完全拒绝，连
localhost都不行，别浪费时间试http://localhost:8000是否走HTTP/2
ASGI的坑不在语法，而在边界——协议层、服务器层、框架层、网络层，任何一层异步/同步混用都会让问题藏得深。最常被忽略的是scope里"type"字段的取值：可能是"http"、"websocket"甚至"lifespan"，但没人告诉你lifespan消息必须响应，否则Uvicorn永远等不到应用就绪。
