Sanic 异常体系深度解析SanicException 层次结构、错误处理与错误页渲染【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址: https://gitcode.com/gh_mirrors/sa/sanic本篇技术指南以 Sanic 官方 API 参考中的sanic.exceptions与sanic.errorpages两个模块见 docs/sanic/api/exceptions.rst为主线系统讲解 Sanic 的异常类层次结构、异常属性、内置 HTTP 异常速查、ErrorHandler处理机制、HTML/Text/JSON 三种错误页渲染器以及FALLBACK_ERROR_FORMAT自动协商逻辑。读完本文你将能够在 Sanic 应用中规范地抛出异常、自定义异常处理器与错误页格式并理解异常信息在 DEBUG 与 PRODUCTION 两种模式下的展示差异。一、异常体系总览两个模块的分工Sanic 的异常相关代码分布在两个模块中二者共同构成了抛异常 → 处理异常 → 渲染错误响应的完整链路sanic/exceptions.py定义全部异常类。以SanicException为根派生HTTPException及一系列与 HTTP 状态码一一对应的标准异常BadRequest、Unauthorized、Forbidden、NotFound、ServerError等。sanic/errorpages.py定义错误页渲染器BaseRenderer、HTMLRenderer、TextRenderer、JSONRenderer以及格式协商函数guess_mime()与exception_response()。当异常未被自定义处理器拦截时由这里的渲染器生成兜底fallback响应。两者的连接点是 sanic/handlers/error.py 中的ErrorHandler类它负责查表匹配用户注册的异常处理器匹配不到时调用default()走 errorpages 渲染流程。二、异常类层次结构SanicException是所有异常的基类其核心声明位于 sanic/exceptions.pyBaseException └── CancelledError └── RequestCancelled └── Exception └── SanicException └── HTTPException ├── NotFound (404) ├── BadRequest (400) ← InvalidUsage / BadURL 别名 ├── MethodNotAllowed (405) ← MethodNotSupported 别名 ├── ServerError (500) ← InternalServerError 别名 ├── ServiceUnavailable (503) ├── URLBuildError (500) ├── FileNotFound (404继承 NotFound) ├── RequestTimeout (408) ├── PayloadTooLarge (413) ├── HeaderNotFound (400继承 BadRequest) ├── InvalidHeader (400继承 BadRequest) ├── RangeNotSatisfiable (416) ← ContentRangeError 别名 ├── ExpectationFailed (417) ← HeaderExpectationFailed 别名 ├── Forbidden (403) ├── InvalidRangeType (416) └── Unauthorized (401)另外还有不属于 HTTP 状态码体系的特殊异常ServerKilled、PyFileError、LoadFileException、InvalidSignal、WebsocketClosed以及继承自asyncio.CancelledError的RequestCancelled。SanicException 的构造逻辑SanicException.__init__sanic/exceptions.py实现了几个关键行为message为None时优先取类属性self.message再退化为从STATUS_CODES表按status_code反查标准状态文本如 500 → Internal Server Errorbytes类型的消息会被自动decode()成str。status_code未显式传入时回退到类属性status_code最终默认 500。quiet、headers同样支持实例传参优先、类属性兜底的两级取值方式。context与extra直接存放在实例上供渲染器在生成响应时读取。三、SanicException 的六大核心属性所有 Sanic 异常都派生自SanicException该基类提供六个可在创建异常时传入、也可作为类变量预定义的属性参见 guide/content/en/guide/best-practices/exceptions.md 的 Exception properties 一节属性含义用途建议message发送给客户端的消息文本在类上定义可统一全应用的错误文案status_code随响应返回的 HTTP 状态码定义自定义 4xx 系列异常时尤其常用quiet为True时抑制 error_logger 的 traceback 输出用异常触发处理器事件、不想刷日志时使用headers附加到 HTTP 响应的请求头从异常侧直接控制响应头context附加键值数据始终随响应发送给客户端校验失败时给出替代值、展示登录用户状态等extra附加键值数据永不发送给生产环境客户端动态生成错误消息、给 logger 传运行时细节在类定义中固化属性from sanic.exceptions import SanicException class TeapotError(SanicException): status_code 418 message Sorry, I cannot brew coffee raise TeapotError # 使用类默认值 raise TeapotError(status_code400) # 实例级覆盖状态码 raise TeapotError(别急我换个说法) # 实例级覆盖消息用 quiet 控制日志噪音默认情况下异常会被输出到error_logger。若你只是想用异常触发某个处理逻辑而不想留下 traceback可设置quiet Trueclass SilentError(SanicException): message Something happened, but not shown in logs quiet True若在调试阶段希望全局忽略quietTrue强制输出所有异常日志可将配置NOISY_EXCEPTIONS置为Truesanic/config.py 中默认值为FalseErrorHandler.log在 sanic/handlers/error.py 中读取该配置决定是否打印app.config.NOISY_EXCEPTIONS True在异常中直接附加响应头SanicException可以直接当作响应工具使用——不仅能控制状态码还能直接控制响应头class MyException(SanicException): headers {X-Foo: bar} # 或按实例传入 raise MyException(headers{X-Foo: bar})渲染器在生成响应时会通过BaseRenderer.headers属性sanic/errorpages.py取出这些头合并进最终响应。四、内置标准异常速查表Sanic 为最常见的 HTTP 错误预置了对应异常源码见 sanic/exceptions.py每个异常类自身携带status_code并在多数场景下默认quiet True异常类状态码说明BadRequest400客户端请求非法Unauthorized401未认证支持拼接WWW-Authenticate头Forbidden403已认证但无权限NotFound404资源不存在MethodNotAllowed405方法不允许自动生成Allow头RequestTimeout408请求超时内部使用PayloadTooLarge413负载过大内部使用RangeNotSatisfiable416Range 请求不满足自动生成Content-Range头ExpectationFailed417Expect 头校验失败ServerError500通用服务端错误应优先于裸SanicException使用URLBuildError500Sanic 内部 URL 构建失败ServiceUnavailable503服务暂不可用FileNotFound404特定于文件系统查找失败的 404官方指南建议你在业务中自行实现的最常用异常是BadRequest400、Unauthorized401、Forbidden403、NotFound404、ServerError500。例如from sanic import exceptions app.route(/login) async def login(request): user await some_login_func(request) if not user: raise exceptions.NotFound( fCould not find user with username{request.json.username} )别名更贴合语义的命名源码中通过简单的赋值提供了语义化别名sanic/exceptions.py、sanic/exceptions.py、sanic/exceptions.py、sanic/exceptions.py、sanic/exceptions.py它们在身份上与原类是同一个对象测试 tests/test_exceptions.py 专门验证了这一点InvalidUsageBadRequestBadURLBadRequestMethodNotSupportedMethodNotAllowedInternalServerErrorServerErrorContentRangeErrorRangeNotSatisfiableHeaderExpectationFailedExpectationFailed带特殊行为的子类MethodNotAllowed构造时可传method与allowed_methods后者会被拼成Allow: GET, POST之类的响应头sanic/exceptions.py。RangeNotSatisfiable传入content_range协议对象后自动写入Content-Range: bytes */total头sanic/exceptions.py服务于静态文件与 Range 下载场景相关实现见 sanic/handlers/content_range.py。Unauthorized支持scheme与任意**challenges关键字参数自动生成WWW-Authenticate响应头sanic/exceptions.py# Basic 认证方案realm 必须存在 raise Unauthorized( Auth required., schemeBasic, realmRestricted Area, ) # Bearer 方案realm 可选 raise Unauthorized(Auth required., schemeBearer) # Digest 方案携带挑战参数 raise Unauthorized( Auth required., schemeDigest, realmRestricted Area, qopauth, auth-int, algorithmMD5, nonceabcdef, opaquezyxwvu, )FileNotFound额外携带path与relative_url属性用于静态文件/目录服务场景sanic/exceptions.py。PyFileError在配置脚本无法执行时抛出消息固定为could not execute config file filesanic/exceptions.py。WebsocketClosedWebSocket 被客户端关闭时抛出自带消息Client has closed the websocket connection且quiet Truesanic/exceptions.py。五、异常处理自定义处理器与 ErrorHandler方式一app.exception()装饰器Sanic 提供app.exception()装饰器不仅可以捕获 Sanic 标准异常还能捕获应用内抛出的任意异常装饰器实现在 sanic/mixins/exceptions.pyfrom sanic.exceptions import NotFound from sanic.response import text app.exception(NotFound, SomeCustomException) async def ignore_404s(request, exception): return text(fYep, I totally found the page: {request.url})可一次传入多个异常类也支持传入列表。app.exception(Exception)可作捕获一切的兜底处理器app.all_exceptionssanic/mixins/exceptions.py是其等价便捷写法。处理器可注册在 Blueprint 上此时仅作用于该蓝图下的路由而NotFound这类通用异常官方建议只注册在应用实例上。方式二app.error_handler.add()async def server_error_handler(request, exception): return text(Oops, server error, status500) app.error_handler.add(Exception, server_error_handler)ErrorHandler.add()sanic/handlers/error.py内部把(异常类型, 路由名)写入cached_handlers字典若对同一 (异常, 路由) 重复注册会抛出ServerErrorsanic/handlers/error.py。lookup()sanic/handlers/error.py在查找时不仅精确匹配类型还会沿type.mro()向上查找父类处理器因此为Exception注册的处理器能覆盖所有异常。response()sanic/handlers/error.py则负责实际执行处理器若处理器自身抛出异常debug 模式返回 500 文本否则返回 An error occurred while handling an error。方式三继承 ErrorHandler 自定义默认行为from sanic.handlers import ErrorHandler from sanic.response import json from sanic.request import Request from sanic.response.types import HTTPResponse class CustomErrorHandler(ErrorHandler): def default(self, request: Request, exception: Exception) - HTTPResponse: # 处理所有未被注册处理器拦截的异常 status_code getattr(exception, status_code, 500) return json({error: str(exception), foo: bar}, statusstatus_code) app.error_handler CustomErrorHandler()ErrorHandler在构造时接收一个base渲染器默认TextRenderer并持有debug标志——该标志会随应用的 debug 状态自动同步见 sanic/application/state.py。六、错误页渲染HTML / Text / JSON 三种格式未捕获异常最终会走进ErrorHandler.default()sanic/handlers/error.py它读取app.config.FALLBACK_ERROR_FORMAT并调用exception_response()渲染兜底响应。渲染器类图如下sanic/errorpages.pyBaseRenderer ├── HTMLRenderer # text/html默认兜底 ├── TextRenderer # text/plain └── JSONRenderer # application/jsonBaseRenderer.render()sanic/errorpages.py根据debug与异常的quiet属性在full完整、含 traceback与minimal简洁、无敏感信息两种输出之间切换debug 为 True 且异常非 quiet渲染full版本包含完整 traceback、请求路径、参数、异常链__cause__链会逐层展开。否则渲染minimal版本。非SanicException的普通异常此时仅显示固定文案The application encountered an unexpected error and could not continue.sanic/errorpages.py避免向生产环境泄露内部细节。FALLBACK_ERROR_FORMAT 的三种显式配置app.config.FALLBACK_ERROR_FORMAT html # 始终 HTML app.config.FALLBACK_ERROR_FORMAT text # 始终纯文本 app.config.FALLBACK_ERROR_FORMAT json # 始终 JSON在 sanic/config.py 中FALLBACK_ERROR_FORMAT被实现为带 setter 的属性一旦应用启动后修改该值会抛出异常提示以保证运行时格式一致性。非法格式值会被check_error_format()sanic/errorpages.py拒绝。各格式的响应示例Textdebug——curl localhost:8000/exc -i返回 500正文包含标题栏、异常类型、路径及完整 traceback⚠️ 500 — Internal Server Error That time when that thing broke that other thing? That happened. ServerError: ... while handling path /exc Traceback of TestApp (most recent call last): ServerError: ... File /path/to/sanic/app.py, line 979, in handle_request response await response ...Text非 debug——只剩标题与消息无 traceback⚠️ 500 — Internal Server Error That time when that thing broke that other thing? That happened.JSONdebug——结构化输出含description、status、message、path、args与exceptions每层含type、exception、frames{ description: Internal Server Error, status: 500, message: That time when that thing broke that other thing? That happened., path: /exc, args: {}, exceptions: [ { type: ServerError, exception: That time when that thing broke that other thing? That happened., frames: [ {file: /path/to/sanic/app.py, line: 979, name: handle_request, src: response await response} ] } ] }JSON非 debug——只保留description、status、message三个字段。按路由控制格式error_format除了全局配置还可以在路由上通过error_format关键字按路由控制错误格式Blueprints 会继承全局FALLBACK_ERROR_FORMAT见 sanic/blueprints.pyapp.route(/, error_formattext) async def handler(request): ...HTML 错误页的调试与生产差异HTML 渲染由HTMLRenderer借助 sanic/pages/error.py 中的ErrorPage完成样式定义在 sanic/pages/styles/ErrorPage.css。下图对比了 debug 开启与关闭时的 HTML 错误页差异七、Auto 模式根据请求协商响应格式设置app.config.FALLBACK_ERROR_FORMAT auto可启用格式自动协商这是 Sanic 的默认行为。guess_mime()sanic/errorpages.py按以下优先级决策路由的error_format若路由显式指定了格式text/json/html直接采用。FALLBACK_ERROR_FORMAT若配置为显式格式采用之。请求线索auto模式下检查请求——若Accept头匹配application/json字面匹配而非通配符或Content-Type含application/json则选择 JSON。旧版本还会尝试解析request.json推断该行为已标记弃用并计划移除见 sanic/errorpages.py。Accept 头匹配用req.accept.match()在所有支持的 MIME 间协商映射表MIME_BY_CONFIG/RENDERERS_BY_CONTENT_TYPE见 sanic/errorpages.py。直观效果浏览器访问返回 HTML 错误页curl或 API 客户端则可能收到 JSON 或纯文本。exception_response()sanic/errorpages.py根据协商结果实例化对应渲染器并产出最终响应。八、Contextual Exceptionscontext 与 extra 的正确用法Sanic 的异常支持运行时附加键值数据自 v21.12 起raise TeapotError(extra{name: Adam}, context{foo: bar})两者的关键区别在于是否发送给生产环境客户端extra对象本身永不发送给生产客户端仅供内部使用。典型场景结合property message动态生成错误消息向 logger 提供运行时细节开发模式下作为调试信息渲染。context始终随响应发送给客户端。典型场景在BadRequest校验失败时给出可替代的合法取值向客户返回便于开支持工单的补充信息展示当前登录用户等状态信息。用 extra 动态生成消息class TeapotError(SanicException): status_code 418 property def message(self): return fSorry {self.extra[name]}, I cannot make you coffee raise TeapotError(extra{name: Adam})用 context 向客户端传递信息raise TeapotError(context{foo: bar})非 debug 模式下 JSON 响应会包含context字段{ description: Im a teapot, status: 418, message: Sorry Adam, I cannot make you coffee, context: {foo: bar} }debug 模式则会额外附加path、args、exceptions完整 traceback与extra字段。context在 HTML 错误页中以exception-context定义列表展示、在 Text 输出中以Context小节展示extra则在 debug 下以Extra小节展示渲染逻辑见 sanic/errorpages.py 与 sanic/errorpages.py。源码中的测试 tests/test_exceptions.py 对三种格式下的context/extra/动态消息行为做了逐项断言例如extra在非 debug 下不会出现在 JSON 中、动态message可被实例级message覆盖等。九、错误上报report_exception 与信号若希望把异常信息上报给 Sentry、Rollbar 等第三方服务可以挂载report_exception处理器自 v23.6 起对应示例可参考仓库中的 examples/sentry_example.py 与 examples/rollbar_example.pyapp.report_exception async def catch_any_exception(app: Sanic, exception: Exception): print(Caught exception:, exception)注意该处理器会被调度进后台任务仅用于日志与上报不能用于修改返回给客户端的响应数据。从源码看异常处理流程中还会派发http.lifecycle.exception信号sanic/app.py可用于监听所有请求生命周期内的异常。十、测试与源码验证路径以下文件可帮助你进一步深入验证本文所述机制异常类定义sanic/exceptions.py渲染器与格式协商sanic/errorpages.py处理器核心实现sanic/handlers/error.py装饰器实现sanic/mixins/exceptions.py配置项定义sanic/config.pyNOISY_EXCEPTIONS、FALLBACK_ERROR_FORMAT异常在请求主流程中的处理位置sanic/app.py行为测试tests/test_exceptions.py别名、消息属性、quiet 属性、contextual exceptions、处理器异常等约 30 个用例官方使用指南guide/content/en/guide/best-practices/exceptions.md小结Sanic 的异常体系是一条完整闭环SanicException及标准子类负责以统一方式表达发生了什么错误context/extra负责携带结构化附加信息ErrorHandler负责按注册表分发到自定义处理器而errorpages中的三种渲染器与auto协商逻辑则保证未捕获异常也能以合适的格式、合适的信息量debug 全量、生产精简优雅地返回给客户端。掌握这套机制你就能把异常从不可控的报错转变为可预期、可观测、对客户端友好的业务响应。【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址: https://gitcode.com/gh_mirrors/sa/sanic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考