rust-web

Rust HTTP 服务交付

基于 HTTP 契约和运行时生命周期交付服务端 HTTP API。框架负责传输适配；领域逻辑和数据访问应保持独立可测试，不要将所有后端问题都塞进处理器。

确认服务契约

修改前，请根据 OpenAPI 规范、现有路由、客户端、测试、配置和运行环境进行验证：

• 方法、路径、状态码、请求/响应架构以及兼容性策略；
• 身份验证上下文的来源（身份验证系统设计不在本技能的范围内）；
• 请求体、并发限制、超时、上传大小和响应大小限制；
• 对外部 HTTP 服务、数据库、缓存或队列的依赖，包括故障语义；
• 监听地址、代理、TLS 终止、运行状况检查、优雅关闭时限；
• 锁定依赖下 axum、Tokio、Tower 和相关 crate 的 Rust/MSRV 版本；
• 日志级别、跟踪配置、指标暴露、敏感字段处理和数据保留策略。

现有客户端库中的响应字段构成兼容性约束。缺少契约时，请先声明最小假设。

工作流

1. 确立当前基线

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -e features
cargo test --all-targets

验证服务入口、路由组合、状态管理、错误类型、中间件顺序、关闭信号和测试工具。严格遵循 Cargo.lock 中的版本和官方文档；不要凭记忆混用 axum/Tower API，应以对应版本的规范为准。

2. 定义传输边界

建议的调用流程：

HTTP request
  -> router / extractor / transport validation
  -> application service / use case
  -> repository or outbound HTTP port
  -> domain result/error
  -> centralized HTTP response mapping

• 处理器负责提取数据、进行传输层验证、调用用例并映射响应；
• 领域逻辑不依赖 axum 请求/响应类型；
• 数据库连接池和 HTTP 客户端作为服务层中的有状态依赖；不要将业务数据存储在全局锁中。
• 事务应属于用例/数据访问边界，不要由处理器零散地控制。
• 应根据变更原因分离 DTO、领域模型和持久化模型，避免不受控地重复使用结构体。

确定具体分层或适配器要求时，请参阅服务边界。

3. 实现路由和输入边界

• 路由路径、提取器和响应类型必须与锁定的 axum 版本一致；
• 明确验证路径参数、查询字符串、标头和请求体，以区分语法错误与领域冲突；
• 限制请求体大小、上传大小、分页大小和批次大小；
• 避免在持有锁的状态下执行 .await 操作；优先将共享可变状态委托给专用服务或存储机制。
• 不要使用 unwrap()/expect() 处理请求、网络访问、数据库查询或序列化中的故障；应将无法表达的前置条件转化为类型级检查，并采用集中式验证，避免在多个处理器中重复验证。

4. 统一错误响应映射

定义从应用程序错误到 HTTP 响应的单一映射：

• 验证失败 → 客户端可修正的 4xx 状态码；
• 未找到、冲突和权限拒绝 → 稳定的客户端错误状态码，例如 404、409 和 403；
• 下游不可用、超时、内部缺陷 → 不泄露内部详情的 5xx 状态码。

每个错误响应都必须包含稳定的机器码以及用于关联的请求/跟踪标识符。完整错误链应写入受控日志；响应不得暴露 SQL 查询、令牌、文件路径或回溯信息。避免将所有错误都映射为 500，或通过返回 200 隐藏故障。

5. 中间件组合与安全边界

按照实际调用顺序检查 Tower 中间件层：

• 在保留请求 ID 和跟踪标识符的同时，脱敏敏感请求头；
• 配置全局超时和下游超时；
• 强制执行请求体大小限制，并采取并发和负载保护措施；
• 在适当的位置集成身份验证上下文和授权检查。
• 精确维护 CORS 允许列表；当服务链中包含凭据时，不要默认采用宽松策略。
• 考虑压缩的 CPU 开销，以及响应采用压缩请求头时可能暴露敏感信息的风险。
• 仅信任来自明确受控来源的代理请求头。

中间件顺序、超时配置和优雅关闭策略记录在 中间件与生命周期 中。

6. 管理异步生命周期

• 为服务、外部请求和数据库操作配置分层超时；
• 确保取消操作向下传播，以清理子任务，并避免创建脱离请求生命周期的泄漏任务；
• 优雅关闭：停止接收新的传入请求，并在预算限制内处理完正在进行的请求，然后再释放资源。
• 区分不可重试错误和可重试错误；重试需要设置预算、退避策略，并保证操作幂等。
• 将 Tokio 任务、通道、Send/Sync、取消安全性和锁作用域的深层设计交由 $rust-concurrency 处理。

7. 对外部适配器进行有界访问

此技能可与需要数据库或出站 HTTP 客户端的服务集成，但仅关注服务端边界：

• 复用连接池和客户端实例，而不是为每个请求创建新实例；
• 为下游组件配置超时、连接数限制和可观测的错误报告；
• 确保事务覆盖完整用例，避免不必要地等待外部网络。
• 将数据库架构迁移、索引、事务、SQL 调优和 ORM 建模交由 $rust-database 处理。
• 独立的 SDK、爬虫或批量 HTTP 客户端不属于服务端主流程，应归入单独的工具领域。
• 将 JWT/OAuth 流程、会话、令牌、CORS/CSRF 策略和密钥管理交由 $rust-web-security 处理；此技能仅使用来自已验证来源的主体身份和授权结果。
• 仅在明确提出请求时，才将 WebSocket 升级、消息协议、心跳机制和背压处理作为独立子流程处理。

8. 分层服务测试

确保涵盖以下内容：

1. 领域／用例纯测试；
2. 针对每个用例进行路由器级请求测试，无需绑定真实端口；
3. 提取器失败、错误映射逻辑、请求体限制、超时和身份验证边界；
4. 外部适配器契约验证和故障注入场景；
5. 需要使用真实数据库时，对数据库迁移、提交和回滚进行隔离测试；
6. 数量有限的套接字测试，用于验证监听行为、代理配置或优雅关闭动态。

详细测试矩阵见 HTTP 服务测试。测试组织、覆盖率目标、CI 门禁策略和性能基线由 rust-testing 负责。

常见门禁

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings

根据项目情况添加 OpenAPI／架构兼容性检查、集成环境测试和安全扫描。不要悄悄跳过基于依赖的失败测试，并声称整体通过。

完成标准

• 明确说明 HTTP 契约、版本假设和兼容性保证；
• 保持处理器精简，并确保领域逻辑和外部适配器可独立测试；
• 错误处理、状态码、超时、中间件顺序和优雅关闭行为均有相应测试；
• 日志和响应不会泄露密钥或内部细节。
• cargo fmt、cargo check、cargo test 和 clippy 均成功通过；
• 如果真实数据库、网络、TLS 连接或部署未经验证，必须明确标出尚未验证的边界。

交接边界

主要问题	分配的职责
Schema 定义、迁移、事务、连接池、SQL/ORM 建模	rust-database
身份验证、授权、会话/令牌、CORS/CSRF 策略、SSRF 防护	rust-web-security
Tokio 任务、锁、通道、取消安全、优雅关闭实现	rust-concurrency
测试分层策略、覆盖率目标、属性测试、性能基线	rust-testing
所有权语义、serde 类型契约、通用错误设计模式	rust-stable
功能、工作区配置、构建脚本、发布流水线	rust-cargo-build
不安全的网络库、C ABI 接口、原始缓冲区处理	rust-unsafe-ffi

按需资源

• 服务边界：设计处理器、状态管理、数据结构或出站 HTTP 适配器时查阅。
• 中间件和生命周期：检查 Tower 配置、超时策略、CORS 规则、负载均衡策略或优雅关闭逻辑时查阅。
• HTTP 服务测试：参考路由器集成、端到端测试和故障注入场景的设计模式。
• 示例：需要时，使用模板进行端到端任务分解。
• examples/golden-handler/：离线编译并验证传输边界行为和错误映射逻辑。

参考资料

• Rust 网络编程
• axum 文档
• Tokio 文档
• Tower 文档
• Serde