---

name: domain-web description: “用于构建Web服务时使用。关键词：web服务器，HTTP，REST API，GraphQL，WebSocket，axum，actix，warp，rocket，tower，hyper，reqwest，中间件，路由器，处理器，提取器，状态管理，身份验证，授权，JWT，会话，cookie，CORS，速率限制，web开发，HTTP服务，API设计，中间件，路由” globs: [“**/Cargo.toml”] user-invocable: false

Web领域

第3层：领域约束

领域约束 → 设计影响

领域规则	设计约束	Rust实现含义
无状态HTTP	无请求本地全局变量	状态在提取器中
并发性	处理大量连接	异步，Send + Sync
延迟SLA	快速响应	高效的所有权
安全性	输入验证	类型安全的提取器
可观测性	请求追踪	tracing + tower 层

---

关键约束

默认异步

规则：Web处理器不能阻塞
原因：阻塞一个任务 = 阻塞多个请求
RUST：async/await，CPU密集型工作使用 spawn_blocking

状态管理

规则：共享状态必须是线程安全的
原因：处理器在任何线程上运行
RUST：Arc<T>，Arc<RwLock<T>> 用于可变状态

请求生命周期

规则：资源仅存在于请求期间
原因：内存管理，避免泄漏
RUST：提取器，正确的所有权

---

向下追踪 ↓

从约束到设计（第2层）：

"需要共享应用状态"
    ↓ m07-并发性：使用 Arc 进行线程安全共享
    ↓ m02-资源：Arc<RwLock<T>> 用于可变状态

"需要请求验证"
    ↓ m05-类型驱动：已验证的提取器
    ↓ m06-错误处理：IntoResponse 用于错误

"需要中间件栈"
    ↓ m12-生命周期：Tower 层
    ↓ m04-零成本：基于Trait的组合

---

框架比较

框架	风格	最适合
axum	函数式，tower	现代API
actix-web	基于Actor	高性能
warp	过滤器组合	可组合API
rocket	宏驱动	快速开发

关键Crate

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

设计模式

模式	目的	实现
提取器	请求解析	State(db), Json(payload)
错误响应	统一错误处理	impl IntoResponse
中间件	横切关注点	Tower 层
共享状态	应用配置	Arc<AppState>

代码模式：Axum处理器

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, "未找到"),
            Self::Internal(_) => (StatusCode::INTERNAL_SERVER_ERROR, "内部错误"),
        };
        (status, Json(json!({"error": message}))).into_response()
    }
}

---

常见错误

错误	领域违反	修复方法
在处理器中阻塞	延迟激增	spawn_blocking
在状态中使用 Rc	非 Send + Sync	使用 Arc
无验证	安全风险	类型安全的提取器
无错误响应	糟糕的用户体验	实现 IntoResponse

---

追踪到第1层

约束	第2层模式	第1层实现
异步处理器	Async/await	tokio 运行时
线程安全状态	共享状态	Arc<T>, Arc<RwLock<T>>
请求生命周期	提取器	通过 From<Request> 的所有权
中间件	Tower 层	基于Trait的组合

---

相关技能

何时	参见
异步模式	m07-并发性
状态管理	m02-资源
错误处理	m06-错误处理
中间件设计	m12-生命周期