SuperAPI AI 工具集

hyper-architecture-axum

编程与开发

查看项目

更新于 11-04 21:28

技能介绍

用途

hyper-architecture-axum 是一个面向 Axum(Rust)HTTP 服务器的架构约束技能,用于构建、审查、重构或审计 Axum 服务的架构。技能在应用任何 Axum 规则前,会先通过 Cargo.toml 中的 axum 依赖、axum::Router、axum::serve、tokio::main 等迹象确认目标确实是 Axum 服务器;若目标属于 Actix Web、Rocket、Poem、warp 等其他框架,或是不涉及架构边界的纯复制修改,则不适用。

主要能力

技能围绕一组主题规则文件组织,覆盖:

  • 项目结构:crate 与模块归属、依赖方向、工作区与结构性迁移(rules/project-structure.md)
  • 路由:Router 组合、嵌套与合并、路径语法、回退路由、版本前缀(rules/routes.md)
  • 处理函数:函数签名、提取器顺序、State、Path/Query/Json、类型化拒绝(rules/handlers.md)
  • 中间件:tower 层、from_fn、route_layer、层顺序、tower-http 栈、HandleErrorLayer(rules/middleware.md)
  • 验证:serde 与 validator 边界、自定义验证提取器、错误映射(rules/validation.md)
  • 数据库:SQLx 连接池、查询、离线模式、迁移、事务、仓储边界(rules/database.md)
  • OpenAPI:utoipa 与 utoipa-axum 定义、规范端点、Swagger UI 暴露策略、契约漂移(rules/openapi.md)
  • 错误:AppError、IntoResponse、错误信封、404/405 行为(rules/errors.md)
  • 测试:tower::ServiceExt::oneshot、axum-test、集成测试与数据库测试(rules/testing.md)
  • 平台:main.rs 启动、配置、axum::serve、优雅关闭、tracing(rules/platform.md)
  • 约定:Rust 命名、模块、导入、clippy 与风格(rules/conventions.md)

技能还附带官方参考文档摘录(axum、tower、sqlx、utoipa 及生态 crate),并据此区分“官方行为”与“Hypercore 约定”:官方 crate 文档在 API 事实上优先,Hypercore 约定用于标注比 axum 更严格的要求。

使用方式

技能通过参数调整修复范围:无参数时审查并修复请求或触及的 Axum 范围;“전체 수정”“full fix”“fix all”进入全量修复模式,扫描整个检测到的 Axum crate 并修复所有安全、局部、可逆、可验证的违规;“공식 기본만”“official defaults only”则以官方 crate 行为为默认面,把 Hypercore 专属约定降级为可选发现。

执行流程分为:确认目标为 Axum 服务器;加载触及面对应的规则文件;依据关键门禁判断计划变更;在触及范围内应用低风险自动修复;按模块命名、Router 组合、处理函数与验证、数据库边界、中间件与错误、OpenAPI、启动与可观测性的顺序实施并验证。

低风险自动修复包括:调整提取器顺序使消费 body 的提取器位于最后、把处理器中的直接 SQLx 查询移入仓储或服务、用共享 AppState 连接池替代每次请求的 pool.clone()、补充缺失的仓储包装或服务调用、用 FromRef 子状态替代传递整个 AppState、把直接的 sqlx::Error 响应转换为既有 AppError、为已发布规范的公开路由补充 utoipa 注解、把 axum::serve 或监听绑定移出路由模块、把驼峰或短横线命名的 Rust 模块改为 snake_case 并同步更新声明与导入。

高风险变更不会自动应用,包括整体层重写、ORM 或驱动替换、schema 表/列/索引重命名、应用或删除生产迁移、无测试的事务边界重写、破坏客户端的 RPC 或响应结构变更、运行时替换、跨 crate 新增架构层等,这些会记录为带文件路径和失败规则的阻塞项或待办。

适用场景

适合在新增路由前审查 Axum 服务结构、重构 API 使路由/状态/中间件/错误处理遵循统一架构、新增 Axum 路由并保持提取器顺序与类型化拒绝正确、在不让处理器直接接触连接池的前提下接入 SQLx、在添加持久化端点前审查 SQLx 迁移与 OpenAPI 边界、以及执行全量架构修复等任务。

限制

技能不适用于非 Axum 的 Rust Web 框架、纯客户端或嵌入式 Rust、不跨架构边界的复制修改,以及用户明确只要官方 crate 默认行为而不需要 Hypercore 约定的请求。技能不附带脚本,验证依赖 cargo check、cargo clippy、cargo test 及对运行中服务器的一次真实 HTTP 请求;迁移、凭据访问、生产副作用、运行时替换与大规模重写需要门禁控制。默认面向用户的交付物、报告、计划与摘要使用韩语,源代码标识符、命令、路径、crate 名、类型名等保留原语言,仅在用户明确要求或既有产物需保持其他语言时切换。