ما هو Idempotency ولماذا هو مهم جداً؟

Idempotency يعني أن تنفيذ نفس الـ Request مرتين (أو أكثر) بنفس البيانات يعطي نفس النتيجة بدون أي آثار جانبية بعد المرة الأولى.

السيناريو الكارثي:

المستخدم يضغط على "Place Order" → 

شبكة بطيئة → 

timeout → 

المستخدم يضغط مرة ثانية → 

💥 تم إنشاء طلبين! 💥

💳 تم الخصم مرتين! 💳

الفرق بين Safe و Idempotent

Safe Operations (آمنة)

GET /products       ✅ Safe & Idempotent
GET /orders/{id}    ✅ Safe & Idempotent

لا تغير البيانات، يمكن تكرارها ألف مرة بأمان.

Idempotent Operations

PUT /products/{id}     ✅ Idempotent
DELETE /orders/{id}    ✅ Idempotent

تغير البيانات، لكن التكرار لا يسبب تغييرات إضافية.

Non-Idempotent Operations (المشكلة!)

POST /orders           ❌ Non-Idempotent
POST /payments         ❌ Non-Idempotent
POST /send-email       ❌ Non-Idempotent

كل تكرار يسبب عملية جديدة → هنا نحتاج Idempotency!

لماذا الموضوع مهم؟

• الشبكات غير مستقرة: Timeout, Retry, Network errors
• المستخدمون يخطئون: الضغط المزدوج على الأزرار
• Queue Retries: Jobs قد تُنفذ أكثر من مرة
• API Clients: Automatic retries في حالة الفشل

❌ بدون Idempotency:

• Duplicate payments 💸
• Duplicate orders 📦📦
• Duplicate emails 📧📧📧
• فوضى في قاعدة البيانات

✅ مع Idempotency:

• نفس الـ Request → نفس النتيجة
• حماية من التكرار
• تجربة مستخدم ممتازة

الحل الأول:

 Idempotency Key في الـ Header

المفهوم الأساسي

Client يرسل Idempotency-Key فريد مع كل request :

POST /api/orders
Headers:
  Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
  Authorization: Bearer xxx
Body:
  { "product_id": 123, "quantity": 2 }

Server يفحص:

هل هذا الـ Key موجود من قبل؟

نعم موجود → أرجع نفس الـ Response السابق (لا تنفذ مرة ثانية)

لا، جديد → نفذ العملية واحفظ النتيجة

التطبيق في Laravel

1. إنشاء جدول Idempotency

bash
php artisan make:migration create_idempotency_keys_table
php// database/migrations/xxxx_create_idempotency_keys_table.php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;


return new class extends Migration
{
    public function up(): void
    {
        Schema::create('idempotency_keys', function (Blueprint $table) {
            $table->id();
            $table->string('key', 255)->unique(); // الـ Idempotency Key
            $table->string('user_id')->nullable()->index(); // للربط بالمستخدم
            $table->string('endpoint', 255); // /api/orders مثلاً
            $table->enum('status', ['processing', 'completed', 'failed'])->default('processing');
            $table->text('request_payload')->nullable(); // البيانات المرسلة
            $table->text('response_data')->nullable(); // النتيجة المحفوظة
            $table->integer('response_code')->nullable(); // HTTP Status Code
            $table->timestamp('completed_at')->nullable();
            $table->timestamps();
            
            // Indexes للأداء
            $table->index(['key', 'status']);
            $table->index('created_at');
        });
    }


    public function down(): void
    {
        Schema::dropIfExists('idempotency_keys');
    }
};

bashphp artisan migrate

2. إنشاء Model

php
// app/Models/IdempotencyKey.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class IdempotencyKey extends Model
{
    protected $fillable = [
        'key',
        'user_id',
        'endpoint',
        'status',
        'request_payload',
        'response_data',
        'response_code',
        'completed_at',
    ];


    protected $casts = [
        'request_payload' => 'array',
        'response_data' => 'array',
        'completed_at' => 'datetime',
    ];


    public function isProcessing(): bool
    {
        return $this->status === 'processing';
    }


    public function isCompleted(): bool
    {
        return $this->status === 'completed';
    }


    public function isFailed(): bool
    {
        return $this->status === 'failed';
    }
}

3. إنشاء Idempotency Middleware

php
// app/Http/Middleware/EnsureIdempotency.php
namespace App\Http\Middleware;

use App\Models\IdempotencyKey;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Symfony\Component\HttpFoundation\Response;


class EnsureIdempotency
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        // فقط للـ POST requests
        if (!$request->isMethod('post')) {
            return $next($request);
        }


        $idempotencyKey = $request->header('Idempotency-Key');


        // إذا لم يتم إرسال Idempotency-Key، نفذ بشكل عادي
        if (!$idempotencyKey) {
            return $next($request);
        }


        // التحقق من وجود الـ Key
        $existing = IdempotencyKey::where('key', $idempotencyKey)->first();


        if ($existing) {
            // إذا كان completed، أرجع الـ Response المحفوظ
            if ($existing->isCompleted()) {
                return response()->json(
                    $existing->response_data,
                    $existing->response_code
                )->header('X-Idempotency-Replay', 'true');
            }


            // إذا كان processing، أرجع 409 Conflict
            if ($existing->isProcessing()) {
                return response()->json([
                    'message' => 'Request is already being processed',
                    'idempotency_key' => $idempotencyKey,
                ], 409);
            }


            // إذا كان failed، يمكن إعادة المحاولة
            if ($existing->isFailed()) {
                $existing->update([
                    'status' => 'processing',
                    'completed_at' => null,
                ]);
            }
        } else {
            // إنشاء سجل جديد
            try {
                IdempotencyKey::create([
                    'key' => $idempotencyKey,
                    'user_id' => $request->user()?->id,
                    'endpoint' => $request->path(),
                    'status' => 'processing',
                    'request_payload' => $request->except(['password', 'password_confirmation']),
                ]);
            } catch (\Exception $e) {
                // Race condition: key تم إنشاؤه للتو
                return response()->json([
                    'message' => 'Request is already being processed',
                    'idempotency_key' => $idempotencyKey,
                ], 409);
            }
        }


        // تخزين الـ key في الـ request للاستخدام لاحقاً
        $request->attributes->set('idempotency_key', $idempotencyKey);


        // تنفيذ الـ Request
        $response = $next($request);


        // حفظ النتيجة
        $this->saveResponse($idempotencyKey, $response);


        return $response;
    }


    /**
     * حفظ Response للاستخدام المستقبلي
     */
    protected function saveResponse(string $key, Response $response): void
    {
        try {
            $record = IdempotencyKey::where('key', $key)->first();


            if ($record) {
                $record->update([
                    'status' => $response->isSuccessful() ? 'completed' : 'failed',
                    'response_data' => json_decode($response->getContent(), true),
                    'response_code' => $response->getStatusCode(),
                    'completed_at' => now(),
                ]);
            }
        } catch (\Exception $e) {
            // Log error but don't fail the request
            \Log::error('Failed to save idempotency response: ' . $e->getMessage());
        }
    }
}

4. تسجيل الـ Middleware

php
// في bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'idempotent' => \App\Http\Middleware\EnsureIdempotency::class,
    ]);
})


// أو في app/Http/Kernel.php (Laravel 10 وأقدم)
protected $middlewareAliases = [
    'idempotent' => \App\Http\Middleware\EnsureIdempotency::class,
];

5. استخدام Middleware في Routes

php
// routes/api.php
use App\Http\Controllers\OrderController;
use App\Http\Controllers\PaymentController;


Route::middleware(['auth:sanctum', 'idempotent'])->group(function () {
    // كل الـ POST requests هنا محمية بـ Idempotency
    Route::post('/orders', [OrderController::class, 'store']);
    Route::post('/payments', [PaymentController::class, 'process']);
    Route::post('/send-notification', [NotificationController::class, 'send']);
});

6. مثال في Controller

php
// app/Http/Controllers/OrderController.php
namespace App\Http\Controllers;


use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;


class OrderController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'product_id' => 'required|exists:products,id',
            'quantity' => 'required|integer|min:1',
            'payment_method' => 'required|string',
        ]);


        try {
            DB::beginTransaction();


            // إنشاء الطلب
            $order = Order::create([
                'user_id' => $request->user()->id,
                'product_id' => $validated['product_id'],
                'quantity' => $validated['quantity'],
                'total' => $this->calculateTotal($validated),
                'status' => 'pending',
            ]);


            // معالجة الدفع
            $payment = $this->processPayment($order, $validated['payment_method']);


            // تحديث المخزون
            $this->updateInventory($validated['product_id'], $validated['quantity']);


            DB::commit();


            return response()->json([
                'message' => 'Order created successfully',
                'order' => $order,
                'payment' => $payment,
            ], 201);


        } catch (\Exception $e) {
            DB::rollBack();
            
            return response()->json([
                'message' => 'Failed to create order',
                'error' => $e->getMessage(),
            ], 500);
        }
    }
}

استخدام من جانب الـ Client

 JavaScript / Vue / React

javascript//
 توليد Idempotency Key فريد
function generateIdempotencyKey() {
    return crypto.randomUUID(); // أو أي UUID generator
}


// حفظ الـ key مع كل request
const placeOrder = async (orderData) => {
    const idempotencyKey = generateIdempotencyKey();
    
    // حفظ الـ key في localStorage لتجنب إرسال نفس الـ request
    localStorage.setItem('last_order_key', idempotencyKey);
    
    try {
        const response = await fetch('/api/orders', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`,
                'Idempotency-Key': idempotencyKey, // هنا الـ magic!
            },
            body: JSON.stringify(orderData),
        });
        
        const data = await response.json();
        
        if (response.status === 409) {
            console.log('Request already processing...');
            // يمكن عمل retry بعد ثواني
            return;
        }
        
        if (response.ok) {
            // تحقق من header للتأكد إذا كان replay
            const isReplay = response.headers.get('X-Idempotency-Replay');
            if (isReplay) {
                console.log('This is a replayed response');
            }
            return data;
        }
    } catch (error) {
        console.error('Order failed:', error);
    }
};

Flutter / Dart

dartimport 'package:uuid/uuid.dart';
import 'package:http/http.dart' as http;


class ApiService {
  final uuid = Uuid();
  
  Future<Map<String, dynamic>> placeOrder(Map<String, dynamic> orderData) async {
    final idempotencyKey = uuid.v4();
    
    try {
      final response = await http.post(
        Uri.parse('https://api.example.com/orders'),
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer $token',
          'Idempotency-Key': idempotencyKey,
        },
        body: jsonEncode(orderData),
      );
      
      if (response.statusCode == 409) {
        // Request already processing
        print('Request is being processed');
        return {'status': 'processing'};
      }
      
      if (response.statusCode >= 200 && response.statusCode < 300) {
        final isReplay = response.headers['x-idempotency-replay'];
        if (isReplay == 'true') {
          print('This is a cached response');
        }
        return jsonDecode(response.body);
      }
    } catch (e) {
      print('Error: $e');
      rethrow;
    }
  }
}

الحل الثاني: Unique Constraint على Business ID

المفهوم

استخدام معرف فريد من External Service (مثل Payment Gateway) كـ Unique Constraint في Database.

مثال عملي: Payment Integration

php
// Migration
Schema::create('payments', function (Blueprint $table) {
    $table->id();
    $table->foreignId('order_id')->constrained();
    $table->string('payment_intent_id')->unique(); // 🔑 المفتاح السحري
    $table->string('payment_provider'); // stripe, paypal, etc
    $table->decimal('amount', 10, 2);
    $table->string('currency', 3);
    $table->enum('status', ['pending', 'completed', 'failed']);
    $table->timestamps();
});

php
// في Controller أو Service
namespace App\Services;


use App\Models\Payment;
use Illuminate\Support\Facades\DB;
use Stripe\PaymentIntent;


class PaymentService
{
    public function processStripePayment(Order $order, string $paymentIntentId)
    {
        try {
            DB::beginTransaction();


            // محاولة إنشاء Payment record
            $payment = Payment::create([
                'order_id' => $order->id,
                'payment_intent_id' => $paymentIntentId, // Unique!
                'payment_provider' => 'stripe',
                'amount' => $order->total,
                'currency' => 'USD',
                'status' => 'pending',
            ]);


            // التأكيد من Stripe
            $intent = PaymentIntent::retrieve($paymentIntentId);
            
            if ($intent->status === 'succeeded') {
                $payment->update(['status' => 'completed']);
                $order->update(['status' => 'paid']);
            }


            DB::commit();


            return ['success' => true, 'payment' => $payment];


        } catch (\Illuminate\Database\QueryException $e) {
            DB::rollBack();


            // تحقق إذا كان Duplicate Entry Error
            if ($e->getCode() === '23000') { // Unique constraint violation
                // الـ payment موجود مسبقاً
                $existing = Payment::where('payment_intent_id', $paymentIntentId)->first();
                
                return [
                    'success' => true,
                    'payment' => $existing,
                    'message' => 'Payment already processed',
                    'duplicate' => true,
                ];
            }


            throw $e;
        }
    }
}

مثال: Transaction ID من External API

php
// app/Models/Transaction.php
class Transaction extends Model
{
    protected $fillable = [
        'external_transaction_id', // من Payment Gateway
        'user_id',
        'amount',
        'status',
    ];


    // Event للتعامل مع Duplicate
    protected static function boot()
    {
        parent::boot();


        static::creating(function ($transaction) {
            // التحقق قبل الإنشاء
            $exists = static::where('external_transaction_id', $transaction->external_transaction_id)
                ->exists();


            if ($exists) {
                throw new \DomainException('Transaction already exists');
            }
        });
    }
}

php

// في Controller
public function processTransaction(Request $request)
{
    try {
        $transaction = Transaction::create([
            'external_transaction_id' => $request->transaction_id,
            'user_id' => auth()->id(),
            'amount' => $request->amount,
            'status' => 'completed',
        ]);


        return response()->json([
            'message' => 'Transaction processed',
            'transaction' => $transaction,
        ], 201);


    } catch (\DomainException $e) {
        // Transaction موجود مسبقاً
        $existing = Transaction::where('external_transaction_id', $request->transaction_id)
            ->first();


        return response()->json([
            'message' => 'Transaction already processed',
            'transaction' => $existing,
            'duplicate' => true,
        ], 200); // 200 لأن العملية تمت بالفعل
    }
}

متى تستخدم كل طريقة؟

استخدم Idempotency-Key عندما:

✅ تحتاج تحكم كامل في العملية

✅ تريد معرفة حالة الـ Request (processing/completed/failed)

✅ لا يوجد معرف فريد خارجي

✅ تحتاج retry logic معقد

استخدم Unique Constraint عندما:

✅ يوجد معرف فريد من External Service

✅ تريد حل بسيط وسريع

✅ لا تحتاج تتبع حالات معقدة

✅ الأداء هو الأولوية القصوى

Best Practices

1. Cleanup للـ Keys القديمة

php
// app/Console/Commands/CleanupIdempotencyKeys.php
namespace App\Console\Commands;


use App\Models\IdempotencyKey;
use Illuminate\Console\Command;


class CleanupIdempotencyKeys extends Command
{
    protected $signature = 'idempotency:cleanup {--days=7}';
    protected $description = 'Clean up old idempotency keys';


    public function handle()
    {
        $days = $this->option('days');
        
        $deleted = IdempotencyKey::where('created_at', '<', now()->subDays($days))
            ->where('status', 'completed')
            ->delete();


        $this->info("Deleted {$deleted} old idempotency keys");
    }
}

php
// في app/Console/Kernel.php أو routes/console.php
Schedule::command('idempotency:cleanup')->daily();

2. Monitoring

php
// في AppServiceProvider
use App\Models\IdempotencyKey;


public function boot()
{
    // تنبيه عند وجود requests عالقة
    if (app()->environment('production')) {
        $stuck = IdempotencyKey::where('status', 'processing')
            ->where('created_at', '<', now()->subMinutes(5))
            ->count();


        if ($stuck > 10) {
            \Log::warning("Found {$stuck} stuck idempotency keys");
            // أرسل تنبيه
        }
    }
}

الخلاصة، لماذا Idempotency ضروري؟

✅ يمنع Duplicate Operations تحت أي ظرف

✅ يحمي من الأخطاء البشرية (الضغط المزدوج)

✅ يتعامل مع Network Issues بأمان

✅ يدعم Automatic Retries بدون قلق

✅ يحسن تجربة المستخدم (لا توجد مفاجآت)