企业官网建设流程全解析

• 后端

gevent 自带一个纯 Python 实现、基于协程（greenlet）的高性能 WSGI 服务器gevent.pywsgi，它无需依赖任何 C 扩展即可与 gevent 的事件循环无缝协作。本文以仓库示例文档 docs/examples/wsgiserver.rst 及其引用的 examples/wsgiserver.py 为骨架，完整讲解示例代码的每一处细节、WSGIServer的构造参数与运行方式，并深入 src/gevent/pywsgi.py 源码，剖析一次 HTTP 请求从接入到响应背后的完整调用链。读完后，你将能独立编写、启动并扩展一个基于 gevent 的 WSGI 服务，也能读懂 pywsgi 内部的工作机制。

示例文档与示例代码概览

docs/examples/wsgiserver.rst是官方示例文档中专门讲解 WSGI 服务器的一页。它的主体内容并不冗长——通过 RST 的literalinclude指令，把 examples/wsgiserver.py 的完整源码直接嵌入文档正文：

Example wsgiserver.py ============================= .. literalinclude:: ../../examples/wsgiserver.py :language: python :linenos:

也就是说，这页文档的"灵魂"就是examples/wsgiserver.py这份可运行的示例程序。它是整个示例库（docs/examples/index.rst）中规模最小、最容易上手的入门样例：全文不到 20 行，却覆盖了 WSGI 应用的三个核心要素——WSGIServer的导入、application可调用对象的定义、以及serve_forever()的服务启动。与之配套的还有 TLS 版本 examples/wsgiserver_ssl.py，以及对应的自动化测试 src/gevent/tests/test__example_wsgiserver.py。

逐行解析 wsgiserver.py 示例

导入服务器类

from gevent.pywsgi import WSGIServer

示例从gevent.pywsgi模块导入WSGIServer。这个模块是整个 gevent 项目中"纯 Python WSGI 服务器"的实现，其 API 文档见 docs/api/gevent.pywsgi.rst。WSGIServer的核心特性包括：

• 继承自StreamServer（见 src/gevent/pywsgi.py 第 1526 行class WSGIServer(StreamServer)），因此天然支持 SSL/HTTPS；
• 每个连接由 gevent 的 greenlet 并发处理，不会像线程模型那样产生高额上下文切换开销；
• 纯 Python 实现，可被gevent.monkey补丁后的第三方库直接集成。

编写 WSGI 应用

def application(env, start_response): if env['PATH_INFO'] == '/': start_response('200 OK', [('Content-Type', 'text/html')]) return [b"<b>hello world</b>"] start_response('404 Not Found', [('Content-Type', 'text/html')]) return [b'<h1>Not Found</h1>']

这段代码定义了一个标准的 WSGI 应用可调用对象，遵循 PEP 3333 的约定：

关键点：

• 路径分发：PATH_INFO是 WSGI 环境字典中记录请求路径的标准键。本例仅做了最简单的二分支判断：根路径/返回200 OK，其余任何路径统一返回404 Not Found。
• 响应体是字节串的可迭代对象：return [b"<b>hello world</b>"]返回一个只含一个字节串元素的列表。这是 WSGI 规范要求的返回形式——应用必须返回一个可迭代对象，其中每个元素都是bytes（PEP 3333 下）或str（Python 2 下）。
• 响应头必须为二元组列表：[('Content-Type', 'text/html')]指定了响应内容的 MIME 类型，供浏览器正确渲染 HTML。

从源码层面看，服务器端调用应用的入口在 src/gevent/pywsgi.py 的WSGIHandler.run_application()方法（第 1054 行）：

self.result = self.application(self.environ, self.start_response) self.process_result()

application正是WSGIServer构造时传入的应用对象，self.environ是服务器组装好的 WSGI 环境字典，self.start_response则是WSGIHandler提供的回调。调用结束后，process_result()负责把应用返回的字节串可迭代对象真正写入 socket。

启动服务器

if __name__ == '__main__': print('Serving on 8088...') WSGIServer(('127.0.0.1', 8088), application).serve_forever()

这是示例的最后一段，也是最关键的启动逻辑：

• 监听地址：('127.0.0.1', 8088)是一个二元组，表示只在本机回环地址的 8088 端口上监听。如果想对外提供服务，可以改成('0.0.0.0', 8088)，或者直接传字符串':8088'（等价于监听所有网卡）。
• 应用注入：application作为第二个位置参数传入，服务器每次收到请求都会调用它。
• serve_forever()：进入阻塞式事件循环，持续接受并处理连接，直到进程被终止。它是 src/gevent/pywsgi.py 中WSGIServer从StreamServer继承的服务入口方法。

运行示例

在仓库根目录下直接执行即可启动服务：

python examples/wsgiserver.py

终端会输出Serving on 8088...，随后服务开始监听。用curl即可验证：

curl -i http://127.0.0.1:8088/ # HTTP/1.1 200 OK # Content-Type: text/html # <b>hello world</b> curl -i http://127.0.0.1:8088/anything # HTTP/1.1 404 Not Found # Content-Type: text/html # <h1>Not Found</h1>

仓库中对应的自动化测试 src/gevent/tests/test__example_wsgiserver.py 正是以这两个行为作为断言依据：_test_hello期望200 OK且响应体为b"<b>hello world</b>"，_test_not_found期望404 Not Found且响应体为b'<h1>Not Found</h1>'（测试第 22、44-52 行）。这个测试文件同时也验证了一个非常有价值的特性——test_a_blocking_client（第 54-91 行）：当某个客户端只发送了一半请求就挂起时，其他请求依然能被正常处理。这正是 gevent 协程模型相对传统线程模型处理大量慢连接时的核心优势。

深入 WSGIServer：构造参数与内部机制

WSGIServer的构造函数定义在 src/gevent/pywsgi.py 第 1609 行：

def __init__(self, listener, application=None, backlog=None, spawn='default', log='default', error_log='default', handler_class=None, environ=None, **ssl_args):

各参数的实战含义如下：

默认 WSGI 环境字典

在构造过程中，服务器会调用set_environ()（第 1649 行）基于base_env（第 1601 行）构建基础 WSGI 环境：

base_env = {'GATEWAY_INTERFACE': 'CGI/1.1', 'SERVER_SOFTWARE': 'gevent/%d.%d Python/%d.%d' % (...), 'SCRIPT_NAME': '', 'wsgi.version': (1, 0), 'wsgi.multithread': False, 'wsgi.multiprocess': False, 'wsgi.run_once': False}

• wsgi.version表明实现符合 WSGI 1.0 规范；
• wsgi.multithread与wsgi.multiprocess均为False，如实声明 gevent 服务器既不是线程模型也不是进程模型；
• 随后set_environ()会根据是否启用 SSL 设置wsgi.url_scheme为'https'或'http'，并把wsgi.errors指向error_log。

请求处理调用链

当客户端连接到达时，WSGIServer.handle(sock, address)（第 1696 行）会创建一个WSGIHandler实例并调用其handle()方法。WSGIHandler类定义在第 495 行，其handle()方法（第 564 行）是一个循环：

while self.socket is not None: result = self.handle_one_request() ...

这个循环实现了 HTTP keep-alive：同一个 TCP 连接上可以连续处理多个请求，直到客户端关闭连接或服务器决定断开。每次请求的处理流程大致是：

1. 从 socket 读取并解析请求行与请求头；
2. 组装该请求的 WSGI 环境字典self.environ；
3. 调用run_application()执行应用，得到响应体；
4. 通过process_result()写出状态行、响应头与响应体；
5. 记录访问日志（log_request()）。

此外，WSGIHandler还内置了针对慢客户端的保护：ignored_socket_errors = (errno.EPIPE, errno.ECONNRESET)（第 1086 行）——当客户端提前断开导致写失败时，这类EPIPE/ECONNRESET错误会被静默忽略，避免在正常运维场景下刷出大量无意义日志；在 Windows 上还会额外追加WSAECONNABORTED。

实战扩展一：启用 HTTPS（wsgiserver_ssl.py）

examples/wsgiserver_ssl.py 展示了同一服务器的 SSL 用法。与普通版相比，差异仅在两处：

from gevent import pywsgi server = pywsgi.WSGIServer(('127.0.0.1', 8443), hello_world, keyfile='server.key', certfile='server.crt') server.serve_forever()

• keyfile与certfile是透传给底层StreamServer的 SSL 参数，分别指向 PEM 格式的私钥与证书文件；
• 监听端口换成了 8443，访问协议变为https://127.0.0.1:8443/；
• 该文件头部注释提示：证书生成方法可参考 src/gevent/tests/test__ssl.py，而示例仓库根目录恰好自带开发用证书 examples/server.key 与 examples/server.crt，可以直接拿来跑通 HTTPS 示例。

由于 SSL 参数与监听地址被封装在同一个WSGIServer中，你可以在同一进程里创建多个实例（例如一个 HTTP 实例加一个 HTTPS 实例），各自独立serve_forever()。

实战扩展二：异步启动与命令行快速起服

异步启动

wsgiserver_ssl.py的注释里特意提到：

# to start the server asynchronously, call server.start()

serve_forever()会阻塞当前 greenlet 直到服务结束，适合作为进程的主任务；而start()则在一个后台 greenlet 中启动服务并立即返回，适合与主程序中的其他任务并发运行。两种方式都来自StreamServer的公共 API。

命令行快速起服

src/gevent/pywsgi.py 末尾（第 1706 行起）还提供了一个命令行入口_main()，可以直接从 shell 启动任意已安装的 WSGI 应用：

python -m gevent.pywsgi mypackage.mymodule:app -b :8080

• app位置参数为模块:可调用对象形式的点分路径，示例会用importlib动态导入并取出应用；
• -b/--bind指定监听地址，默认:8080；
• 启动前会自动调用gevent.monkey.patch_all()，把标准库的阻塞 IO 替换为 gevent 版本。

该入口的注释明确声明它"仅用于快速测试，不建议生产使用"（Provisional main handler, for quick tests, not production usage），生产环境推荐像示例那样显式构造WSGIServer并交给进程管理器（如 gunicorn 的geventworker）托管。

相关文档与进一步阅读

围绕本文主题，仓库中还有以下可直接查阅的资料：

• API 参考：docs/api/gevent.pywsgi.rst（自动生成的模块级文档，包含WSGIServer、WSGIHandler的完整成员列表）；
• 示例索引：docs/examples/index.rst（示例库总览，其中 docs/examples/wsgiserver_ssl.rst 讲解 HTTPS 版）；
• 更复杂的 WSGI 应用示例：examples/webpy.py（集成 WebPy 框架）、examples/psycopg2_pool.py（数据库连接池 + WSGI）、examples/wsgiserver_ssl.py；
• 服务器基类StreamServer的完整文档见 docs/api/gevent.server.rst；
• 测试用例 src/gevent/tests/test__example_wsgiserver.py 可作为验证示例行为正确性的参照。

总而言之，wsgiserver.py虽然只有 18 行，却是理解 gevent 网络编程模型的绝佳入口：一个标准 WSGI 应用、一行WSGIServer构造、一行serve_forever()，就构成了一个能并发处理海量慢连接的服务端。当示例无法满足需求时，WSGIServer的log/error_log/spawn/handler_class/environ等构造参数与WSGIHandler的扩展点，为定制访问日志、错误处理、环境变量注入与请求处理器提供了充分的空间。

• 后端