Sanic 响应(Response)完全指南:从 HTTPResponse 到 JSONResponse 的实战与源码解析

原创2026-09-20 22:56:421,997 阅读
文章标签:后端Web框架

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 等测试中逐一验证。

登录后查看全文
sanic