罗罗编程学习记录
本页内容 展开查看

04.7.19.1 Sanic 与 Tornado

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.19 其他主流 Web 框架

覆盖范围

  • Sanic 异步路由、路径参数类型转换、反向解析与 Blueprint 分层组织
  • HTTPMethodView 类视图、函数视图、请求/响应中间件与 listener 生命周期钩子
  • sanic-ext 请求校验、依赖注入与 OpenAPI 文档生成
  • Sanic 自有协议实现与标准 ASGI 的差别、并发模型、阻塞调用处理与选型取舍
  • Tornado IOLoop、Application/HTTPServer 与 RequestHandler 生命周期
  • Tornado 协程从 gen.coroutine 到 async/await 的演进、混用边界与非阻塞客户端
  • Tornado 多进程 fork 模型、与 asyncio 事件循环融合、WebSocket 与安全 cookie
  • 两者性能取舍、适用场景,以及与 FastAPI、Flask、Starlette 的横向对比

04.7.19.1-001 Sanic 是什么,它的定位和版本基线是什么?

一句话结论

Sanic 是一个原生异步的 Python Web 框架兼自带服务器,早期以高并发、低延迟为卖点,路由、视图、中间件、蓝图都围绕 async/await 设计。版本基线按 Sanic 23.x/24.x 讨论;它既可以用自带服务器启动,也兼容 ASGI 接口交给 uvicorn/hypercorn 托管。

概念解释

  • Sanic 与 Flask 的 API 风格接近(装饰器路由、蓝图、配置对象),但执行模型是单事件循环上的协程,而不是 WSGI 同步 worker。
  • 它和 FastAPI 同属异步框架阵营,差别在于 Sanic 更强调自带服务器与协议层可控性,FastAPI 则构建在 Starlette 之上、依赖 Pydantic 做校验。

原理流程

  1. 进程启动后创建 Sanic 应用对象,注册路由、中间件、蓝图与监听器。
  2. 自带服务器绑定端口,在事件循环上接收连接、解析请求并分发到协程视图。
  3. 视图 await 异步 IO,事件循环在等待期间调度其他连接,单进程承载高并发。

代码或图示

from sanic import Sanic
from sanic.response import json

app = Sanic("demo")

@app.get("/hello")
async def hello(request):
    return json({"msg": "ok"})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000, workers=1)

常见误区

  • 不要把 Sanic 当成“异步版 Flask”直接平移:视图默认是协程,视图里出现同步阻塞调用会卡住整个事件循环,这是和 Flask 最大的行为差异。
  • Sanic 的性能优势只在 IO 密集、异步链路完整时成立;业务里混着同步数据库驱动、同步 HTTP 客户端,优势会被抵消甚至不如同步框架加多进程。

追问

  • Sanic 是 WSGI 框架吗?答:不是,它原生异步,走自有服务器或 ASGI 适配,不能直接交给 gunicorn 的 sync worker。
  • Sanic 和 FastAPI 最大的架构差别是什么?答:Sanic 自带服务器与协议层,FastAPI 基于 Starlette 并以 Pydantic 为校验核心。
  • Sanic 视图必须写 async 吗?答:可以写同步函数,但同步函数会被放到线程池执行,失去原生异步的调度优势。

04.7.19.1-002 最小 Sanic 应用如何启动,启动参数有哪些?

一句话结论

最小应用是创建 Sanic(name) 实例,用装饰器注册路由,再调用 app.run() 绑定主机、端口与 worker 数。生产环境通常不在代码里写 app.run,而是通过 CLI(sanic module:app)或 ASGI 服务器启动,便于控制 worker、日志与监听地址。

概念解释

  • Sanic 构造参数里可以传 config、load_env、strict_slashes 等;name 主要用于日志与多实例区分。
  • app.run() 是开发与本地调试入口;生产部署常用 CLI 或外部服务器,配置通过环境变量与配置文件注入。

原理流程

  1. 实例化 Sanic,应用配置默认值与环境变量。
  2. 注册路由、中间件、蓝图与监听器。
  3. run() 启动自有服务器:主进程 fork 出指定 worker,每个 worker 跑一个事件循环。

代码或图示

# CLI 启动(生产常用),workers 指定进程数
sanic server:app --host 0.0.0.0 --port 8000 --workers 4
# 代码内启动(本地调试为主)
app.run(host="127.0.0.1", port=8000, workers=2, debug=False, auto_reload=False)

常见误区

  • debug=True 会开启自动重载与详细异常页,绝不能带进生产;它还会改变性能与行为,不能用调试模式的表现判断生产吞吐。
  • workers>1 时每个进程持有独立内存,进程间不共享本地变量;把请求状态挂在全局字典上会出现“时有时无”的串数据问题。

追问

  • app.run 与 sanic CLI 是什么关系?答:CLI 是生产入口,run() 是代码内调试入口,底层都走到自有服务器的启动流程。
  • 多 worker 下全局变量共享吗?答:不共享,各进程独立内存,跨进程状态要落 Redis/数据库等外部存储。
  • 自动重载在生产为什么要关?答:会监视文件变化并重启进程,带来额外开销、不稳定与信息泄露风险。

04.7.19.1-003 Sanic 路由装饰器如何绑定 HTTP 方法?

一句话结论

Sanic 提供 @app.get、@app.post、@app.put、@app.delete、@app.patch 等方法专用装饰器,也有通用的 @app.route(path, methods=[...])。装饰器把视图函数与路径、方法集合登记到路由表,请求匹配后由调度器调用对应协程。

概念解释

  • 方法专用装饰器语义清晰,OpenAPI 文档生成时也能直接识别允许的方法。
  • 一个路径需要支持多个方法时,用 route 并显式声明 methods,或分别为同一函数注册多次。

原理流程

  1. 装饰器在应用构建期把 (path, methods, handler) 加入路由表。
  2. 请求进入后路由层按路径与方法匹配,未匹配方法会返回 405 Method Not Allowed。
  3. 匹配成功后把 request 对象与路径参数传给视图协程。

代码或图示

from sanic import Sanic
from sanic.response import json

app = Sanic("demo")

@app.get("/items")
async def list_items(request):
    return json({"items": []})

@app.post("/items")
async def create_item(request):
    body = request.json or {}
    return json(body, status=201)

@app.route("/health", methods=["GET", "HEAD"])
async def health(request):
    return json({"ok": True})

常见误区

  • 只注册了 get 却用 POST 请求,不会自动落到同一个函数,而是 405;需要在 methods 里显式放开。
  • 路径末尾斜杠策略受 strict_slashes 影响:开启时 /items 与 /items/ 视为不同路由,关闭时做重定向归一化,跨环境行为要保持一致。

追问

  • 405 是在哪一层产生的?答:路由层路径匹配成功但方法不在允许集合内时返回。
  • strict_slashes 关闭后行为是什么?答:对末尾斜杠做归一化与重定向,避免两条等价路径。
  • 如何让一个视图同时处理 GET 和 POST?答:用 @app.route(path, methods=["GET", "POST"])。

04.7.19.1-004 Sanic 路径参数有哪些类型转换器?

一句话结论

路径参数用尖括号声明,如 /users/<uid>,可指定转换器:str(默认)、int、float、alpha、uuid、any、regex。转换器既决定路径匹配规则,也决定传入视图参数的类型;不匹配会落到 404。

概念解释

  • str 匹配除斜杠外的任意字符;int 只匹配整数并转成 int;alpha 只匹配字母;uuid 匹配 UUID 格式;any(a,b,c) 限定枚举值;regex(...) 用自定义正则。
  • 类型转换在路由层完成,视图拿到的已经是转换后的值,不需要再手动 int()。

原理流程

  1. 路由注册时把路径模板编译成匹配规则与转换器列表。
  2. 请求路径逐段匹配,转换器校验格式并做类型转换。
  3. 转换成功后以关键字参数形式传给视图;失败则不匹配该路由。

代码或图示

import uuid

@app.get("/users/<uid:int>")
async def user_by_id(request, uid: int):
    return json({"uid": uid, "type": type(uid).__name__})

@app.get("/tags/<name:alpha>")
async def tag(request, name: str):
    return json({"tag": name})

@app.get("/uuid/<token:uuid>")
async def by_uuid(request, token: uuid.UUID):
    return json({"token": str(token)})

@app.get("/files/<path:regex([^/]+\\.txt)>")
async def file(request, path: str):
    return json({"file": path})

常见误区

  • 忘记指定 int 转换器时,uid 是字符串,直接做数值比较或运算会得到错误结果;这是从其他框架迁过来最常见的坑。
  • regex 转换器的正则不能跨斜杠匹配;需要分段捕获时要拆成多个路径段,正则写法在不同版本上的转义规则需对照官方文档确认(待确认:验证点:当前版本 regex 转换器分组与转义行为)。

追问

  • 转换器在哪里完成类型转换?答:路由匹配阶段,视图拿到的已是转换后的值。
  • 路径不匹配转换器返回什么?答:该路由不命中,继续匹配其他路由,最终 404。
  • 如何限定参数只能取固定几个值?答:用 any(active, disabled) 枚举转换器。

04.7.19.1-005 路由命名与 url_for 反向解析怎么用?

一句话结论

每条路由可以起一个名字,默认取视图函数名;app.url_for(name, **params) 根据名字和路径参数反推出 URL,避免在代码里硬编码路径。蓝图内的路由名字会带蓝图前缀,反向解析时要用全名。

概念解释

  • 命名路由用于模板跳转、重定向、生成文档链接与测试断言,路径调整时只改路由声明,引用处自动跟随。
  • 蓝图路由的端点名格式为 蓝图名.视图名,跨蓝图引用时必须写全。

原理流程

  1. 注册路由时记录端点名、路径模板与参数列表。
  2. url_for 按端点名找到模板,填入路径参数,拼出完整路径。
  3. 需要外部绝对地址时传 _external=True,由请求主机生成完整 URL。

代码或图示

@app.get("/users/<uid:int>", name="user_detail")
async def user_detail(request, uid):
    return json({"url": app.url_for("user_detail", uid=uid)})

@app.get("/go")
async def go(request):
    return json({"next": app.url_for("user_detail", uid=42, _external=True)})

常见误区

  • 蓝图内视图用裸函数名去 url_for 会找不到端点;必须用 蓝图名.函数名 的全名。
  • url_for 拼出的是相对路径,生成可对外访问的链接要显式 _external=True,并正确配置代理后的主机头,否则会拿到内网地址。

追问

  • 端点名默认是什么?答:视图函数本身的名字,可在装饰器里用 name= 覆盖。
  • 蓝图路由反向解析为什么要加前缀?答:避免不同蓝图下同名视图端点冲突。
  • _external=True 依赖什么?答:依赖请求里的主机头与代理转发配置。

04.7.19.1-006 Blueprint 如何定义、注册并加 URL 前缀?

一句话结论

Blueprint 把一组路由、中间件、监听器组织成可复用模块,创建时指定名字与 url_prefix,再用 app.blueprint(bp) 挂到应用上。它是按业务域拆分大型应用的主要手段,和 Flask 蓝图概念对应。

概念解释

  • 蓝图可以自带路由、静态目录、异常处理器与中间件,注册时统一并入主应用。
  • url_prefix 拼在蓝图内每条路由路径之前,适合按 /api/v1/users 这类域划分模块。

原理流程

  1. 创建 Blueprint("users", url_prefix="/api/users"),在其上用 @bp.get 注册路由。
  2. 主应用调用 app.blueprint(bp),蓝图的路由表合并进主路由表,端点名加蓝图前缀。
  3. 请求匹配时按合并后的路由表分发,蓝图中间件按注册顺序参与请求链。

代码或图示

from sanic import Blueprint, Sanic
from sanic.response import json

bp = Blueprint("users", url_prefix="/api/users")

@bp.get("/<uid:int>")
async def detail(request, uid):
    return json({"uid": uid})

app = Sanic("demo")
app.blueprint(bp)

常见误区

  • 蓝图前缀只拼路径,不自动隔离状态;蓝图内挂在全局对象上的数据仍会跨请求共享。
  • 多个蓝图注册顺序会影响路由匹配优先级,先注册的更具体路由要排在前面,避免被宽泛路由截胡。

追问

  • 蓝图解决什么问题?答:按业务域拆分路由与钩子,支持模块化复用与团队并行开发。
  • 蓝图端点名长什么样?答:蓝图名.视图函数名。
  • 蓝图可以带自己的中间件吗?答:可以,蓝图级中间件只作用于该蓝图路由。

04.7.19.1-007 蓝图嵌套与分组在 Sanic 里怎么组织?

一句话结论

Sanic 支持蓝图分组:把多个子蓝图放进一个父蓝图,父蓝图统一加前缀、挂中间件,再整体注册到应用。分组适合多级版本号或多层业务域(如 /api/v1/admin/...)的目录式组织。

概念解释

  • 分组本质是路由与钩子的层级合并:子蓝图继承父蓝图的前缀与中间件配置。
  • 相比把所有前缀拼在单个蓝图上,分组让目录结构与代码目录一一对应,便于维护。

原理流程

  1. 创建父蓝图,声明公共前缀与公共中间件。
  2. 子蓝图通过分组机制挂到父蓝图下,路径逐级拼接。
  3. 应用只注册父蓝图,合并后的完整路由表进入主应用。

代码或图示

api = Blueprint("api", url_prefix="/api")
v1 = Blueprint("v1", url_prefix="/v1")
users = Blueprint("users", url_prefix="/users")

@users.get("/<uid:int>")
async def detail(request, uid):
    return json({"uid": uid})

v1.blueprint(users)
api.blueprint(v1)
app.blueprint(api)
# 最终路径:/api/v1/users/<uid>

常见误区

  • 层级拼接时前缀重复或遗漏,最终路径与文档不一致;改动层级后要回归 url_for 与前端调用。
  • 分组不是进程隔离或权限隔离:父蓝图的中间件可以约束子路由,但安全边界仍要靠认证/授权中间件显式实现。

追问

  • 蓝图分组和普通多蓝图注册差别在哪?答:分组带层级前缀与公共钩子,普通注册是平铺合并。
  • 父蓝图中间件作用于子蓝图吗?答:作用于,按层级参与请求链。
  • 路径前缀在哪里拼接?答:注册合并阶段逐级拼到完整路径上。

04.7.19.1-008 HTTPMethodView 类视图怎么写?

一句话结论

HTTPMethodView 把同一资源的 GET/POST/PUT/DELETE 写成类的方法,as_view() 生成可注册的视图对象。它适合 REST 资源风格:一个类对应一个资源路径,方法名即 HTTP 方法,比在函数里判断 request.method 更清晰。

概念解释

  • 类视图实例方法接收 request 与路径参数;未实现的方法返回 405。
  • 类视图便于继承复用公共逻辑(认证、序列化),函数视图则更适合装饰器组合。

原理流程

  1. 继承 HTTPMethodView,按需要实现 get/post/put/delete 等异步方法。
  2. 调用 View.as_view() 得到视图可调用对象,用 add_route 注册到路径。
  3. 请求进来后调度器按方法名选择对应实例方法执行。

代码或图示

from sanic import Sanic
from sanic.views import HTTPMethodView
from sanic.response import json

app = Sanic("demo")

class ItemView(HTTPMethodView):
    async def get(self, request, item_id: int):
        return json({"item": item_id})

    async def post(self, request):
        return json({"created": request.json}, status=201)

app.add_route(ItemView.as_view(), "/items/<item_id:int>")
app.add_route(ItemView.as_view(), "/items")

常见误区

  • 类方法签名漏了 self 或路径参数顺序,调度时会报参数不匹配;路径参数必须与路由模板一致。
  • 以为类视图天然带实例状态隔离:每个请求调度时创建/复用实例的方式受框架实现约束,不要在类属性上存请求级数据,请求数据放 request 上下文或请求级存储。

追问

  • 未实现的方法返回什么?答:405 Method Not Allowed。
  • 类视图怎么注册?答:as_view() 后用 add_route 挂到路径。
  • 公共逻辑放哪里?答:父类方法、中间件或依赖注入,不要依赖类属性存请求状态。

04.7.19.1-009 函数视图和类视图应该怎么选?

一句话结论

函数视图轻量、装饰器直观,适合动作型接口与简单逻辑;类视图按资源聚合方法、便于继承与复用,适合 RESTful 资源控制器。团队约定统一比选哪种更“高级”更重要,混用要保持边界清晰。

概念解释

  • 函数视图:一个函数对应一条路由,认证、日志等用装饰器或中间件叠加。
  • 类视图:一个资源一个类,公共前置逻辑可抽到父类;代价是多一层抽象,小接口显得笨重。

原理流程

  1. 先判断接口是“资源动作”还是“单一动作”。
  2. 资源的增删改查聚合成类视图;独立动作(登录、回调、健康检查)用函数视图。
  3. 跨视图复用通过父类、装饰器或中间件实现,而不是复制粘贴方法体。

代码或图示

# 函数视图:单一动作
@app.post("/login")
async def login(request):
    return json({"token": "..."})

# 类视图:资源聚合
class Resource(HTTPMethodView):
    async def get(self, request, rid): ...
    async def delete(self, request, rid): ...

常见误区

  • 为了“面向对象”把只有一个 GET 的接口也写成类视图,增加阅读成本;反过来,资源接口在函数里堆 if request.method 判断,可读性差。
  • 类视图继承链过深会让调用栈难追;公共逻辑优先用组合(中间件/依赖)而不是多层继承。

追问

  • 认证逻辑在两种视图里分别怎么复用?答:函数用装饰器/中间件,类用父类方法或中间件。
  • 类视图的优势具体是什么?答:同资源方法聚合、便于继承与统一序列化。
  • 什么场景函数视图更合适?答:独立动作、回调、健康检查等单方法接口。

04.7.19.1-010 Sanic 请求中间件和响应中间件如何注册?

一句话结论

请求中间件用 @app.on_request(或 @app.middleware("request"))注册,在视图执行前运行;响应中间件用 @app.on_response(或 @app.middleware("response")),在视图返回后、响应写出前运行。中间件可挂在应用级或蓝图级。

概念解释

  • 请求中间件常用于认证、日志、请求 ID 注入、参数预处理;响应中间件常用于统一加头、压缩、响应包装。
  • 中间件是协程或同步函数,签名接收 request;响应中间件额外接收 response。

原理流程

  1. 请求进入后按注册顺序依次执行请求中间件。
  2. 任一请求中间件返回响应即短路,不再进入视图。
  3. 视图产出响应后,响应中间件按相反或注册顺序(以框架实现为准)加工响应再写出。

代码或图示

import time

@app.on_request
async def add_request_id(request):
    request.ctx.req_id = request.headers.get("X-Request-ID", "-")

@app.on_response
async def add_timing(request, response):
    response.headers["X-Request-ID"] = request.ctx.req_id
    return response

常见误区

  • 响应中间件必须返回响应对象;直接修改后不返回,可能导致响应丢失或类型错误。
  • 中间件里做重 IO(查库、远程调用)会让所有请求都承担这份开销,阻塞型调用还会卡住事件循环;重逻辑应下沉到服务层或用异步客户端。

追问

  • 请求中间件什么时候跑?答:路由匹配后、视图执行前。
  • 响应中间件能改状态码吗?答:可以,通过返回或修改传入的响应对象。
  • 蓝图级中间件作用范围?答:只作用于该蓝图下的路由。

04.7.19.1-011 中间件执行顺序与短路返回有什么规则?

一句话结论

请求中间件按注册先后顺序执行,先注册先跑;响应中间件按注册的反向顺序处理(与多数 Web 框架的洋葱模型一致,具体顺序以当前版本实现为准,待确认:验证点:Sanic 23.x/24.x 响应中间件回环顺序)。请求中间件一旦返回非 None 的响应对象,链条短路,视图不再执行。

概念解释

  • 短路常用于认证失败直接返回 401、限流拒绝直接返回 429,避免继续消耗业务资源。
  • 顺序决定保护范围:认证中间件排在限流之前还是之后,影响被拦截请求的计数与日志口径。

原理流程

  1. 应用级请求中间件先跑,再跑蓝图级请求中间件。
  2. 某层返回响应则立刻中断后续请求中间件与视图。
  3. 响应沿回程链路穿过响应中间件,最后由服务器写出。

代码或图示

@app.on_request
async def auth(request):
    if not request.headers.get("Authorization"):
        return json({"error": "unauthorized"}, status=401)

@app.on_request
async def rate_limit(request):
    # 认证通过后才计入限流
    ...

常见误区

  • 把限流放在认证前面会导致匿名请求也占用限额;把重日志放在最外层又会让被短路的请求缺失鉴权信息。
  • 在请求中间件里 await 一个永不结束的任务,会让链路悬挂;所有中间件调用必须有明确超时。

追问

  • 短路返回后视图还执行吗?答:不执行,响应直接走回程。
  • 应用级和蓝图级中间件谁先跑?答:应用级先于蓝图级。
  • 响应中间件顺序为什么容易记错?答:回程与请求方向相反,按洋葱模型嵌套执行。

04.7.19.1-012 Sanic listener 生命周期钩子有哪些?

一句话结论

listener 监听服务器进程的生命周期节点,常用的有 before_server_start、after_server_start、before_server_stop、after_server_stop,以及主进程级的 main_process_start、main_process_stop。钩子用于建连池、加载缓存、关闭外部资源。

概念解释

  • worker 级钩子在每个 worker 进程内执行;主进程级钩子只在主进程执行,跨进程资源要在 worker 钩子中分别初始化。
  • 钩子是协程,await 异步初始化(数据库连接池、消息队列客户端)放在这里,而不是模块导入时。

原理流程

  1. 主进程启动触发 main_process_start,fork worker。
  2. 每个 worker 事件循环起来后触发 before_server_start,完成连接池等初始化;就绪后 after_server_start。
  3. 关停时先 before_server_stop 停止接新请求,释放资源,再 after_server_stop。

代码或图示

@app.listener("before_server_start")
async def setup_db(app, loop):
    app.ctx.db = await create_pool()

@app.listener("after_server_stop")
async def close_db(app, loop):
    await app.ctx.db.close()

常见误区

  • 在模块顶层 await 建连接池会偏离生命周期,多 worker 下初始化时序不可控;必须放进对应钩子。
  • 把主进程钩子当成每个 worker 都执行:main_process_start 只跑一次,worker 内要复用的资源需在 worker 级钩子重建或从外部存储获取。

追问

  • 连接池应该在哪个钩子建?答:before_server_start,每个 worker 各自建立。
  • main_process_start 会在几个进程跑?答:只在主进程跑一次。
  • 关停释放资源放哪里?答:before_server_stop 或 after_server_stop,按是否还要处理在途请求选择。

04.7.19.1-013 Sanic 信号机制和 listener 是什么关系?

一句话结论

listener 是信号机制的语法糖:Sanic 内部用信号总线在生命周期节点派发事件,@app.listener(节点名) 本质是订阅对应信号。除内置生命周期信号外,也可以用 app.signal(...) 订阅或派发自定义事件。

概念解释

  • 信号解耦了“谁触发事件”和“谁响应事件”:核心流程派发信号,扩展或业务代码订阅处理。
  • 内置信号覆盖启动、停止、worker 退出等阶段;自定义信号用于模块间事件通知。

原理流程

  1. 应用在生命周期节点调用信号总线派发事件。
  2. 已订阅的监听器(含 listener 注册的函数)被依次调用。
  3. 自定义信号由业务代码显式 app.dispatch(...) 派发,订阅者协程被调度执行。

代码或图示

@app.signal("before_server_start")
async def on_start(app, loop):
    ...

# 自定义信号(接口名与参数以当前版本为准,待确认:验证点:自定义信号 dispatch 签名)
@app.signal("order.created")
async def after_order(app, order):
    ...

常见误区

  • 把信号当成同步调用栈:信号订阅者是异步调度的,派发方不能假设订阅逻辑已经执行完再返回。
  • 在信号里做过重的阻塞工作会拖慢启动/关停节点;重任务应异步化或交给后台任务队列。

追问

  • listener 底层是什么?答:订阅内置生命周期信号的便捷装饰器。
  • 自定义信号怎么触发?答:通过信号总线显式派发。
  • 信号订阅者执行是同步等待的吗?答:按异步调度执行,不能当同步调用栈依赖顺序结果。

04.7.19.1-014 sanic-ext 是什么,解决哪些问题?

一句话结论

sanic-ext 是 Sanic 官方扩展包,提供请求校验、依赖注入、序列化与 OpenAPI/Swagger 文档等能力,补齐框架本体偏薄的工程化设施。Sanic 本体保持轻量,校验与文档这类“横切能力”由 sanic-ext 按需启用。

概念解释

  • 它与 sanic 本体分离:安装后通过 Extend(app) 挂载,避免把所有团队都不需要的功能塞进核心。
  • 能力覆盖:参数校验(请求体/查询参数/路径参数)、依赖注入、OpenAPI schema 生成、文档页面挂载。

原理流程

  1. 安装 sanic-ext,在应用初始化时调用 Extend(app)。
  2. 视图上用校验装饰器声明请求/响应模型,扩展在调度前完成解析与校验。
  3. 启动时扫描路由与模型,生成 OpenAPI 文档并挂载文档路由。

代码或图示

from sanic import Sanic
from sanic_ext import Extend

app = Sanic("demo")
Extend(app)

# 文档默认路径与校验装饰器用法见后续题目

常见误区

  • 以为 Sanic 本体内置 Pydantic 式校验:本体只做基础请求解析,类型校验要靠 sanic-ext 或自行接入 Pydantic。
  • 扩展版本要与 Sanic 主版本对齐,跨大版本混用可能出现装饰器签名不兼容;升级时两者一起验证。

追问

  • sanic-ext 是核心依赖吗?答:不是,按需安装挂载。
  • 它补齐了哪些能力?答:校验、DI、序列化、OpenAPI 文档。
  • 不用 sanic-ext 怎么校验?答:手动解析 request.json 后交给 Pydantic/msgspec 等模型校验。

04.7.19.1-015 sanic-ext 的 @validate 如何做请求校验?

一句话结论

@validate 装饰器在视图执行前解析并校验请求体、查询参数或路径参数:把声明的模型绑定到 json、query、args、form、body 等位置,校验通过后把模型实例注入视图;校验失败由框架转换为 400 类错误响应。模型类型支持范围随版本变化,具体以官方文档为准(待确认:验证点:当前 sanic-ext 版本对 Pydantic v1/v2、attrs、dataclass 的支持矩阵)。

概念解释

  • 校验层把“取参数”和“验参数”合并:视图直接拿类型化对象,不再手写 request.json["x"] 与判空。
  • 与 FastAPI 的依赖式校验不同,sanic-ext 走装饰器声明;校验模型既描述输入,也可用于生成 OpenAPI schema。

原理流程

  1. 视图声明 @validate(json=CreateItem, query=PageQuery)。
  2. 请求进入后扩展按位置读取原始数据,交给对应模型解析校验。
  3. 校验通过则把模型作为参数传入视图;失败则抛校验异常,经异常处理器转成错误响应。

代码或图示

from sanic_ext import validate
from pydantic import BaseModel

class CreateItem(BaseModel):
    name: str
    price: float

@app.post("/items")
@validate(json=CreateItem)
async def create_item(request, body: CreateItem):
    return json({"name": body.name, "price": body.price}, status=201)

常见误区

  • 以为 @validate 会自动校验路径参数:路径参数仍需转换器与视图注解配合,查询体校验只覆盖声明的位置。
  • 模型字段与实际请求不符时,错误信息定位依赖校验库的异常格式;生产环境要统一异常处理器,避免把内部校验细节直接抛给前端。

追问

  • 校验失败默认返回什么状态?答:通常映射为 400 类请求错误,具体状态码以扩展实现为准。
  • 校验模型实例怎么进视图?答:按声明位置作为关键字/位置参数注入。
  • 不用扩展能否自己校验?答:可以,手动取 request.json 后交给 Pydantic 模型解析。

04.7.19.1-016 sanic-ext 如何生成 OpenAPI 文档?

一句话结论

sanic-ext 扫描路由、校验模型与响应声明,自动生成 OpenAPI(Swagger)schema,并挂载文档页面(Swagger UI / ReDoc)。文档来源是代码里的路由、模型与装饰器声明,不需要手工维护独立的接口描述文件。

概念解释

  • 文档能力与校验模型共享同一套元数据:模型字段即 schema,减少“代码与文档两张皮”。
  • 可通过扩展配置调整文档标题、版本、路由路径、是否开启外部 CDN 资源等。

原理流程

  1. Extend(app) 挂载后,启动期遍历路由表与装饰器元数据。
  2. 结合请求/响应模型生成 OpenAPI 文档对象。
  3. 文档路由挂载到应用,浏览器访问文档页面渲染并可在线调试。

代码或图示

from sanic_ext import Extend, ExtendConfig

Extend(app, config=ExtendConfig(
    title="Demo API",
    version="1.0.0",
    # 文档路由路径等配置项以当前版本文档为准(待确认:验证点:ExtendConfig 字段名)
))

常见误区

  • 手写 dict 返回值而没有声明响应模型,文档里响应结构会缺失或只能显示泛型对象;想让文档完整要显式声明响应模型。
  • 文档页面依赖前端资源,内网/离线部署要确认静态资源加载方式,不能假设浏览器一定能访问外部 CDN。

追问

  • OpenAPI schema 从哪里来?答:扫描路由与校验模型的元数据自动生成。
  • 文档与代码会脱节吗?答:只要响应模型在代码里声明,schema 随代码更新;裸 dict 返回不会自动出结构。
  • 如何改文档标题版本?答:通过 ExtendConfig 配置传入。

04.7.19.1-017 Sanic 配置如何加载,环境变量优先级怎样?

一句话结论

配置挂在 app.config 对象上,支持字典更新、代码内赋值与环境变量加载;环境变量以 SANIC_ 为前缀覆盖配置项。启动时加载环境与配置文件,运行期配置不应被业务请求随意改写。

概念解释

  • 配置与应用实例绑定,多实例测试时各自隔离,避免全局配置串用。
  • 敏感配置(密钥、数据库地址)从环境变量或受管配置中心注入,不写进代码仓库。

原理流程

  1. 应用实例化时载入默认配置。
  2. 通过 update_config 或环境变量覆盖,环境变量按前缀匹配大写配置键。
  3. 视图与钩子通过 app.config.KEY 读取,运行期只读。

代码或图示

app = Sanic("demo", load_env="SANIC_")
app.update_config({"DEBUG": False, "DB_URL": "postgres://..."})

@app.get("/cfg")
async def cfg(request):
    return json({"debug": app.config.DEBUG})

常见误区

  • 把配置写在模块级全局变量里,多环境(测试/开发/生产)切换时互相污染;应通过工厂与配置注入隔离。
  • 环境变量是字符串,数值、布尔、列表类型需要显式转换;直接拿 "0" 当布尔判断会得到真值。

追问

  • 环境变量前缀默认是什么?答:SANIC_,构造应用时可改。
  • 运行期能改配置吗?答:技术上可写,但生产约定只读,避免请求改写全局行为。
  • 敏感配置放哪里?答:环境变量或配置中心,不入库不入代码。

04.7.19.1-018 Sanic Request 对象有哪些常用属性?

一句话结论

request 携带本次连接的全部输入:request.method、request.path、request.headers、request.args(查询参数 MultiDict)、request.query_args、request.json、request.form、request.files、request.body、request.ip 与 request.ctx。request.ctx 是请求级临时存储,跨中间件与视图传递本次请求的数据。

概念解释

  • args 是解析后的 MultiDict,同名多值用 getlist;json 在 Content-Type 为 JSON 时解析,非法 JSON 会抛解析异常。
  • ctx 生命周期与请求一致,请求结束即销毁,不能跨请求保存状态。

原理流程

  1. 服务器解析报文后构造 Request,挂到当前请求上下文。
  2. 中间件与视图按属性读取输入,需要共享的中间结果写进 request.ctx。
  3. 请求结束后 ctx 随请求对象回收。

代码或图示

@app.get("/search")
async def search(request):
    kw = request.args.get("q", "")
    page = request.args.get("page", "1")
    return json({"q": kw, "page": page, "ip": request.ip})

@app.post("/upload")
async def upload(request):
    f = request.files.get("file")
    return json({"filename": f.name if f else None})

常见误区

  • 直接访问 request.json 而不判空:请求体不是 JSON 或为空时会抛异常,应由异常处理器兜底或先判 None。
  • 把数据挂到应用级全局对象冒充 g:多并发下会串请求;请求级数据一律放 request.ctx。

追问

  • 同名查询参数怎么取全部值?答:用 MultiDict 的 getlist。
  • request.ctx 什么时候销毁?答:本次请求结束后随请求对象回收。
  • 非法 JSON 请求体会怎样?答:解析阶段抛异常,需异常处理器转成 400。

04.7.19.1-019 Sanic 响应如何构造,支持流式响应吗?

一句话结论

响应由 sanic.response 下的辅助函数构造:json()、text()、html()、raw()、redirect(),也可直接返回 HTTPResponse 实例。支持流式响应:用 stream 响应逐块写出,适合大文件下载与分块推送;响应头、状态码通过参数或实例方法设置。

概念解释

  • json() 负责序列化与 Content-Type 设置;返回 dict/list 时框架也会按 JSON 处理(以当前版本约定为准)。
  • 流式响应保持连接逐步写块,避免把整个响应体读进内存。

原理流程

  1. 视图返回响应对象或辅助函数结果。
  2. 响应中间件加工状态码、头与体。
  3. 流式响应由服务器分块写出,普通响应一次性序列化后写出。

代码或图示

from sanic.response import json, stream
import asyncio

@app.get("/report")
async def report(request):
    async def writer(response):
        for i in range(5):
            await response.write(f"line {i}\n")
            await asyncio.sleep(0)
    return stream(writer, content_type="text/plain")

@app.get("/item")
async def item(request):
    return json({"id": 1}, status=201, headers={"X-Trace": "abc"})

常见误区

  • 大文件先 read() 进内存再返回,内存随并发数放大;下载场景应走流式或文件响应。
  • 流式写出过程中客户端断开,服务端写块会收到取消/断连异常,要在生成器里处理清理与日志,不能假设连接一直存活。

追问

  • JSON 响应头由谁设置?答:json() 辅助函数设置 Content-Type: application/json。
  • 流式响应解决什么问题?答:避免大响应体整体进内存,支持逐步产出。
  • 客户端断开后要做什么?答:处理取消异常并释放下游资源。

04.7.19.1-020 Sanic 自有协议实现带来了哪些性能来源?

一句话结论

Sanic 的高性能叙事来自:原生异步单事件循环避免线程切换开销、自有服务器在连接调度上直接可控、配合 uvloop 等高性能事件循环后端降低系统调用成本。但框架版本演进中协议解析组件有调整,当前版本的具体解析实现以官方文档为准(待确认:验证点:当前 Sanic 版本 HTTP 解析器与连接管理组件),面试时不要把早期版本的实现细节当成现代版本事实。

概念解释

  • 性能分三层:事件循环调度、协议解析、业务处理;瓶颈可能在任一层,框架只优化前两层,业务阻塞照样拖垮吞吐。
  • 基准成绩受响应体大小、IO 占比、序列化库影响,单看“QPS 第一”没有意义。

原理流程

  1. 连接与请求由事件循环调度,协程在 IO 等待时让出控制权。
  2. 协议层解析报文并构造请求对象,减少额外线程/进程中转。
  3. 业务协程处理后产出响应,协议层写回连接。

代码或图示

client → own server / event loop → protocol parse → middleware → handler → response
                 ↑ 等待 IO 时调度其他连接,而非阻塞线程

常见误区

  • 以为“用了 Sanic 就快”:同步阻塞调用、慢数据库、大 JSON 序列化都是真实瓶颈,框架帮不上忙。
  • 把早期版本“自写 C 解析器”的说法套到现代版本;协议实现随版本重构,引用前必须核对当前版本文档。

追问

  • 异步框架性能主要赢在哪?答:IO 等待期间调度其他连接,减少线程阻塞与切换成本。
  • 事件循环后端可以换吗?答:可在支持范围内选择 uvloop 等后端,具体可用后端版本相关。
  • 为什么基准 QPS 不能直接对比?答:测试口径、负载类型、序列化与下游环境不同。

04.7.19.1-021 Sanic 与标准 ASGI 的差别是什么?

一句话结论

Sanic 同时提供自有服务器与 ASGI 兼容入口:自有服务器使用 Sanic 自己的启动流程、worker 管理与生命周期信号;ASGI 模式下应用被适配成标准 (scope, receive, send) 调用,可由 uvicorn/hypercorn 托管。标准 ASGI 的价值是跨服务器可移植,Sanic 自有模式则保留框架特有的进程与信号能力。

概念解释

  • ASGI 规定应用是 await app(scope, receive, send) 的可调用对象,服务器只认标准协议;Sanic 适配层把内部请求模型翻译成 ASGI 消息。
  • 自有模式下多 worker、主进程/worker 信号等是 Sanic 服务器特有的编排能力;切到外部 ASGI 服务器后,进程编排由服务器负责。

原理流程

  1. 自有模式:sanic CLI 或 app.run 启动主进程,fork worker,内部信号驱动生命周期。
  2. ASGI 模式:暴露标准 ASGI 应用,外部服务器接管监听、循环与 worker 进程。
  3. 业务视图代码不变,差别主要在启动编排与生命周期钩子由谁触发。

代码或图示

# 自有服务器
sanic server:app --workers 4

# ASGI 服务器托管(应用对象可被 ASGI 调用的前提以当前版本适配为准)
uvicorn server:app --workers 4

常见误区

  • 以为 ASGI 适配后所有 Sanic 特有能力都原样可用:部分进程级编排、主进程信号在外部服务器模型下没有对应概念,行为可能不同(待确认:验证点:ASGI 模式下各 listener 信号的触发情况)。
  • 反过来认为 Sanic 不能进标准 ASGI 生态:现代版本已提供兼容入口,只是特性覆盖面要逐个核对。

追问

  • ASGI 应用长什么样?答:await app(scope, receive, send) 的标准可调用对象。
  • 自有模式独有的是什么?答:主/worker 进程编排与框架自带信号体系。
  • 切 ASGI 服务器要改业务代码吗?答:视图基本不改,主要调整启动方式与进程编排。

04.7.19.1-022 Sanic 异常体系与全局异常处理器怎么用?

一句话结论

Sanic 内置 SanicException 及 NotFound、BadRequest、Unauthorized 等常用子类,视图里直接 raise;用 @app.exception(异常类型) 注册处理器,把异常转换成统一格式的错误响应。未被捕获的异常由默认处理器转成 500,生产环境应兜底统一响应结构与日志记录。

概念解释

  • 异常携带状态码、message 与上下文属性;处理器签名接收 request 与 exception,返回响应对象。
  • 业务异常应继承框架异常并声明状态码,避免把 Python 内部异常直接暴露给客户端。

原理流程

  1. 视图或中间件抛出框架异常或业务异常。
  2. 调度器按异常类型查找已注册处理器。
  3. 处理器生成错误响应,经响应中间件写出;未匹配则走默认 500 处理器。

代码或图示

from sanic import Sanic, json
from sanic.exceptions import SanicException, NotFound

app = Sanic("demo")

@app.exception(NotFound)
async def not_found(request, exception):
    return json({"error": "not_found"}, status=404)

@app.get("/items/<uid:int>")
async def item(request, uid):
    if uid < 0:
        raise SanicException("invalid id", status_code=400)
    return json({"uid": uid})

常见误区

  • 处理器里再抛异常会进入递归或被默认处理器接管;兜底处理器必须保证自身不再抛未捕获异常。
  • 把数据库异常、第三方调用异常原样返回给前端,会泄露内部信息;应在边界层翻译为对外错误码。

追问

  • 业务自定义异常怎么带状态码?答:继承 SanicException 并传 status_code。
  • 未注册处理器的异常返回什么?答:走默认处理器,通常为 500。
  • 异常处理器返回什么?答:一个响应对象。

04.7.19.1-023 Sanic 静态文件服务如何配置?

一句话结论

用 app.static(uri, file_or_directory) 把 URL 前缀映射到本地目录或单个文件,框架负责读取与响应;目录映射支持索引文件与 MIME 判断。生产环境静态资源通常交给 Nginx/CDN,框架内静态路由主要用于开发、后台或小体量场景。

概念解释

  • 静态路由与 API 路由分开注册,避免业务路径被静态规则截胡。
  • 文件读取在大文件场景同样要注意内存与并发,必要时用文件响应或外置静态服务器。

原理流程

  1. 启动期注册静态映射:URL 前缀到文件系统路径。
  2. 请求匹配静态前缀后,框架定位文件并按 MIME 返回。
  3. 文件不存在返回 404,可由异常处理器统一包装。

代码或图示

app.static("/static", "./assets", name="static_assets")

# 单个文件映射
app.static("/favicon.ico", "./assets/favicon.ico")

常见误区

  • 静态目录路径相对运行时工作目录解析,部署目录变化会导致文件找不到;启动时校验目录存在性更稳妥。
  • 把用户上传文件放到静态目录直接对外暴露,等于开放任意文件访问风险;上传文件要做类型校验、隔离存储与访问鉴权。

追问

  • 生产静态资源最优解是什么?答:Nginx/CDN 直接服务,不经过应用进程。
  • 静态目录路径按什么解析?答:按进程工作目录与配置路径组合,部署时要固定。
  • 静态文件 404 能统一处理吗?答:能,走全局 NotFound 处理器。

04.7.19.1-024 Sanic 的并发模型是怎样的,多 worker 如何工作?

一句话结论

Sanic 单 worker 内部是一个 asyncio 事件循环,所有连接由协程在循环上调度;多 worker 由主进程 prefork 出多个子进程,每个子进程独立跑一个事件循环。并发容量 = worker 数 × 单循环协程承载能力,进程间不共享内存。

概念解释

  • 异步模型下一个 worker 就能承载大量 IO 等待中的连接;worker 数主要按 CPU 核数与 CPU 密集程度决定,而不是像同步框架那样按阻塞连接数堆进程。
  • 主进程负责监听与分发(具体 socket 继承/绑定方式以实现为准),worker 处理请求。

原理流程

  1. 主进程解析配置,绑定监听端口。
  2. fork 出 N 个 worker,各自初始化应用、连接池与事件循环。
  3. 请求由内核在进程间分发,worker 内协程处理,阻塞在 IO 时让出循环。

代码或图示

sanic server:app --workers 4
master ├─ worker1: event loop + coroutines
       ├─ worker2: event loop + coroutines
       ├─ worker3: event loop + coroutines
       └─ worker4: event loop + coroutines

常见误区

  • 多开 worker 不能解决事件循环内阻塞:单个协程卡住会拖慢该 worker 上所有连接,加 worker 只是分摊 CPU。
  • 把内存缓存当共享状态用:各 worker 内存独立,本地缓存不一致;跨进程共享必须用 Redis 等外部存储。

追问

  • 异步 worker 数按什么定?答:参考 CPU 核数,结合压测与 CPU 占用调整。
  • 一个 worker 能同时处理多少请求?答:取决于 IO 并发与循环延迟,协程数量没有固定上限,受内存与下游限制。
  • 进程间怎么共享状态?答:走外部存储,不靠内存变量。

04.7.19.1-025 在 Sanic 里遇到同步阻塞调用怎么办?

一句话结论

视图里出现同步阻塞(CPU 密集计算、同步驱动、同步 HTTP 客户端、本地大 IO)会卡住整个事件循环;正确做法是替换为异步库,或把阻塞函数丢到线程池/进程池执行(loop.run_in_executor 或异步线程工具),并控制池大小与超时。

概念解释

  • 事件循环是单线程抢占式协作调度:协程不主动 await 让出,其他连接就无法被调度。
  • 线程池适合 IO 阻塞,进程池适合 CPU 密集;线程池过大反而增加 GIL 竞争与上下文切换。

原理流程

  1. 识别阻塞点:同步驱动调用、time.sleep、同步 HTTP、重计算。
  2. 优先换成对应异步客户端/驱动。
  3. 无法替换的部分提交执行器,await 结果,并设置超时与熔断。

代码或图示

import asyncio
from anyio import to_thread

@app.get("/compute")
async def compute(request):
    # 阻塞计算放到线程/进程执行器,避免卡住循环
    result = await to_thread.run_sync(heavy_cpu_task, request.args)
    return json({"result": result})

常见误区

  • 用 asyncio.sleep 之外的同步 time.sleep 模拟等待,直接冻结循环;所有等待必须是异步原语。
  • 给阻塞任务开无界线程池:下游变慢时线程数暴涨,内存与连接同时失控;池大小要有上限并监控排队。

追问

  • 为什么阻塞调用在异步框架里危害更大?答:单循环被卡住会影响该 worker 全部连接。
  • CPU 密集放线程池就够了吗?答:GIL 下 CPU 密集建议进程池,线程池只缓解 IO 阻塞。
  • 替换不了的同步库怎么接入?答:执行器隔离 + 超时 + 限流。

04.7.19.1-026 Sanic 如何做接口测试?

一句话结论

官方测试工具包提供测试客户端(sanic-testing),基于内部请求适配器直接调用应用而不监听真实端口,支持 async 测试用例,可断言状态码、响应 JSON、头与异常。测试时每个用例独立应用/上下文,避免请求状态串用。

概念解释

  • 测试客户端复用应用内部调度链路,覆盖中间件、路由与视图,比起真实服务器快。
  • 异步测试配合 pytest-asyncio 或框架自带测试运行器编写协程用例(具体集成方式以当前版本为准)。

原理流程

  1. 构造应用实例并挂载测试客户端。
  2. 客户端发起 GET/POST 等请求,应用内部走完中间件到视图链路。
  3. 断言响应状态、体与头;用例结束清理上下文与外部资源。

代码或图示

from sanic_testing.testing import SanicTestClient

client = SanicTestClient(app)

def test_hello():
    request, response = client.get("/hello")
    assert response.status == 200
    assert response.json["msg"] == "ok"

常见误区

  • 测试里复用带脏状态的应用实例:前一个用例写入的缓存/会话影响后一个;每个用例重建应用或显式清理。
  • 只测 happy path:认证失败、参数非法、下游超时等分支同样要有覆盖,断言异常处理器行为。

追问

  • 测试客户端需要监听端口吗?答:不需要,走内部适配器调用。
  • 异步用例怎么跑?答:配合异步测试运行器执行协程用例。
  • 应用状态怎么隔离?答:用例间重建应用或清理请求级/应用级状态。

04.7.19.1-027 Sanic 与 FastAPI/Starlette 横向对比怎么说?

一句话结论

三者都是异步栈:FastAPI 构建在 Starlette 之上,强依赖 Pydantic 做校验与 OpenAPI,生态与文档热度最高;Starlette 是底层 ASGI 工具集,轻量灵活;Sanic 自带服务器与协议层,路由/蓝图风格接近 Flask,校验与文档靠 sanic-ext 补齐,生态规模小于 FastAPI。

概念解释

  • 选型差异不只是性能:FastAPI 的类型驱动开发与 Pydantic 生态是主要吸引力;Sanic 更接近 Flask 心智模型,适合从 Flask 思路迁移又要异步能力的团队。
  • 底层服务器都可换成 uvicorn/hypercorn,框架本身的性能差距通常小于业务代码与下游瓶颈。

原理流程

  1. 按需求拆解:校验模型强度、文档要求、团队熟悉的 API 风格、生态包 availability。
  2. 对比异步链路完整性(数据库驱动、客户端、消息队列客户端是否都有异步实现)。
  3. 用贴近真实业务的压测口径验证吞吐与延迟,而不是照搬第三方基准。

代码或图示

FastAPI  = Starlette(ASGI 工具集) + Pydantic 校验 + 依赖注入 + OpenAPI
Starlette = 底层 ASGI 路由/中间件/工具,不绑定校验模型
Sanic    = 自有服务器 + 类 Flask 路由风格 + sanic-ext 校验/文档

常见误区

  • 把 GitHub 星数等同于工程适用性:生态小不代表不能用,但遇到冷门问题可查资料少,需要团队自己排障。
  • 只看框架基准选 FastAPI 或 Sanic;业务里若大量依赖同步生态,异步框架反而要额外做隔离改造。

追问

  • FastAPI 底层基于什么?答:Starlette,校验基于 Pydantic。
  • Sanic 的 API 风格接近谁?答:接近 Flask,装饰器路由加蓝图。
  • 框架间性能差距一定很大吗?答:通常小于业务与下游瓶颈,需实测。

04.7.19.1-028 Sanic 有哪些选型误区与生态短板?

一句话结论

Sanic 适合想要异步、类 Flask 风格、可控服务器的团队;短板是第三方生态与资料规模小于 FastAPI/Flask,部分工程化设施要靠 sanic-ext 或自行拼装,异步数据库/客户端链路需要团队自己确认成熟度。团队不熟悉异步、业务以同步 ORM 为主时,硬上 Sanic 收益有限。

概念解释

  • 选型要同时看框架与周边:异步 MySQL/Redis/消息队列客户端、认证/权限包、定时任务、监控集成是否齐备。
  • 招人与维护成本也是生态的一部分:团队现有经验能直接复用多少,决定落地速度。

原理流程

  1. 列出业务用到的中间件与库,逐个确认异步实现成熟度。
  2. 评估团队异步排障能力(事件循环阻塞、任务泄漏、取消处理)。
  3. 做小范围 PoC 验证关键链路,再决定是否全量采用。

代码或图示

选型核对清单:异步驱动可用性 / 校验与文档方案 / 认证权限方案 /
测试与监控集成 / 团队异步经验 / 版本维护活跃度

常见误区

  • 因为“性能排名高”选 Sanic,却没盘点周边库的异步支持,最后在阻塞隔离上反复救火。
  • 把 Flask 扩展直接搬过来用:绑定 WSGI 上下文或同步会话的扩展在 Sanic 里不能直接工作,需要找对应替代。

追问

  • Sanic 生态最大短板是什么?答:包与资料规模小于主流框架,冷门问题自助排障成本高。
  • 同步 ORM 为主的业务适合直接上 Sanic 吗?答:要先确认异步迁移代价,否则收益有限。
  • 选型 PoC 重点验什么?答:关键异步链路、阻塞隔离与周边库成熟度。

04.7.19.1-029 Tornado 是什么定位,和普通 Web 框架有何不同?

一句话结论

Tornado 是一个“Web 框架 + 异步网络库”的组合:既提供路由、处理器、模板等框架能力,也自带事件循环与非阻塞网络基础设施,历史上专为长轮询、WebSocket、高并发长连接场景设计。版本基线按 Tornado 6.x 讨论,内部已与 asyncio 事件循环融合。

概念解释

  • 与 Flask/Django 这类 WSGI 框架不同,Tornado 不依赖外部 WSGI 服务器,自身就是可监听端口的异步服务。
  • 它的网络库部分(IOLoop、AsyncHTTPClient、WebSocketHandler)可以脱离 Web 框架单独用于异步网络程序。

原理流程

  1. 应用把路由元组交给 Application,服务器绑定端口。
  2. IOLoop 在单线程上多路复用监听所有连接。
  3. 请求分发到 RequestHandler,协程在 IO 等待时让出循环,支撑大量长连接。

代码或图示

import tornado.ioloop
import tornado.web

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write("hello")

app = tornado.web.Application([(r"/", MainHandler)])
app.listen(8888)
tornado.ioloop.IOLoop.current().start()

常见误区

  • 把 Tornado 当成“另一个 Flask”:它不是 WSGI 应用,不能挂到 gunicorn sync worker 下按同步模型运行。
  • 以为 Tornado 只做 Web:其异步网络组件可用于编写长连接推送、爬虫客户端等非 Web 程序。

追问

  • Tornado 是 WSGI 框架吗?答:不是,它是自有异步服务器模型。
  • Tornado 历史上解决什么问题?答:高并发长连接、长轮询与 WebSocket 实时推送。
  • Tornado 6.x 事件循环基于什么?答:基于 asyncio 事件循环封装。

04.7.19.1-030 最小 Tornado 应用如何组织,路由表长什么样?

一句话结论

最小应用是定义继承 RequestHandler 的处理器类,在 Application 构造时传入 (正则路径, 处理器类) 元组列表,app.listen(port) 后启动 IOLoop。路由用正则匹配,路径参数通过正则分组在 get/post 等方法签名里接收。

概念解释

  • 路由表是正则到处理器类的映射,不像装饰器那样分散注册;配置集中在 Application 初始化处。
  • 元组第三项可传参数字典,在处理器 initialize 里接收。

原理流程

  1. 编写处理器类,实现对应 HTTP 方法。
  2. 组装路由元组列表与 settings,构造 Application。
  3. listen 启动服务器,IOLoop 开始轮询,请求按正则命中处理器。

代码或图示

class HelloHandler(tornado.web.RequestHandler):
    def get(self, name):
        self.write({"hello": name})

app = tornado.web.Application([
    (r"/hello/(?P<name>\w+)", HelloHandler),
])
app.listen(8888)
tornado.ioloop.IOLoop.current().start()

常见误区

  • 正则分组名与方法参数名不一致会导致调用时报参数错误;分组位置/命名要和 get 签名对齐。
  • 路由顺序即匹配优先级:宽泛正则排在前面会截胡后面的具体路由,注册顺序要从具体到宽泛。

追问

  • 路由用什么匹配?答:正则表达式,分组捕获路径参数。
  • 路由参数怎么进处理器?答:作为 get/post 方法的命名/位置参数。
  • 路由表在哪里集中配置?答:Application 构造参数的 handlers 列表。

04.7.19.1-031 Tornado IOLoop 承担什么职责?

一句话结论

IOLoop 是 Tornado 的核心事件循环:封装底层多路复用(epoll/kqueue),管理文件事件、定时器、回调与协程调度,在单线程上驱动所有网络连接。应用启动后调用 IOLoop.current().start() 进入循环,循环不退出则进程持续服务。

概念解释

  • IOLoop 把“连接可读/可写/超时/回调”统一成事件,按就绪状态调度对应的回调或协程。
  • 单线程模型避免多线程锁竞争,但要求所有回调不得长时间阻塞,否则整个循环停顿。

原理流程

  1. 服务器把监听 socket 与连接 socket 注册到 IOLoop。
  2. 循环等待事件就绪,回调对应的读写处理函数。
  3. 协程在 await/yield 等待时挂起,事件就绪后恢复执行。

代码或图示

import tornado.ioloop

loop = tornado.ioloop.IOLoop.current()
loop.add_timeout(loop.time() + 1, lambda: print("tick"))
loop.start()

常见误区

  • 在回调里做同步阻塞(同步驱动、重计算)会卡住 IOLoop,所有连接一起延迟;阻塞工作必须走执行器或异步客户端。
  • 手动 IOLoop() 创建多个循环:一个进程通常只应有一个当前循环,混用循环实例会导致回调调度不到。

追问

  • IOLoop 封装了什么系统机制?答:epoll/kqueue 等多路复用,加定时器与回调调度。
  • 循环里能跑阻塞任务吗?答:不能直接跑,要交执行器或换异步实现。
  • IOLoop.current() 返回什么?答:当前线程绑定的事件循环实例。

04.7.19.1-032 Tornado IOLoop 与 asyncio 事件循环如何融合?

一句话结论

Tornado 5.0 起 IOLoop 直接包装 asyncio 事件循环:IOLoop.current() 拿到的是 asyncio 循环的 Tornado 适配层,Tornado 的 Future、协程与标准 asyncio 原语可以互通。现代 Tornado 代码直接写 async def + await,不再需要 gen.coroutine 包装。

概念解释

  • 融合后,asyncio.gather、asyncio.sleep、标准异步驱动都能在 Tornado 应用里使用;Tornado 自身的异步客户端也返回兼容 awaitable 的 Future。
  • 老版本基于自研循环的历史包袱已基本移除,但存量老代码里仍可见 gen 写法。

原理流程

  1. 进程启动时获取/创建 asyncio 事件循环,Tornado IOLoop 在其之上提供兼容 API。
  2. 处理器协程作为任务提交到该循环调度。
  3. Tornado Future 与 asyncio Future 通过适配层互相 await。

代码或图示

import asyncio
import tornado.web

class SleepHandler(tornado.web.RequestHandler):
    async def get(self):
        await asyncio.sleep(0.1)
        self.write({"ok": True})

常见误区

  • 在 Tornado 里又另起一个独立 asyncio 循环并跨循环提交任务,会出现“任务不执行”的诡异问题;一个进程内统一使用当前循环。
  • 以为 Tornado 6 还要求所有协程必须用 @gen.coroutine;新代码直接 async/await,gen 主要用于兼容旧代码。

追问

  • Tornado 6 的 IOLoop 底层是什么?答:asyncio 事件循环的适配封装。
  • asyncio 原语能在 Tornado 里用吗?答:可以,Future 与协程互通。
  • 一个进程能跑多个事件循环吗?答:服务场景应保持单一当前循环,跨循环任务需要显式调度。

04.7.19.1-033 RequestHandler 的生命周期有哪些阶段?

一句话结论

一个请求在处理器内经历 initialize(初始化路由参数)→ prepare(请求前统一处理)→ 对应 HTTP 方法(get/post/…)→ on_finish(请求结束后清理)。异常处理由 write_error 兜底,响应在 finish 后不再允许写入。

概念解释

  • initialize 接收路由元组第三项的参数,按请求调用;prepare 适合做鉴权、解析公共头。
  • on_finish 常用于日志、埋点、释放请求级资源,此时响应已发出,不能再改响应体。

原理流程

  1. 路由命中处理器类,实例化并调用 initialize(**kwargs)。
  2. 调用 prepare(),再按方法分发到 get/post/...。
  3. 响应 finish 后调用 on_finish;异常进入 write_error。

代码或图示

class Base(tornado.web.RequestHandler):
    def initialize(self, service=None):
        self.service = service

    def prepare(self):
        self.start = self.request.request_time()

    def on_finish(self):
        cost = self.request.request_time() - self.start
        # 记录请求耗时,响应已发出,不能再 write

常见误区

  • 在 on_finish 里调用 write/finish 会报错:响应已经结束,这里只能做收尾与日志。
  • 把重资源在 initialize 里新建、却不在 on_finish 释放:长连接高并发下资源泄漏,要成对管理。

追问

  • initialize 的参数来自哪里?答:路由元组第三项的参数字典。
  • 鉴权逻辑放哪个阶段?答:通常放 prepare 或方法基类里统一拦截。
  • on_finish 还能改响应吗?答:不能,只能收尾。

04.7.19.1-034 如何读取请求参数,查询串与表单参数有什么区别?

一句话结论

处理器用 self.get_argument(name) 同时从查询串和表单体取值,self.get_arguments(name) 取多值;要区分来源用 get_query_argument/get_query_arguments 与 get_body_argument/get_body_arguments。原始参数在 self.request.arguments(合并)、query_arguments、body_arguments 里。

概念解释

  • get_argument 合并 query 与 body,同名时取值规则受实现约束;需要明确来源时不要用合并接口。
  • 参数默认值、是否去空白(strip)是显式参数;缺失且无默认值抛 MissingArgumentError(400)。

原理流程

  1. 服务器解析 URL query 与请求体,存入 request 的参数字典。
  2. 处理器按方法读取对应来源,做去空白与默认值处理。
  3. 校验不通过抛参数异常,由错误处理器转成 400。

代码或图示

class SearchHandler(tornado.web.RequestHandler):
    async def get(self):
        kw = self.get_argument("q", "")
        tags = self.get_arguments("tag")
        page = int(self.get_query_argument("page", "1"))
        self.write({"q": kw, "tags": tags, "page": page})

常见误区

  • 把查询参数和表单参数混在一个接口里靠 get_argument 取值,来源不清导致越权或误解析;复杂请求体应解析 JSON 并自行校验。
  • 多值参数用 get_argument 只拿到第一个,漏数据;需要列表必须用 get_arguments。

追问

  • 同时取 query 和 body 用哪个接口?答:get_argument/get_arguments 合并取值。
  • 只要表单体参数用哪个?答:get_body_argument/get_body_arguments。
  • 缺失参数默认行为?答:无默认值时抛参数缺失异常,映射 400。

04.7.19.1-035 响应输出、状态码与重定向怎么写?

一句话结论

self.write(chunk) 写响应片段,self.finish(chunk=None) 结束响应;self.set_status(code, reason=None) 设状态码,self.set_header/add_header 设头,self.redirect(url, status=...) 做跳转。JSON 直接传 dict/list 给 write 会被序列化(以当前版本约定为准)。

概念解释

  • write 可多次调用分块写,finish 标志响应完成;之后再写会报错。
  • 重定向状态码默认 302,永久跳转显式传对应状态码。

原理流程

  1. 处理器方法内组织数据,调用 write 输出片段。
  2. 需要时设置状态码与响应头。
  3. finish 提交响应,触发 on_finish。

代码或图示

class DemoHandler(tornado.web.RequestHandler):
    def get(self):
        self.set_status(201)
        self.set_header("X-Req-Id", "abc")
        self.write({"ok": True})
        self.finish()

    def old(self):
        self.redirect("/new", status=301)

常见误区

  • 多次 write 拼接大响应却没考虑分块编码与内存;流式场景要配合异步写出。
  • finish 之后继续写头或体触发“finished 后写入”异常;控制好收尾时机。

追问

  • write 能调用几次?答:可以多次分块写,finish 后停止。
  • 永久重定向状态码是多少?答:301,临时跳转默认 302。
  • JSON 怎么返回?答:dict/list 传给 write 由框架序列化。

04.7.19.1-036 gen.coroutine 机制是什么,和旧式回调怎么对比?

一句话结论

gen.coroutine 是 Tornado 早期的协程实现:装饰器把生成器函数变成返回 Future 的协程,函数内 yield 一个 Future,事件循环在 Future 完成后恢复生成器并带回结果。它解决了旧式回调嵌套(callback hell),但写法比 async/await 啰嗦,现代代码应优先 async/await。

概念解释

  • yield 等待的对象可以是 Future、协程或 gen 提供的工具(gen.sleep、gen.multi)。
  • 旧式回调把下一步逻辑作为参数传入,异步链路越深嵌套越多;yield 让流程写成顺序代码。

原理流程

  1. @gen.coroutine 包装生成器,调用后立即返回 Future。
  2. 生成器 yield Future,控制权交还 IOLoop。
  3. Future 完成后循环恢复生成器,把结果作为 yield 返回值继续执行。

代码或图示

from tornado import gen

class LegacyHandler(tornado.web.RequestHandler):
    @gen.coroutine
    def get(self):
        result = yield async_client.fetch(url)
        self.write({"status": result.code})

常见误区

  • 在 gen.coroutine 函数里漏写 yield:异步调用 fire-and-forget,结果与异常都接不住。
  • 把 gen.coroutine 当 async/await 混用直觉写:异常通过 Future 传播,未 yield 的任务异常不会进当前调用栈。

追问

  • gen.coroutine 返回什么?答:一个 Future,可被 yield 或 await。
  • yield 后面能接什么?答:Future、协程或 gen 工具对象。
  • 为什么现代代码不再推荐它?答:async/await 语法更标准,与 asyncio 生态互通更好。

04.7.19.1-037 Tornado 协程是如何从 gen.coroutine 演进到 async/await 的?

一句话结论

演进路径是:旧式回调 → @gen.coroutine + yield Future → async/await 原生协程。Tornado 4.x 引入对原生协程的初步支持,5.0 起 IOLoop 基于 asyncio,6.x 全面以 async/await 为主流写法;gen.coroutine 保留为兼容层,新代码不应再新增。

概念解释

  • 原生协程由 Python 解释器直接支持,不依赖生成器装饰器包装,与 asyncio 生态无缝互通。
  • 演进的驱动力是标准语言层面协程成熟,框架不再需要自造协程调度方言。

原理流程

  1. 早期:回调函数作为参数传递,链路嵌套。
  2. gen 时代:生成器 yield Future,框架驱动恢复。
  3. 现代:async def 声明协程,await 挂起,交给 asyncio 循环调度。

代码或图示

# 旧:gen.coroutine
@gen.coroutine
def old(self):
    r = yield client.fetch(url)

# 新:async/await
async def new(self):
    r = await client.fetch(url)

常见误区

  • 把老代码里的 yield 机械替换成 await 就完事:gen.multi、gen.Task 等工具在原生协程里有对应 asyncio 写法,需要逐个替换。
  • 新代码继续套 @gen.coroutine:多一层包装,异常与任务语义反而绕弯。

追问

  • Tornado 哪个版本起基于 asyncio 循环?答:5.0 起 IOLoop 包装 asyncio 事件循环。
  • 原生协程和 gen 协程能互相等待吗?答:可以,Future 兼容 awaitable,混用可互通。
  • 存量 gen 代码要一次性重写吗?答:不必,可按模块逐步迁移到 async/await。

04.7.19.1-038 gen.coroutine 与 async/await 混用有哪些注意点?

一句话结论

两者可以互相 await/yield,因为底层 Future 兼容;但要注意异常传播路径、任务取消与未等待任务的清理。混用期间统一异常处理口径,避免 gen 层吞异常、async 层漏捕获。

概念解释

  • gen.coroutine 函数返回的 Future 可被 await;async 协程也可被 yield。
  • 混用最容易出问题的是“忘记等待”:未持有引用的后台任务异常不会冒泡到请求处理器。

原理流程

  1. 跨风格调用时,调用方按自己的风格 await 或 yield 对方返回的 awaitable。
  2. 异常沿 Future 链传播,未捕获则进入循环异常回调。
  3. 后台任务要保留引用并在关停时取消,防止任务泄漏。

代码或图示

class MixHandler(tornado.web.RequestHandler):
    async def get(self):
        # await 一个 gen 风格函数返回的 Future
        result = await legacy_fetch(url)
        self.write({"result": result})

常见误区

  • 在 async 处理器里调用 gen 函数却不 await,返回的 Future 被丢弃,异常静默丢失。
  • 混用期间两套超时/取消写法并存:gen.with_timeout 与 asyncio.wait_for 语义要统一,避免一处超时不生效。

追问

  • gen 函数返回值能被 await 吗?答:能,其 Future 兼容 awaitable。
  • 未等待的后台任务异常去哪了?答:不会冒泡到当前处理器,需单独收集处理。
  • 混用迁移先改哪一层?答:先改边界处理器为 async/await,内部工具逐步替换。

04.7.19.1-039 AsyncHTTPClient 如何做非阻塞外部调用?

一句话结论

AsyncHTTPClient 是 Tornado 自带的非阻塞 HTTP 客户端,fetch() 返回 Future,处理器 await/yield 等待结果,等待期间 IOLoop 可处理其他连接。它是 Tornado 异步链路的关键一环,避免同步 requests 阻塞循环。

概念解释

  • 客户端底层复用连接与事件循环,并发发起多个请求时用 asyncio.gather 或 gen.multi 汇总。
  • 可配置请求超时、默认头、认证与代理;具体配置项以当前版本文档为准。

原理流程

  1. 创建客户端实例(按需复用,不要每请求新建)。
  2. fetch 发起请求并返回 Future,协程挂起等待。
  3. 响应就绪后 Future 完成,取回 HTTPResponse(状态码、头、体)。

代码或图示

from tornado.httpclient import AsyncHTTPClient

class ProxyHandler(tornado.web.RequestHandler):
    async def get(self):
        client = AsyncHTTPClient()
        resp = await client.fetch("https://example.com/api", request_timeout=3)
        self.write({"status": resp.code, "body": resp.body[:100]})

常见误区

  • 每请求新建客户端导致连接无法复用,TIME_WAIT 堆积;客户端应在应用级复用。
  • 不设超时:下游慢响应会长时间占住连接与协程,级联拖垮服务;必须配置超时与重试。

追问

  • 为什么不能用同步 requests?答:同步调用阻塞 IOLoop,影响该 worker 全部连接。
  • 多个外部请求怎么并发?答:用 asyncio.gather 等并发原语汇总 Future。
  • 客户端实例要复用吗?答:要,复用以利用连接池。

04.7.19.1-040 Application 的 settings 配置项有哪些常用的?

一句话结论

Application(handlers, **settings) 的常用配置包括 debug、cookie_secret、template_path、static_path、xsrf_cookies、autoreload 等。settings 在应用初始化时固化,处理器通过 self.settings 或路由传入的 kwargs 读取。

概念解释

  • debug=True 开启自动重载与详细错误页,仅开发使用;生产关闭。
  • cookie_secret 是签名安全 cookie 的密钥,xsrf_cookies 开启跨站请求伪造保护。

原理流程

  1. 构造 Application 时传入路由表与 settings。
  2. 框架按 settings 初始化模板/静态路径、安全 Cookie 与调试行为。
  3. 处理器运行期读取配置,敏感值从环境变量注入。

代码或图示

app = tornado.web.Application(
    handlers,
    debug=False,
    cookie_secret=os.environ["COOKIE_SECRET"],
    template_path="./templates",
    static_path="./static",
    xsrf_cookies=True,
)

常见误区

  • 把 debug=True 带进生产:自动重载监视文件、暴露调试信息,既不稳定也不安全。
  • cookie_secret 硬编码进仓库:密钥泄露后安全 Cookie 可被伪造;必须走环境变量/配置中心。

追问

  • debug 控制什么?答:自动重载、调试页面与错误详情展示。
  • 安全 Cookie 依赖哪个配置?答:cookie_secret 签名密钥。
  • 处理器怎么读 settings?答:self.settings 或路由 kwargs 注入。

04.7.19.1-041 HTTPServer 与 listen/bind/start 是什么关系?

一句话结论

app.listen(port) 是便捷方法:内部创建 HTTPServer 并绑定端口、单进程服务;需要多进程或更细控制时,手动构造 HTTPServer(app),先 bind(port) 再 start(num_processes)。listen 封装了单进程常用路径,bind/start 暴露进程控制。

概念解释

  • bind 只绑定 socket 不 fork;start(n) 才按进程数拉起服务。
  • 服务器持有应用引用,请求到达后交给 Application 分发。

原理流程

  1. 方式一:app.listen(port) 创建服务器并监听,随后启动 IOLoop。
  2. 方式二:HTTPServer(app).bind(port) 绑定端口,server.start(N) 拉起进程。
  3. IOLoop 启动后开始接受连接。

代码或图示

from tornado.httpserver import HTTPServer

server = HTTPServer(app)
server.bind(8888)
server.start(num_processes=1)
tornado.ioloop.IOLoop.current().start()

常见误区

  • 多进程场景先 listen 再 start,绑定与 fork 时机错乱;多进程必须走 bind 后 start(n) 的路径。
  • 在 IOLoop 已经启动后再 bind/start,socket 监听与循环时序不符;启动顺序要先服务器后循环。

追问

  • app.listen 内部做了什么?答:创建 HTTPServer 并绑定监听,单进程使用。
  • 多进程用哪组 API?答:bind 后 start(num_processes=N)。
  • 服务器和应用是什么关系?答:服务器持有应用,负责连接与协议,应用负责分发。

04.7.19.1-042 Tornado 多进程 fork 模型是怎样工作的?

一句话结论

server.start(num_processes=N) 在 POSIX 上按进程数 fork 出多个子进程,共享已绑定的监听 socket,每个子进程独立跑一个 IOLoop;num_processes=0 按 CPU 核数取值。fork 必须在 IOLoop 启动前完成,且各进程内存独立。

概念解释

  • 与 prefork 模型类似:主进程绑定端口后 fork,子进程继承监听 socket,内核在进程间分发连接。
  • fork 之后不能再在主进程做依赖单进程状态的初始化;共享状态靠外部存储。

原理流程

  1. bind 完成监听 socket 创建。
  2. start(N) 调用 fork,生成 N 个子进程。
  3. 各子进程启动自己的 IOLoop 处理连接,进程间不共享内存。

代码或图示

server.bind(8888)
server.start(num_processes=0)  # 0 = CPU 核数
tornado.ioloop.IOLoop.current().start()

常见误区

  • 在 fork 之前创建了数据库连接池/线程池,子进程继承描述符导致连接共享错乱;重资源应在 fork 后的子进程内初始化。
  • 在 Windows 上依赖该 fork 多进程模型:fork 语义在 Windows 支持有限,跨平台部署要另行确认(待确认:验证点:当前版本 Windows 下多进程启动行为)。

追问

  • 子进程共享监听 socket 吗?答:继承自父进程的同一监听 socket,内核分发连接。
  • 多 worker 内存共享吗?答:不共享,fork 后各自独立。
  • fork 时机有什么要求?答:必须在 IOLoop 启动前完成。

04.7.19.1-043 Tornado 的 WebSocket 支持怎么实现?

一句话结论

继承 tornado.websocket.WebSocketHandler,实现 open()(连接建立)、on_message(message)(收到消息)、on_close()(连接关闭),用 write_message() 主动推送。Tornado 自诞生起就把长连接作为一等公民,WebSocket 是其传统优势场景。

概念解释

  • WebSocket 是升级(upgrade)握手后的全双工长连接,与短连接请求-响应模型不同。
  • check_origin 用于跨域校验,生产环境要限制来源,避免页面被任意站点建立 WS 连接。

原理流程

  1. 客户端发起 HTTP Upgrade 请求,握手通过后连接转为 WebSocket。
  2. 连接建立回调 open,注册连接到会话/连接表。
  3. 消息到达触发 on_message,服务端处理后 write_message 回推;断开触发 on_close 清理。

代码或图示

from tornado.websocket import WebSocketHandler

class ChatHandler(WebSocketHandler):
    def open(self):
        self.write_message("connected")

    def on_message(self, message):
        self.write_message(f"echo: {message}")

    def on_close(self):
        # 清理连接表中的记录
        pass

    def check_origin(self, origin):
        return True  # 生产应按白名单校验来源

常见误区

  • 把 WebSocket 连接对象存在全局列表里却不在 on_close 移除,断连后僵尸连接继续占用内存与推送目标。
  • 单进程内存保存连接表:多进程下连接分散在各进程,跨进程推送要经消息队列广播,不能假设本进程列表就是全部在线连接。

追问

  • 握手阶段做什么校验?答:check_origin 校验来源,鉴权可在 open 前的握手参数里完成。
  • 服务端主动推调用什么?答:write_message,支持文本与二进制。
  • 多进程怎么广播消息?答:经 Redis Pub/Sub 或消息队列跨进程分发。

04.7.19.1-044 Tornado 模板引擎与 UIModule 是怎么回事?

一句话结论

Tornado 自带轻量模板引擎,处理器 render(模板名, **上下文) 渲染 HTML;UIModule 封装可复用的页面片段(导航、卡片),在模板里以模块标签调用。与 Jinja2 相比,Tornado 模板更轻,能力有限,复杂视图逻辑应放处理器层。

概念解释

  • 模板路径由 settings 的 template_path 指定,模板语法含变量、循环、条件与转义。
  • UIModule 把渲染逻辑与片段绑定,适合复用组件,但在前后端分离项目中很少使用。

原理流程

  1. 处理器调用 render,传入模板名与上下文数据。
  2. 模板引擎渲染变量与片段,UIModule 回调生成对应 HTML。
  3. 渲染结果作为响应体写回。

代码或图示

class PageHandler(tornado.web.RequestHandler):
    def get(self):
        self.render("index.html", title="Home", items=[])

常见误区

  • 在模板里堆复杂业务逻辑,违背视图层分层;数据组装应在处理器/服务层完成。
  • 前后端分离项目仍引入模板渲染:Tornado 可纯做 JSON API,模板能力不是必选项。

追问

  • 模板路径在哪里配置?答:settings 的 template_path。
  • UIModule 解决什么问题?答:复用可渲染的页面片段组件。
  • Tornado 模板和 Jinja2 谁更强?答:Jinja2 生态与功能更丰富,Tornado 模板更轻量。

一句话结论

set_secure_cookie/get_secure_cookie 用 cookie_secret 对 Cookie 值做 HMAC 签名,防篡改;xsrf_cookies=True 开启 XSRF 保护,下发 _xsrf Cookie,表单或请求头携带匹配值才能通过校验。Tornado 不内置服务端 Session,会话标识存在签名 Cookie 里。

概念解释

  • 安全 Cookie 只防篡改,不等于加密;敏感数据不要放 Cookie。
  • XSRF 校验依赖 Cookie 与表单/头里的 token 双值一致,AJAX 请求通过 X-Xsrftoken 头携带。

原理流程

  1. 应用配置 cookie_secret,登录后写签名安全 Cookie。
  2. 开启 xsrf 后框架下发 _xsrf Cookie,页面渲染 token 字段或前端读 Cookie 放请求头。
  3. 跨站请求缺少匹配 token,校验拒绝。

代码或图示

self.set_secure_cookie("user", str(uid), httponly=True, secure=True)
uid = self.get_secure_cookie("user")

常见误区

  • 以为安全 Cookie 内容加密不可读:签名只保证不被篡改,值仍可被客户端读取,密码等敏感信息绝不能放进去。
  • 前后端分离用 Bearer Token 时仍套 XSRF 流程;非 Cookie 认证天然规避多数 CSRF,但要管好 token 存储。

追问

  • 签名用什么算法?答:基于 cookie_secret 的 HMAC 签名(具体实现以版本为准)。
  • AJAX 请求 XSRF token 放哪?答:X-Xsrftoken 请求头。
  • Tornado 内置 Session 吗?答:不内置,会话数据要存外部存储。

04.7.19.1-046 Tornado 错误处理与 HTTPError 怎么用?

一句话结论

处理器中 raise HTTPError(status_code, reason=...) 抛出 HTTP 错误,框架调用 write_error 生成错误响应;子类可覆盖 write_error 统一错误页面或 JSON 结构。未捕获异常由默认错误处理器处理,生产环境要记录日志并隐藏内部细节。

概念解释

  • HTTPError 携带状态码与 reason,可附加响应参数;write_error 在错误分支被回调。
  • 业务异常应映射为合适状态码(400/401/403/404/409),不要一律 500。

原理流程

  1. 处理器校验失败或业务条件不满足时 raise HTTPError。
  2. 框架捕获后调用当前处理器的 write_error。
  3. 错误响应写出,on_finish 仍会执行。

代码或图示

from tornado.web import HTTPError

class ItemHandler(tornado.web.RequestHandler):
    def write_error(self, status_code, **kwargs):
        self.write({"error": {"code": status_code, "msg": self._reason}})

    def get(self, item_id):
        if int(item_id) < 0:
            raise HTTPError(400, reason="invalid id")

常见误区

  • write_error 里又抛异常导致错误响应生成失败;错误处理器要保持极简、自身可兜底。
  • 把数据库原始异常直接转成对外消息,泄露表名、SQL 等内部信息;边界层要翻译错误码。

追问

  • HTTPError 携带什么?答:状态码、reason 与可选响应参数。
  • 统一错误 JSON 在哪里做?答:覆盖基类的 write_error。
  • 错误后 on_finish 还执行吗?答:执行,可用于日志与清理。

04.7.19.1-047 Tornado 里的阻塞代码如何交给线程池?

一句话结论

阻塞工作不能进 IOLoop;用 ThreadPoolExecutor 配合 @run_on_executor 装饰器把方法放到线程池执行,处理器 await 其返回的 Future。CPU 密集场景仅靠线程池受 GIL 限制,需要多进程分担。

概念解释

  • 线程池适合调用同步 IO 库(同步驱动、同步 HTTP);池大小要有上限,避免线程失控。
  • run_on_executor 读取类属性上的 executor,装饰方法返回可 await 的 Future。

原理流程

  1. 处理器类声明 executor = ThreadPoolExecutor(max_workers=N)。
  2. 阻塞方法用 @run_on_executor 装饰,提交到线程池运行。
  3. 处理器 await 结果,等待期间循环继续调度其他连接。

代码或图示

from concurrent.futures import ThreadPoolExecutor
from tornado.concurrent import run_on_executor

class CpuHandler(tornado.web.RequestHandler):
    executor = ThreadPoolExecutor(max_workers=4)

    @run_on_executor
    def blocking_work(self, n):
        return sync_compute(n)

    async def get(self):
        result = await self.blocking_work(int(self.get_argument("n")))
        self.write({"result": result})

常见误区

  • 线程池开得过大:GIL 竞争与上下文切换反而拉低吞吐,池大小按压测调整。
  • 在线程里访问处理器请求对象:线程与请求生命周期不一致,跨线程读 self.request 有竞态;需要的数据先复制进线程函数参数。

追问

  • IO 阻塞用什么隔离?答:线程池执行器。
  • CPU 密集线程池有效吗?答:受 GIL 限制,需多进程分担。
  • 线程里能直接读请求对象吗?答:不建议,先拷贝所需数据。

04.7.19.1-048 Tornado 和 WSGI 是什么关系?

一句话结论

Tornado 应用本身不是 WSGI 可调用对象,不能直接被 WSGI 服务器按 app(environ, start_response) 调用;tornado.wsgi.WSGIAdapter 的作用相反——把一个外部 WSGI 应用包装成 Tornado 可挂载的处理器,在 Tornado 进程里跑传统 WSGI 应用。

概念解释

  • WSGI 是同步一次性请求-响应协议;Tornado 是异步长连接模型,协议层不同。
  • 适配器桥接时 WSGI 部分仍退化为同步执行,无法享受 Tornado 的异步并发。

原理流程

  1. Tornado 服务器收到连接,按异步模型调度。
  2. 挂载的 WSGI 应用经适配器转换 environ 与响应。
  3. WSGI 调用在阻塞边界执行,结果回写成 Tornado 响应。

代码或图示

from tornado.wsgi import WSGIAdapter

wsgi_app = FlaskApp  # 某个 WSGI 应用
adapter = WSGIAdapter(wsgi_app)
# 作为处理器挂载进 Tornado 路由(用法以当前版本为准)

常见误区

  • 以为 Tornado 可以像 Flask 一样 gunicorn app:app 直接跑;同步 worker 模型下异步能力完全退化。
  • 以为适配器能让 WSGI 应用变异步:被桥接的 WSGI 代码仍是同步阻塞,需要线程/进程隔离。

追问

  • Tornado 应用能当 WSGI 用吗?答:不能,协议模型不同。
  • WSGIAdapter 方向是什么?答:把 WSGI 应用包进 Tornado,而不是反过来。
  • 桥接后的 WSGI 代码是异步的吗?答:不是,仍是同步执行。

04.7.19.1-049 Tornado 的性能取舍体现在哪里?

一句话结论

Tornado 的性能优势来自单线程事件循环、非阻塞网络库与少中间层开销,擅长海量 IO 等待中的长连接;代价是要求整条链路异步化,阻塞代码会击穿模型,且生态与 ORM/管理后台不如主流框架完备。CPU 密集型业务不是它的主场。

概念解释

  • 异步框架的吞吐上限取决于事件循环不被阻塞;一旦出现同步慢调用,延迟毛刺影响全 worker。
  • 性能还受序列化、日志、下游响应时间影响,框架本身只占其中一段。

原理流程

  1. 长连接在等待 IO 时挂起,循环调度其他连接,线程/进程数不必按连接数增长。
  2. 出现阻塞回调时循环停顿,所有连接排队等待。
  3. CPU 密集任务需要拆到进程池或独立服务,避免占住循环。

代码或图示

长连接 / 实时推送:Tornado 优势明显
同步 ORM / 重计算 / 管理后台:需额外隔离或换框架

常见误区

  • 拿 Tornado 短连接 CRUD 吞吐和同步框架比:场景不匹配,结论没有参考价值。
  • 忽视异步链路完整性:数据库驱动、缓存客户端、外部 HTTP 任一环节是同步阻塞,整体就退化成阻塞服务。

追问

  • Tornado 最擅长什么负载?答:高并发 IO 等待、长连接与实时推送。
  • 阻塞回调为什么伤害大?答:单循环被占住,该进程所有连接一起延迟。
  • CPU 密集怎么办?答:进程池或独立服务分担。

04.7.19.1-050 Tornado 适合哪些业务场景?

一句话结论

Tornado 适合:WebSocket 实时推送、长轮询、IM/通知/行情等长连接服务、需要自带异步网络库的网关或爬虫客户端;传统 CRUD 后台、强依赖 ORM/Admin 生态的业务,用 Django/Flask/FastAPI 更省力。

概念解释

  • 选型看连接模型:大量等待中的长连接是 Tornado 的传统强项。
  • 也要看团队是否接受异步编程与较少的现成扩展。

原理流程

  1. 梳理连接形态:短连接请求-响应还是长连接双向推送。
  2. 盘点周边库异步支持与团队经验。
  3. 关键场景 PoC 验证长连接稳定性与下游链路。

代码或图示

适合:WebSocket 推送 / 长轮询 / 实时网关 / 异步网络程序
谨慎:纯 CRUD / 重表单后台 / 团队无异步经验

常见误区

  • 因为“老牌高性能”给普通后台选 Tornado,结果 ORM、权限、后台模板都要自己拼。
  • 实时推送场景不评估多进程广播与连接表外部化,单进程内存方案无法水平扩展。

追问

  • 实时推送为什么 Tornado 合适?答:长连接是一等公民,原生 WebSocket 与事件循环支撑。
  • CRUD 后台为什么不优先 Tornado?答:ORM/Admin/扩展生态不如 Django 等完备。
  • 长连接服务水平扩展要注意什么?答:连接状态外部化,跨进程消息广播。

04.7.19.1-051 Tornado 生产部署怎么组织?

一句话结论

生产环境 Tornado 通常前置 Nginx 做 TLS 终止、静态资源与负载均衡,后端按进程数启动 Tornado 实例(start(N) 或 systemd 多实例);服务器开启 xheaders 以识别代理转发的真实 IP 与协议。进程数按 CPU 核数与压测结果调整。

概念解释

  • Nginx 处理 TLS、静态文件、连接缓冲,应用进程专注业务。
  • 真实客户端信息通过 X-Real-IP、X-Forwarded-Proto 等头传递,应用需信任代理链并开启对应解析。

原理流程

  1. Nginx 终止 TLS,反向代理到多个 Tornado 进程。
  2. Tornado 绑定内网端口,xheaders 解析代理头。
  3. 进程管理由 systemd/容器编排负责重启与副本数。

代码或图示

from tornado.httpserver import HTTPServer

server = HTTPServer(app, xheaders=True)
server.bind(8888)
server.start(num_processes=2)
tornado.ioloop.IOLoop.current().start()

常见误区

  • 不开启 xheaders,应用拿到的全是 Nginx 内网 IP,按客户端 IP 做限流/审计全部失效。
  • 让应用进程直接对外承担 TLS 与静态资源,职责混杂;生产应分层处理。

追问

  • TLS 在哪一层终止?答:Nginx/网关层,应用走内网 HTTP。
  • 真实 IP 怎么传给应用?答:代理头 X-Real-IP 等,应用开启 xheaders 解析。
  • 副本数怎么定?答:参考 CPU 核数与压测,异步进程不必按连接数堆。

04.7.19.1-052 Tornado 与 Sanic、现代 asyncio 生态相比如何?

一句话结论

三者都跑在异步事件循环上:Tornado 历史最久、自带网络库与 WebSocket 能力,但 API 偏老派、生态规模有限;Sanic 类 Flask 风格、自带服务器;现代新项目更多在 FastAPI/Litestar/Starlette 与标准 ASGI 生态里选择。Tornado 的价值在存量维护与长连接传统场景,新选型要评估生态活跃度。

概念解释

  • 标准 ASGI 生态(uvicorn/hypercorn、Starlette 系)提供统一部署与中间件生态;Tornado 有自己的服务器与 API 体系。
  • 框架迁移成本包括路由写法、处理器模型、客户端与中间件接口的重写。

原理流程

  1. 对比部署模型:自有服务器还是标准 ASGI。
  2. 对比周边生态:异步驱动、认证、校验、文档、监控包。
  3. 对比团队既有经验与长期维护投入。

代码或图示

Tornado:自有 IOLoop + 处理器类,长连接传统强,生态偏老
Sanic:类 Flask 异步,自有服务器,扩展靠 sanic-ext
ASGI 系:Starlette/FastAPI/Litestar,标准部署与生态最活跃

常见误区

  • 认为 Tornado “老”就不能用于新项目:成熟稳定仍是优点,但要确认依赖维护活跃度与招聘可得性。
  • 只比较框架基准吞吐,忽略生态成熟度与排障资料;生产问题最终多卡在周边库与工具链。

追问

  • Tornado 最大历史资产是什么?答:成熟的异步网络库与长连接处理经验。
  • 新项目为什么常选 ASGI 系?答:标准部署、中间件与异步库生态更活跃。
  • 存量 Tornado 系统要不要立刻迁走?答:按业务价值逐步评估,先维持再按模块迁移。

04.7.19.1-053 Tornado 的认证与会话通常怎么实现?

一句话结论

Tornado 不内置 Session 框架:通过覆写 self.current_user 属性识别当前用户,@web.authenticated 装饰器保护需要登录的处理器;会话标识存签名安全 Cookie,会话数据放数据库或 Redis。登录态校验在 prepare 或基类处理器里统一完成。

概念解释

  • authenticated 装饰器在 current_user 为空时跳转登录或返回 401。
  • 多进程下会话数据必须外部存储,不能依赖进程内存。

原理流程

  1. 登录成功后写签名安全 Cookie(会话标识)。
  2. 受保护处理器经 current_user 从外部存储取回用户。
  3. @authenticated 校验未登录则拦截,鉴权授权在业务层细化。

代码或图示

from tornado.web import authenticated

class MeHandler(tornado.web.RequestHandler):
    @authenticated
    def get(self):
        self.write({"user": self.current_user})

    def get_current_user(self):
        uid = self.get_secure_cookie("user")
        return load_user(uid) if uid else None

常见误区

  • 把用户对象直接序列化进 Cookie:体积大且暴露信息;Cookie 只存会话标识,数据落服务端。
  • 只在每个处理器方法里手写鉴权,漏一个接口就成越权入口;应在基类 prepare 或装饰器层统一拦截。

追问

  • Tornado 自带 Session 表吗?答:不带,会话数据需外部存储。
  • @authenticated 依据什么判断?答:current_user 属性是否为空。
  • 会话标识放哪里?答:签名安全 Cookie,数据在服务端。

04.7.19.1-054 使用 Tornado 最常见的误区有哪些?

一句话结论

高频误区包括:在协程里跑同步阻塞调用、把处理器当有状态单例存数据、每请求新建 HTTP 客户端/连接池、不设超时、在 fork 前建连接池、把 WSGI 应用直接挂进来跑。这些问题都会让异步模型退化或产生资源泄漏。

概念解释

  • 处理器实例按请求创建/复用的方式受框架管理,请求级状态不要挂实例属性长期保留。
  • 异步服务的资源(连接池、客户端、后台任务)生命周期必须与应用生命周期对齐。

原理流程

  1. 代码评审时排查同步阻塞调用与缺失的超时。
  2. 核对资源创建时机:应用级复用、请求级隔离。
  3. 压测观察连接数、线程数、协程积压与慢请求分布。

代码或图示

排查清单:同步阻塞 / 缺失超时 / 实例属性存状态 /
客户端未复用 / fork 前建池 / WSGI 直接挂载

常见误区

  • 以为“异步框架自动处理阻塞”:框架只调度协程,阻塞库仍需手动隔离或替换。
  • 后台任务不保留引用、关停时不取消:进程退出时任务被强杀,数据不一致。

追问

  • 请求级数据能存处理器实例属性吗?答:谨慎使用,生命周期以框架为准,优先请求上下文。
  • 为什么客户端要应用级复用?答:复用连接池,避免频繁建连与端口耗尽。
  • 后台任务关停时怎么办?答:保留引用,关停阶段取消并等待收尾。

04.7.19.1-055 什么时候不该选 Tornado?

一句话结论

以下情况不建议选 Tornado:团队以同步 Django/Flask 经验为主、业务是标准 CRUD 且依赖成熟 Admin/ORM 生态、需要标准 ASGI 中间件与最新异步库生态、或长期维护希望社区资料与招人最容易。这些场景应在 Django、Flask、FastAPI、Litestar 中按需求选择。

概念解释

  • 框架选型是综合决策:性能只是其中一维,生态、团队经验、维护成本同样权重很高。
  • 没有“最好的框架”,只有与业务形态和团队能力匹配的选择。

原理流程

  1. 明确业务连接模型与实时性需求。
  2. 盘点所需周边库的成熟度与团队掌握程度。
  3. 对比长期维护成本(招聘、排障资料、版本跟进)后决策。

代码或图示

不选 Tornado:纯 CRUD 后台 / 同步生态为主 / 追求 ASGI 标准生态 /
团队无异步经验 / 依赖成熟 Admin 与 ORM 全家桶

常见误区

  • 因历史名气选型,忽略当前社区活跃度与项目长期维护投入。
  • 为少量实时需求给整个服务选老框架,导致大部分接口都要额外绕路。

追问

  • CRUD 后台优先考虑什么框架?答:Django(全家桶)或 Flask(轻量灵活)。
  • 要标准 ASGI 生态选什么?答:FastAPI/Litestar/Starlette 系。
  • 存量 Tornado 系统要不要立刻迁走?答:按业务价值与维护压力逐步评估,不做无谓重写。

本节高频题

  • Sanic 定位与异步执行模型(001、024)
  • Sanic 路由装饰器与路径参数转换器(003、004)
  • Blueprint 分层与嵌套分组(006、007)
  • HTTPMethodView 类视图与函数视图取舍(008、009)
  • 请求/响应中间件顺序与短路(010、011)
  • listener 生命周期钩子与信号机制(012、013)
  • sanic-ext 校验与 OpenAPI 文档(014、015、016)
  • Sanic 自有协议与 ASGI 适配差别(020、021)
  • 阻塞调用隔离与并发模型(025、024)
  • Sanic 与 FastAPI/Starlette 对比及选型短板(027、028)
  • Tornado 定位与 IOLoop 职责(029、031)
  • IOLoop 与 asyncio 事件循环融合(032)
  • RequestHandler 生命周期与参数读取(033、034)
  • gen.coroutine 到 async/await 演进与混用(036、037、038)
  • AsyncHTTPClient 非阻塞调用与复用(039)
  • HTTPServer listen/bind/start 与多进程 fork(041、042)
  • WebSocketHandler 长连接与广播(043)
  • 安全 Cookie、XSRF 与认证会话(045、053)
  • 阻塞代码线程池隔离(047)
  • Tornado 适用场景与不适用场景(050、055)