Litestar 状态码参考litestar.status_codes模块全量解析与实战用法【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本文是 Litestar 框架内置状态码模块litestar.status_codes的完整技术参考。该模块集中定义了 63 个 HTTP 状态码常量与 16 个 WebSocket 关闭码常量是框架响应构建、异常体系、缓存判定与测试断言的公共事实来源。读完本文你将掌握每个常量的准确数值与语义、框架内部如何使用这些常量生成默认响应状态码以及如何在业务代码、异常处理和测试中正确引用它们。模块概览litestar/status_codes.py的设计docs/reference/status_codes.rst通过automodule:: litestar.status_codes指令将 litestar/status_codes.py 的全部公开成员自动渲染为参考文档因此该文件的真实内容即模块的完整定义。从源码看该模块的设计有以下几个特点全部使用Final类型标注每个常量都声明为from typing import Final的类型级常量例如HTTP_200_OK: Final 200。这向静态类型检查器mypy、pyright声明这些值不可被重新赋值避免业务代码中意外覆盖框架级常量。命名约定统一HTTP 状态码统一使用HTTP_前缀WebSocket 关闭码统一使用WS_前缀均以十进制数值作为常量值一眼即可识别类别。显式__all__导出模块末尾显式定义了__all__元组完整列出全部 79 个公开名称。这意味着from litestar.status_codes import *只会导入这些受控的常量文档生成与 IDE 补全也会以__all__为准。常量的 docstring 即标准语义短语每个常量都配有与 RFC 语义一致的短语说明例如HTTP_404_NOT_FOUND的 docstring 为 HTTP status code Not Found这些短语会在异常处理时被用作默认的错误详情。HTTP 状态码常量全量参考1xx 信息类4 个常量数值标准语义HTTP_100_CONTINUE100ContinueHTTP_101_SWITCHING_PROTOCOLS101Switching ProtocolsHTTP_102_PROCESSING102ProcessingHTTP_103_EARLY_HINTS103Early Hints2xx 成功类10 个常量数值标准语义HTTP_200_OK200OKHTTP_201_CREATED201CreatedHTTP_202_ACCEPTED202AcceptedHTTP_203_NON_AUTHORITATIVE_INFORMATION203Non Authoritative InformationHTTP_204_NO_CONTENT204No ContentHTTP_205_RESET_CONTENT205Reset ContentHTTP_206_PARTIAL_CONTENT206Partial ContentHTTP_207_MULTI_STATUS207Multi StatusHTTP_208_ALREADY_REPORTED208Already ReportedHTTP_226_IM_USED226Im Used3xx 重定向类8 个常量数值标准语义HTTP_300_MULTIPLE_CHOICES300Multiple ChoicesHTTP_301_MOVED_PERMANENTLY301Moved PermanentlyHTTP_302_FOUND302FoundHTTP_303_SEE_OTHER303See OtherHTTP_304_NOT_MODIFIED304Not ModifiedHTTP_305_USE_PROXY305Use ProxyHTTP_306_RESERVED306ReservedHTTP_307_TEMPORARY_REDIRECT307Temporary RedirectHTTP_308_PERMANENT_REDIRECT308Permanent Redirect4xx 客户端错误类29 个常量数值标准语义HTTP_400_BAD_REQUEST400Bad RequestHTTP_401_UNAUTHORIZED401UnauthorizedHTTP_402_PAYMENT_REQUIRED402Payment RequiredHTTP_403_FORBIDDEN403ForbiddenHTTP_404_NOT_FOUND404Not FoundHTTP_405_METHOD_NOT_ALLOWED405Method Not AllowedHTTP_406_NOT_ACCEPTABLE406Not AcceptableHTTP_407_PROXY_AUTHENTICATION_REQUIRED407Proxy Authentication RequiredHTTP_408_REQUEST_TIMEOUT408Request TimeoutHTTP_409_CONFLICT409ConflictHTTP_410_GONE410GoneHTTP_411_LENGTH_REQUIRED411Length RequiredHTTP_412_PRECONDITION_FAILED412Precondition FailedHTTP_413_REQUEST_ENTITY_TOO_LARGE413Request Entity Too LargeHTTP_414_REQUEST_URI_TOO_LONG414Request URI Too LongHTTP_415_UNSUPPORTED_MEDIA_TYPE415Unsupported Media TypeHTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE416Requested Range Not SatisfiableHTTP_417_EXPECTATION_FAILED417Expectation FailedHTTP_418_IM_A_TEAPOT418Im A TeapotHTTP_421_MISDIRECTED_REQUEST421Misdirected RequestHTTP_422_UNPROCESSABLE_ENTITY422Unprocessable EntityHTTP_423_LOCKED423LockedHTTP_424_FAILED_DEPENDENCY424Failed DependencyHTTP_425_TOO_EARLY425Too EarlyHTTP_426_UPGRADE_REQUIRED426Upgrade RequiredHTTP_428_PRECONDITION_REQUIRED428Precondition RequiredHTTP_429_TOO_MANY_REQUESTS429Too Many RequestsHTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE431Request Header Fields Too LargeHTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS451Unavailable For Legal Reasons5xx 服务端错误类11 个常量数值标准语义HTTP_500_INTERNAL_SERVER_ERROR500Internal Server ErrorHTTP_501_NOT_IMPLEMENTED501Not ImplementedHTTP_502_BAD_GATEWAY502Bad GatewayHTTP_503_SERVICE_UNAVAILABLE503Service UnavailableHTTP_504_GATEWAY_TIMEOUT504Gateway TimeoutHTTP_505_HTTP_VERSION_NOT_SUPPORTED505Http Version Not SupportedHTTP_506_VARIANT_ALSO_NEGOTIATES506Variant Also NegotiatesHTTP_507_INSUFFICIENT_STORAGE507Insufficient StorageHTTP_508_LOOP_DETECTED508Loop DetectedHTTP_510_NOT_EXTENDED510Not ExtendedHTTP_511_NETWORK_AUTHENTICATION_REQUIRED511Network Authentication Required注意4xx 类别中刻意跳过了419、420等未在 RFC 标准化的编号也未见HTTP_444等非标准码说明该模块严格对齐标准语义不含供应商扩展。WebSocket 关闭码常量全量参考16 个WebSocket 协议使用独立的 16 位关闭码1000–4999与 HTTP 状态码语义不同。模块中所有WS_前缀常量定义于 litestar/status_codes.py常量数值标准语义WS_1000_NORMAL_CLOSURE1000Normal ClosureWS_1001_GOING_AWAY1001Going AwayWS_1002_PROTOCOL_ERROR1002Protocol ErrorWS_1003_UNSUPPORTED_DATA1003Unsupported DataWS_1005_NO_STATUS_RECEIVED1005No Status ReceivedWS_1006_ABNORMAL_CLOSURE1006Abnormal ClosureWS_1007_INVALID_FRAME_PAYLOAD_DATA1007Invalid Frame Payload DataWS_1008_POLICY_VIOLATION1008Policy ViolationWS_1009_MESSAGE_TOO_BIG1009Message Too BigWS_1010_MANDATORY_EXT1010Mandatory Ext.WS_1011_INTERNAL_ERROR1011Internal ErrorWS_1012_SERVICE_RESTART1012Service RestartWS_1013_TRY_AGAIN_LATER1013Try Again LaterWS_1014_BAD_GATEWAY1014Bad GatewayWS_1015_TLS_HANDSHAKE1015TLS Handshake注意1004与1005/1006属于协议保留值其中1005未收到状态码与1006异常关闭仅用于描述对端状态不可由本端主动发送模块仍将其导出以便在逻辑判断中引用。响应构建默认状态码与无响应体规则Litestar 在未显式指定status_code时会根据 HTTP 方法自动推导默认值。该逻辑位于 litestar/handlers/http_handlers/_utils.py 的get_default_status_codedef get_default_status_code(http_methods: set[HttpMethodName]) - int: if HttpMethod.POST in http_methods: return HTTP_201_CREATED if HttpMethod.DELETE in http_methods: return HTTP_204_NO_CONTENT return HTTP_200_OK即框架的默认规则是HTTP 方法默认状态码POST201CreatedDELETE204No ContentGET/PATCH/PUT200OK使用route装饰器声明多个方法时200OK其中DELETE默认为204是因为框架假设删除操作默认不返回数据如果你的实现需要返回响应体应在装饰器中显式覆盖参见 docs/usage/responses.rst 的说明。业务代码中显式指定状态码的推荐写法来自 docs/usage/responses.rstfrom pydantic import BaseModel from litestar import get from litestar.status_codes import HTTP_202_ACCEPTED class Resource(BaseModel): id: int name: str get(/resources, status_codeHTTP_202_ACCEPTED) def retrieve_resource() - Resource: return Resource(id1, namemy resource)无响应体限制当状态码为204 No Content、304 Not Modified或小于100时HTTP 响应不允许携带响应体。这一约束在 litestar/response/base.py 中有硬性校验——若返回注解不是None而状态码不允许 body会抛出ImproperlyConfiguredException提示 response content is not supported for HEAD responses and responses with a status code that does not allow content。同时 litestar/response/base.py 中ASGIResponse的默认状态码即为HTTP_200_OK。异常体系中的状态码绑定Litestar 的 HTTP 异常体系以HTTPException为基类通过类属性status_code与状态码常量直接绑定见 litestar/exceptions/http_exceptions.py异常类绑定的状态码常量HTTPException基类HTTP_500_INTERNAL_SERVER_ERRORClientExceptionHTTP_400_BAD_REQUESTValidationException继承ClientException即 400NotAuthorizedExceptionHTTP_401_UNAUTHORIZEDPermissionDeniedExceptionHTTP_403_FORBIDDENNotFoundExceptionHTTP_404_NOT_FOUNDMethodNotAllowedExceptionHTTP_405_METHOD_NOT_ALLOWEDRequestEntityTooLargeHTTP_413_REQUEST_ENTITY_TOO_LARGETooManyRequestsExceptionHTTP_429_TOO_MANY_REQUESTSInternalServerExceptionHTTP_500_INTERNAL_SERVER_ERRORServiceUnavailableExceptionHTTP_503_SERVICE_UNAVAILABLE当未提供detail时HTTPException.__init__会借助标准库http.HTTPStatus(self.status_code).phrase生成默认错误短语因此状态码常量的语义说明与标准库枚举保持一致。在业务路由中也可以直接构造带状态码的响应。官方处理器的示例见 docs/usage/routing/handlers.rstfrom litestar.status_codes import HTTP_400_BAD_REQUEST # 在处理器内返回带状态码的 JSON 响应 return Response( {detail: unsupported request}, status_codeHTTP_400_BAD_REQUEST, )WebSocket 场景中的关闭码使用WebSocket 连接关闭时通过关闭帧携带关闭码。Litestar 的 WebSocket.close 方法签名默认即为code: int WS_1000_NORMAL_CLOSURE即默认以 Normal Closure 优雅关闭await websocket.close(codeWS_1008_POLICY_VIOLATION, reasonpolicy breach)异常层面litestar/exceptions/websocket_exceptions.py 定义了WebSocketDisconnect其code参数默认同样为WS_1000_NORMAL_CLOSURE而更通用的WebSocketException默认使用私有码4500其 docstring 明确指出自定义异常码应使用4000范围的数值其余协议定义码则以WS_前缀常量引用见 litestar/exceptions/websocket_exceptions.py。测试客户端 litestar/testing/websocket_test_session.py 的close方法同样以WS_1000_NORMAL_CLOSURE为默认值保证测试与运行时行为一致。测试断言中的标准用法状态码常量是编写测试断言的推荐方式避免了魔法数字。官方测试与文档示例中随处可见这种模式例如 docs/usage/testing.rstfrom litestar.status_codes import HTTP_200_OK def test_health_check(client: TestClient) - None: response client.get(/health) assert response.status_code HTTP_200_OK仓库测试套件也大量使用该约定例如 CORS 测试断言预检请求返回HTTP_204_NO_CONTENT、非法请求返回HTTP_400_BAD_REQUEST见 tests/e2e/test_cors/test_cors_allowed_headers.py依赖注入测试断言成功响应为HTTP_200_OK、校验失败为HTTP_400_BAD_REQUEST见 tests/e2e/test_dependency_injection/test_http_handler_dependency_injection.py。框架内部的其余引用点除上述核心场景外litestar.status_codes还贯穿框架多个子模块可作为阅读源码的索引响应缓存判定litestar/config/response_cache.py 中通过HTTP_200_OK status_code HTTP_300_MULTIPLE_CHOICES判断响应是否属于可缓存的 2xx 范围静态文件与 OpenAPI 404litestar/static_files.py 与 litestar/_openapi/plugin.py 在资源缺失时返回HTTP_404_NOT_FOUNDJWT 认证注册litestar/security/jwt/auth.py 中登录/注册类处理器默认响应码为HTTP_201_CREATED模板渲染litestar/response/template.py 中TemplateResponse默认状态码为HTTP_200_OK。最佳实践小结优先引用常量而非魔法数字无论是装饰器status_code参数、Response(...)构造还是测试断言一律使用from litestar.status_codes import HTTP_200_OK这类导入语义自明且便于全局搜索。注意默认值陷阱POST默认201、DELETE默认204若你的 DELETE 接口需要返回数据务必显式覆盖status_code204/304与HEAD响应不允许携带 body。自定义异常遵循层级绑定自定义异常应继承HTTPException或ClientException并覆盖类属性status_code而不是在抛出点散落数字。WebSocket 自定义码避开协议保留段业务自定义关闭码使用4000范围框架示例默认4500协议语义码统一引用WS_常量。与标准库互操作官方文档同时认可http.HTTPStatus枚举作为备选方案但litestar.status_codes提供的常量更贴近框架内部实现见 docs/usage/responses.rst。延伸阅读状态码在响应上下文中的完整用法docs/usage/responses.rst异常体系与状态码的对应关系docs/usage/exceptions.rst、litestar/exceptions/http_exceptions.pyWebSocket 异常与关闭码litestar/exceptions/websocket_exceptions.py处理器默认状态码推导逻辑litestar/handlers/http_handlers/_utils.py模块源码与全量常量定义litestar/status_codes.py【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考