نظرة عامة على الخلفية

يُنشئ FORGE واجهة برمجة تطبيقات REST جاهزة للإنتاج مبنية على Axum، إطار عمل الويب غير المتزامن الرائد في Rust. الخلفية المُولّدة تتبع معمارية متعددة الطبقات تفصل المسؤوليات بوضوح، مما يجعل قاعدة الكود قابلة للصيانة مع نموها من API CRUD بسيط إلى تطبيق كامل الميزات.

المعمارية

الـ API المُولّد يتبع معمارية متعددة الطبقات صارمة حيث لكل طبقة مسؤولية واحدة:

┌─────────────────────────────────────────────┐
│              HTTP Request                    │
├─────────────────────────────────────────────┤
│           طبقة Middleware                    │
│    (Auth, RBAC, Request ID, CORS)           │
├─────────────────────────────────────────────┤
│           طبقة Handler                       │
│    (تحليل الطلبات، بناء الاستجابات)          │
├─────────────────────────────────────────────┤
│           طبقة Service                       │
│    (منطق الأعمال، التحقق من الصحة)           │
├─────────────────────────────────────────────┤
│           طبقة Model                         │
│    (استعلامات قاعدة البيانات، تعيين البيانات) │
├─────────────────────────────────────────────┤
│           قاعدة بيانات PostgreSQL            │
└─────────────────────────────────────────────┘

البيانات تتدفق نزولاً عبر الطبقات: يستقبل handler طلب HTTP ويفوّض منطق الأعمال لـ service، الذي بدوره يستعلم قاعدة البيانات عبر models. الاستجابات تتدفق صعوداً.

نصيحة

كل طبقة تتواصل فقط مع جارتها المباشرة. الـ handlers لا تصل لقاعدة البيانات مباشرة، والـ services لا تبني استجابات HTTP.

بنية المشروع

api/
├── src/
│   ├── main.rs              # Entry point, router setup, middleware registration
│   ├── config/
│   │   ├── mod.rs            # Config module
│   │   ├── app.rs            # Application config (port, environment, secrets)
│   │   └── database.rs       # Database connection pool config
│   ├── handlers/
│   │   ├── mod.rs            # Handler module export
│   │   ├── auth.rs           # Authentication endpoints
│   │   ├── profile.rs        # User profile endpoints
│   │   └── admin/
│   │       ├── mod.rs        # Admin handler module export
│   │       ├── users.rs      # User management (CRUD)
│   │       ├── roles.rs      # Role management
│   │       ├── contents.rs   # Content management
│   │       └── settings.rs   # Application settings
│   ├── models/
│   │   ├── mod.rs            # Model module export
│   │   ├── user.rs           # User model and queries
│   │   ├── role.rs           # Role model
│   │   ├── permission.rs     # Permission model
│   │   └── content.rs        # Content model (translatable)
│   ├── dto/
│   │   ├── mod.rs            # DTO module export
│   │   ├── common.rs         # Shared types (ApiResponse, Pagination)
│   │   ├── auth.rs           # Auth request/response types
│   │   ├── user.rs           # User DTOs
│   │   └── content.rs        # Content DTOs
│   ├── services/
│   │   ├── mod.rs            # Service module export
│   │   ├── auth.rs           # Authentication logic
│   │   ├── user.rs           # User business logic
│   │   └── content.rs        # Content business logic
│   ├── middleware/
│   │   ├── mod.rs            # Middleware module export
│   │   ├── auth.rs           # JWT authentication middleware
│   │   ├── rbac.rs           # Permission checking middleware
│   │   └── request_id.rs     # Request ID generation
│   ├── routes/
│   │   ├── mod.rs            # Route module export
│   │   ├── admin.rs          # Admin routes registration (/api/admin/*)
│   │   └── public.rs         # Public routes registration (/api/*)
│   └── utils/
│       ├── mod.rs            # Utility module export
│       ├── response.rs       # Response building helpers
│       └── pagination.rs     # Pagination utilities
├── database/
│   ├── migrations/           # Sequential SQL migrations
│   └── seeders/              # Seed data (roles, permissions, admin user)
├── .env                      # Environment variables
└── Cargo.toml                # Rust dependencies

نقطة الدخول

ملف main.rs يُهيّئ التطبيق، يُعدّ middleware، ويبدأ الخادم:

use axum::{Router, middleware};
use tower_http::cors::CorsLayer;
use std::net::SocketAddr;

#[tokio::main]
async fn main() {
    // Initialize tracing
    tracing_subscriber::init();

    // Load configuration
    let config = config::AppConfig::from_env();

    // Create database connection pool
    let pool = config::database::create_pool(&config.database_url).await;

    // Run pending migrations
    sqlx::migrate!("./database/migrations")
        .run(&pool)
        .await
        .expect("Failed to run migrations");

    // Build application router
    let app = Router::new()
        .nest("/api/admin", routes::admin::routes(pool.clone()))
        .nest("/api", routes::public::routes(pool.clone()))
        .route("/health", axum::routing::get(|| async { "OK" }))
        .route("/ready", axum::routing::get(health_check))
        .layer(CorsLayer::permissive())
        .layer(middleware::from_fn(middleware::request_id::add_request_id));

    // Start server
    let addr = SocketAddr::from(([0, 0, 0, 0], config.port));
    tracing::info!("Server listening on {}", addr);
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

فحوصات الصحة

الـ API المُولّد يُعرّض نقطتي نهاية للصحة:

نقطة النهاية	الغرض	الاستجابة
/health	فحص liveness (الخادم يعمل)	200 OK
/ready	فحص readiness (قاعدة البيانات متصلة)	200 OK أو 503

async fn health_check(
    State(pool): State<PgPool>,
) -> impl IntoResponse {
    match sqlx::query("SELECT 1")
        .execute(&pool)
        .await
    {
        Ok(_) => (StatusCode::OK, "Ready"),
        Err(_) => (StatusCode::SERVICE_UNAVAILABLE, "Not Ready"),
    }
}

تحذير

نقطة النهاية /ready تتحقق من اتصال قاعدة البيانات. استخدمها لـ Kubernetes readiness probes أو فحوصات صحة موازن الحمل. نقطة النهاية /health هي فحص liveness بسيط يُرجع دائماً 200 إذا كانت عملية الخادم تعمل.

المنفذ الافتراضي

الـ API يعمل على المنفذ 8080 افتراضياً. عدّله عبر متغير البيئة PORT:

PORT=3000 cargo run

دورة حياة الطلب

كل طلب يتدفق عبر خط أنابيب يمكن التنبؤ به:

1. CORS middleware يتحقق من أصل الطلب
2. Request ID middleware يُعيّن ترويسة X-Request-Id فريدة
3. مطابقة المسار توجّه للـ handler المناسب
4. Auth middleware (على المسارات المحمية) يتحقق من JWT token
5. RBAC middleware (على مسارات الإدارة) يتحقق من صلاحيات المستخدم
6. Handler يحلل الطلب ويفوّض لـ service
7. Service ينفّذ منطق الأعمال ويستعلم قاعدة البيانات
8. الاستجابة تُسلسل كـ JSON وتُرجع

ما التالي

• المصادقة — مصادقة JWT مع access و refresh tokens
• التفويض — التحكم بالوصول المبني على الأدوار (RBAC)
• قاعدة البيانات — مخطط PostgreSQL والترحيلات والـ seeders
• الـ Models — نماذج قاعدة البيانات وأنماط الاستعلام
• الـ Handlers — اصطلاحات معالجات الطلبات
• الـ Services — طبقة منطق الأعمال
• الـ Middleware — Auth و RBAC وخط أنابيب الطلبات
• الـ Routes — تسجيل المسارات وتجميعها
• الـ DTOs — تعريفات أنواع الطلب/الاستجابة
• معالجة الأخطاء — استجابات الأخطاء المُنظّمة
• توثيق API — توليد OpenAPI/Swagger