用途:为 Rust HTTP 服务开发提供一套隐式技能规范,强调显式状态、类型化边界、可观测行为与生产级运行时契约。
主要能力:涵盖 Axum 与 Tower 层构建 REST API、路由与状态管理、请求提取器、中间件/层、类型化错误映射、tracing 追踪、配置、数据库访问与优雅关停。资料提供三份参考文档:axum-tower-architecture.md 涉及路由结构、状态、提取器、中间件、错误与版本化 API;runtime-config-data.md 涉及 Tokio 运行时、配置、数据库、后台任务与优雅关停;testing-observability.md 涉及集成测试、追踪、指标、契约测试与生产就绪。
使用方式:先阅读现有服务形态(路由、应用状态、中间件层、配置、数据库访问、测试、部署脚本与可观测性)。新服务优先采用 axum 加 tower 层,除非仓库已统一使用其他框架。保持 handler 精简:提取输入、调用领域代码、将结果映射为 HTTP 响应;应用状态显式且克隆成本低,避免隐藏全局变量与每请求创建连接。错误、追踪、超时、请求大小限制与关停应作为功能组成部分。默认使用所需特征的 tokio;HTTP 边界用 serde DTO,内部用领域类型;领域错误用 thiserror 并在 HTTP 边缘类型化映射;用 tracing/tracing-subscriber 结构化 span 与请求 ID;数据库服务在需要编译期查询检查和异步连接池时用 sqlx。
验证:服务变更后运行 cargo fmt --all --check、cargo test --all-targets、cargo clippy --all-targets --all-features -- -D warnings;为新路由、错误状态映射、认证/授权分支、配置解析、数据库行为及优雅关停或后台任务补充集成测试。
限制:资料未提供具体版本号、安装命令、收费或价格信息;实际框架与工具选择应以现有仓库约定为准。