跳转至

Web 应用

canary_framework.web.asgi.app 是一个小的 Web 框架:路由是单元,应用也是单元,而且应用单元 自己就是一个 ASGI 应用。它站在 ASGI 协议的应用一侧,只依赖 pydantic。

pip install "canary-framework[app]"        # 只要应用
pip install "canary-framework[web]"        # 应用 + 本框架的服务器单元

它不提供依赖注入系统——依赖走 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 照常可用:

# main.py
app = LibraryApi()
uvicorn main:app --reload

暂行 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")   # 异步迭代器:流式

异常

raise HTTPError(404, "no such reader")

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:

async with running(Gateway) as gateway:     # Gateway 的子类,port = 0
    async with websockets.connect(f"ws://127.0.0.1:{gateway.port}/rooms/a") as client:
        await client.send("hi")
        assert await client.recv() == "guest@a: hi"