domain-web

用途

domain-web 属于 actionbook/rust-skills 中的第三层“领域约束”（Layer 3: Domain Constraints），用于在构建 Web 服务时提供设计层面的指导。它把 Web 领域的规则转化为 Rust 的设计约束，帮助开发者在架构选择、状态管理、异步处理和错误处理上遵循一致的思路。关键词覆盖 web server、HTTP、REST API、GraphQL、WebSocket，以及 axum、actix、warp、rocket、tower、hyper、reqwest、middleware、router 等。

主要能力

该技能列出了 Web 领域的核心约束与对应的 Rust 实现方向：

无状态 HTTP：不使用请求级全局变量，状态放在 extractor 中。
并发：需要处理大量连接，采用异步并满足 Send + Sync。
延迟 SLA：要求快速响应，因此关注高效的所有权管理。
安全：通过类型安全的 extractor 做输入校验。
可观测性：使用 tracing 结合 tower layer 做请求追踪。

关键约束进一步细化为三条规则：

默认异步：Web handler 不得阻塞，因为阻塞一个任务等于阻塞大量请求；使用 async/await，CPU 密集工作使用 spawn_blocking。
状态管理：共享状态必须线程安全，因为 handler 可能运行在任意线程；使用 Arc<T>，可变状态使用 Arc<RwLock<T>>。
请求生命周期：资源只在请求期间存活，以管理内存且避免泄漏；依赖 extractor 与正确的所有权。

从约束到设计

技能给出了从领域约束推导到第二层设计模式（Layer 2）的示例：

需要共享应用状态 → m07-concurrency：使用 Arc 做线程安全共享；m02-resource：可变状态用 Arc<RwLock<T>>。
需要请求校验 → m05-type-driven：使用经过校验的 extractor；m06-error-handling：为错误实现 IntoResponse。
需要中间件栈 → m12-lifecycle：使用 Tower layers；m04-zero-cost：基于 trait 的组合。

框架与 crate 选择

框架对比：

axum：函数式、基于 tower，适合现代 API。
actix-web：基于 actor，追求高性能。
warp：filter 组合，适合可组合 API。
rocket：宏驱动，适合快速开发。

常用 crate：

HTTP 服务端：axum、actix-web
HTTP 客户端：reqwest
JSON：serde_json
认证/JWT：jsonwebtoken
会话：tower-sessions
数据库：sqlx、diesel
中间件：tower

设计模式

技能总结了常见的 Web 设计模式及实现方式：

Extractors：请求解析，如 State(db)、Json(payload)。
Error response：统一错误，实现 IntoResponse。
Middleware：横切关注点，使用 Tower layers。
Shared state：应用配置，使用 Arc<AppState>。

代码示例一：Axum handler

async fn handler(
    State(db): State<Arc<DbPool>>,
    Json(payload): Json<CreateUser>,
) -> Result<Json<User>, AppError> {
    let user = db.create_user(&payload).await?;
    Ok(Json(user))
}

代码示例二：错误处理

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            Self::NotFound => (StatusCode::NOT_FOUND, "Not found"),
            Self::Internal(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Internal error"),
        };
        (status, Json(json!({"error": message}))).into_response()
    }
}

常见错误与修正

技能列出了初学者容易犯的错误及对应修正方向：

在 handler 中阻塞 → 造成延迟飙升，改用 spawn_blocking。
在状态中使用 Rc → 不满足 Send + Sync，改用 Arc。
缺少校验 → 安全风险，改用类型安全的 extractor。
没有错误响应 → 用户体验差，实现 IntoResponse。

从约束到第一层实现（Layer 1）的追踪关系：

异步 handler → async/await → tokio 运行时。
线程安全状态 → 共享状态 → Arc、Arc<RwLock>。
请求生命周期 → extractor → 通过 From 的所有权。
中间件 → Tower layers → 基于 trait 的组合。

适用场景

适用于使用 Rust 构建 Web 服务的场景，包括 HTTP 服务、REST API、GraphQL、WebSocket 服务，以及需要处理高并发、低延迟、输入校验和请求追踪的后端开发。

限制

资料未提供该技能的安装方式、收费方式、运行环境要求或与具体工具链集成的操作步骤，这些内容暂未提供。

技能介绍

用途