WSGI是一个约定application(environ, start_response)函数签名的协议，要求响应体为bytes可迭代对象、响应头为二元组列表，且必须先调用start_response再返回响应体。
WSGI不是服务器，也不是框架，而是一个函数签名协议
WSGI 是 Python Web 生态里最常被误解的概念之一：它既不是 uWSGI 这类进程管理器，也不等同于 Flask 或 Django。它就是一个极简的、约定俗成的函数接口——所有符合 WSGI 的应用，都必须提供一个叫 application 的可调用对象，接收两个参数：environ（dict，含全部 HTTP 请求环境变量）和 start_response（回调函数，用于设置状态码与响应头）。
常见错误现象：TypeError: application() missing 2 required positional arguments: 'environ' and 'start_response'，说明你写的模块没暴露符合签名的 application 函数，或者名字写成了 app、run 等非标准名。
- 使用场景：你用
gunicorn --bind :8000 myapp:application启动时，myapp.py里必须有顶层的def application(environ, start_response): - 参数差异：
environ里字段如REQUEST_METHOD、PATH_INFO、QUERY_STRING都是字符串，但CONTENT_LENGTH是字符串形式的数字，需手动int() - 性能影响：这个函数本身不处理 I/O，也不做路由；它只是“接单+下单”——把请求转给真正干活的逻辑，所以 WSGI 层几乎零开销
为什么不能直接用 print() 或 return 发送响应？
WSGI 要求响应体必须是可迭代的字节序列（bytes 类型的 list、generator 或 bytes 本身），且必须在调用 start_response 之后才开始 yield/return 响应体。直接 print("HTTP/1.1 200 OK...") 或 return "hello" 不仅无效，还会让服务器卡死或返回空响应。
典型错误：ValueError: Response body must be bytes or iterable of bytes，往往是因为返回了 str（比如 "Hello"）而没编码为 b"Hello"。
立即学习“Python免费学习笔记（深入）”；
- 正确做法：先调用
start_response("200 OK", [("Content-Type", "text/plain")])，再return [b"Hello World"] - 容易踩的坑：返回
["Hello"]（str 列表）、[b"Hello".decode()]（又转回 str）、或漏掉b""前缀 - 兼容性注意：Python 3 中
str和bytes严格区分，任何混用都会在 WSGI 层报错，且错误堆栈往往不指向你的代码行
start_response 的第二个参数必须是二元组列表，不是字典
很多人误以为响应头可以传 {"Content-Type": "text/html"}，但 WSGI 明确要求它是 [("key", "value"), ("key2", "value2")] 形式的列表。传字典会立刻触发 TypeError，而且多数服务器（如 gunicorn）不会帮你转换。
错误示例：start_response("200 OK", {"Content-Type": "text/html"}) → 报错并中断请求。
- 必须写成：
start_response("200 OK", [("Content-Type", "text/html"), ("X-Frame-Options", "DENY")]) - 注意键名规范：HTTP 头字段名建议用首字母大写的驼峰格式（如
"Content-Length"），虽然小写也能工作，但某些中间件（如安全扫描器）可能校验格式 - 空格敏感：
("Set-Cookie", "sid=abc; Path=/; HttpOnly")中分号后若有空格，部分老浏览器可能解析失败，这不是 WSGI 问题，但会影响最终效果
本地开发用 python -m wsgiref.simple_server 就够了
不需要一上来就配 uWSGI 或 gunicorn。Python 标准库自带的 wsgiref 模块提供了轻量、无依赖的参考实现，适合验证 WSGI 接口是否写对，也足够跑通调试流程。
命令：python -m wsgiref.simple_server myapp:application，默认监听 http://localhost:8000。它不支持多进程、静态文件服务或 HTTPS，但恰好能帮你聚焦在「函数是否可调、响应是否合法」这个核心点上。
- 优势：启动快、无额外依赖、错误提示相对友好（比如会明确告诉你哪一行
environ缺少SERVER_NAME） - 局限：不处理并发连接，多个请求会阻塞；别拿它压测，也别部署到生产
- 真实陷阱：有些框架（如早期 Bottle）默认启用 auto-reload，但在
wsgiref下 reload 机制不可靠，改代码后得手动重启
真正复杂的地方从来不在协议定义本身，而在于你写的 application 函数里，怎么从 environ 安全提取参数、怎么避免响应体编码错乱、以及怎么让 start_response 调用时机刚好卡在 headers 定好、body 还没发之前——这三个点，漏一个，整个请求就静默失败。
