用途:当 API 路径设计、处理器注册、路由组合与参数行为是任务核心时使用本技能。
主要能力:通过语义化装饰器与严格类型注解定义端点契约;选择注册模型——在 app 上直接注册简单处理器,用 Router 做路径分组与嵌套路由树,用 Controller 子类在共享路径下做 OOP 式分组。可选择路径/查询/请求头/Cookie/分层参数的来源与约束,应用路由元数据与索引(name、opt)。
实现规则:URL 设计保持稳定、面向资源并带版本;处理器保持精简,业务逻辑交给服务层;优先使用 @get、@post 等语义装饰器而非 @route(),以获得更清晰的 OpenAPI 操作;使用显式路径转换器与更窄的参数类型;动态注册仅作例外;元数据与守卫应用在最窄有效范围;所有处理器参数与返回值保持完整类型注解。
关键机制:App(route_handlers=[...]) 是根注册点;Router 可注册 Controller、处理器与嵌套 Router;Controller 类级 path 作为各方法路径前缀,省略时默认 /。路径与 HTTP 方法组合须在有效路由树中唯一。处理器支持同步与异步;同步处理器用 sync_to_thread=True/False 显式声明线程行为。路径写作 {name:type},支持 date、datetime、decimal、float、int、path、str、time。非路径函数 kwarg 默认视为查询参数,默认必填。请求头与 Cookie 需用 Parameter(header=...) / Parameter(cookie=...) 声明。可用 opt={...} 携带任意元数据并按层合并。反向路由可用 route_reverse(name, **params) 或 request.url_for(name, **params),需为处理器设置唯一 name。
限制:缺失注解会在启动时抛出 ImproperlyConfiguredException;name 重复同样报错;已注册的 Router 不可重复注册;多路径匹配时反向查找结果可能不确定;动态注册会增加运维复杂度,应避免用于常规拓扑。版本、收费与平台信息暂未提供。