Rust HTTP API框架Dropshot的使用指南

Dropshot是一个轻量级的Rust HTTP API框架，专注于构建RESTful端点和提供OpenAPI集成。它特别适合需要自动生成OpenAPI文档的项目。

主要特性

• 轻量级且易于使用的RESTful端点构建工具
• 自动生成OpenAPI 3.0文档
• 内置支持JSON请求/响应
• 与hyper集成，提供异步支持
• 类型安全的端点处理

基本使用方法

1. 添加依赖

首先在Cargo.toml中添加dropshot依赖：

[dependencies]
dropshot = "0.8"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }

2. 创建基本API服务器

use dropshot::{ApiDescription, HttpServer, ConfigDropshot};
use dropshot::endpoint;
use dropshot::RequestContext;
use dropshot::HttpError;
use http::{Response, StatusCode};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Serialize, Deserialize)]
struct Greeting {
    message: String,
}

#[endpoint {
    method = GET,
    path = "/greet/{name}",
}]
async fn greet(
    ctx: Arc<RequestContext>,
    name: String,
) -> Result<Greeting, HttpError> {
    Ok(Greeting {
        message: format!("Hello, {}!", name),
    })
}

#[tokio::main]
async fn main() -> Result<(), String> {
    let mut api = ApiDescription::new();
    api.register(greet).unwrap();

    let server = HttpServer::new(
        &ConfigDropshot::default(),
        api,
        Arc::new(()), // 共享状态
    )
    .await
    .map_err(|e| e.to_string())?;

    server.await
}

3. 启动服务器并测试

运行程序后，可以访问：

• 获取JSON响应
• 查看自动生成的OpenAPI文档

高级功能

请求体和参数处理

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

#[endpoint {
    method = POST,
    path = "/users",
}]
async fn create_user(
    ctx: Arc<RequestContext>,
    body: Json<CreateUser>,
) -> Result<Response<()>, HttpError> {
    println!("Creating user: {} <{}>", body.name, body.email);
    Ok(Response::builder()
        .status(StatusCode::CREATED)
        .body(())
        .unwrap())
}

共享状态

struct AppState {
    counter: Mutex<u32>,
}

#[endpoint {
    method = GET,
    path = "/counter",
}]
async fn get_counter(
    ctx: Arc<RequestContext<AppState>>,
) -> Result<Json<u32>, HttpError> {
    let counter = ctx.app_private.counter.lock().unwrap();
    Ok(Json(*counter))
}

自定义错误处理

#[derive(Debug, Serialize)]
struct ErrorMessage {
    code: u16,
    message: String,
}

impl IntoResponse for ErrorMessage {
    fn into_response(self) -> Response<BoxBody> {
        let body = Json(self).into_response().into_body();
        Response::builder()
            .status(StatusCode::from_u16(self.code).unwrap()
            .body(body)
            .unwrap()
    }
}

#[endpoint {
    method = GET,
    path = "/error",
}]
async fn error_endpoint() -> Result<String, ErrorMessage> {
    Err(ErrorMessage {
        code: 418,
        message: "I'm a teapot".to_string(),
    })
}

OpenAPI集成

Dropshot会自动为所有注册的端点生成OpenAPI文档。你还可以通过endpoint属性添加更多元数据：

#[endpoint {
    method = GET,
    path = "/user/{id}",
    tags = ["user"],
    summary = "Get user by ID",
    description = "Returns a single user",
}]
async fn get_user(
    ctx: Arc<RequestContext>,
    id: u64,
) -> Result<Json<User>, HttpError> {
    // 实现代码
}

完整示例代码

下面是一个完整的Dropshot API服务器示例，包含了基本路由、共享状态和错误处理：

use dropshot::{ApiDescription, HttpServer, ConfigDropshot, endpoint, HttpError, RequestContext};
use http::{Response, StatusCode};
use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};
use tokio::sync::Mutex as AsyncMutex;

// 共享应用状态
#[derive(Default)]
struct AppState {
    counter: AsyncMutex<u32>,  // 使用异步互斥锁
    users: Mutex<Vec<User>>,   // 使用同步互斥锁(因为本例中users操作不涉及await)
}

// 用户数据结构
#[derive(Serialize, Deserialize, Clone)]
struct User {
    id: u64,
    name: String,
    email: String,
}

// 错误响应
#[derive(Debug, Serialize)]
struct ApiError {
    code: u16,
    message: String,
}

// 获取计数器端点
#[endpoint {
    method = GET,
    path = "/counter",
}]
async fn get_counter(
    ctx: Arc<RequestContext<AppState>>,
) -> Result<Json<u32>, HttpError> {
    let counter = ctx.app_private.counter.lock().await;
    Ok(Json(*counter))
}

// 增加计数器端点
#[endpoint {
    method = POST,
    path = "/counter/increment",
}]
async fn increment_counter(
    ctx: Arc<RequestContext<AppState>>,
) -> Result<Json<u32>, HttpError> {
    let mut counter = ctx.app_private.counter.lock().await;
    *counter += 1;
    Ok(Json(*counter))
}

// 创建用户端点
#[endpoint {
    method = POST,
    path = "/users",
}]
async fn create_user(
    ctx: Arc<RequestContext<AppState>>,
    body: Json<User>,
) -> Result<Response<()>, HttpError> {
    let mut users = ctx.app_private.users.lock().unwrap();
    users.push(body.into_inner());
    Ok(Response::builder()
        .status(StatusCode::CREATED)
        .body(())
        .unwrap())
}

// 获取所有用户端点
#[endpoint {
    method = GET,
    path = "/users",
}]
async fn get_users(
    ctx: Arc<RequestContext<AppState>>,
) -> Result<Json<Vec<User>>, HttpError> {
    let users = ctx.app_private.users.lock().unwrap();
    Ok(Json(users.clone()))
}

// 自定义错误端点
#[endpoint {
    method = GET,
    path = "/error",
}]
async fn error_endpoint() -> Result<String, ApiError> {
    Err(ApiError {
        code: 418,
        message: "I'm a teapot".to_string(),
    })
}

#[tokio::main]
async fn main() -> Result<(), String> {
    // 创建API描述
    let mut api = ApiDescription::new();
    api.register(get_counter).unwrap();
    api.register(increment_counter).unwrap();
    api.register(create_user).unwrap();
    api.register(get_users).unwrap();
    api.register(error_endpoint).unwrap();

    // 初始化共享状态
    let shared_state = Arc::new(AppState {
        counter: AsyncMutex::new(0),
        users: Mutex::new(Vec::new()),
    });

    // 配置并启动服务器
    let server_config = ConfigDropshot {
        bind_address: "127.0.0.1:8080".parse().unwrap(),
        ..Default::default()
    };

    let server = HttpServer::new(&server_config, api, shared_state)
        .await
        .map_err(|e| e.to_string())?;

    println!("Server running on port 8080");
    server.await
}

总结

Dropshot是一个简单但功能强大的Rust HTTP框架，特别适合需要良好文档化的RESTful API项目。它的自动OpenAPI集成可以显著减少API文档维护的工作量，同时保持类型安全和良好的性能。