KBEngine 内嵌 Python 3.7 的 http 包与 HTTPStatus 状态码完全指南
KBEngine 内嵌 Python 3.7 的 http 包与 HTTPStatus 状态码完全指南
导读
本文以 KBEngine 仓库内嵌 Python 3.7.3 标准库文档 http.rst 为核心,系统讲解 http 包的模块构成(http.client、http.server、http.cookies、http.cookiejar)以及 http.HTTPStatus 状态码枚举的设计与用法,并逐条列出全部受支持的状态码及其语义出处。读完本文,你将掌握在 KBEngine 服务器脚本与工具中如何用 HTTPStatus 精确表达 HTTP 响应语义、如何利用 http.client 做底层协议请求,并能结合仓库中的真实调用(如安装脚本、WebConsole)理解其落地方式。
http 包:一个聚合 HTTP 相关模块的标准包
在 Python 标准库中,http 是一个包(package),它把与超文本传输协议(HTTP)相关的多个模块聚合在一起。依据关联文档与仓库源码 Lib/http/ 目录,该包包含四个子模块:
| 子模块 | 职责定位 | 仓库实现 |
|---|---|---|
http.client |
底层 HTTP 协议客户端,适合直接操控连接、请求与响应;高层 URL 打开请用 urllib.request |
Lib/http/client.py |
http.server |
基于 socketserver 的基础 HTTP 服务器类 |
Lib/http/server.py |
http.cookies |
服务端与客户端 Cookie 状态管理的工具 | Lib/http/cookies.py |
http.cookiejar |
提供 Cookie 的持久化能力 | Lib/http/cookiejar.py |
其中 http.cookiejar 提供了 CookieJar、FileCookieJar、LWPCookieJar、MozillaCookieJar 等类(见 cookiejar.py 中 class CookieJar: 等定义),用于把 Cookie 持久化到磁盘文件,配合 urllib.request 可模拟浏览器式会话。
环境说明:本文所涉代码均来自 KBEngine 仓库内嵌的 CPython 3.7.3(见 Include/patchlevel.h 中
PY_VERSION "3.7.3")。http包及其全部子模块在服务器 Python 脚本中可直接import使用。
HTTPStatus:HTTP 状态码的枚举化表达
http 包本身还定义了一个非常重要的枚举类型:http.HTTPStatus。它是 enum.IntEnum 的子类(Python 3.5 起加入),定义了一整套 HTTP 状态码、对应的原因短语(reason phrase)与英文长描述(long description)。
源码实现剖析
在 Lib/http/init.py 中,HTTPStatus 通过自定义 __new__ 在构造枚举成员时同时挂载 phrase 与 description 两个属性:
class HTTPStatus(IntEnum):
def __new__(cls, value, phrase, description=''):
obj = int.__new__(cls, value)
obj._value_ = value
obj.phrase = phrase
obj.description = description
return obj
# informational
CONTINUE = 100, 'Continue', 'Request received, please continue'
SWITCHING_PROTOCOLS = (101, 'Switching Protocols',
'Switching to new protocol; obey Upgrade header')
PROCESSING = 102, 'Processing'
# success
OK = 200, 'OK', 'Request fulfilled, document follows'
...
由于继承自 IntEnum,每个枚举成员本质上就是 int,因此可以直接与整数比较;而 phrase(原因短语)和 description(长描述)则让状态码携带了可读语义。成员按语义划分为五组:
- informational(信息响应):100–102
- success(成功):200–226
- redirection(重定向):300–308
- client error(客户端错误):400–431
- server error(服务端错误):500–511
基本用法
关联文档给出的交互示例可直接在 KBEngine 服务器 Python 脚本中运行:
>>> from http import HTTPStatus
>>> HTTPStatus.OK
<HTTPStatus.OK: 200>
>>> HTTPStatus.OK == 200
True
>>> http.HTTPStatus.OK.value
200
>>> HTTPStatus.OK.phrase
'OK'
>>> HTTPStatus.OK.description
'Request fulfilled, document follows'
>>> list(HTTPStatus)
[<HTTPStatus.CONTINUE: 100>, <HTTPStatus.SWITCHING_PROTOCOLS: 101>, ...]
要点归纳:
HTTPStatus.OK既是枚举成员,又可以直接与整数200比较,便于与协议解析结果比对;.value取回纯整数值;.phrase返回标准原因短语(如'OK'、'Not Found');.description返回英文长描述;list(HTTPStatus)按定义顺序枚举全部成员,可用于生成映射表或文档。
与 http.client 的兼容常量
为了保持向后兼容,状态码枚举成员还以常量形式暴露在 http.client 模块中:枚举名与常量名一一对应,即 http.HTTPStatus.OK 与 http.client.OK 完全等价。这一机制在 Lib/http/client.py 中实现:
# hack to maintain backwards compatibility
globals().update(http.HTTPStatus.__members__)
# another hack to maintain backwards compatibility
# Mapping status codes to official W3C names
responses = {v: v.phrase for v in http.HTTPStatus.__members__.values()}
此外 client.py 还维护了一个 responses 字典,把每个状态码枚举映射到其标准原因短语,供代码按码取短语(如 responses[404] → 'Not Found')。同文件还定义了 HTTP_PORT = 80、HTTPS_PORT = 443 等常量。
HTTP 状态码全表(100–511)
下表完整列出 http.HTTPStatus 中受支持的全部状态码、枚举名与语义出处(依据关联文档及 Lib/http/init.py 实现)。其中 421 MISDIRECTED_REQUEST 是 Python 3.7 新增的成员(关联文档 versionchanged:: 3.7 亦有说明),KBEngine 内嵌的 3.7.3 已包含。
| Code | Enum Name | Details |
|---|---|---|
100 |
CONTINUE |
HTTP/1.1 RFC 7231, Section 6.2.1 |
101 |
SWITCHING_PROTOCOLS |
HTTP/1.1 RFC 7231, Section 6.2.2 |
102 |
PROCESSING |
WebDAV RFC 2518, Section 10.1 |
200 |
OK |
HTTP/1.1 RFC 7231, Section 6.3.1 |
201 |
CREATED |
HTTP/1.1 RFC 7231, Section 6.3.2 |
202 |
ACCEPTED |
HTTP/1.1 RFC 7231, Section 6.3.3 |
203 |
NON_AUTHORITATIVE_INFORMATION |
HTTP/1.1 RFC 7231, Section 6.3.4 |
204 |
NO_CONTENT |
HTTP/1.1 RFC 7231, Section 6.3.5 |
205 |
RESET_CONTENT |
HTTP/1.1 RFC 7231, Section 6.3.6 |
206 |
PARTIAL_CONTENT |
HTTP/1.1 RFC 7233, Section 4.1 |
207 |
MULTI_STATUS |
WebDAV RFC 4918, Section 11.1 |
208 |
ALREADY_REPORTED |
WebDAV Binding Extensions RFC 5842, Section 7.1 (Experimental) |
226 |
IM_USED |
Delta Encoding in HTTP RFC 3229, Section 10.4.1 |
300 |
MULTIPLE_CHOICES |
HTTP/1.1 RFC 7231, Section 6.4.1 |
301 |
MOVED_PERMANENTLY |
HTTP/1.1 RFC 7231, Section 6.4.2 |
302 |
FOUND |
HTTP/1.1 RFC 7231, Section 6.4.3 |
303 |
SEE_OTHER |
HTTP/1.1 RFC 7231, Section 6.4.4 |
304 |
NOT_MODIFIED |
HTTP/1.1 RFC 7232, Section 4.1 |
305 |
USE_PROXY |
HTTP/1.1 RFC 7231, Section 6.4.5 |
307 |
TEMPORARY_REDIRECT |
HTTP/1.1 RFC 7231, Section 6.4.7 |
308 |
PERMANENT_REDIRECT |
Permanent Redirect RFC 7238, Section 3 (Experimental) |
400 |
BAD_REQUEST |
HTTP/1.1 RFC 7231, Section 6.5.1 |
401 |
UNAUTHORIZED |
HTTP/1.1 Authentication RFC 7235, Section 3.1 |
402 |
PAYMENT_REQUIRED |
HTTP/1.1 RFC 7231, Section 6.5.2 |
403 |
FORBIDDEN |
HTTP/1.1 RFC 7231, Section 6.5.3 |
404 |
NOT_FOUND |
HTTP/1.1 RFC 7231, Section 6.5.4 |
405 |
METHOD_NOT_ALLOWED |
HTTP/1.1 RFC 7231, Section 6.5.5 |
406 |
NOT_ACCEPTABLE |
HTTP/1.1 RFC 7231, Section 6.5.6 |
407 |
PROXY_AUTHENTICATION_REQUIRED |
HTTP/1.1 Authentication RFC 7235, Section 3.2 |
408 |
REQUEST_TIMEOUT |
HTTP/1.1 RFC 7231, Section 6.5.7 |
409 |
CONFLICT |
HTTP/1.1 RFC 7231, Section 6.5.8 |
410 |
GONE |
HTTP/1.1 RFC 7231, Section 6.5.9 |
411 |
LENGTH_REQUIRED |
HTTP/1.1 RFC 7231, Section 6.5.10 |
412 |
PRECONDITION_FAILED |
HTTP/1.1 RFC 7232, Section 4.2 |
413 |
REQUEST_ENTITY_TOO_LARGE |
HTTP/1.1 RFC 7231, Section 6.5.11 |
414 |
REQUEST_URI_TOO_LONG |
HTTP/1.1 RFC 7231, Section 6.5.12 |
415 |
UNSUPPORTED_MEDIA_TYPE |
HTTP/1.1 RFC 7231, Section 6.5.13 |
416 |
REQUESTED_RANGE_NOT_SATISFIABLE |
HTTP/1.1 Range Requests RFC 7233, Section 4.4 |
417 |
EXPECTATION_FAILED |
HTTP/1.1 RFC 7231, Section 6.5.14 |
421 |
MISDIRECTED_REQUEST |
HTTP/2 RFC 7540, Section 9.1.2 |
422 |
UNPROCESSABLE_ENTITY |
WebDAV RFC 4918, Section 11.2 |
423 |
LOCKED |
WebDAV RFC 4918, Section 11.3 |
424 |
FAILED_DEPENDENCY |
WebDAV RFC 4918, Section 11.4 |
426 |
UPGRADE_REQUIRED |
HTTP/1.1 RFC 7231, Section 6.5.15 |
428 |
PRECONDITION_REQUIRED |
Additional HTTP Status Codes RFC 6585 |
429 |
TOO_MANY_REQUESTS |
Additional HTTP Status Codes RFC 6585 |
431 |
REQUEST_HEADER_FIELDS_TOO_LARGE |
Additional HTTP Status Codes RFC 6585 |
500 |
INTERNAL_SERVER_ERROR |
HTTP/1.1 RFC 7231, Section 6.6.1 |
501 |
NOT_IMPLEMENTED |
HTTP/1.1 RFC 7231, Section 6.6.2 |
502 |
BAD_GATEWAY |
HTTP/1.1 RFC 7231, Section 6.6.3 |
503 |
SERVICE_UNAVAILABLE |
HTTP/1.1 RFC 7231, Section 6.6.4 |
504 |
GATEWAY_TIMEOUT |
HTTP/1.1 RFC 7231, Section 6.6.5 |
505 |
HTTP_VERSION_NOT_SUPPORTED |
HTTP/1.1 RFC 7231, Section 6.6.6 |
506 |
VARIANT_ALSO_NEGOTIATES |
Transparent Content Negotiation in HTTP RFC 2295, Section 8.1 (Experimental) |
507 |
INSUFFICIENT_STORAGE |
WebDAV RFC 4918, Section 11.5 |
508 |
LOOP_DETECTED |
WebDAV Binding Extensions RFC 5842, Section 7.2 (Experimental) |
510 |
NOT_EXTENDED |
An HTTP Extension Framework RFC 2774, Section 7 (Experimental) |
511 |
NETWORK_AUTHENTICATION_REQUIRED |
Additional HTTP Status Codes RFC 6585, Section 6 |
这些码值覆盖了 IANA 注册的通用状态码,并额外纳入 WebDAV、HTTP/2、Delta Encoding、HTTP Extension Framework 等扩展规范中的码值,全部定义于 Lib/http/init.py。
状态码在 http.client 响应对象上的应用
http.client 的响应对象(HTTPResponse)持有 status 属性,可直接与 HTTPStatus 成员比较。例如判断成功响应可以写作:
from http import HTTPStatus
from http.client import HTTPConnection
conn = HTTPConnection('example.com')
conn.request('GET', '/path')
resp = conn.getresponse()
if resp.status == HTTPStatus.OK:
body = resp.read()
elif resp.status == HTTPStatus.NOT_FOUND:
print('resource missing')
conn.close()
KBEngine 仓库中的真实落地场景
场景一:安装脚本用 http.client 追踪重定向
KBEngine 的安装工具 kbe/tools/server/install/installer.py 是 http 包在仓库内的典型消费者:它在 Python 2/3 兼容层中 import http.client(见该文件第 19 行附近),并通过 getRealUrl 函数实现 URL 重定向解析:
def getRealUrl(url):
parsedurl = urlparse(url)
httpConn = http.client.HTTPConnection(parsedurl[1])
httpConn.request('GET', parsedurl[2])
response = httpConn.getresponse()
if response.status != 200:
return getRealUrl(response.getheader('Location'))
return url
其逻辑是:用 HTTPConnection 发起 GET 请求,若响应状态不是 200,则递归读取 Location 响应头继续追踪,直到拿到真实下载地址。这正是 http.client 作为底层客户端、手动控制连接与响应解析的典型用法;若换用高层接口,urllib.request.urlopen 会自动处理重定向,但此处选择手动控制以精确校验下载源。
同文件中下载逻辑还使用了 urllib.request.urlopen / urllib.request.urlretrieve(见 installer.py 附近),与文档中"高层 URL 打开使用 urllib.request"的分层定位完全吻合。
场景二:WebConsole 的 HTTP 响应与状态码语义
KBEngine 的 Web 控制台 kbe/tools/server/webconsole/ 基于 Django 构建,其视图(如 WebConsole/views.py、WebConsole/views_status.py)大量使用 django.http 的 HttpResponse、HttpResponseBadRequest、HttpResponseRedirect。Django 底层即依赖 Python 标准库的 http 包与状态码体系:
- 未登录访问受保护页面时,
login_check装饰器返回HttpResponseRedirect("/wc/login")(对应 3xx 重定向语义); - 参数错误时返回
HttpResponseBadRequest(对应 400 Bad Request); - 正常渲染使用
HttpResponse(对应 200 OK)。
这套语义与 HTTPStatus 枚举的分组一一对应,是理解 WebConsole 拦截逻辑(登录校验、权限校验)背后 HTTP 语义的钥匙。管理入口配置与说明可参考 WebConsole_Guide(cn).pdf.pdf)。
场景三:服务器脚本侧的 HTTP 能力(pyscript 扩展)
KBEngine 的 Python 脚本库 kbe/src/lib/pyscript/ 额外提供了 pyurl 模块(编译目标见 Makefile),向脚本层导出 KBEngine.urlopen,用于服务器发起 HTTP 请求(源码 pyurl.cpp 中注册 urlopen 方法)。它支持 GET/POST、自定义 headers、回调等参数形态,返回结果包含 httpcode、data、headers 等字段。这意味着游戏服务器逻辑可直接调用 http 家族的能力(或等价封装)与外部 HTTP 服务交互,例如对接运营后台、第三方支付回调等。
常见问题与使用要点
- 何时用
http.client,何时用urllib.request? 文档明确:http.client是底层协议客户端,需要精细控制(手动管理连接、解析每个响应头、处理重定向)时使用;普通 URL 打开、自动处理重定向与 Cookie 时用urllib.request更省事。 - 状态码比较建议用枚举而非裸整数:
HTTPStatus.OK == 200成立,但写成resp.status == HTTPStatus.OK可读性更高,且能利用.phrase、.description直接输出可读文案(如记日志时打印HTTPStatus(resp.status).phrase)。 - 兼容常量:
http.client.OK与http.HTTPStatus.OK等价,旧代码迁移到新代码时无需修改;http.client.responses字典可按键取标准原因短语。 - 版本注意:
421 MISDIRECTED_REQUEST在 Python 3.7 才加入;KBEngine 内嵌 3.7.3(patchlevel.h),因此全部上表成员均可用。若在更老的内嵌 Python 中运行,需自行判断该成员是否存在。
小结
http 包是 Python 标准库 HTTP 能力的基石:四个子模块分别覆盖客户端、服务端、Cookie 操作与 Cookie 持久化,HTTPStatus 枚举则把 100–511 的全部标准状态码、原因短语与长描述统一为可编程的 IntEnum。在 KBEngine 环境中,无论是安装脚本 installer.py 的底层连接控制,还是 WebConsole 的 Django 响应语义,抑或服务器脚本通过 KBEngine.urlopen 与外部服务通信,都建立在这套标准库能力之上。掌握 http 包与 HTTPStatus,是编写健壮的服务器 HTTP 集成代码的前提。