KBEngine 内嵌 Python 3.7 的 http 包与 HTTPStatus 状态码完全指南

原创2026-10-16 20:17:481,753 阅读
文章标签:游戏开发后端

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 服务交互,例如对接运营后台、第三方支付回调等。

常见问题与使用要点

  1. 何时用 http.client,何时用 urllib.request? 文档明确:http.client 是底层协议客户端,需要精细控制(手动管理连接、解析每个响应头、处理重定向)时使用;普通 URL 打开、自动处理重定向与 Cookie 时用 urllib.request 更省事。
  2. 状态码比较建议用枚举而非裸整数:HTTPStatus.OK == 200 成立,但写成 resp.status == HTTPStatus.OK 可读性更高,且能利用 .phrase、.description 直接输出可读文案(如记日志时打印 HTTPStatus(resp.status).phrase)。
  3. 兼容常量:http.client.OK 与 http.HTTPStatus.OK 等价,旧代码迁移到新代码时无需修改;http.client.responses 字典可按键取标准原因短语。
  4. 版本注意: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 集成代码的前提。

登录后查看全文
kbengine