# Rocket 框架指南 > 适用于：Rocket 0.5+、Rust Web API、类型安全的 Web 应用程序与：`.claude/skills/rust-guide/SKILL.md` 一起使用 ## 概述 Rocket 是一个 Rust Web 框架，专注于易用性、开发人员体验和类型安全。它使用 Rust 的类型系统来确保编译时的正确性，并具有强大的功能，如请求保护、整流罩（中间件）和最小样板的派生宏。 ### 何时使用火箭 * **类型安全的 API** ：最大编译时保证 * **开发人员体验**：简洁、富有表现力的语法，具有最少的样板文件 * **快速原型制作**：快速启动；属性宏处理路由 * **表单处理**：对 HTML 表单和分段上传的出色支持 * **传统 Web 应用程序**：API 和服务器渲染的 HTML ### 何时不使用 Rocket * **异步繁重工作负载**：考虑 Axum 以获得纯异步性能 * **最小依赖** ：Rocket 的编译时间较长 * **最大控制** ：使用 Axum/Actix 进行细粒度中间件控制 ## 项目结构我的项目/ ├── Cargo.toml ├── Rocket.toml # Rocket 配置（每个配置文件） ├── src/ │ ├── main.rs # 入口点（#[launch] 或 #[rocket::main]） │ ├── lib.rs # 库导出 │ ├── 路线/ │ │ ├── mod.rs # 路由挂载函数 │ │ ├── users.rs # 用户处理程序 │ │ └── health.rs # 健康检查 │ ├── 型号/ │ │ ├── mod.rs │ │ └── user.rs # 域+请求/响应模型 │ ├── Guards/ # 请求守卫（身份验证、速率限制等） │ │ ├── mod.rs │ │ └── auth.rs │ ├── fairings/ # 中间件（日志记录、CORS、计时） │ │ ├── mod.rs │ │ └── 日志记录.rs │ ├── db/ │ │ ├── mod.rs # 数据库池定义 │ │ └── 池.rs │ ├── services/ # 业务逻辑层 │ │ ├── mod.rs │ │ └── user_service.rs │ ├── error.rs # AppError + 捕获器 │ └── config.rs # 自定义配置提取 ├── 测试/ │ └── api_tests.rs # 通过客户端进行集成测试 ├── 迁徙/ └── static/ # 静态文件服务 ## 依赖关系 [依赖项] 火箭= {版本=“0.5”，功能=[“json”，“秘密”]} Rocket_db_pools = { 版本 = "0.1", features = ["sqlx_postgres"] } sqlx = { 版本 = "0.7", features = ["runtime-tokio", "postgres", "chrono", "uuid"] } serde = { 版本 = "1.0", features = ["derive"] } serde_json =“1.0” 验证器={版本=“0.16”，功能=[“派生”]} jsonwebtoken =“9” bcrypt =“0.15” chrono = { 版本 = "0.4", 功能 = ["serde"] } uuid = { 版本 = "1", features = ["v4", "serde"] } 这个错误=“1.0” 多滕维=“0.15” tokio = { 版本 = "1", 功能 = ["完整"] } [开发依赖项] 火箭= {版本=“0.5”，功能=[“json”，“秘密”]} ## 应用程序入口点 #[macro_use] 外部板条箱火箭；使用火箭::{构建，火箭}；使用 Rocket_db_pools::数据库； #[启动] fn Rocket() -> Rocket<构建> { dotenvy::dotenv().ok(); 火箭::构建() .attach(DbPool::init()) .attach(请求记录器) .mount("/api", 路线::api_routes()) .mount("/health", 路线::health_routes()) .register("/", 捕手！[ 错误::未找到，错误::内部错误，错误::未经授权，错误::bad_request， ]） } ## 配置 (Rocket.toml) [默认] 地址 =“0.0.0.0” 端口=8000 工人 = 16 保持活动= 5 日志级别=“正常” 限制 = { form = "64 kB", json = "1 MiB" } [默认.数据库.db_pool] url = "postgres://用户:密码@localhost/mydb" 最小连接数 = 5 最大连接数 = 20 连接超时= 5 空闲超时= 300 [调试] log_level = “调试” [发布] Secret_key =“生成256位base64密钥” log_level = “严重” 通过环境或 Rocket.toml 自定义配置值：使用 Rocket::serde::反序列化； #[导出（调试、反序列化）] #[serde(crate = "rocket::serde")] pub 结构 AppConfig { pub jwt_secret：字符串， pub jwt_expiration_hours：i64， } impl 默认 AppConfig { fn 默认() -> 自身 { 自我{ jwt_secret: std::env::var("JWT_SECRET") .unwrap_or_else(|_| "开发秘钥".to_string()), jwt_expiration_hours: std::env::var("JWT_EXPIRATION_HOURS") .unwrap_or_else(|_| "24".to_string()) .parse() .unwrap_or(24), } } } ## 路由宏 Rocket 在处理函数上使用属性宏。该宏定义了 HTTP 方法、路径和动态段。 #[get("/")] // 获取/ #[post("/users", data = "")]// POST /users 和 body #[put("/users/", data = "")] // PUT /users/:id 和 body #[delete("/users/")] // 删除 /users/:id #[get("/users?&")] // GET /users?limit=&offset= 通过 `Vec` 挂载路由： pub fn api_routes() -> Vec<路线> { 路线！[注册，登录，获取用户，列表用户，删除用户] } ## 请求守卫请求防护实现“FromRequest”并在处理程序之前运行。它们是 Rocket 的身份验证、授权和请求验证的主要机制。 #[导出（调试）] pub 结构 AuthUser { pub user_id: Uuid, 酒吧电子邮件：字符串，酒吧角色：字符串， } #[火箭::async_trait] 为 AuthUser 实现 <'r> FromRequest<'r> { 类型错误=应用程序错误； async fn from_request(请求: &'r Request<'_>) -> 结果 { let token = match request.headers().get_one("授权") { Some(h) if h.starts_with("Bearer ") => &h[7..], _ => 返回结果::错误(( 状态::未经授权， AppError::Unauthorized("缺少授权标头".into()), ））， }; // 解码并验证JWT，返回Outcome::Success 或Outcome::Error // ... } } 为基于角色的访问编写守卫： pub struct AdminUser(pub AuthUser); #[火箭::async_trait] 为 AdminUser 实现 <'r> FromRequest<'r> { 类型错误=应用程序错误； async fn from_request(请求: &'r Request<'_>) -> 结果 { 让 user = match AuthUser::from_request(request).await { 结果::成功(u) => u, 结果::错误(e) => 返回结果::错误(e), 结果::转发(s) => 返回结果::转发(s), }; if user.role != "admin" { 返回结果::错误(( 状态::禁止， AppError::Unauthorized("需要管理员访问权限".into()), ））； } 结果::成功(AdminUser(用户)) } } 可选身份验证：包裹在 `Option` 中或创建一个 `OptionalUser` 防护。 ## 响应程序和错误处理为自定义错误类型实现“Responder”以返回结构化 JSON 错误： #[导出（错误，调试）] pub 枚举 AppError { #[错误(“未找到：{0}”)] 未找到（字符串）， #[错误(“未经授权：{0}”)] 未经授权（字符串）， #[错误(“验证：{0}”)] 验证（字符串）， #[error("数据库错误：{0}")] 数据库(#[来自] sqlx::Error), #[错误(“内部：{0}”)] 内部（字符串）， } impl<'r> Responder<'r, 'static> for AppError { fn respond_to(self, request: &'r Request<'_>) -> 响应::Result<'static> { 让（状态，主体）=匹配＆自我{ AppError::NotFound(m) => (Status::NotFound, json!({"error": m})), AppError::Unauthorized(m) => (Status::Unauthorized, json!({"error": m})), AppError::Validation(m) => (Status::BadRequest, json!({"error": m})), AppError::Database(_) => (Status::InternalServerError, json!({"error": "数据库错误"})), AppError::Internal(_) => (Status::InternalServerError, json!({"error": "内部错误"})), }; 响应::build_from(Json(body).respond_to(request)?) .状态（状态） .ok() } } 为未处理的状态代码注册捕获器： #[捕获(404)] pub fn not_found() -> Json { Json(json!({"error": "未找到"})) } #[捕获(500)] pub fn internal_error() -> Json { Json(json!({"error": "内部错误"})) } #[捕获(401)] pub fn 未经授权() -> Json { Json(json!({"error": "unauthorized"})) } ## 整流罩（中间件）整流罩将横切行为附加到请求/响应生命周期。 pub 结构RequestLogger； #[火箭::async_trait] 为 RequestLogger 实现公平化 { fn 信息(&self) -> 信息 { 信息 { name: "请求记录器", kind: Kind::Request |种类::响应 } } async fn on_request(&self, request: &mut Request<'_>, _: &mut Data<'_>) { request.local_cache(|| Instant::now()); } async fn on_response<'r>(&self, 请求: &'r 请求<'_>, 响应: &mut Response<'r>) { 让 start = request.local_cache(|| Instant::now()); println!("{} {} {} - {:?}", request.method(), request.uri(), response.status().code, start.elapsed()); } } CORS整流罩图案： pub 结构 Cors； #[火箭::async_trait] 为 Cors 实现整流{ fn info(&self) -> Info { Info { name: "CORS", kind: Kind::Response } } async fn on_response<'r>(&self, _: &'r 请求<'_>, 响应: &mut Response<'r>) { response.set_header(Header::new("Access-Control-Allow-Origin", "*")); response.set_header(Header::new("Access-Control-Allow-Methods", "GET、POST、PUT、DELETE、OPTIONS")); response.set_header(Header::new("Access-Control-Allow-Headers", "Content-Type, Authorization")); } } ## 状态管理 ### 数据库池 (rocket_db_pools) 使用 Rocket_db_pools::{sqlx, 数据库, 连接}; #[导出（数据库）] #[数据库(“db_pool”)] pub struct DbPool(sqlx::PgPool); pub 类型 DbConn = Connection; 在处理程序中使用： #[get("/users/")] pub async fn get_user(mut db: DbConn, id: &str) -> Result, AppError> { 让 user = sqlx::query_as::<_, User>("从用户中选择 * WHERE id = $1") .bind(id) .fetch_可选(&mut **db) .等待？ .ok_or_else(|| AppError::NotFound("找不到用户".into()))?; 好的（Json（用户）） } ### 托管状态 // 附加到构建中 Rocket::build().manage(AppConfig::default()) // 提取到处理程序中 #[获取(“/信息”)] fn info(config: &State) -> 字符串 { 格式！("JWT 过期时间：{}h", config.jwt_expiration_hours) } ## 表单处理 #[派生（FromForm）] pub 结构UploadForm<'r> { 酒吧名称：字符串，酒吧描述：选项， pub 文件：TempFile<'r>, } #[post("/上传", data = "<表单>")] pub async fn upload(mut form: Form>, auth: AuthUser) -> Result, AppError> { let filename = format!("uploads/{}_{}", auth.user_id, form.name); form.file.persist_to(&文件名).await .map_err(|e| AppError::Internal(e.to_string()))?; Ok(Json(json!({"status": "已上传", "filename": 文件名}))) } 具有内置验证的多部分： #[派生（FromForm）] pub struct ProfileForm<'r> { #[字段（验证= len（1..100））] 酒吧名称：字符串， #[字段(验证=包含('@'))] 酒吧电子邮件：字符串， #[字段(验证 = len(..1_000_000))] 酒吧头像：选项>， } ## 命令 Cargo run # 启动开发服务器 Cargo build --release # 生产版本货物测试 # 所有测试 Cargo test test_health_check # 具体测试货物 fmt # 格式货物 Clippy # Lint 货物检查#快速类型检查 Cargo doc --open # 生成文档 ROCKET_LOG_LEVEL=debug Cargo run # 调试日志记录 ## 最佳实践 ### 做 * 使用请求防护进行身份验证/授权 * 为自定义错误类型实现“Responder” * 使用整流罩来解决跨领域问题（日志记录、CORS、计时） * 利用 Rocket 的类型系统进行编译时验证 * 使用“rocket_db_pools”进行托管数据库连接 * 通过“Rocket.toml”使用每个配置文件设置进行配置 * 使用派生宏（`FromForm`、`FromRequest`）来减少样板文件 * 使用 `rocket::local::asynchronous::Client` 进行测试 * 为所有常见的 HTTP 错误代码注册捕获器 ### 不要 * 在处理程序代码中使用 `unwrap()`/`expect()` * 忽略表单或 JSON 输入的验证错误 * 将秘密存储在`Rocket.toml`中（使用环境变量） * 使用同步操作阻止异步处理程序 * 跳过 404、401、500 的错误捕获器 * 当 `State` 或请求本地缓存足够时使用全局可变状态 * 忘记通过 `.attach(DbPool::init())` 附加数据库池 ## 高级模式有关详细的处理程序示例、数据库集成、身份验证流程、表单处理和测试模式，请参阅： * [references/patterns.md]() \-- CRUD 处理程序、Diesel/SQLx、JWT 身份验证、使用客户端进行测试 ## 外部参考 * [Rocket 文档]() * [火箭指南]() * [Rocket API 参考]() * [rocket_db_pools]() * [Rocket GitHub]() * [Rocket 示例]()

火箭

包含技能