Sanic 应用实例完全指南:从 `app = Sanic()` 到类型化定制
Sanic 应用实例完全指南:从 app = Sanic() 到类型化定制
本文以 Sanic 官方文档 guide/content/en/guide/basics/app.md 为核心,结合 sanic/app.py、sanic/config.py、sanic/mixins/listeners.py 等源码与测试,系统讲解 Sanic 应用实例的创建、上下文共享、App Registry、配置管理、工厂模式以及六大定制入口(配置、上下文、请求类、错误处理器、JSON 序列化、类型化应用),帮助你从「能跑」进阶到「按需定制」。
实例(Instance):一切的起点
Sanic 应用最基本的构件就是 sanic.app.Sanic 实例。虽然并非强制,但社区惯例是在名为 server.py 的文件中实例化它:
# /path/to/server.py
from sanic import Sanic
app = Sanic("MyHelloWorldApp")
从源码看,Sanic 类定义于 sanic/app.py#L109-L170,构造函数接受 14 个以上的参数,其中第一个 name 是必填项。命名并非毫无限制——根据类文档字符串,name 必须近似于合法的 Python 模块名,不能包含空格,但可以包含连字符:
# 非法:包含空格会报错
Sanic("This is not legal")
# 合法:连字符和下划线均可
Sanic("Hyphens-are-legal_or_also_underscores")
name 不仅仅是个标签,它还是应用在 App Registry 中注册的唯一键(后文详述),因此值得起一个稳定且唯一的名字。
应用上下文(Application Context):跨模块共享数据的标准姿势
大多数应用都有在代码库不同部分之间共享或复用数据/对象的需求。Sanic 为此在应用实例上提供了 ctx 对象——它是一个「自由空间」,开发者可以把任何对象或数据挂载上去,使其在整个应用生命周期内存在。
最常见的模式是把数据库实例挂到应用上:
app = Sanic("MyApp")
app.ctx.db = Database()
从 sanic/app.py#L369 可以看到,self.ctx 在构造时默认为 ctx or SimpleNamespace(),即 Python 标准库的 types.SimpleNamespace,因此可以任意设置属性。
虽然上面的直接赋值可以工作,但官方推荐的最佳实践是把对象挂载放到应用启动监听器(listener)中。Sanic 提供了四个服务器生命周期监听器(定义于 sanic/mixins/listeners.py):
before_server_start:在所有 worker 进程上触发,官方明确建议在此初始化全局性、跨请求共享的资源(如数据库连接池、缓存客户端);after_server_start:适合启动后台任务(如定时清理缓存、健康检查),注意此事件触发前可能已有请求被处理,因此不应在此初始化请求所需的资源;before_server_stop:服务器开始关闭前触发,适合停止after_server_start启动的后台任务;after_server_stop:所有请求处理完毕、服务器关闭后触发,适合清理before_server_start初始化的资源(如关闭连接池)。
app = Sanic("MyApp")
@app.before_server_start
async def attach_db(app, loop):
app.ctx.db = Database()
放在监听器里的好处:资源创建时机可控、失败可在启动阶段暴露、worker 进程各自正确初始化,且关闭时也有对应的清理时机。
App Registry:按名称找回你的应用
每当你实例化一个 Sanic 应用,它都会自动注册到 Sanic 的类级注册表中。这在「需要从无法直接访问实例的地方取回应用」时非常有用。
# ./path/to/server.py
from sanic import Sanic
app = Sanic("my_awesome_server")
# ./path/to/somewhere_else.py
from sanic import Sanic
app = Sanic.get_app("my_awesome_server")
注册表是类变量 _app_registry: ClassVar<a href="https://link.gitcode.com/i/4c2fd9cb18dc8a3048199fdc36bf659a" target="_blank">dict[str, Sanic]]([sanic/app.py#L224),构造 Sanic 实例时会在 sanic/app.py#L391 自动调用 register_app。底层还暴露了 Sanic.register_app(app) 与 Sanic.unregister_app(app) 两个类方法(sanic/app.py#L2113-L2167),后者通常用于测试清理或明确移除实例的场景。
Sanic.get_app 的几个行为要点(见 sanic/app.py#L2170-L2239):
-
按名查找:
Sanic.get_app("name")返回对应实例;若不存在,默认抛出sanic.exceptions.SanicException。 -
强制创建:传入
force_create=True,当名称不存在时会直接新建并返回该名称的实例:app = Sanic.get_app( "non-existing", force_create=True, ) -
唯一实例免参取回:若注册表中只有一个 Sanic 实例,
Sanic.get_app()不带任何参数即可返回它:Sanic("My only app") app = Sanic.get_app()若存在多个实例却省略名称,会抛出
SanicException("Multiple Sanic apps found, ...");若一个都没有,则抛出SanicException("No Sanic apps have been registered.")。
注意:源码在
get_app的 docstring 中给出了警告——避免在全局作用域调用Sanic.get_app(),因为 import 顺序可能导致全局代码先于实例创建执行而报错;它最适合放在应用实例创建之后才被调用的函数或方法中。
配置(Configuration):点号访问与字典访问双通道
Sanic 把配置保存在实例的 config 属性中,该属性的类型是继承自 dict 的 sanic/config.py#L131 Config 类。你可以同时用点号记法或字典记法修改配置:
app = Sanic('myapp')
app.config.DB_NAME = 'appdb'
app.config['DB_USER'] = 'appuser'
db_settings = {
'DB_HOST': 'localhost',
'DB_NAME': 'appdb',
'DB_USER': 'appuser'
}
app.config.update(db_settings)
从源码看,Config 重写了 __getattr__ / __setattr__ / __setitem__(sanic/config.py#L212-L222),底层都归结为字典的读写与 update,因此两种写法完全等价。update 还支持传入可转换为字典的对象(如另一个 Config、字典、甚至 Python 配置文件路径)。
关于键名大小写,官方提示:配置键「应该」全大写,但这主要是约定,小写在大多数情况下也能工作:
app.config.GOOD = "yay!"
app.config.bad = "boo"
Config 在初始化时(sanic/config.py#L180-L210)会载入 DEFAULT_CONFIG(sanic/config.py#L31-L73),其中内置了诸如 REQUEST_MAX_SIZE=100_000_000、REQUEST_TIMEOUT=60、KEEP_ALIVE_TIMEOUT=120、WEBSOCKET_MAX_SIZE=2**20、FORWARDED_FOR_HEADER、PROXIES_COUNT 等大量开箱即用的键,并默认以 SANIC_ 前缀自动加载环境变量(load_environment_vars)。更完整的配置专题见 guide/content/en/guide/running/configuration.md。
工厂模式(Factory Pattern):告别全局单例
本文档大量示例都在 server.py 的「全局作用域」实例化应用,这对 hello world 式的极简应用很常见,但工厂模式往往更优:工厂只是一个返回目标对象实例的函数,它把实例化过程抽象出来,也让应用实例更易隔离、更便于测试和多环境创建。
一个极简工厂:
# ./path/to/server.py
from sanic import Sanic
from .path.to.config import MyConfig
from .path.to.some.blueprint import bp
def create_app(config=MyConfig) -> Sanic:
app = Sanic("MyApp", config=config)
app.blueprint(bp)
return app
工厂模式带来的一个直接收益是:Sanic CLI 能识别这种模式并直接运行你的应用:
sanic path.to.server:create_app
即用「模块路径:工厂函数名」的方式启动,CLI 会调用 create_app() 得到实例再运行,这样路由、蓝图、监听器的注册都被封装在工厂内,天然规避了 get_app 在全局作用域调用的风险。
定制(Customization):六大入口按需改造应用实例
Sanic 构造函数本身就是一个巨大的定制入口(完整参数列表见 sanic/app.py#L137-L170 的 docstring),以下逐一展开。
1. 自定义配置类
最简单的定制是把自定义配置对象直接传入 Sanic(..., config=...)。官方强烈建议:自定义配置类要继承 sanic.config.Config,以继承其全部行为(环境变量加载、默认值、post-set 校验等),并可在子类中添加属性或自定义逻辑。该能力 v21.6 引入。
from sanic.config import Config
class MyConfig(Config):
FOO = "bar"
app = Sanic(..., config=MyConfig())
一个非常实用的场景是:当你的配置文件格式不是 Sanic 原生支持的格式(原生支持见 guide/content/en/guide/running/configuration.md#using-sanicupdateconfig)时,你可以写一个自定义 Config 子类来自行加载。比如加载 TOML 配置:
from sanic import Sanic, text
from sanic.config import Config
class TomlConfig(Config):
def __init__(self, *args, path: str, **kwargs):
super().__init__(*args, **kwargs)
with open(path, "r") as f:
self.apply(toml.load(f))
def apply(self, config):
self.update(self._to_uppercase(config))
def _to_uppercase(self, obj: Dict[str, Any]) -> Dict[str, Any]:
retval: Dict[str, Any] = {}
for key, value in obj.items():
upper_key = key.upper()
if isinstance(value, list):
retval[upper_key] = [
self._to_uppercase(item) for item in value
]
elif isinstance(value, dict):
retval[upper_key] = self._to_uppercase(value)
else:
retval[upper_key] = value
return retval
toml_config = TomlConfig(path="/path/to/config.toml")
app = Sanic(toml_config.APP_NAME, config=toml_config)
这个示例的核心思路:在 __init__ 里读文件,通过递归把 TOML 的键全部转成大写,再调用继承自 Config 的 update 完成注入。由于 update 对转换器、setter 和 post-set 逻辑一视同仁,自定义格式与原生格式在行为上保持一致。
2. 自定义上下文对象
默认应用上下文是 SimpleNamespace(),允许任意设置属性。但你也可以传入任意对象作为 ctx。该能力 v21.6 引入。
app = Sanic(..., ctx=1)
app = Sanic(..., ctx={})
class MyContext:
...
app = Sanic(..., ctx=MyContext())
对应地,sanic/app.py#L369 中 self.ctx = cast(ctx_type, ctx or SimpleNamespace())——当传入非空对象时原样使用。用自定义类的好处是可以在上下文上定义方法、属性校验或类型注解,配合后文「类型化应用」可以享受 IDE 的完整提示。
3. 自定义请求类
有时你会希望 Sanic 使用你自己的 Request 子类而非默认的 Request。一个经典场景是修改默认的 request.id 生成器。
⚠️ 重要:传给
request_class的是类本身,不是实例。
import time
from sanic import Request, Sanic, text
class NanoSecondRequest(Request):
@classmethod
def generate_id(*_):
return time.time_ns()
app = Sanic(..., request_class=NanoSecondRequest)
@app.get("/")
async def handler(request):
return text(str(request.id))
从源码看,sanic/app.py#L376 处 self.request_class = request_class or Request 保存类引用,请求处理时 Sanic 会用该类实例化请求对象。此外,请求还支持自定义请求上下文:默认的 Request.ctx 由 make_context() 工厂方法创建(见 sanic/request/types.py),同样可以重写。
4. 自定义错误处理器
你可以传入自定义的错误处理器,接管没有专门处理器的异常。更多细节见 guide/content/en/guide/best-practices/exceptions.md 的 Custom error handling 一节。
from sanic.handlers import ErrorHandler
class CustomErrorHandler(ErrorHandler):
def default(self, request, exception):
''' handles errors that have no error handlers assigned '''
# You custom error handling logic...
return super().default(request, exception)
app = Sanic(..., error_handler=CustomErrorHandler())
对应源码 sanic/app.py#L370:self.error_handler = error_handler or ErrorHandler()。ErrorHandler 基类位于 sanic/handlers/error.py,重写 default 时记得调用 super().default(request, exception) 以保留默认行为作为兜底。
5. 自定义 dumps / loads:接管 JSON 序列化
有时需要提供自定义函数把对象序列化为 JSON(dumps),或反序列化(loads,v22.9 引入)。例如使用 ujson 并关闭正斜杠转义:
import ujson
dumps = partial(ujson.dumps, escape_forward_slashes=False)
app = Sanic(__name__, dumps=dumps)
或者直接使用其他库:
from orjson import dumps
app = Sanic("MyApp", dumps=dumps)
反序列化同理:
from orjson import loads
app = Sanic("MyApp", loads=loads)
从源码看,传入的 dumps/loads 会被分别挂到 BaseHTTPResponse._dumps 与 Request._loads(sanic/app.py#L393-L396),从而影响所有响应序列化与请求体解析。这对于追求极致 JSON 性能或需要自定义编码规则(如 datetime 格式)的应用很有价值。
6. 类型化应用(Typed Application)与类型化请求
自 v23.6 起,Sanic 是泛型类 Sanic<a href="https://link.gitcode.com/i/2e22cd5b6c29330c87da174ae84f5992" target="_blank">config_type, ctx_type](见 [sanic/app.py#L109-L116),默认实例的完整类型注解是:
sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]
两个泛型参数含义:
- 第一个:配置对象的类型,默认
sanic.config.Config,可以是其任意子类; - 第二个:应用上下文的类型,默认
types.SimpleNamespace,可以是任意对象(如上面的ctx=...)。
配合 mypy 的 reveal_type,可以直观看到类型如何随参数变化:
from sanic import Sanic
from sanic.config import Config
class CustomConfig(Config):
pass
app = Sanic("test", config=CustomConfig())
reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]"
sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]
传入自定义上下文时:
from sanic import Sanic
class Foo:
pass
app = Sanic("test", ctx=Foo())
reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, main.Foo]"
sanic.app.Sanic[sanic.config.Config, main.Foo]
两者同时定制:
from sanic import Sanic
from sanic.config import Config
class CustomConfig(Config):
pass
class Foo:
pass
app = Sanic("test", config=CustomConfig(), ctx=Foo())
reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, main.Foo]"
sanic.app.Sanic[main.CustomConfig, main.Foo]
官方推荐的进阶用法:为你的应用实例定义一个类型别名,然后用于注解监听器与处理器。该能力 v23.6 引入。
# ./path/to/types.py
from sanic.app import Sanic
from sanic.config import Config
from myapp.context import MyContext
from typing import TypeAlias
MyApp = TypeAlias("MyApp", Sanic[Config, MyContext])
# ./path/to/listeners.py
from myapp.types import MyApp
def add_listeners(app: MyApp):
@app.before_server_start
async def before_server_start(app: MyApp):
# do something with your fully typed app instance
await app.ctx.db.connect()
# ./path/to/server.py
from myapp.types import MyApp
from myapp.context import MyContext
from myapp.config import MyConfig
from myapp.listeners import add_listeners
app = Sanic("myapp", config=MyConfig(), ctx=MyContext())
add_listeners(app)
类型化请求同样支持。默认请求实例类型为:
sanic.request.Request[
sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace],
types.SimpleNamespace
]
两个泛型参数含义:
- 第一个:应用实例的类型,默认
Sanic[Config, SimpleNamespace],可以是其任意子类; - 第二个:请求上下文的类型,默认
types.SimpleNamespace,可以是任意对象(见上文 自定义请求类)。
承接上面的类型别名示例,可以这样注解路由处理器:
from sanic import Request
from myapp.types import MyApp
from types import SimpleNamespace
def add_routes(app: MyApp):
@app.get("/")
async def handler(request: Request[MyApp, SimpleNamespace]):
# do something with your fully typed app instance
results = await request.app.ctx.db.query("SELECT * FROM foo")
如果你有自定义请求类、且它生成自定义请求上下文对象,还可以精确地注解:
from sanic import Request, Sanic
from sanic.config import Config
class CustomConfig(Config):
pass
class Foo:
pass
class RequestContext:
foo: Foo
class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]):
@staticmethod
def make_context() -> RequestContext:
ctx = RequestContext()
ctx.foo = Foo()
return ctx
app = Sanic(
"test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest
)
@app.get("/")
async def handler(request: CustomRequest):
# Full access to typed:
# - custom application configuration object
# - custom application context object
# - custom request context object
pass
这里 make_context 对应 sanic/request/types.py 中 Request.make_context 的默认实现(返回 SimpleNamespace),重写后每次请求的 request.ctx 就是你的 RequestContext 实例。自定义请求上下文更完整的内容见 guide/content/en/guide/basics/request.md 的 Custom request context 一节。该能力 v23.6 引入。
仓库中 tests/typing/samples/app_fully_custom.py 正是「自定义 Config + 自定义 ctx」组合的 typing 测试样例,可作为类型化应用的实际参考;完整的 API 参数细节可查阅官方 API 文档的 sanic.app 部分(仓库中文档入口见 docs/sanic/api/app.rst)。
小结
| 关注点 | 关键 API / 入口 | 底层实现 |
|---|---|---|
| 实例创建 | Sanic(name, ...) |
sanic/app.py#L311 |
| 共享数据 | app.ctx.*、启动监听器 |
sanic/mixins/listeners.py |
| 按名取回 | Sanic.get_app(name, force_create=...) |
sanic/app.py#L2170 |
| 配置读写 | app.config.X / app.config["X"] / update |
sanic/config.py |
| 工厂启动 | sanic path.to.server:create_app |
Sanic CLI |
| 定制入口 | config / ctx / request_class / error_handler / dumps / loads |
sanic/app.py#L137-L170 |
| 类型安全 | Sanic<a href="https://link.gitcode.com/i/9b3d9a07b6be01803bba79c4e156ef85" target="_blank">Config, Ctx]、Request[Sanic, Ctx] |
[sanic/app.py#L109、sanic/request/types.py |
掌握这些应用级基础后,可以继续深入 guide/content/en/guide/basics/handlers.md、guide/content/en/guide/basics/routing.md 与 guide/content/en/guide/basics/blueprints.md(仓库文档入口 guide/content/en/guide/basics),搭建结构清晰、类型安全、可测试的 Sanic 应用。