بناء واجهات REST API باستخدام Rust و Axum: دليل عملي للمبتدئين

cargo new bookmark-api && cd bookmark-api

[package]
name = "bookmark-api"
version = "0.1.0"
edition = "2021"
 
[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "uuid", "chrono"] }
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
tower-http = { version = "0.6", features = ["cors", "trace"] }
tracing = "0.1"
tracing-subscriber = "0.3"
dotenvy = "0.15"
thiserror = "2"

DATABASE_URL=postgres://postgres:password@localhost:5432/bookmarks

docker run -d \
  --name bookmarks-db \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=bookmarks \
  -p 5432:5432 \
  postgres:16-alpine

cargo install sqlx-cli --no-default-features --features postgres

sqlx migrate add create_bookmarks

-- migrations/YYYYMMDD_create_bookmarks.sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
 
CREATE TABLE bookmarks (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    title VARCHAR(255) NOT NULL,
    url TEXT NOT NULL,
    description TEXT,
    tags TEXT[] DEFAULT '{}',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
 
CREATE INDEX idx_bookmarks_tags ON bookmarks USING GIN (tags);
CREATE INDEX idx_bookmarks_created_at ON bookmarks (created_at DESC);

sqlx migrate run

touch src/config.rs src/db.rs src/error.rs src/models.rs src/handlers.rs src/routes.rs

// src/config.rs
use std::env;
 
pub struct Config {
    pub database_url: String,
    pub host: String,
    pub port: u16,
}
 
impl Config {
    pub fn from_env() -> Self {
        dotenvy::dotenv().ok();
 
        Self {
            database_url: env::var("DATABASE_URL")
                .expect("DATABASE_URL must be set"),
            host: env::var("HOST").unwrap_or_else(|_| "0.0.0.0".to_string()),
            port: env::var("PORT")
                .unwrap_or_else(|_| "3000".to_string())
                .parse()
                .expect("PORT must be a number"),
        }
    }
}

// src/db.rs
use sqlx::postgres::PgPoolOptions;
use sqlx::PgPool;
 
pub async fn create_pool(database_url: &str) -> PgPool {
    PgPoolOptions::new()
        .max_connections(10)
        .connect(database_url)
        .await
        .expect("Failed to create database pool")
}

// src/models.rs
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sqlx::FromRow;
use uuid::Uuid;
 
#[derive(Debug, Serialize, FromRow)]
pub struct Bookmark {
    pub id: Uuid,
    pub title: String,
    pub url: String,
    pub description: Option<String>,
    pub tags: Vec<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
 
#[derive(Debug, Deserialize)]
pub struct CreateBookmark {
    pub title: String,
    pub url: String,
    pub description: Option<String>,
    #[serde(default)]
    pub tags: Vec<String>,
}
 
#[derive(Debug, Deserialize)]
pub struct UpdateBookmark {
    pub title: Option<String>,
    pub url: Option<String>,
    pub description: Option<String>,
    pub tags: Option<Vec<String>>,
}
 
#[derive(Debug, Deserialize)]
pub struct BookmarkQuery {
    pub tag: Option<String>,
    pub search: Option<String>,
    #[serde(default = "default_limit")]
    pub limit: i64,
    #[serde(default)]
    pub offset: i64,
}
 
fn default_limit() -> i64 {
    20
}

// src/error.rs
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::Json;
use serde_json::json;
 
#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("Resource not found")]
    NotFound,
 
    #[error("Validation error: {0}")]
    Validation(String),
 
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),
 
    #[error("Internal server error")]
    Internal(String),
}
 
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match &self {
            AppError::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
            AppError::Validation(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
            AppError::Database(err) => {
                tracing::error!("Database error: {:?}", err);
                (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "Internal server error".to_string(),
                )
            }
            AppError::Internal(msg) => {
                tracing::error!("Internal error: {}", msg);
                (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "Internal server error".to_string(),
                )
            }
        };
 
        let body = Json(json!({
            "error": {
                "status": status.as_u16(),
                "message": message,
            }
        }));
 
        (status, body).into_response()
    }
}

// src/handlers.rs
use axum::extract::{Path, Query, State};
use axum::http::StatusCode;
use axum::Json;
use sqlx::PgPool;
use uuid::Uuid;
 
use crate::error::AppError;
use crate::models::{Bookmark, BookmarkQuery, CreateBookmark, UpdateBookmark};
 
// GET /api/bookmarks
pub async fn list_bookmarks(
    State(pool): State<PgPool>,
    Query(params): Query<BookmarkQuery>,
) -> Result<Json<Vec<Bookmark>>, AppError> {
    let bookmarks = if let Some(tag) = &params.tag {
        sqlx::query_as::<_, Bookmark>(
            "SELECT * FROM bookmarks WHERE $1 = ANY(tags) ORDER BY created_at DESC LIMIT $2 OFFSET $3"
        )
        .bind(tag)
        .bind(params.limit)
        .bind(params.offset)
        .fetch_all(&pool)
        .await?
    } else if let Some(search) = &params.search {
        let pattern = format!("%{}%", search);
        sqlx::query_as::<_, Bookmark>(
            "SELECT * FROM bookmarks WHERE title ILIKE $1 OR description ILIKE $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3"
        )
        .bind(&pattern)
        .bind(params.limit)
        .bind(params.offset)
        .fetch_all(&pool)
        .await?
    } else {
        sqlx::query_as::<_, Bookmark>(
            "SELECT * FROM bookmarks ORDER BY created_at DESC LIMIT $1 OFFSET $2"
        )
        .bind(params.limit)
        .bind(params.offset)
        .fetch_all(&pool)
        .await?
    };
 
    Ok(Json(bookmarks))
}
 
// GET /api/bookmarks/:id
pub async fn get_bookmark(
    State(pool): State<PgPool>,
    Path(id): Path<Uuid>,
) -> Result<Json<Bookmark>, AppError> {
    let bookmark = sqlx::query_as::<_, Bookmark>(
        "SELECT * FROM bookmarks WHERE id = $1"
    )
    .bind(id)
    .fetch_optional(&pool)
    .await?
    .ok_or(AppError::NotFound)?;
 
    Ok(Json(bookmark))
}
 
// POST /api/bookmarks
pub async fn create_bookmark(
    State(pool): State<PgPool>,
    Json(input): Json<CreateBookmark>,
) -> Result<(StatusCode, Json<Bookmark>), AppError> {
    if input.title.trim().is_empty() {
        return Err(AppError::Validation("Title cannot be empty".to_string()));
    }
 
    if input.url.trim().is_empty() {
        return Err(AppError::Validation("URL cannot be empty".to_string()));
    }
 
    let bookmark = sqlx::query_as::<_, Bookmark>(
        r#"
        INSERT INTO bookmarks (title, url, description, tags)
        VALUES ($1, $2, $3, $4)
        RETURNING *
        "#,
    )
    .bind(&input.title)
    .bind(&input.url)
    .bind(&input.description)
    .bind(&input.tags)
    .fetch_one(&pool)
    .await?;
 
    Ok((StatusCode::CREATED, Json(bookmark)))
}
 
// PUT /api/bookmarks/:id
pub async fn update_bookmark(
    State(pool): State<PgPool>,
    Path(id): Path<Uuid>,
    Json(input): Json<UpdateBookmark>,
) -> Result<Json<Bookmark>, AppError> {
    let bookmark = sqlx::query_as::<_, Bookmark>(
        r#"
        UPDATE bookmarks
        SET
            title = COALESCE($1, title),
            url = COALESCE($2, url),
            description = COALESCE($3, description),
            tags = COALESCE($4, tags),
            updated_at = NOW()
        WHERE id = $5
        RETURNING *
        "#,
    )
    .bind(&input.title)
    .bind(&input.url)
    .bind(&input.description)
    .bind(&input.tags)
    .bind(id)
    .fetch_optional(&pool)
    .await?
    .ok_or(AppError::NotFound)?;
 
    Ok(Json(bookmark))
}
 
// DELETE /api/bookmarks/:id
pub async fn delete_bookmark(
    State(pool): State<PgPool>,
    Path(id): Path<Uuid>,
) -> Result<StatusCode, AppError> {
    let result = sqlx::query("DELETE FROM bookmarks WHERE id = $1")
        .bind(id)
        .execute(&pool)
        .await?;
 
    if result.rows_affected() == 0 {
        return Err(AppError::NotFound);
    }
 
    Ok(StatusCode::NO_CONTENT)
}

// src/routes.rs
use axum::routing::{delete, get, post, put};
use axum::Router;
use sqlx::PgPool;
 
use crate::handlers;
 
pub fn create_router(pool: PgPool) -> Router {
    Router::new()
        .route("/api/bookmarks", get(handlers::list_bookmarks))
        .route("/api/bookmarks", post(handlers::create_bookmark))
        .route("/api/bookmarks/{id}", get(handlers::get_bookmark))
        .route("/api/bookmarks/{id}", put(handlers::update_bookmark))
        .route("/api/bookmarks/{id}", delete(handlers::delete_bookmark))
        .route("/health", get(health_check))
        .with_state(pool)
}
 
async fn health_check() -> &'static str {
    "OK"
}

// src/main.rs
mod config;
mod db;
mod error;
mod handlers;
mod models;
mod routes;
 
use tower_http::cors::CorsLayer;
use tower_http::trace::TraceLayer;
use tracing_subscriber;
 
#[tokio::main]
async fn main() {
    // تهيئة التتبع
    tracing_subscriber::fmt()
        .with_target(false)
        .compact()
        .init();
 
    // تحميل الإعدادات
    let config = config::Config::from_env();
 
    // إنشاء مجمع قاعدة البيانات
    let pool = db::create_pool(&config.database_url).await;
 
    // تشغيل الترحيلات المعلّقة
    sqlx::migrate!()
        .run(&pool)
        .await
        .expect("Failed to run migrations");
 
    tracing::info!("Migrations applied successfully");
 
    // بناء الموجّه مع الوسطاء
    let app = routes::create_router(pool)
        .layer(TraceLayer::new_for_http())
        .layer(CorsLayer::permissive());
 
    // تشغيل الخادم
    let addr = format!("{}:{}", config.host, config.port);
    tracing::info!("Server starting on {}", addr);
 
    let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

# تأكد من أن PostgreSQL يعمل
cargo run

# فحص الصحة
curl http://localhost:3000/health
 
# إنشاء مفضلة
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rust Book",
    "url": "https://doc.rust-lang.org/book/",
    "description": "الكتاب الرسمي للغة Rust",
    "tags": ["rust", "learning", "documentation"]
  }'
 
# عرض جميع المفضلات
curl http://localhost:3000/api/bookmarks
 
# الفلترة حسب الوسم
curl "http://localhost:3000/api/bookmarks?tag=rust"
 
# البحث بالعنوان
curl "http://localhost:3000/api/bookmarks?search=rust"
 
# جلب مفضلة محددة (استبدل UUID)
curl http://localhost:3000/api/bookmarks/YOUR_UUID_HERE
 
# تحديث مفضلة
curl -X PUT http://localhost:3000/api/bookmarks/YOUR_UUID_HERE \
  -H "Content-Type: application/json" \
  -d '{"title": "The Rust Programming Language Book"}'
 
# حذف مفضلة
curl -X DELETE http://localhost:3000/api/bookmarks/YOUR_UUID_HERE

[dependencies]
# ... التبعيات الموجودة ...
tower = { version = "0.5", features = ["limit", "timeout"] }

use axum::middleware::{self, Next};
use axum::extract::Request;
use axum::response::Response;
use std::time::Instant;
 
async fn track_request_time(request: Request, next: Next) -> Response {
    let method = request.method().clone();
    let uri = request.uri().clone();
    let start = Instant::now();
 
    let response = next.run(request).await;
 
    let duration = start.elapsed();
    tracing::info!(
        "{} {} → {} ({}ms)",
        method,
        uri,
        response.status(),
        duration.as_millis()
    );
 
    response
}

let app = routes::create_router(pool)
    .layer(middleware::from_fn(track_request_time))
    .layer(TraceLayer::new_for_http())
    .layer(CorsLayer::permissive());

// tests/api_tests.rs
use axum::http::StatusCode;
use axum_test::TestServer;
use serde_json::json;
 
async fn setup() -> TestServer {
    dotenvy::dotenv().ok();
    let database_url = std::env::var("DATABASE_URL")
        .expect("DATABASE_URL must be set");
 
    let pool = sqlx::postgres::PgPoolOptions::new()
        .max_connections(5)
        .connect(&database_url)
        .await
        .unwrap();
 
    sqlx::migrate!().run(&pool).await.unwrap();
 
    let app = bookmark_api::routes::create_router(pool);
    TestServer::new(app).unwrap()
}
 
#[tokio::test]
async fn test_health_check() {
    let server = setup().await;
    let response = server.get("/health").await;
    assert_eq!(response.status_code(), StatusCode::OK);
    assert_eq!(response.text(), "OK");
}
 
#[tokio::test]
async fn test_create_and_get_bookmark() {
    let server = setup().await;
 
    // إنشاء
    let response = server
        .post("/api/bookmarks")
        .json(&json!({
            "title": "Test Bookmark",
            "url": "https://example.com",
            "tags": ["test"]
        }))
        .await;
 
    assert_eq!(response.status_code(), StatusCode::CREATED);
 
    let bookmark: serde_json::Value = response.json();
    let id = bookmark["id"].as_str().unwrap();
 
    // جلب
    let response = server.get(&format!("/api/bookmarks/{}", id)).await;
    assert_eq!(response.status_code(), StatusCode::OK);
 
    let fetched: serde_json::Value = response.json();
    assert_eq!(fetched["title"], "Test Bookmark");
}
 
#[tokio::test]
async fn test_not_found() {
    let server = setup().await;
    let response = server
        .get("/api/bookmarks/00000000-0000-0000-0000-000000000000")
        .await;
    assert_eq!(response.status_code(), StatusCode::NOT_FOUND);
}

[dev-dependencies]
axum-test = "16"

pub mod config;
pub mod db;
pub mod error;
pub mod handlers;
pub mod models;
pub mod routes;

cargo test