当前位置：首页 > news >正文

[Python3高阶编程] - 什么是 WSGI 标准

news 2026/6/9 6:17:02

什么是 WSGI 标准？

WSGI（Web Server Gateway Interface，发音为 “wiz-gee”）是 Python 社区制定的一个标准接口规范，用于统一Web 服务器（如 Gunicorn、uWSGI）和Python Web 应用/框架（如 Flask、Django、FastAPI）之间的通信方式。

它的官方定义在PEP 3333（Python Enhancement Proposal 3333）中，是现代 Python Web 开发的基石。

WSGI 的核心目标

解耦 Web 服务器与 Web 应用，让两者可以独立开发、自由组合。

你写的 Flask 应用，无需修改就能部署在 Gunicorn、uWSGI、Apache mod_wsgi 等任意 WSGI 服务器上。
服务器开发者只需实现 WSGI 接口，就能支持所有符合标准的 Python Web 框架。

WSGI 的基本结构

WSGI 定义了两个核心角色：

1.Application（应用端）

一个可调用对象（通常是函数或类），接收两个参数：

def application(environ, start_response): ...

参数说明：

参数	类型	作用
`environ`	`dict`	包含 HTTP 请求信息和运行环境的字典
`start_response`	`callable`	一个回调函数，用于设置响应状态码和头部

返回值：

一个可迭代对象（如列表、生成器），每个元素是字节串（bytes），代表响应体的一部分。

2.Server（服务器端）

负责：

接收原始 HTTP 请求
解析请求，构建environ字典
调用 Application
将 Application 返回的响应体发送回客户端

Gunicorn、uWSGI、Waitress 等都是 WSGI Server。

WSGI`environ`字典详解

environ是一个包含 CGI 风格变量和 WSGI 特有变量的字典。常见键包括：

必填的标准变量（来自 PEP 3333）：

{ 'REQUEST_METHOD': 'GET', # HTTP 方法 'PATH_INFO': '/hello', # 路径部分 'QUERY_STRING': 'name=alice', # 查询字符串（不含 ?） 'CONTENT_TYPE': 'text/plain', # 请求体类型 'CONTENT_LENGTH': '100', # 请求体长度 'SERVER_NAME': 'localhost', # 服务器主机名 'SERVER_PORT': '8000', # 服务器端口 'SERVER_PROTOCOL': 'HTTP/1.1', # HTTP 协议版本 # WSGI 特有 'wsgi.version': (1, 0), # WSGI 版本 'wsgi.url_scheme': 'http', # http 或 https 'wsgi.input': <file-like object>, # 用于读取请求体 'wsgi.errors': <file-like object>, # 错误输出流（通常是 sys.stderr） 'wsgi.multithread': False, # 是否多线程 'wsgi.multiprocess': True, # 是否多进程 'wsgi.run_once': False, # 是否只运行一次（CGI 模式） }

HTTP 头部转换规则：

所有 HTTP 头部会转换为大写、下划线、加HTTP_前缀：

User-Agent: curl→'HTTP_USER_AGENT': 'curl'
Content-Type: application/json→'CONTENT_TYPE': 'application/json'（注意：这是例外，不加HTTP_）

`start_response`回调函数

用于告诉服务器响应的状态码和头部：

def start_response(status, response_headers, exc_info=None): ...

status: 字符串，如'200 OK'
response_headers: 列表 of 元组，如[('Content-Type', 'text/plain')]
exc_info: 可选，用于错误处理（通常由中间件使用）

注意：start_response必须在返回响应体之前调用！

完整的 WSGI 应用示例

def simple_app(environ, start_response): # 1. 处理请求 path = environ['PATH_INFO'] method = environ['REQUEST_METHOD'] if method == 'GET' and path == '/hello': # 2. 设置响应状态和头部 status = '200 OK' headers = [('Content-Type', 'text/plain; charset=utf-8')] start_response(status, headers) # 3. 返回响应体（必须是 bytes） return [b"Hello, WSGI World!"] else: status = '404 Not Found' headers = [('Content-Type', 'text/plain')] start_response(status, headers) return [b"Not Found"]

这个应用可以直接被任何 WSGI 服务器运行！

WSGI 中间件（Middleware）

WSGI 的另一个强大特性是支持中间件——既是 Application，又是 Server。

class UpperCaseMiddleware: def __init__(self, app): self.app = app # 下游应用 def __call__(self, environ, start_response): # 调用下游应用 response = self.app(environ, start_response) # 修改响应（转大写） return [chunk.upper() for chunk in response] # 使用 app = UpperCaseMiddleware(simple_app)

中间件可以用于：

日志记录
身份验证
Gzip 压缩
CORS 处理
异常捕获

WSGI vs 其他协议

全屏复制

协议	语言	特点
WSGI	Python	同步、简单、广泛支持
ASGI	Python	异步（支持 WebSocket、HTTP/2），用于 FastAPI、Starlette
Rack	Ruby	Ruby 的 WSGI
PSR-7	PHP	PHP 的 HTTP 消息接口标准