Web 应用¶
canary_framework.web.asgi.app 是一个小的 Web 框架:路由是单元,应用也是单元,而且应用单元
自己就是一个 ASGI 应用。它站在 ASGI 协议的应用一侧,只依赖 pydantic。
它不提供依赖注入系统——依赖走 dep()。它不生成 OpenAPI,但公开了接口表,照着它写一份
只要几十行。
谁来服务它¶
ASGI 的两侧只认协议,所以可以任意组合:
| 应用 | 服务器 | 怎么写 |
|---|---|---|
本包的 App |
本框架的 Server |
class Gateway(Server): api = dep(LibraryApi) |
本包的 App |
uvicorn、hypercorn …… | app = LibraryApi(),然后 uvicorn main:app |
| FastAPI 等别的框架 | 本框架的 Server |
在 Server 的 @init 里 self.app = fastapi_app |
第一种,图由 Canary 驱动,监听是生命周期的一部分。第二种,图由服务器的 lifespan 消息驱动:
启动时应用单元连同它的依赖按序 init、start,停止时逆序回收——于是 --reload 与
--workers 照常可用:
暂行 API
扩展包在稳定之前可能在次版本中调整,见版本与兼容性。
一个完整的例子¶
import asyncio
from canary_framework import dep
from canary_framework.web.asgi.app import App, Request, Response, Router, error, get, post
from canary_framework.web.asgi.server import Server
class ReaderApi(Router, prefix="/readers"):
readers = dep(ReaderService)
@get
async def search(self, keyword: str | None = None, limit: int = 20) -> list[Reader]:
return await self.readers.search(keyword, limit)
@get("/{reader_id}")
async def show(self, reader_id: int) -> Reader:
return await self.readers.get(reader_id)
@post(status=201)
async def create(self, body: NewReader) -> Reader:
return await self.readers.create(body)
class Api(Router, prefix="/api"):
readers = dep(ReaderApi)
loans = dep(LoanApi)
class LibraryApi(App):
api = dep(Api)
@error(DomainError)
async def on_domain_error(self, request: Request, exc: DomainError) -> Response:
return Response.json({"msg": exc.message}, status=exc.code)
class Gateway(Server):
library = dep(LibraryApi)
port = 8010
async def main() -> None:
async with Gateway():
await asyncio.Event().wait()
asyncio.run(main())
路由¶
Router 是带前缀的单元,get / post / put / patch / delete 把它的方法标记为接口。
聚合就是依赖:dep() 一个路由单元,它就挂在自己之下,前缀逐层叠加。
- 路径省略时即所在单元的前缀本身:上例的
@get对应GET /api/readers。 {name}是路径参数,必须占一整段。- 成功时的状态码写在标记上:
@post(status=201)。 - 路由单元只有被
App或另一个路由单元直接依赖时才会被挂载;被两处依赖则出现在两处 前缀之下,背后是同一个实例。 - 接口方法是普通方法,测试里可以不经 HTTP 直接
await api.show(3)。
方法别叫 get
在类体里定义一个叫 get 的方法,会遮住它后面的 @get。给方法起别的名字。
匹配规则¶
应用在 @init 时把所有接口拍平成一张表:
- 不含参数的路径优先于含参数的:
/books/new先于/books/{book_id}。 - 都含参数时,静态段靠左的优先:
/a/b/{y}先于/a/{x}/c。 - 尾斜杠严格区分,不做重定向。
HEAD没有自己的接口时由GET应答。
形参怎么绑定¶
形参按以下顺序归类:
| 形参 | 来源 |
|---|---|
注解是 Request |
请求对象 |
| 名字出现在路径模板里 | 路径参数 |
名字是 body |
JSON 请求体;注解为 bytes 时是原始字节 |
| 其余 | 查询参数 |
- 请求体按名字认:只有叫
body的形参是请求体,所以一个接口最多一个。 - 查询参数有默认值即可选;注解是
list[...]之类时取全部同名值(?tag=1&tag=2)。 - 没有注解的形参按
str;没有注解的body是任意 JSON。 - 校验与转换交给 pydantic,任何它能校验的类型都可以用。请求体用的是它的 JSON 模式:直接
校验原始字节,所以
strict=True的模型也接受 JSON 里的日期、UUID 这类字符串。 - 请求头与 Cookie 不做注解魔法,写一个
request: Request自己读。
校验失败应答 422,一次报告全部出错的形参:
{"detail": [{"loc": ["query", "limit"], "msg": "Input should be a valid integer, ...", "type": "int_parsing"}]}
同步与异步¶
async def的接口在事件循环里运行。- 普通
def的接口放进线程池(asyncio.to_thread),里面的阻塞调用——同步的数据库驱动、requests、文件读写——不会卡住别的请求。
@error 标记的处理器同样如此。两点要留意:async def 里的阻塞调用仍然会卡住整个进程;
线程池里的方法与事件循环并发运行,读写单元上的状态时要自己保证线程安全。
返回值与响应¶
| 返回 | 应答 |
|---|---|
Response |
原样发出 |
None |
空响应,204(标记上另写了 status 时用它) |
| 其余 | 按返回注解序列化成 JSON |
返回注解只用来序列化,不重新校验返回值。
Response 用来自己决定状态码、响应头与内容类型:
return Response("pong") # 纯文本
return Response.json({"id": 7}, status=201, headers={"location": "/readers/7"})
return Response(self.events(), media_type="text/event-stream") # 异步迭代器:流式
异常¶
HTTPError 在接口、服务或任何被调用到的地方抛出都可以,应答 {"detail": ...}。路由不匹配
(404)、方法不允许(405,带 Allow 头)、校验失败(422)也是它。
@error(异常类型) 把应用单元的方法标记为处理器。异常交给类型最贴近的那个,返回值与接口的
返回值同样处理:
class LibraryApi(App):
@error(HTTPError)
def envelope(self, request: Request, exc: HTTPError) -> Response:
body = {"code": exc.status, "msg": exc.detail}
return Response.json(body, status=exc.status, headers=exc.headers)
HTTPError 可能带着头——405 的 Allow 就在 exc.headers 里——自己处理它时要一并带上。
处理器属于应用单元。同一个路由单元挂在两个应用之下时,它抛出的异常由各个应用自己的处理器 处理,没有处理器的那个应用按默认方式应答。
没有处理器的异常应答 500 并记到 canary_framework.web.asgi.app 这个日志器,响应里不带内部细节。
中间件¶
App 的 self.app 就是一个 ASGI 应用。子类的 @init 在它建好之后运行,包一层即可,任何
ASGI 中间件都能用。本包不自带中间件——跨域(CORS)这类需求用现成的 ASGI 中间件,例如
Starlette 的 CORSMiddleware:
class LibraryApi(App):
api = dep(Api)
@init
def wrap(self) -> None:
self.app = CORSMiddleware(self.app, allow_origins=["*"])
WebSocket¶
@websocket 把方法标记为 WebSocket 接口,和 HTTP 接口写在同一个路由单元里:
from canary_framework.web.asgi.app import Router, WebSocket, websocket
class RoomApi(Router, prefix="/rooms"):
rooms = dep(RoomService)
@websocket("/{room}")
async def chat(self, socket: WebSocket, room: str, name: str = "guest") -> None:
async for message in socket:
await socket.send(f"{name}@{room}: {message}")
- 路径和形参的写法与 HTTP 接口相同:路径参数、查询参数照常绑定和校验;注解为
WebSocket的形参是连接本身。没有请求体,也不能有Request形参——请求头从socket.headers读。 - 必须是
async def,返回值被忽略。 - 同一路径可以同时有 HTTP 接口和 WebSocket 接口,各走各的。
连接上能做的事:
await socket.receive() |
下一条消息:文本帧是 str,二进制帧是 bytes |
async for message in socket |
逐条收消息,对端离开时正常结束 |
await socket.send(data) |
str 发文本帧,bytes 发二进制帧 |
await socket.send_json(data) |
序列化成 JSON 发文本帧,pydantic 模型、dataclass 都行 |
await socket.accept(subprotocol, headers=...) |
接受握手 |
await socket.close(code, reason) |
关闭;还没接受时就是拒绝握手 |
headers、query、path_params、closed |
前三个与 Request 相同;closed 表示已经关闭 |
第一次收发时自动接受握手,只有要选子协议或附加响应头时才需要自己调用 accept。JSON 消息
自己解析,比如 Note.model_validate_json(await socket.receive())。
对端离开后,收发会抛出 WebSocketClosedError。接口里不必捕获它,框架把它当作正常结束;
离开时要清理什么,用 try / finally。
握手与出错¶
接受握手之前抛出的异常——路径不匹配(404)、形参校验失败(422)、你自己抛的 HTTPError——
在服务器支持时(uvicorn 支持)应答和 HTTP 接口一样的错误响应,否则拒绝握手(客户端看到
403)。所以鉴权就是在第一次收发之前检查、不通过就抛:
@websocket("/admin")
async def admin(self, socket: WebSocket, token: str) -> None:
if not self.auth.check(token):
raise HTTPError(403, "bad token")
...
接受之后,HTTPError 以 1008 关闭连接,其余异常以 1011 关闭并记日志。接口返回时连接若还
开着,以 1000 关闭。@error 处理器只处理 HTTP 接口。
服务器单元停止时,uvicorn 以 1012 关闭还连着的客户端,正在收发的接口因此结束。接口若长时间
在等别的东西,@stop 会一直等它,所以给服务器设上 timeout_graceful_shutdown,见
Web 服务器。
服务器要有 WebSocket 实现:canary-framework[server] 已经带上 wsproto。把应用交给你自己装的
uvicorn 时,装上 wsproto 并用 --ws wsproto——uvicorn 默认的 websockets-sansio 在拒绝握手时
会误报一条错误日志,见 Web 服务器。
接口表¶
@init 之后,App.endpoints 是拍平之后的全部接口,只读。每个 Endpoint 说明一个接口:
| 属性 | 含义 |
|---|---|
method、path |
HTTP 方法(WebSocket 接口是 "WEBSOCKET")与完整的路径模板(已带上逐层叠加的前缀) |
status |
成功时的状态码;方法返回 None 而这里是 200 时,实际应答 204 |
call、name |
绑定方法本身(可以取它的文档字符串),与它的限定名,如 ReaderApi.show |
params |
形参,每个 Param 有 name、source("path" / "query" / "body" / "request" / "websocket")、annotation、default、required |
returns |
返回注解;没有写时是 Any,-> None 是 type(None) |
顺序是应用单元自己的接口在前,然后是它依赖的路由单元的,按声明顺序。由 GET 应答的 HEAD 不单列。
本包不生成 OpenAPI,但这张表给出了生成它所需的一切,类型到 JSON Schema 的翻译交给 pydantic。 下面这个函数生成一份 OpenAPI 3.1 文档:
import inspect
from typing import Any
from pydantic import TypeAdapter
from canary_framework.web.asgi.app import Endpoint, Response
def openapi(endpoints: tuple[Endpoint, ...], title: str, version: str = "0.1.0") -> dict[str, Any]:
schemas: dict[str, Any] = {}
def schema(annotation: Any, mode: Any = "validation") -> dict[str, Any]:
found = TypeAdapter(annotation).json_schema(
ref_template="#/components/schemas/{model}", mode=mode
)
schemas.update(found.pop("$defs", {}))
return found
paths: dict[str, Any] = {}
for endpoint in endpoints:
if endpoint.method == "WEBSOCKET":
continue # OpenAPI 不描述 WebSocket
operation: dict[str, Any] = {"operationId": endpoint.name}
if endpoint.call.__doc__:
operation["summary"] = inspect.cleandoc(endpoint.call.__doc__).splitlines()[0]
operation["parameters"] = [
{"name": p.name, "in": p.source, "required": p.required, "schema": schema(p.annotation)}
for p in endpoint.params
if p.source in ("path", "query")
]
for p in endpoint.params:
if p.source == "body" and p.annotation is not bytes:
content = {"application/json": {"schema": schema(p.annotation)}}
operation["requestBody"] = {"required": p.required, "content": content}
if endpoint.returns is type(None):
status = 204 if endpoint.status == 200 else endpoint.status
operation["responses"] = {str(status): {"description": "No Content"}}
elif endpoint.returns in (Any, Response):
operation["responses"] = {str(endpoint.status): {"description": "OK"}}
else:
content = {"application/json": {"schema": schema(endpoint.returns, "serialization")}}
operation["responses"] = {
str(endpoint.status): {"description": "OK", "content": content}
}
paths.setdefault(endpoint.path, {})[endpoint.method.lower()] = operation
return {
"openapi": "3.1.0",
"info": {"title": title, "version": version},
"paths": paths,
"components": {"schemas": schemas},
}
应用单元自己的方法也可以是接口,所以把文档挂出来只要几行。子类的 @init 在表建好之后运行:
class LibraryApi(App):
api = dep(Api)
@init
def describe(self) -> None:
self.document = openapi(self.endpoints, "Library")
@get("/openapi.json")
async def spec(self) -> dict[str, Any]:
return self.document
要 Swagger UI 之类的页面,把任意一个静态的文档页指向 /openapi.json 即可。两个不同模块里
同名的模型会在 components.schemas 里互相覆盖,遇到时给其中一个改名。
启动时就报错的事¶
以下问题在 @init 或定义类时抛出 DeclarationError,不会留到请求到来时:
- 同一个方法与路径有两个接口;
- 路径参数没有对应的形参;
- 看起来是请求体的形参(pydantic 模型、dataclass、
dict)不叫body; *args/**kwargs,或注解无法解析、无法校验;- 前缀不以
/开头,或以/结尾; - WebSocket 接口不是
async def,或有body、Request形参;HTTP 接口有WebSocket形参。
不做的事¶
OpenAPI 的生成与文档页面(接口表够你自己写)、表单与文件上传、静态文件、后台任务。
测试¶
与其他单元一样用 running。不经网络:
async with running(LibraryApi) as api:
transport = httpx.ASGITransport(app=api)
async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
response = await client.get("/api/readers/7")
走真实的套接字:给 Gateway 的子类写 port = 0,见 Web 服务器。
httpx 不支持 WebSocket,WebSocket 接口走真实的套接字测,客户端用 websockets: