starlette 通过挂载自定义的 exceptionmiddleware 实例来设置自定义错误页面。你需要创建一个继承自 starlette.exceptions.exceptionmiddleware 的类,重写其 handle_404、handle_500 等方法,并在初始化应用时将其实例传入 app.add_middleware 或构造函数中。

如何拦截并返回特定 HTTP 状态码的 HTML 响应
要拦截特定的 HTTP 状态码(如 404 或 500)并返回自定义 HTML,需要重写 ExceptionMiddleware 中的对应处理方法。这些方法接收请求和异常实例作为参数,你可以在此处构造并返回一个 HTMLResponse 对象。例如,重写 handle_404 可以捕获所有未匹配路由的请求,并重写 handle_500 来捕获未处理的服务器内部错误。

from starlette.applications import Starlette
from starlette.responses import HTMLResponse
from starlette.exceptions import ExceptionMiddleware
from starlette.routing import Route, Mount
from starlette.staticfiles import StaticFiles
class CustomExceptionMiddleware(ExceptionMiddleware):
def handle_404(self, request, exc):
return HTMLResponse("<h1>Custom 404 Page</h1><p>Page not found.</p>>", status_code=404)
def handle_500(self, request, exc):
return HTMLResponse("<h1>Custom 500 Page</h1><p>Internal Server Error.</p>>", status_code=500)
# 假设有一个简单的路由
async def homepage(request):
return HTMLResponse("<h1>Home</h1>>")
routes = [
Route("/", homepage),
]
app = Starlette(
routes=routes,
debug=False, # 生产环境建议关闭 debug
exception_handlers={
404: CustomExceptionMiddleware().handle_404,
500: CustomExceptionMiddleware().handle_500,
}
)
# 或者更推荐的方式:
# custom_middleware = CustomExceptionMiddleware()
# app = Starlette(routes=routes, middleware=[custom_middleware])
# 注意:通常直接替换默认的 exception_handlers 字典更简单
上述代码展示了两种主要方式。第一种是直接修改 exception_handlers 字典,将状态码映射到处理函数。第二种是创建中间件实例。在实际操作中,直接覆盖 exception_handlers 是最常见且直观的做法。当访问不存在的路由时,Starlette 会触发 404 异常,此时 handle_404 被调用,返回自定义 HTML。当发生未捕获异常时,handle_500 被调用。
如何在自定义错误页中传递上下文数据
有时需要在错误页面中显示更多信息,例如请求的路径或错误详情。可以通过在自定义处理函数中访问 request 对象来获取这些信息。此外,如果需要传递模板变量,可以使用 Jinja2 等模板引擎渲染 HTML 字符串,而不是直接返回硬编码的字符串。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.responses import HTMLResponse
from jinja2 import Template
class AdvancedExceptionMiddleware:
def __init__(self):
self.error_template = Template("""
<title>Error {{ status_code }}</title><h1>Error {{ status_code }}</h1>
<p>Path: {{ path }}</p>
<p>Message: {{ message }}</p>
""")
def handle_404(self, request, exc):
context = {
'status_code': 404,
'path': request.url.path,
'message': 'The requested resource was not found.'
}
html_content = self.error_template.render(**context)
return HTMLResponse(html_content, status_code=404)
def handle_500(self, request, exc):
context = {
'status_code': 500,
'path': request.url.path,
'message': 'An unexpected error occurred.'
}
html_content = self.error_template.render(**context)
return HTMLResponse(html_content, status_code=500)
# 使用示例
app = Starlette(
routes=[],
exception_handlers={
404: AdvancedExceptionMiddleware().handle_404,
500: AdvancedExceptionMiddleware().handle_500,
}
)
在这个例子中,我们使用了 Jinja2 模板来动态生成错误页面。通过访问 request.url.path,我们可以将用户尝试访问的路径显示在错误页面上。这种方法使得错误页面更加友好和具有信息量。需要注意的是,在生产环境中,应避免泄露详细的错误堆栈信息,只展示必要的用户友好信息。
基于程序中某个输入、条件或结果的具体问题
当程序接收到一个不存在的静态文件请求时,Starlette 默认行为是什么?
如果配置了 StaticFiles 并且请求的文件不存在,Starlette 会触发 404 异常。此时,如果已经设置了自定义的 handle_404 方法,该方法将被调用并返回自定义的 404 页面。如果没有设置自定义处理,Starlette 会返回默认的 404 响应。可以通过检查 request.url.path 来确认请求的路径,从而在自定义错误页中显示该路径。










