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 做校验。
原理流程
- 进程启动后创建
Sanic应用对象,注册路由、中间件、蓝图与监听器。 - 自带服务器绑定端口,在事件循环上接收连接、解析请求并分发到协程视图。
- 视图
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 或外部服务器,配置通过环境变量与配置文件注入。
原理流程
- 实例化
Sanic,应用配置默认值与环境变量。 - 注册路由、中间件、蓝图与监听器。
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与sanicCLI 是什么关系?答: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,或分别为同一函数注册多次。
原理流程
- 装饰器在应用构建期把
(path, methods, handler)加入路由表。 - 请求进入后路由层按路径与方法匹配,未匹配方法会返回
405 Method Not Allowed。 - 匹配成功后把
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()。
原理流程
- 路由注册时把路径模板编译成匹配规则与转换器列表。
- 请求路径逐段匹配,转换器校验格式并做类型转换。
- 转换成功后以关键字参数形式传给视图;失败则不匹配该路由。
代码或图示
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,避免在代码里硬编码路径。蓝图内的路由名字会带蓝图前缀,反向解析时要用全名。
概念解释
- 命名路由用于模板跳转、重定向、生成文档链接与测试断言,路径调整时只改路由声明,引用处自动跟随。
- 蓝图路由的端点名格式为
蓝图名.视图名,跨蓝图引用时必须写全。
原理流程
- 注册路由时记录端点名、路径模板与参数列表。
url_for按端点名找到模板,填入路径参数,拼出完整路径。- 需要外部绝对地址时传
_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这类域划分模块。
原理流程
- 创建
Blueprint("users", url_prefix="/api/users"),在其上用@bp.get注册路由。 - 主应用调用
app.blueprint(bp),蓝图的路由表合并进主路由表,端点名加蓝图前缀。 - 请求匹配时按合并后的路由表分发,蓝图中间件按注册顺序参与请求链。
代码或图示
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/...)的目录式组织。
概念解释
- 分组本质是路由与钩子的层级合并:子蓝图继承父蓝图的前缀与中间件配置。
- 相比把所有前缀拼在单个蓝图上,分组让目录结构与代码目录一一对应,便于维护。
原理流程
- 创建父蓝图,声明公共前缀与公共中间件。
- 子蓝图通过分组机制挂到父蓝图下,路径逐级拼接。
- 应用只注册父蓝图,合并后的完整路由表进入主应用。
代码或图示
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。 - 类视图便于继承复用公共逻辑(认证、序列化),函数视图则更适合装饰器组合。
原理流程
- 继承
HTTPMethodView,按需要实现get/post/put/delete等异步方法。 - 调用
View.as_view()得到视图可调用对象,用add_route注册到路径。 - 请求进来后调度器按方法名选择对应实例方法执行。
代码或图示
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 资源控制器。团队约定统一比选哪种更“高级”更重要,混用要保持边界清晰。
概念解释
- 函数视图:一个函数对应一条路由,认证、日志等用装饰器或中间件叠加。
- 类视图:一个资源一个类,公共前置逻辑可抽到父类;代价是多一层抽象,小接口显得笨重。
原理流程
- 先判断接口是“资源动作”还是“单一动作”。
- 资源的增删改查聚合成类视图;独立动作(登录、回调、健康检查)用函数视图。
- 跨视图复用通过父类、装饰器或中间件实现,而不是复制粘贴方法体。
代码或图示
# 函数视图:单一动作
@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。
原理流程
- 请求进入后按注册顺序依次执行请求中间件。
- 任一请求中间件返回响应即短路,不再进入视图。
- 视图产出响应后,响应中间件按相反或注册顺序(以框架实现为准)加工响应再写出。
代码或图示
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,避免继续消耗业务资源。
- 顺序决定保护范围:认证中间件排在限流之前还是之后,影响被拦截请求的计数与日志口径。
原理流程
- 应用级请求中间件先跑,再跑蓝图级请求中间件。
- 某层返回响应则立刻中断后续请求中间件与视图。
- 响应沿回程链路穿过响应中间件,最后由服务器写出。
代码或图示
@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异步初始化(数据库连接池、消息队列客户端)放在这里,而不是模块导入时。
原理流程
- 主进程启动触发
main_process_start,fork worker。 - 每个 worker 事件循环起来后触发
before_server_start,完成连接池等初始化;就绪后after_server_start。 - 关停时先
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 退出等阶段;自定义信号用于模块间事件通知。
原理流程
- 应用在生命周期节点调用信号总线派发事件。
- 已订阅的监听器(含 listener 注册的函数)被依次调用。
- 自定义信号由业务代码显式
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 生成、文档页面挂载。
原理流程
- 安装
sanic-ext,在应用初始化时调用Extend(app)。 - 视图上用校验装饰器声明请求/响应模型,扩展在调度前完成解析与校验。
- 启动时扫描路由与模型,生成 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。
原理流程
- 视图声明
@validate(json=CreateItem, query=PageQuery)。 - 请求进入后扩展按位置读取原始数据,交给对应模型解析校验。
- 校验通过则把模型作为参数传入视图;失败则抛校验异常,经异常处理器转成错误响应。
代码或图示
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 资源等。
原理流程
Extend(app)挂载后,启动期遍历路由表与装饰器元数据。- 结合请求/响应模型生成 OpenAPI 文档对象。
- 文档路由挂载到应用,浏览器访问文档页面渲染并可在线调试。
代码或图示
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_ 为前缀覆盖配置项。启动时加载环境与配置文件,运行期配置不应被业务请求随意改写。
概念解释
- 配置与应用实例绑定,多实例测试时各自隔离,避免全局配置串用。
- 敏感配置(密钥、数据库地址)从环境变量或受管配置中心注入,不写进代码仓库。
原理流程
- 应用实例化时载入默认配置。
- 通过
update_config或环境变量覆盖,环境变量按前缀匹配大写配置键。 - 视图与钩子通过
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生命周期与请求一致,请求结束即销毁,不能跨请求保存状态。
原理流程
- 服务器解析报文后构造
Request,挂到当前请求上下文。 - 中间件与视图按属性读取输入,需要共享的中间结果写进
request.ctx。 - 请求结束后
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 处理(以当前版本约定为准)。- 流式响应保持连接逐步写块,避免把整个响应体读进内存。
原理流程
- 视图返回响应对象或辅助函数结果。
- 响应中间件加工状态码、头与体。
- 流式响应由服务器分块写出,普通响应一次性序列化后写出。
代码或图示
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 第一”没有意义。
原理流程
- 连接与请求由事件循环调度,协程在 IO 等待时让出控制权。
- 协议层解析报文并构造请求对象,减少额外线程/进程中转。
- 业务协程处理后产出响应,协议层写回连接。
代码或图示
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 服务器后,进程编排由服务器负责。
原理流程
- 自有模式:
sanicCLI 或app.run启动主进程,fork worker,内部信号驱动生命周期。 - ASGI 模式:暴露标准 ASGI 应用,外部服务器接管监听、循环与 worker 进程。
- 业务视图代码不变,差别主要在启动编排与生命周期钩子由谁触发。
代码或图示
# 自有服务器
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 内部异常直接暴露给客户端。
原理流程
- 视图或中间件抛出框架异常或业务异常。
- 调度器按异常类型查找已注册处理器。
- 处理器生成错误响应,经响应中间件写出;未匹配则走默认 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 路由分开注册,避免业务路径被静态规则截胡。
- 文件读取在大文件场景同样要注意内存与并发,必要时用文件响应或外置静态服务器。
原理流程
- 启动期注册静态映射:URL 前缀到文件系统路径。
- 请求匹配静态前缀后,框架定位文件并按 MIME 返回。
- 文件不存在返回 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 处理请求。
原理流程
- 主进程解析配置,绑定监听端口。
- fork 出 N 个 worker,各自初始化应用、连接池与事件循环。
- 请求由内核在进程间分发,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 竞争与上下文切换。
原理流程
- 识别阻塞点:同步驱动调用、
time.sleep、同步 HTTP、重计算。 - 优先换成对应异步客户端/驱动。
- 无法替换的部分提交执行器,
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或框架自带测试运行器编写协程用例(具体集成方式以当前版本为准)。
原理流程
- 构造应用实例并挂载测试客户端。
- 客户端发起 GET/POST 等请求,应用内部走完中间件到视图链路。
- 断言响应状态、体与头;用例结束清理上下文与外部资源。
代码或图示
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,框架本身的性能差距通常小于业务代码与下游瓶颈。
原理流程
- 按需求拆解:校验模型强度、文档要求、团队熟悉的 API 风格、生态包 availability。
- 对比异步链路完整性(数据库驱动、客户端、消息队列客户端是否都有异步实现)。
- 用贴近真实业务的压测口径验证吞吐与延迟,而不是照搬第三方基准。
代码或图示
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/消息队列客户端、认证/权限包、定时任务、监控集成是否齐备。
- 招人与维护成本也是生态的一部分:团队现有经验能直接复用多少,决定落地速度。
原理流程
- 列出业务用到的中间件与库,逐个确认异步实现成熟度。
- 评估团队异步排障能力(事件循环阻塞、任务泄漏、取消处理)。
- 做小范围 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 框架单独用于异步网络程序。
原理流程
- 应用把路由元组交给
Application,服务器绑定端口。 - IOLoop 在单线程上多路复用监听所有连接。
- 请求分发到
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里接收。
原理流程
- 编写处理器类,实现对应 HTTP 方法。
- 组装路由元组列表与 settings,构造
Application。 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 把“连接可读/可写/超时/回调”统一成事件,按就绪状态调度对应的回调或协程。
- 单线程模型避免多线程锁竞争,但要求所有回调不得长时间阻塞,否则整个循环停顿。
原理流程
- 服务器把监听 socket 与连接 socket 注册到 IOLoop。
- 循环等待事件就绪,回调对应的读写处理函数。
- 协程在
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写法。
原理流程
- 进程启动时获取/创建 asyncio 事件循环,Tornado IOLoop 在其之上提供兼容 API。
- 处理器协程作为任务提交到该循环调度。
- 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常用于日志、埋点、释放请求级资源,此时响应已发出,不能再改响应体。
原理流程
- 路由命中处理器类,实例化并调用
initialize(**kwargs)。 - 调用
prepare(),再按方法分发到get/post/...。 - 响应
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)。
原理流程
- 服务器解析 URL query 与请求体,存入
request的参数字典。 - 处理器按方法读取对应来源,做去空白与默认值处理。
- 校验不通过抛参数异常,由错误处理器转成 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,永久跳转显式传对应状态码。
原理流程
- 处理器方法内组织数据,调用
write输出片段。 - 需要时设置状态码与响应头。
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让流程写成顺序代码。
原理流程
@gen.coroutine包装生成器,调用后立即返回 Future。- 生成器
yieldFuture,控制权交还 IOLoop。 - 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 生态无缝互通。
- 演进的驱动力是标准语言层面协程成熟,框架不再需要自造协程调度方言。
原理流程
- 早期:回调函数作为参数传递,链路嵌套。
gen时代:生成器yieldFuture,框架驱动恢复。- 现代:
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。- 混用最容易出问题的是“忘记等待”:未持有引用的后台任务异常不会冒泡到请求处理器。
原理流程
- 跨风格调用时,调用方按自己的风格
await或yield对方返回的 awaitable。 - 异常沿 Future 链传播,未捕获则进入循环异常回调。
- 后台任务要保留引用并在关停时取消,防止任务泄漏。
代码或图示
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汇总。 - 可配置请求超时、默认头、认证与代理;具体配置项以当前版本文档为准。
原理流程
- 创建客户端实例(按需复用,不要每请求新建)。
fetch发起请求并返回 Future,协程挂起等待。- 响应就绪后 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开启跨站请求伪造保护。
原理流程
- 构造
Application时传入路由表与 settings。 - 框架按 settings 初始化模板/静态路径、安全 Cookie 与调试行为。
- 处理器运行期读取配置,敏感值从环境变量注入。
代码或图示
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分发。
原理流程
- 方式一:
app.listen(port)创建服务器并监听,随后启动 IOLoop。 - 方式二:
HTTPServer(app).bind(port)绑定端口,server.start(N)拉起进程。 - 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 之后不能再在主进程做依赖单进程状态的初始化;共享状态靠外部存储。
原理流程
bind完成监听 socket 创建。start(N)调用 fork,生成 N 个子进程。- 各子进程启动自己的 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 连接。
原理流程
- 客户端发起 HTTP Upgrade 请求,握手通过后连接转为 WebSocket。
- 连接建立回调
open,注册连接到会话/连接表。 - 消息到达触发
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 把渲染逻辑与片段绑定,适合复用组件,但在前后端分离项目中很少使用。
原理流程
- 处理器调用
render,传入模板名与上下文数据。 - 模板引擎渲染变量与片段,UIModule 回调生成对应 HTML。
- 渲染结果作为响应体写回。
代码或图示
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 模板更轻量。
04.7.19.1-045 Tornado 安全 Cookie 与 XSRF 如何工作?
一句话结论
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头携带。
原理流程
- 应用配置
cookie_secret,登录后写签名安全 Cookie。 - 开启 xsrf 后框架下发
_xsrfCookie,页面渲染 token 字段或前端读 Cookie 放请求头。 - 跨站请求缺少匹配 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。
原理流程
- 处理器校验失败或业务条件不满足时
raise HTTPError。 - 框架捕获后调用当前处理器的
write_error。 - 错误响应写出,
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。
原理流程
- 处理器类声明
executor = ThreadPoolExecutor(max_workers=N)。 - 阻塞方法用
@run_on_executor装饰,提交到线程池运行。 - 处理器
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 的异步并发。
原理流程
- Tornado 服务器收到连接,按异步模型调度。
- 挂载的 WSGI 应用经适配器转换 environ 与响应。
- 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。
- 性能还受序列化、日志、下游响应时间影响,框架本身只占其中一段。
原理流程
- 长连接在等待 IO 时挂起,循环调度其他连接,线程/进程数不必按连接数增长。
- 出现阻塞回调时循环停顿,所有连接排队等待。
- 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 的传统强项。
- 也要看团队是否接受异步编程与较少的现成扩展。
原理流程
- 梳理连接形态:短连接请求-响应还是长连接双向推送。
- 盘点周边库异步支持与团队经验。
- 关键场景 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等头传递,应用需信任代理链并开启对应解析。
原理流程
- Nginx 终止 TLS,反向代理到多个 Tornado 进程。
- Tornado 绑定内网端口,
xheaders解析代理头。 - 进程管理由 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 体系。
- 框架迁移成本包括路由写法、处理器模型、客户端与中间件接口的重写。
原理流程
- 对比部署模型:自有服务器还是标准 ASGI。
- 对比周边生态:异步驱动、认证、校验、文档、监控包。
- 对比团队既有经验与长期维护投入。
代码或图示
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。- 多进程下会话数据必须外部存储,不能依赖进程内存。
原理流程
- 登录成功后写签名安全 Cookie(会话标识)。
- 受保护处理器经
current_user从外部存储取回用户。 @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 应用直接挂进来跑。这些问题都会让异步模型退化或产生资源泄漏。
概念解释
- 处理器实例按请求创建/复用的方式受框架管理,请求级状态不要挂实例属性长期保留。
- 异步服务的资源(连接池、客户端、后台任务)生命周期必须与应用生命周期对齐。
原理流程
- 代码评审时排查同步阻塞调用与缺失的超时。
- 核对资源创建时机:应用级复用、请求级隔离。
- 压测观察连接数、线程数、协程积压与慢请求分布。
代码或图示
排查清单:同步阻塞 / 缺失超时 / 实例属性存状态 /
客户端未复用 / fork 前建池 / WSGI 直接挂载
常见误区
- 以为“异步框架自动处理阻塞”:框架只调度协程,阻塞库仍需手动隔离或替换。
- 后台任务不保留引用、关停时不取消:进程退出时任务被强杀,数据不一致。
追问
- 请求级数据能存处理器实例属性吗?答:谨慎使用,生命周期以框架为准,优先请求上下文。
- 为什么客户端要应用级复用?答:复用连接池,避免频繁建连与端口耗尽。
- 后台任务关停时怎么办?答:保留引用,关停阶段取消并等待收尾。
04.7.19.1-055 什么时候不该选 Tornado?
一句话结论
以下情况不建议选 Tornado:团队以同步 Django/Flask 经验为主、业务是标准 CRUD 且依赖成熟 Admin/ORM 生态、需要标准 ASGI 中间件与最新异步库生态、或长期维护希望社区资料与招人最容易。这些场景应在 Django、Flask、FastAPI、Litestar 中按需求选择。
概念解释
- 框架选型是综合决策:性能只是其中一维,生态、团队经验、维护成本同样权重很高。
- 没有“最好的框架”,只有与业务形态和团队能力匹配的选择。
原理流程
- 明确业务连接模型与实时性需求。
- 盘点所需周边库的成熟度与团队掌握程度。
- 对比长期维护成本(招聘、排障资料、版本跟进)后决策。
代码或图示
不选 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)