在前五篇中,笔者对applications.py
,routing.py
,requests.py
,responses.py
进行了解读。了解到了从app进入,到endpoint返回responses的大致流程。本篇将对其内容进行总结,方便记忆。
applications.py
Starlette类
Starlette(
debug: bool = False,
# 用于设置在出现错误时是否应返回调试回溯
routes: typing.Sequence[BaseRoute] = None,
# 一个由BaseRoute衍生类实例组成列表,用于定义路由
middleware: typing.Sequence[Middleware] = None,
# 中间件列表,左外右内
exception_handlers: typing.Dict[
typing.Union[int, typing.Type[Exception]], typing.Callable
] = None,
# 异常处理的字典,定义了一个状态码/异常类发生时,执行的处理函数
# 格式应该为handler(request, exc) -> response
on_startup: typing.Sequence[typing.Callable] = None,
# 启动时的调用项列表
on_shutdown: typing.Sequence[typing.Callable] = None,
# 结束时的调用项列表
lifespan: typing.Callable[["Starlette"], typing.AsyncGenerator] = None,
# 前两者结合的生命周期函数,启动和结束项用一个yield分隔开
)
def build_middleware_stack(self) -> ASGIApp
app构建时的方法,构建一个中间件堆栈,其返回值为ServerErrorMiddleware
其app属性指向下一个中间件,一直串到最内层中间件ExceptionMiddleware
,其app指向了router,即穿过了中间件层
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None
app被调用时的方法,即入口。在这里将传过来的内容,传递给中间件层的最外层。
routing.py
Router类
Router(
self,
routes: typing.Sequence[BaseRoute] = None,
# 路由列表
redirect_slashes: bool = True,
# 重定向斜杠
default: ASGIApp = None,
# 处理无法匹配项的最基础App
on_startup: typing.Sequence[typing.Callable] = None,
# 启动事件列表
on_shutdown: typing.Sequence[typing.Callable] = None,
# 结束事件列表
lifespan: typing.Callable[[typing.Any], typing.AsyncGenerator] = None,
# 上述两者的合并
)
async def not_found(self, scope: Scope, receive: Receive, send: Send) -> None
当没有定义default时,默认的default为not_found
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None
router的主入口进行路由的调度,重定向的分配,匹配失败的处理,以及可以执行lifespan
五个路由节点类
BaseRoutej基类,以及其四个衍生类
Route类
Route(
path: str,
# 路径
endpoint: typing.Callable,
# 路径对应的函数(使用者所写的那些)
methods: typing.List[str] = None,
# 支持的HTTP方法
name: str = None,
# 用于反向查找的名字
include_in_schema: bool = True,
# 暂时未知
)
def matches(self, scope: Scope) -> typing.Tuple[Match, Scope]
将router传过来的path与自身进行匹配
async def handle(self, scope: Scope, receive: Receive, send: Send) -> None
被router调用的函数,可以调用自己的app
WebSocketRoute类
WebSocketRoute(
path: str,
endpoint: typing.Callable,
name: str = None
)
同上
Mount
用于实现子路由,其app还是一个router
"""
例:
Route('/', homepage),
Mount('/users', routes=[
Route('/', users),
Route('/{username}', user)
])
用于实现子路由, 他的app是一个router
"""
Mount(
path: str,
app: ASGIApp = None,
routes: typing.Sequence[BaseRoute] = None,
name: str = None,
)
同上
Host
推测用于通过host匹配请求
Host(
host: str,
app: ASGIApp,
name: str = None
)
同上
requests.py
Request类
request是使用者在endpoint中最能直接获得的信息,尤其其中的scope,是整个请求从app入口一路到endpoint的处理信息的记录
Request(
scope: Scope,
receive: Receive = empty_receive,
send: Send = empty_send
)
https://www.starlette.io/requests/
关于request的详细方法,可以直接参考官方文档。
Response.py
Request类
Response(
content: typing.Any = None,
status_code: int = 200,
headers: dict = None,
media_type: str = None,
background: BackgroundTask = None,
)
def set_cookie
和delete_cookie
可以用于cookies的设置
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None
Response也可以调用,调用时会开始发送response数据
其余Response类在此略
何为app
asgi接受的Starlette实例是个app,每个中间件都是个app,Router是个app,route里面也包含app,而其中包括endpoint封装成的app,或者像Mount的app又是个Router
那么究竟什么是app,什么算作app?
我觉得,所有接收
(self, scope: Scope, receive: Receive, send: Send)
参数的方法函数,都是app。
app即可被其他app调用,也可以独立存在。他们都可以接收上述三个参数,并加以处理
每个app,都可能直接或间接包含一个app属性,用于将自己处理好的数据,传给下一个app。
Starlette实例app,它的app属性的值,是中间件堆栈最外层的app,它将三个方法传给堆栈最外层,而最外层中间件app,他的app属性,指向的是第二次app。最内层中间件app,指向了Router这个app,router中有许多route,每个route都有自己的app,router可以选择将数据传给那个route,而route的app,可能是由endpoint封装而成,代表流程以及接近终点,快返程了。也可能是一个子router,继续处理数据。
直到产生了response,response标志着返程的开始,“按app索骥”的路程才可能就此结束。
所以我们可以将app群组的职能对通常流程进行大体划分
Starlette实例app
→中间件堆栈app
→路由列表app
→endpoint封装app
注意:流程的终点不是endpoint,而是产生response
send与receive,究竟是在与谁通讯?
我猜测可能是ASGI服务器,也可能是直接发送给前端
这个需要在其他代码中寻找蛛丝马迹,或者等到了解ASGI服务器时,方可清晰理解。
当触发response的call中的send时starlette部分的工作才宣告结束
总结
简单的starlette流程在此已经解读完毕。但starlette是个强大的asgi工具包,源码解读的工作还远远没有结束。
下一章将开始进行其他次重要的模块源码解读。