mcpField
L
litestar-routing

litestar-routing

github.com/alti3开发740 次安装33 周前更新
代码仓库

关于 litestar-routing

litestar-routing 是面向 Litestar API 开发者的技能，涵盖路由声明与组合、参数行为，以及路由正确性和 OpenAPI 输出检查。

主要功能

  1. 01应用、路由器与控制器组合
  2. 02带类型的处理器和语义装饰器
  3. 03路径、查询、标头与 Cookie 参数
  4. 04路由元数据与反向路由
  5. 05路由验证检查清单

适用场景

  1. 01设计 API 路由树
  2. 02定义并验证路由参数
  3. 03检查反向路由和 OpenAPI 路径

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alti3/litestar-skills --skill litestar-routing

安装后在 Claude Code 中输入/litestar-routing确认已加载。

附带文件agents/openai.yaml

详细介绍

路由

当 API 路径设计、处理器注册、路由组合和参数行为是任务的核心时，请使用此技能。

执行工作流

  1. 使用语义化处理器装饰器和严格的类型注解定义端点契约。
  2. 选择组合模型：
  3. 将简单处理器直接注册到 app。
  4. 使用路由器对路径分组并构建嵌套路由树。
  5. 使用控制器，在共享的控制器路径下按面向对象的方式对端点分组。
  6. 选择参数来源和约束（路径／查询／请求头／Cookie／分层参数）。
  7. 应用路由元数据和索引（name、opt），以便发现路由并挂接策略。
  8. 验证反向路由、路径 + 方法组合的唯一性，以及分层优先级行为。

实现规则

  • 保持 URL 设计稳定、面向资源，并考虑版本。
  • 保持处理器精简；将业务逻辑委托给服务。
  • 优先使用语义化装饰器（@get、@post 等），而不是 @route()，以便更清晰地描述 OpenAPI 操作。
  • 使用明确的路径转换器和范围更窄的参数类型。
  • 将动态注册视为例外；避免将其用于常规拓扑结构。
  • 在作用范围最小且有效的层级应用元数据和守卫。
  • 为所有处理器参数和返回值提供完整的类型注解。

路由拓扑：App、路由器、控制器

在 App 层级注册
  • Litestar(route_handlers=[...]) 是根注册点。
  • 注册的组件会添加到根路径 / 下。
  • 将多个路径组成的列表传给装饰器，即可将处理器挂载到多个路径。
动态注册
  • 只有确实需要在运行时注册时，才使用 app.register(handler)。
  • App 实例可通过连接对象（Request、WebSocket、ASGIConnection）获取，因此可从处理器／中间件／依赖项中调用动态注册。
  • 应谨慎使用动态注册，因为它会增加运维复杂性。
路由器
  • Router 可注册控制器、处理器和嵌套路由器。
  • 嵌套路由器会组合路径；将路由器 A 注册到路由器 B 时，会把 A 的路径追加到 B 的路径下。
控制器
  • 控制器是带有类级别 path 的 Controller 子类。
  • 控制器路径会作为每个路由处理器方法路径的前缀。
  • 如果省略 path，默认值为 /。
  • 每个有效路由树中的路径 + HTTP 方法组合必须保持唯一。

多次注册组件

  • 控制器可以在不同路由器中多次注册；每个路由器都会创建自己的控制器实例。
  • 独立处理器也可以多次注册；Litestar 会为每个注册上下文复制处理器。
  • 路由器可以嵌套，但注册后就不能再次注册。

路由处理器

核心行为
  • 使用 Litestar 装饰器构建处理器，可应用于函数或控制器方法。
  • 同步和异步可调用对象均受支持。
  • 对于同步处理器：
  • sync_to_thread=True 会在线程池中运行（适用于阻塞代码）。
  • sync_to_thread=False 表示该同步代码不会阻塞。
  • 如果不明确指定同步行为，可能会产生警告。
声明路径
  • 路径可以作为位置参数（@get("/x")）或关键字参数（@get(path="/x")）传入。
  • 路径可以是列表，以便注册多个路径并设置可选的路径参数模式。
类型注解要求
  • 所有处理器参数和返回值都必须有类型注解。
  • 缺少注解会在应用启动时引发 ImproperlyConfiguredException。
保留关键字参数注入

保留名称包括：

  • cookies、headers、query
  • request（HTTP 处理器）
  • socket（WebSocket 处理器）
  • scope、state、body（HTTP 处理器的请求体）

如果发生冲突，请使用其他参数命名方式。

HTTP 处理器
  • @route() 会映射到 HTTPRouteHandler，但通常不建议在常规 CRUD 风格的 API 中使用。
  • 优先使用语义化装饰器：
  • @get、@post、@put、@patch、@delete、@head
WebSocket 处理器
  • @websocket() 直接支持底层套接字处理。
  • 对于更高层级的实时模式，请使用专用的 WebSocket 架构模式（参见跨技能交接）。
ASGI 处理器
  • @asgi() / ASGIRouteHandler 支持自定义 ASGI 应用。
  • ASGI 处理器的签名仅限于 scope、receive、send。
  • ASGI 处理器必须是异步的。

挂载 ASGI 应用

  • 使用 @asgi(..., is_mount=True) 在路径前缀上挂载子应用行为。
  • 挂载的处理器会接收此前缀下的所有流量。
  • 使用 copy_scope=True 时，转发的 scope["path"] 会被重写为相对于挂载根路径的值。
  • 这适用于集成第三方 ASGI 应用。

路由索引与反向路由

  • 为处理器设置明确且唯一的 name，以便稳定查找。
  • 名称必须唯一；重复名称会引发 ImproperlyConfiguredException。
  • route_reverse(name, **params) 可构建路径。
  • request.url_for(name, **params) 可构建绝对 URL。
  • 避免对具有多个模糊匹配路径的处理器执行反向查找；结果选择可能无法预测。

使用 opt 设置任意路由元数据

  • 所有路由装饰器都接受 opt={...} 元数据。
  • 路由装饰器上的任意关键字参数会合并到 opt 中。
  • opt 可供守卫、请求路由处理器上下文和 ASGI 作用域使用。
  • opt 采用分层设置（应用／路由器／控制器／处理器），并按优先级合并。
  • 发生键冲突时，离处理器最近的层级优先。

签名命名空间解析

  • Litestar 会为处理器／依赖项构建运行时签名模型。
  • 如果类型仅在 TYPE_CHECKING 下导入，请通过以下方式解析：
  • 根据需要在应用／路由器／控制器／处理器层级设置 signature_types=[...]。
  • 当别名名称与运行时类型 __name__ 不同时，使用 signature_namespace={...}。

默认签名命名空间包括：

  • Headers、ImmutableState、Receive、Request、Scope、Send、State、WebSocket、WebSocketScope

参数：路径、查询、请求头、Cookie、分层

路径参数
  • 在路由路径中以 {name:type} 声明，例如 {user_id:int}。
  • 支持的路径转换器类型包括：
  • date、datetime、decimal、float、int、path、str、time。
  • 只要强制转换有效，路径转换器类型与函数注解就不必完全一致。
  • 路径中可以存在未在函数签名中声明的路径参数；这些参数仍会经过验证并写入文档。
Parameter() 辅助函数
  • 将 Parameter(...) 与 Annotated[...] 搭配使用，以添加额外验证和 OpenAPI 元数据。
  • 支持约束和文档属性（例如 gt、lt、标题／描述／示例）。
查询参数
  • 默认情况下，所有非路径函数关键字参数都会被视为查询参数。
  • 查询参数默认必填。
  • 默认值会在运行时产生类似可选参数的行为：省略时使用默认值。
  • 可选注解（str | None / Optional[str]）表示可为空的查询参数。
  • 查询值可转换为更丰富的类型（例如日期时间、数字、列表）。
其他名称与约束
  • 通过 Parameter(query="externalName") 重映射 URL 查询参数名称。
  • 通过 Parameter(...) 应用验证约束，例如数值范围限制。
枚举查询参数文档
  • 默认情况下，枚举文档字符串会作为架构描述。
  • 当同一枚举在不同端点需要不同的参数描述时，请使用 schema_component_key。
请求头和 Cookie 参数
  • 必须使用 Parameter(header="...") 或 Parameter(cookie="...") 声明。
  • 其他行为遵循查询参数的解析／验证模型。
分层参数
  • 可在应用／路由器／控制器／处理器层级声明参数。
  • 分层声明会参与验证和 OpenAPI 生成。
  • 处理器本地声明可进一步收紧外层的约束。
  • 非处理器层级不能声明路径参数。

验证清单

  • 确认 route_handlers 拓扑解析为预期的最终路径。
  • 确认路径+方法操作唯一，处理程序名称唯一。
  • 确认控制器与路由器的路径组合符合预期。
  • 确认同步处理程序已明确决定是否使用 sync_to_thread。
  • 确认所有处理程序参数和返回值都存在类型注解。
  • 确认保留关键字参数与注入的依赖项不会意外冲突。
  • 确认查询、请求头、Cookie 和路径参数会按预期进行验证和类型转换。
  • 确认分层参数会强制执行外层约束，并正确处理处理程序覆盖项。
  • 确认索引处理程序的反向路由（route_reverse / url_for）具有确定性。
  • 确认各层之间的 opt 元数据合并行为正确。
  • 确认挂载的 ASGI 应用会收到预期的重写路径语义。
  • 确认 OpenAPI 输出与生效路径、参数和操作拆分相符。

跨技能协作

  • 使用 litestar-requests 和 litestar-responses 深入了解传输契约。
  • 使用 litestar-authentication 和 litestar-dependency-injection 处理路由范围内的安全机制和服务。
  • 使用 litestar-websockets 设计更高层级的 WebSocket 会话架构。
  • 使用 litestar-openapi 验证操作 ID、参数架构和路由文档的准确性。

Litestar 参考资料

评论

支持 Markdown