后端Web框架【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址https://gitcode.com/gh_mirrors/sa/sanic点击查看免费下载Sanic 的 Blueprint蓝图是用于子路由的模块化对象它以与Sanic()应用实例几乎相同的 API把路由、中间件、异常处理器、监听器、静态文件与信号等逻辑按业务领域分组再以灵活、可插拔的方式注册到应用上尤其适合大型应用中按职责拆分组的架构。读完本文你将掌握 Blueprint 的完整 API构造参数、装饰器、拷贝、分组、BlueprintGroup的组合与嵌套机制、注册的底层实现以及如何在实践中利用它们组织多版本 API 与可复用模块。本文基于仓库中的 API 参考文档 docs/sanic/api/blueprints.rst 展开其覆盖sanic.blueprints与sanic.blueprint_group两个模块对应源码 sanic/blueprints.py 与 sanic/blueprint_group.py。建议配合官方最佳实践指南 guide/content/en/guide/best-practices/blueprints.md 一起阅读。一、Blueprint 是什么逻辑域的分组容器源码 sanic/blueprints.py 中Blueprint的类文档描述得很清楚A logical collection of URLs that consist of a similar logical domain. Blueprint 对象是把路由、异常处理器、中间件以及其他 Web 功能组织成独立、模块化分组的主要工具。也就是说Blueprint 的核心价值是把相似逻辑域的端点聚在一起。与直接往应用实例上挂路由相比Blueprint 提供了完全一致的装饰器/方法route、middleware、listener、exception、signal、static等只是这些对象不会立即作用于应用而是先被延迟收集等到调用app.blueprint(bp)注册时才真正落到应用上。仓库中的最小示例 examples/blueprints.py 演示了最基础的用法# my_blueprint.py from sanic import Blueprint from sanic.response import json bp Blueprint(my_blueprint) bp.route(/) async def bp_root(request): return json({my: blueprint})# app.py from sanic import Sanic from my_blueprint import bp app Sanic(__name__) app.blueprint(bp)除route外Blueprint 还提供websocket()装饰器与add_websocket_route方法用于实现 WebSocket 端点这一点与Sanic应用实例保持一致。二、Blueprint 构造参数详解Blueprint.__init__的定义在 sanic/blueprints.py完整签名如下Blueprint( name: str, url_prefix: str | None None, host: list[str] | str | None None, version: int | str | float | None None, strict_slashes: bool | None None, version_prefix: str /v, )各参数的含义与源码中的处理细节参数类型默认值说明namestr必填Blueprint 名称注册到应用时必须全局唯一否则app.blueprint()会抛出断言错误见 sanic/app.py。同时它也是路由命名空间前缀url_for()生成 URL 时端点名形如{blueprint_name}.{handler_name}url_prefixstr \| NoneNone该 Blueprint 下所有路由的 URL 前缀。注意源码会做一次规范化如果前缀以/结尾会被去掉末尾的/sanic/blueprints.py第 129-133 行hostlist[str] \| str \| NoneNone该 Blueprint 只响应的主机可传列表注册时若为列表会转换为 tuple 传给路由sanic/blueprints.py第 386-388 行versionint \| str \| float \| NoneNoneAPI 版本号会在 URL 中体现为/v1、/v2或/{version_prefix}{version}strict_slashesbool \| NoneNone是否强制 URL 以/结尾None表示继承应用级app.strict_slashes设置见sanic/app.py第 935-939 行的继承逻辑version_prefixstr/v版本号在 URL 中的前缀默认是/v即版本1对应路径/v1Blueprint内部维护一组_future_*集合_future_routes、_future_statics、_future_middleware、_future_listeners、_future_exceptions、_future_signals、_future_commands所有装饰器注册的对象先进入这些未来注册容器直到register()时才统一应用——这正是 Blueprint 可以先注册、后添加对象的机制基础。关于ctx与__repr__每个 Blueprint 实例自带一个ctxSimpleNamespace可像应用级app.ctx一样挂载自定义状态。__repr__会输出Blueprint(name..., url_prefix..., host..., version..., strict_slashes...)便于调试时快速辨认见 sanic/blueprints.py。三、lazy 装饰器Blueprint 的延迟注册魔法Blueprint 的route、middleware、listener、exception、signal、static并非各自独立实现而是统一通过 sanic/blueprints.py 的lazy()函数包装而来exception lazy(BaseSanic.exception) listener lazy(BaseSanic.listener) middleware lazy(BaseSanic.middleware) route lazy(BaseSanic.route) signal lazy(BaseSanic.signal) static lazy(BaseSanic.static, as_decoratorFalse)lazy的关键行为调用底层BaseSanic对应方法时强制传入applyFalse把结果作为FutureRoute/FutureMiddleware等未来对象暂存而不是立刻应用到任何实例支持两种调用形态直接作为装饰器使用bp.route(/)或传入 handler 立即执行热注册支持如果 Blueprint 已经注册到应用bp.registered为真再次添加对象时会自动对已注册的每个 app 重新调用bp.register(app, {})把新对象同步进去。这印证了指南中Beginning in v21.12Blueprint 可以在注册之前或之后添加对象的能力。registered属性由self._apps一个set[Sanic]是否为空决定apps属性返回该 Blueprint 已注册到的应用集合未注册时访问会抛出SanicExceptionsanic/blueprints.py第 154-179 行。四、注册机制从app.blueprint()到Blueprint.register()4.1app.blueprint()入口与唯一性校验Sanic.blueprint()定义在 sanic/app.py签名def blueprint( self, blueprint: Blueprint | Iterable[Blueprint] | BlueprintGroup, *, url_prefix: str | None None, version: int | float | str | None None, strict_slashes: bool | None None, version_prefix: str | None None, name_prefix: str | None None, ) - None它做了三件事选项收集把非None的关键字参数url_prefix、version、strict_slashes、version_prefix、name_prefix收进options字典这些选项在注册时优先于 Blueprint 自身的属性可迭代展开如果传入的是Iterable或BlueprintGroup会递归展开并逐个注册。对BlueprintGroup还会执行前缀合并merge_from逻辑把应用级前缀、组前缀与子 Blueprint 前缀用/拼接再对version、strict_slashes、version_prefix、name_prefix做继承合并单实例注册校验名称唯一性同名且非同一对象即断言失败存入app.blueprints字典与_blueprint_order列表最后调用blueprint.register(self, options)。4.2Blueprint.register()未来的兑现Blueprint.register()是核心应用逻辑位于 sanic/blueprints.py。其执行顺序清晰路由遍历_future_routes用_setup_uri把url_prefix拼到路由 URI 前sanic/blueprints.py第 579-589 行依次解析version_prefix、version、strict_slashes_extract_value按future 级 注册选项级 Blueprint 自身级的优先级取第一个非None值name会先叠加name_prefix再交给app.generate_name()生成带应用名的完整端点名最后通过app._apply_route()真正创建路由对象静态文件对_future_statics同样做前缀拼接后调用app._apply_static()中间件与异常处理器只对该 Blueprint 拥有的路由生效——它们会拿到route_names列表调用app._apply_middleware(future, route_names)与app._apply_exception_handler(future, route_names)做命名空间隔离监听器对_future_listeners逐一app._apply_listener()按事件名聚合信号给每个 future 信号注入condition{__blueprint__: self.name}并强制exclusiveFalse从而把信号作用域限定在该 Blueprint 内Blueprints 也暴露了dispatch()与event()方法分别在该 Blueprint 已注册的所有应用上分发或等待信号sanic/blueprints.py第 509-568 行去重与重注册通过app._future_registry记录(blueprint, future)对避免重复应用若 Blueprint 已注册到多个应用会调用register_futures()把新 futures 同步给所有 app限制_future_commands非空时抛出SanicException(Registering commands with blueprints is not supported.)即 Blueprint 不支持注册 CLI 命令。五、Blueprint 拷贝copy()的深拷贝语义Blueprint.copy()sanic/blueprints.py可以把一个 Blueprint 连同其上挂载的一切复制为全新实例常用于生成多个 API 版本v1 Blueprint(Version1, version1) v1.route(/something) def something(request): pass v2 v1.copy(Version2, version2) app.blueprint(v1) app.blueprint(v2) # 生成路由 # /v1/something # /v2/somethingcopy()的签名与行为要点copy( name: str, # 必填新 Blueprint 的名称 url_prefix_default, version_default, version_prefix_default, allow_route_overwrite_default, strict_slashes_default, with_registration: bool True, # 是否把新实例注册到旧实例已注册的 app with_ctx: bool False, # 是否拷贝 ctx默认不拷贝 )内部实现先把原实例的_apps、routes、middlewares、exceptions、listeners、statics等属性备份reset()后做一次deepcopy再覆盖传入的新属性新实例的copied_from记录旧实例名注册时会把路由名中的旧名称替换为新名称避免命名冲突sanic/blueprints.py第 419-424 行若旧实例已注册且with_registrationTrue新实例会被自动注册到同一批应用但此时若旧实例存在_future_statics会抛出异常——静态路由无法在拷贝时重复注册第 255-260 行with_ctxFalse时新实例得到全新的空ctx。该行为在 tests/test_blueprints.py 中有对应测试如test_blueprint_copy_returns_blueprint_with_the_name_of_original_blueprint、test_blueprint_copy_returns_blueprint_with_overwritten_properties拷贝功能自 v21.9 起加入。六、BlueprintGroup分组、嵌套与组合BlueprintGroup定义于 sanic/blueprints.py实现为一个MutableSequence[Blueprint]的序列容器支持索引、切片、append、insert、__len__等全部列表式操作__getitem__/__setitem__/__delitem__还做了向后兼容处理见第 774-871 行。虽然可以直接实例化BlueprintGroup但源码注释明确建议优先使用Blueprint.group()工厂方法。6.1Blueprint.group()工厂staticmethod def group( *blueprints: Blueprint | BlueprintGroup, url_prefix: str | None None, version: int | str | float | None None, strict_slashes: bool | None None, version_prefix: str /v, name_prefix: str | None , ) - BlueprintGroupgroup()会创建BlueprintGroup并递归展开嵌套的列表/元组后append全部成员sanic/blueprints.py第 314-331 行。BlueprintGroup的属性属性含义url_prefix组级 URL 前缀会拼接在组内每个 Blueprint 前缀之前version组级版本号组内 Blueprint 未显式指定时继承strict_slashes组级严格斜杠行为version_prefix组级版本前缀默认/vname_prefix组级名称前缀用于多组复用同一 Blueprint 时避免命名冲突典型目录化用法完整代码见官方指南 guide/content/en/guide/best-practices/blueprints.mdapi/ ├── content/ │ ├── authors.py │ ├── static.py │ └── __init__.py ├── info.py └── __init__.py app.py# api/content/authors.py from sanic import Blueprint authors Blueprint(content_authors, url_prefix/authors) # api/content/static.py from sanic import Blueprint static Blueprint(content_static, url_prefix/static) # api/content/__init__.py content Blueprint.group(static, authors, url_prefix/content) # api/info.py info Blueprint(info, url_prefix/info) # api/__init__.py api Blueprint.group(content, info, url_prefix/api) # app.py app.blueprint(api)最终挂载路径为/api/content/authors、/api/content/static、/api/info组前缀逐层叠加。6.2 组级中间件、异常与便捷方法BlueprintGroup提供middleware()、exception()装饰器会递归地把同一个处理器应用到组内所有 Blueprintsanic/blueprints.pybp1 Blueprint(bp1, url_prefix/bp1) bp2 Blueprint(bp2, url_prefix/bp2) group Blueprint.group(bp1, bp2) group.middleware(request) async def group_middleware(request): print(common middleware applied for both bp1 and bp2) group.exception(Exception) def handler(request, exception): return text(Exception caught)此外还有便捷方法on_request/on_response分别等价于middleware(attach_torequest)/middleware(attach_toresponse)sanic/blueprints.py第 957-983 行。组级中间件与 Blueprint 级中间件的执行顺序、作用域隔离可以参考示例 examples/blueprint_middlware_execution_order.py。七、Blueprint 支持的功能全览除路由外Blueprint 与组还支持以下能力对应指南 guide/content/en/guide/best-practices/blueprints.md 的实操示例7.1 中间件仅作用于自身端点bp.middleware async def print_on_request(request): print(I am a spy) bp.middleware(request) async def halt_request(request): return text(I halted the request) bp.middleware(response) async def halt_response(request, response): return text(I halted the response)7.2 异常处理器from sanic.exceptions import NotFound bp.exception(NotFound) def ignore_404s(request, exception): return text(Yep, I totally found the page: {}.format(request.url))关于异常处理的通用机制可参考 guide/content/en/guide/best-practices/exceptions.md。7.3 静态文件bp Blueprint(bp, url_prefix/bp) bp.static(/web/path, /folder/to/serve) bp.static(/web/path, /folder/to/server, nameuploads)静态路由同样遵循{blueprint_name}.{name}的命名规则可用url_for反查 print(app.url_for(static, namebp.uploads, filenamefile.txt)) /bp/web/path/file.txt7.4 监听器bp.listener(before_server_start) async def before_server_start(app, loop): ... bp.listener(after_server_stop) async def after_server_stop(app, loop): ...监听器的事件语义可参考 guide/content/en/guide/basics/listeners.md。7.5 版本化Blueprint 是组织多版本 API 的推荐手段详见 guide/content/en/guide/advanced/versioning.mdauth1 Blueprint(auth, url_prefix/auth, version1) auth2 Blueprint(auth, url_prefix/auth, version2) app.blueprint(auth1) app.blueprint(auth2) # 挂载 /v1/auth 与 /v2/auth也可以对整组统一版本化auth Blueprint(auth, url_prefix/auth) metrics Blueprint(metrics, url_prefix/metrics) group Blueprint.group(auth, metrics, versionv1) # 挂载 /v1/auth 与 /v1/metrics对应测试见 tests/test_blueprints.py 中的test_blueprint_group_versioning与test_blueprint_group_strict_slashes。八、组合与命名空间name_prefix解决复用冲突Blueprint 可以注册到多个组组又可以继续嵌套形成任意组合。但同一 Blueprint 被多组复用时其路由名会冲突。name_prefixv23.6 起加入正是为此设计注册时名称会变成{group 的 name_prefix}_{blueprint 名}_{路由名}sanic/blueprints.py第 382-385 行叠加name_prefix再由app.generate_name()拼上应用名。bp1 Blueprint(bp1, url_prefix/bp1) bp2 Blueprint(bp2, url_prefix/bp2) bp1.add_route(lambda _: ..., /, nameroute1) bp2.add_route(lambda _: ..., /, nameroute2) group_a Blueprint.group(bp1, bp2, url_prefix/group-a, name_prefixgroup-a) group_b Blueprint.group(bp1, bp2, url_prefix/group-b, name_prefixgroup-b) app Sanic(TestApp) app.blueprint(group_a) app.blueprint(group_b)生成的路由端点名分别为TestApp.group-a_bp1.route1、TestApp.group-a_bp2.route2、TestApp.group-b_bp1.route1、TestApp.group-b_bp2.route2互不冲突。组合的极限案例下面的例子中两个 handler 因为 Blueprint 与组的自由嵌套最终被挂载为五个不同路由完整代码见官方指南app Sanic(__name__) blueprint_1 Blueprint(blueprint_1, url_prefix/bp1) blueprint_2 Blueprint(blueprint_2, url_prefix/bp2) group Blueprint.group( blueprint_1, blueprint_2, version1, version_prefix/api/v, url_prefix/grouped, strict_slashesTrue, ) primary Blueprint.group(group, url_prefix/primary) blueprint_1.route(/) def blueprint_1_default_route(request): return text(BP1_OK) blueprint_2.route(/) def blueprint_2_default_route(request): return text(BP2_OK) app.blueprint(group) app.blueprint(primary) app.blueprint(blueprint_1) # 挂载路径 # /api/v1/grouped/bp1/ # /api/v1/grouped/bp2/ # /api/v1/primary/grouped/bp1 # /api/v1/primary/grouped/bp2 # /bp1九、URL 生成url_for的命名规则当用url_for()生成 URL 时端点名遵循统一格式{blueprint_name}.{handler_name}例如对bp Blueprint(content_authors)下的/authors路由可通过app.url_for(content_authors.authors)反查 URL。url_for的完整参数语义_anchor、_external、_host、_scheme等特殊关键字定义在 sanic/app.py路由基础可参考 guide/content/en/guide/basics/routing.md。十、源码阅读路径速查若要深入源码建议按以下顺序阅读sanic/blueprints.py —lazy、Blueprint、BlueprintGroup完整实现983 行sanic/blueprint_group.py — 仅一行导出的模块入口BlueprintGroup实际定义在blueprints.py中sanic/app.py —Sanic.blueprint()注册入口与名称唯一性校验sanic/mixins/routes.py —route/add_route等底层路由装饰器lazy包装的源头sanic/mixins/middleware.py、sanic/mixins/listeners.py、sanic/mixins/exceptions.py — 各类 future 对象的_apply_*实现tests/test_blueprints.py 与 tests/test_blueprint_group.py — 覆盖拷贝、分组、版本化、严格斜杠、命名冲突等场景的测试用例是理解行为边界的权威参考。小结Blueprint 与 BlueprintGroup 构成了 Sanic 应用模块化的核心骨架前者以与Sanic一致的 API 封装单个业务域路由、中间件、异常、静态文件、监听器、信号通过lazy机制实现先注册后添加与多应用复用后者以序列容器 前缀合并机制支持任意层级的组合嵌套并借助name_prefix解决复用命名冲突。结合copy()与version参数可以低成本地维护多版本 API。理解register()内部路由 → 静态 → 中间件/异常 → 监听器 → 信号的应用顺序将帮助你在大型项目中更精准地组织代码边界。赞分享后端Web框架【免费下载链接】sanicAccelerate your web app development | Build fast. Run fast.项目地址https://gitcode.com/gh_mirrors/sa/sanic点击查看免费下载相关推荐Sanic 路由版本化实战指南从单路由到 BlueprintGroup 的完整 API Versioning 方案Sanic 路由版本化实战指南从单路由到 BlueprintGroup 的完整 API Versioning 方案 版本化是 API 工程中的标准实践当你在后端Web框架7个核心原则Sanic框架代码组织与模块划分完全指南7个核心原则Sanic框架代码组织与模块划分完全指南 Sanic是一个旨在加速Web应用开发的Python框架其核心理念是Build fast. Run后端Web框架如何永久保存微信聊天记录完全免费的本地数据导出解决方案如何永久保存微信聊天记录完全免费的本地数据导出解决方案 你是否曾经因为手机存储空间不足而不得不删除珍贵的微信聊天记录或者担心重要的对话信息在设备更换后永久丢创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考