Sanic 响应(Response)完全指南:从 HTTPResponse 到 JSONResponse 的实战与源码解析
Sanic 响应(Response)完全指南:从 HTTPResponse 到 JSONResponse 的实战与源码解析
本文围绕 Sanic 的响应体系展开:所有 handler 通常都会返回一个响应对象,中间件(middleware)也可以选择性地返回响应对象来替代 handler 的执行结果。读完本文,你将掌握 HTTPResponse 的基础用法、text/html/json/file/file_stream/raw/redirect/empty 等全部便捷方法及其默认行为、JSON 编码器替换方案,以及从 v22.9 开始引入的 JSONResponse 对象级数据操作方法,并结合仓库源码理解其底层实现。
响应(Response)在 Sanic 中的角色
在 Sanic 中,handler 的返回值通常必须是一个 sanic.response.HTTPResponse 实例。只有一种例外:当 handler 是流式端点(streaming endpoint),自行负责向客户端发送字节流时,可以不返回响应对象(参见 流式响应)。在绝大多数使用场景下,你都需要返回一个响应。
对于中间件(middleware)而言,规则略有不同:如果中间件返回了响应对象,该响应将直接替代 handler 原本要生成的响应返回给客户端(详见 middleware)。
最基本的 handler 写法如下。HTTPResponse 对象允许你设置返回给客户端的状态码(status)、响应体(body)和响应头(headers):
from sanic import HTTPResponse, Sanic
app = Sanic("TestApp")
@app.route("")
def handler(_):
return HTTPResponse()
不过在实际开发中,通常更推荐使用下面介绍的各类便捷方法(convenience methods),它们使用起来更简单、语义更清晰。
响应便捷方法一览
Sanic 在 sanic.response 包中提供了多种便捷函数,可以一键生成不同语义的响应。下表汇总了每种方法的默认 Content-Type 与用途(这些默认值均可在 convenience.py 中逐一定义处核实):
| 方法 | 默认 Content-Type | 说明 |
|---|---|---|
text() |
text/plain; charset=utf-8 |
返回纯文本 |
html() |
text/html; charset=utf-8 |
返回 HTML 文档 |
json() |
application/json |
返回 JSON 文档 |
file() |
N/A(根据文件扩展名自动猜测) | 返回文件内容 |
file_stream() |
N/A(根据文件扩展名自动猜测) | 以流式方式返回文件,适合视频等大文件 |
raw() |
application/octet-stream |
原样发送原始字节,不做编码 |
redirect() |
text/html; charset=utf-8 |
发送 302 重定向响应 |
empty() |
N/A | 按 RFC 2616 返回空消息体,默认状态码 204 |
这些函数同时在 sanic/__init__.py 中被导出为顶层 API,因此既可以从 sanic.response 导入,也可以直接 from sanic import text, html, json, ...(参见 sanic/init.py)。
返回纯文本:text()
from sanic import text
@app.route("/")
async def handler(request):
return text("Hi 😎")
其底层实现(见 convenience.py)要求 body 必须是 str 类型,否则会抛出 TypeError:
def text(body, status=200, headers=None, content_type="text/plain; charset=utf-8"):
if not isinstance(body, str):
raise TypeError(
f"Bad body type. Expected str, got {type(body).__name__})"
)
return HTTPResponse(body, status=status, headers=headers, content_type=content_type)
返回 HTML:html()
from sanic import html
@app.route("/")
async def handler(request):
return html('<!DOCTYPE html><html lang="en"><meta charset="UTF-8"><div>Hi 😎</div>')
html() 的入参更灵活:除 str/bytes 外,还支持任意实现了 __html__ 或 _repr_html_ 方法的对象(如 HTML 模板引擎渲染产物),源码中会依次尝试调用这两个方法获取 HTML 字符串(见 convenience.py)。
返回 JSON:json()
from sanic import json
@app.route("/")
async def handler(request):
return json({"foo": "bar"})
关于 JSON 编码器:默认情况下,Sanic 优先使用 ujson:使用 ujson 时以 escape_forward_slashes=False 调用;回退标准库时使用 separators=(",", ":") 以保持输出风格与 ujson 一致,确保两种编码器下序列化结果尽量统一。
如果你希望更换编码器,可以非常简单地做到,例如改用 orjson 的 dumps:
from sanic import json
from orjson import dumps
json({"foo": "bar"}, dumps=dumps)
也可以在应用初始化时全局声明使用哪种 JSON 序列化实现,这样应用内所有 JSON 响应都会使用它:
from orjson import dumps
app = Sanic(..., dumps=dumps)
从源码看,Sanic.__init__ 收到 dumps 参数后,会将其赋值给 BaseHTTPResponse._dumps(见 app.py),而 JSONResponse 在构造时若未显式传入 dumps,就使用这个类级别的默认值(见 types.py)。也就是说:调用级 dumps 优先,其次才使用应用级全局 dumps。
返回文件:file()
from sanic import file
@app.route("/")
async def handler(request):
return await file("/path/to/whatever.png")
file() 是异步函数,需要 await。Sanic 会检查文件并根据扩展名猜测其 MIME 类型,自动设置合适的 content-type。如果你希望显式指定 MIME 类型:
file("/path/to/whatever.png", mime_type="image/png")
也可以覆盖下载文件名:
file("/path/to/whatever.png", filename="super-awesome-incredible.png")
当指定 filename 时,源码会设置 Content-Disposition: attachment; filename="..." 响应头(见 convenience.py),浏览器会将其作为附件下载。
值得深入了解的增强能力(源码可见,convenience.py):
- 条件请求校验(304 Not Modified):默认开启
validate_when_requested=True,当请求带有If-Modified-Since头且文件自上次修改后未变化时,返回304状态;校验逻辑见validate_file(convenience.py),相关行为在 tests/test_response_file.py 中有测试覆盖。 - 缓存控制:默认设置
cache-control: no-cache;传入max_age时改为public, max-age=<秒>并同时设置expires头;传入no_store=True时使用no-store。 Last-Modified头:默认取文件的st_mtime,也允许通过last_modified参数显式指定。- Range 支持(206 Partial Content):内部
_range参数支持Content-Range与部分内容响应。
流式返回文件:file_stream()
from sanic.response import file_stream
@app.route("/")
async def handler(request):
return await file_stream("/path/to/whatever.mp4")
与 file() 一样,file_stream() 也会自动猜测文件的 MIME 类型。它的优势在于逐块读取文件内容并发送,不会把整个大文件一次性载入内存,非常适合视频等大文件下载场景。
从源码看(convenience.py),其默认 chunk_size=4096 字节,返回的是一个 ResponseStream 对象(定义于 types.py),内部通过 open_async 以 "rb" 模式打开文件循环读取并 response.write(content);同时支持 _range 参数实现断点续传(206)。ResponseStream 是对已废弃的 StreamingHTTPResponse 的兼容层。
返回原始字节:raw()
from sanic import raw
@app.route("/")
async def handler(request):
return raw(b"raw bytes")
raw() 不做任何编码,直接发送传入的字节内容。其默认 Content-Type 为 application/octet-stream,该常量定义于 constants.py:DEFAULT_HTTP_CONTENT_TYPE = "application/octet-stream"。
重定向:redirect()
from sanic import redirect
@app.route("/")
async def handler(request):
return redirect("/login")
默认发送 302 Found 响应。源码实现(convenience.py)会通过 quote_plus 对目标地址进行 URL 编码(保留 :/%#?&=@[]!$&'()*+,; 等合法字符),然后写入 Location 响应头——根据 RFC 7231,相对 URI 是被允许的。如需 301 永久重定向,可传入 status=301。
空响应:empty()
from sanic import empty
@app.route("/")
async def handler(request):
return empty()
默认返回 204 No Content 状态,不携带消息体(符合 RFC 2616 对空消息的定义)。其实现非常直接(convenience.py):
def empty(status: int = 204, headers=None) -> HTTPResponse:
return HTTPResponse(body=b"", status=status, headers=headers)
默认状态码与自定义
Sanic 响应的默认 HTTP 状态码是 200。如果需要改变,可以通过各个响应方法的 status 参数指定:
@app.post("/")
async def create_new(request):
new_thing = await do_create(request)
return json({"created": True, "id": new_thing.thing_id}, status=201)
HTTPResponse 的构造签名是 HTTPResponse(body=None, status=200, headers=None, content_type=None)(见 types.py),status 的默认值正是 200。
另外值得注意:对于 204、304 以及 1xx 系列状态码,RFC 2616 规定响应中不应包含消息体。Sanic 在 helpers.py 中通过 has_message_body(status) 判断,并且在 BaseHTTPResponse.processed_headers 中只在允许消息体的响应上设置 content-type 头(见 types.py)。empty() 返回的 204 响应在测试中也验证了其 content_type 为 None(见 tests/test_response.py)。
JSONResponse:对象级操作 JSON 响应体
自 v22.12 起,当你使用 sanic.json 便捷方法时,返回的将不再是普通的 HTTPResponse,而是其子类 sanic.response.types.JSONResponse。该对象提供了若干便捷方法,用于直接修改常见的 JSON 响应体结构:
from sanic import json
resp = json(...)
可用方法如下(定义于 types.py):
| 方法 | 行为 | 适用根类型 |
|---|---|---|
resp.set_body(<raw_body>) |
将 JSON 对象的响应体设置为传入值 | 任意 |
resp.append(<value>) |
向响应体追加一个值,类似 list.append |
根为数组 |
resp.extend(<value>) |
向响应体扩展一组值,类似 list.extend |
根为数组 |
resp.update(<value>) |
用传入值更新响应体,类似 dict.update |
根为对象 |
resp.pop() |
弹出某个值,类似 list.pop 或 dict.pop |
根为数组或对象 |
警告:原始 Python 对象以
raw_body属性存储在JSONResponse上。虽然安全地将该属性整体替换为新的对象,但不应直接对它进行原地修改(mutate)。请改用上面列出的方法。
下面是官方文档给出的对象(dict)场景示例:
resp = json({"foo": "bar"})
# 可行:整体替换 raw_body
resp.raw_body = {"foo": "bar", "something": "else"}
# 更推荐:使用 set_body
resp.set_body({"foo": "bar", "something": "else"})
# 也很好:使用 update
resp.update({"something": "else"})
# 不可行:直接原地修改 raw_body 不会同步到响应体
resp.raw_body.update({"something": "else"})
以及数组(list)场景示例:
# 或者把它当作 list 使用
resp = json(["foo", "bar"])
# 可行:整体替换
resp.raw_body = ["foo", "bar", "something", "else"]
# 更推荐:使用 extend
resp.extend(["something", "else"])
# 也很好:逐个 append
resp.append("something")
resp.append("else")
# 不可行:直接原地修改
resp.raw_body.append("something")
从源码可以更清楚地理解这些约束(types.py):
JSONResponse内部同时维护_raw_body(原始 Python 对象)和_body(序列化后的字节),并有一个_body_manually_set标记;append/extend只允许在_raw_body为list时使用,update只允许在_raw_body为dict时使用,否则抛出SanicException;pop同时支持list和dict;当根为list时传入默认值会抛出TypeError: pop doesn't accept a default argument for lists;- 一旦通过
set_body或直接赋值body手动设置过响应体,再访问raw_body会抛出SanicException("Cannot use raw_body after body has been manually set.")。
仓库中的测试 tests/test_response_json.py 对上述全部行为均有覆盖,包括:raw_body 的读取与整体替换、set_body 及自定义 dumps、append/extend/update、对 dict 和 list 的 pop 及对 list 使用默认值抛错等场景。
附注:该能力最初在 v22.9 引入,并在后续版本(v22.12)中正式成为
json()的默认返回类型。
响应对象的底层结构
理解 HTTPResponse 的内部结构有助于你更好地掌控响应行为。类继承关系如下(均定义于 types.py):
BaseHTTPResponse(L29-L209):所有响应的基类,通过__slots__定义了asgi、body、content_type、stream、status、headers、_cookies等属性,并提供了processed_headers(将响应头编码为字节迭代器)、send()(向底层流写入数据)以及add_cookie()/delete_cookie()(详见 cookies 指南)等方法。HTTPResponse(L212-L247):最常用的响应类,构造参数为body、status=200、headers、content_type;还实现了异步上下文管理器协议,可用async with配合流式发送。JSONResponse(L250-L475):HTTPResponse的子类,追加了上文介绍的 JSON 操作能力,默认content_type="application/json"。ResponseStream(L478-L553):流式响应的兼容层,file_stream()即返回此对象。
所有这些类型与便捷函数统一从 sanic/response/init.py 导出(empty、file、file_stream、html、json、raw、redirect、text、validate_file 以及 HTTPResponse、JSONResponse、ResponseStream、BaseHTTPResponse 等)。
实践建议
- 优先使用便捷方法而非直接构造
HTTPResponse:它们自带了正确的默认Content-Type、类型校验与额外的便捷行为(如file()的缓存控制与 304 校验、redirect()的 URL 编码),代码更简洁、不易出错。 - JSON 场景统一走
json():既能获得全局/单次调用的编码器定制能力,又能利用JSONResponse在响应中间件中灵活地set_body/update/append响应体,避免直接修改raw_body带来的响应体不同步问题。 - 大文件使用
file_stream():避免整文件载入内存;若需断点续传,可结合 Range 语义(206)。 - 注意
status参数:创建资源用201、删除/空响应用204、重定向用301/302,语义化地使用状态码,这也是 Sanic 官方文档示例中推荐的做法。
小结
Sanic 的响应体系以 HTTPResponse 为核心,通过一组语义清晰的便捷方法覆盖了文本、HTML、JSON、文件、流式文件、原始字节、重定向与空响应等几乎所有常见场景;JSONResponse 更进一步将 JSON 响应体操作提升到对象层面。配合 dumps 的调用级与全局级定制能力,你可以精确控制响应的序列化、状态码与头部行为——这些设计都可以在当前仓库的 sanic/response 目录源码及其 tests/test_response_json.py 等测试中逐一验证。