بناء ونشر واجهة برمجية بدون خوادم باستخدام Cloudflare Workers و Hono و D1

npm install -g wrangler

wrangler login

wrangler whoami

npm create hono@latest task-api

cd task-api
npm install

wrangler d1 create task-db

name = "task-api"
main = "src/index.ts"
compatibility_date = "2026-02-25"
 
[[d1_databases]]
binding = "DB"
database_name = "task-db"
database_id = "ضع_معرّف_قاعدة_البيانات_هنا"

-- schema.sql
DROP TABLE IF EXISTS tasks;
 
CREATE TABLE tasks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  description TEXT DEFAULT '',
  status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'in_progress', 'completed')),
  priority INTEGER DEFAULT 0 CHECK(priority BETWEEN 0 AND 3),
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now'))
);
 
-- بيانات أولية للتجربة
INSERT INTO tasks (title, description, status, priority) VALUES
  ('إعداد خط CI/CD', 'تهيئة GitHub Actions للنشر التلقائي', 'pending', 2),
  ('كتابة توثيق الواجهة البرمجية', 'إنشاء مواصفات OpenAPI لواجهة إدارة المهام', 'in_progress', 1),
  ('تصميم مخطط قاعدة البيانات', 'إنهاء مخطط ERD للمشروع', 'completed', 3);

wrangler d1 execute task-db --local --file=./schema.sql

wrangler d1 execute task-db --remote --file=./schema.sql

// src/types.ts
 
export interface Env {
  DB: D1Database;
}
 
export interface Task {
  id: number;
  title: string;
  description: string;
  status: 'pending' | 'in_progress' | 'completed';
  priority: number;
  created_at: string;
  updated_at: string;
}
 
export interface CreateTaskInput {
  title: string;
  description?: string;
  status?: Task['status'];
  priority?: number;
}
 
export interface UpdateTaskInput {
  title?: string;
  description?: string;
  status?: Task['status'];
  priority?: number;
}

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import type { Env, Task, CreateTaskInput, UpdateTaskInput } from './types';
 
const app = new Hono<{ Bindings: Env }>();
 
// ─── الوسطاء (Middleware) ────────────────────────────────────
app.use('/*', cors());
 
// ─── فحص الحالة ──────────────────────────────────────────────
app.get('/', (c) => {
  return c.json({
    status: 'ok',
    service: 'Task Management API',
    version: '1.0.0',
    timestamp: new Date().toISOString(),
  });
});
 
// ─── GET /tasks ──────────────────────────────────────────────
// عرض جميع المهام مع إمكانية التصفية
app.get('/tasks', async (c) => {
  const status = c.req.query('status');
  const sortBy = c.req.query('sort') || 'created_at';
  const order = c.req.query('order') || 'desc';
  const limit = Math.min(parseInt(c.req.query('limit') || '50'), 100);
  const offset = parseInt(c.req.query('offset') || '0');
 
  let query = 'SELECT * FROM tasks';
  const params: string[] = [];
 
  if (status) {
    query += ' WHERE status = ?';
    params.push(status);
  }
 
  const allowedSorts = ['created_at', 'updated_at', 'priority', 'title'];
  const safeSort = allowedSorts.includes(sortBy) ? sortBy : 'created_at';
  const safeOrder = order.toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
 
  query += ` ORDER BY ${safeSort} ${safeOrder} LIMIT ? OFFSET ?`;
  params.push(limit.toString(), offset.toString());
 
  try {
    const result = await c.env.DB.prepare(query)
      .bind(...params)
      .all<Task>();
 
    return c.json({
      tasks: result.results,
      meta: {
        total: result.results.length,
        limit,
        offset,
      },
    });
  } catch (error) {
    return c.json({ error: 'فشل في جلب المهام' }, 500);
  }
});
 
// ─── GET /tasks/:id ─────────────────────────────────────────
// جلب مهمة واحدة بالمعرّف
app.get('/tasks/:id', async (c) => {
  const id = c.req.param('id');
 
  try {
    const task = await c.env.DB.prepare(
      'SELECT * FROM tasks WHERE id = ?'
    )
      .bind(id)
      .first<Task>();
 
    if (!task) {
      return c.json({ error: 'المهمة غير موجودة' }, 404);
    }
 
    return c.json({ task });
  } catch (error) {
    return c.json({ error: 'فشل في جلب المهمة' }, 500);
  }
});
 
// ─── POST /tasks ─────────────────────────────────────────────
// إنشاء مهمة جديدة
app.post('/tasks', async (c) => {
  let body: CreateTaskInput;
 
  try {
    body = await c.req.json<CreateTaskInput>();
  } catch {
    return c.json({ error: 'جسم الطلب JSON غير صالح' }, 400);
  }
 
  if (!body.title || body.title.trim().length === 0) {
    return c.json({ error: 'العنوان مطلوب' }, 400);
  }
 
  if (body.title.length > 255) {
    return c.json({ error: 'العنوان يجب ألا يتجاوز 255 حرفاً' }, 400);
  }
 
  const validStatuses = ['pending', 'in_progress', 'completed'];
  if (body.status && !validStatuses.includes(body.status)) {
    return c.json({ error: `الحالة يجب أن تكون إحدى: ${validStatuses.join(', ')}` }, 400);
  }
 
  if (body.priority !== undefined && (body.priority < 0 || body.priority > 3)) {
    return c.json({ error: 'الأولوية يجب أن تكون بين 0 و 3' }, 400);
  }
 
  try {
    const result = await c.env.DB.prepare(
      `INSERT INTO tasks (title, description, status, priority)
       VALUES (?, ?, ?, ?)
       RETURNING *`
    )
      .bind(
        body.title.trim(),
        body.description || '',
        body.status || 'pending',
        body.priority ?? 0
      )
      .first<Task>();
 
    return c.json({ task: result }, 201);
  } catch (error) {
    return c.json({ error: 'فشل في إنشاء المهمة' }, 500);
  }
});
 
// ─── PUT /tasks/:id ─────────────────────────────────────────
// تحديث مهمة موجودة
app.put('/tasks/:id', async (c) => {
  const id = c.req.param('id');
  let body: UpdateTaskInput;
 
  try {
    body = await c.req.json<UpdateTaskInput>();
  } catch {
    return c.json({ error: 'جسم الطلب JSON غير صالح' }, 400);
  }
 
  const existing = await c.env.DB.prepare(
    'SELECT * FROM tasks WHERE id = ?'
  )
    .bind(id)
    .first<Task>();
 
  if (!existing) {
    return c.json({ error: 'المهمة غير موجودة' }, 404);
  }
 
  const updates: string[] = [];
  const values: (string | number)[] = [];
 
  if (body.title !== undefined) {
    if (body.title.trim().length === 0) {
      return c.json({ error: 'العنوان لا يمكن أن يكون فارغاً' }, 400);
    }
    updates.push('title = ?');
    values.push(body.title.trim());
  }
 
  if (body.description !== undefined) {
    updates.push('description = ?');
    values.push(body.description);
  }
 
  if (body.status !== undefined) {
    const validStatuses = ['pending', 'in_progress', 'completed'];
    if (!validStatuses.includes(body.status)) {
      return c.json({ error: `الحالة يجب أن تكون إحدى: ${validStatuses.join(', ')}` }, 400);
    }
    updates.push('status = ?');
    values.push(body.status);
  }
 
  if (body.priority !== undefined) {
    if (body.priority < 0 || body.priority > 3) {
      return c.json({ error: 'الأولوية يجب أن تكون بين 0 و 3' }, 400);
    }
    updates.push('priority = ?');
    values.push(body.priority);
  }
 
  if (updates.length === 0) {
    return c.json({ error: 'لا توجد حقول للتحديث' }, 400);
  }
 
  updates.push("updated_at = datetime('now')");
  values.push(id);
 
  try {
    const result = await c.env.DB.prepare(
      `UPDATE tasks SET ${updates.join(', ')} WHERE id = ? RETURNING *`
    )
      .bind(...values)
      .first<Task>();
 
    return c.json({ task: result });
  } catch (error) {
    return c.json({ error: 'فشل في تحديث المهمة' }, 500);
  }
});
 
// ─── DELETE /tasks/:id ───────────────────────────────────────
// حذف مهمة
app.delete('/tasks/:id', async (c) => {
  const id = c.req.param('id');
 
  try {
    const existing = await c.env.DB.prepare(
      'SELECT id FROM tasks WHERE id = ?'
    )
      .bind(id)
      .first();
 
    if (!existing) {
      return c.json({ error: 'المهمة غير موجودة' }, 404);
    }
 
    await c.env.DB.prepare('DELETE FROM tasks WHERE id = ?')
      .bind(id)
      .run();
 
    return c.json({ message: 'تم حذف المهمة بنجاح' });
  } catch (error) {
    return c.json({ error: 'فشل في حذف المهمة' }, 500);
  }
});
 
// ─── معالج 404 ───────────────────────────────────────────────
app.notFound((c) => {
  return c.json({ error: 'غير موجود' }, 404);
});
 
// ─── معالج الأخطاء ──────────────────────────────────────────
app.onError((err, c) => {
  console.error('خطأ غير متوقع:', err);
  return c.json({ error: 'خطأ داخلي في الخادم' }, 500);
});
 
export default app;

wrangler dev

# فحص الحالة
curl http://localhost:8787/
 
# عرض جميع المهام
curl http://localhost:8787/tasks
 
# إنشاء مهمة جديدة
curl -X POST http://localhost:8787/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "تعلّم Cloudflare Workers", "description": "إكمال هذا الدليل", "priority": 2}'
 
# جلب مهمة محددة
curl http://localhost:8787/tasks/1
 
# تحديث مهمة
curl -X PUT http://localhost:8787/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'
 
# حذف مهمة
curl -X DELETE http://localhost:8787/tasks/4
 
# التصفية حسب الحالة
curl "http://localhost:8787/tasks?status=pending&sort=priority&order=desc"

// src/middleware.ts
import { Context, Next } from 'hono';
 
export function validateJson() {
  return async (c: Context, next: Next) => {
    if (['POST', 'PUT', 'PATCH'].includes(c.req.method)) {
      const contentType = c.req.header('content-type');
      if (!contentType?.includes('application/json')) {
        return c.json(
          { error: 'يجب أن يكون Content-Type هو application/json' },
          415
        );
      }
    }
    await next();
  };
}
 
export function requestLogger() {
  return async (c: Context, next: Next) => {
    const start = Date.now();
    await next();
    const duration = Date.now() - start;
    console.log(
      `${c.req.method} ${c.req.path} → ${c.res.status} (${duration}ms)`
    );
  };
}
 
export function rateLimit(maxRequests: number, windowMs: number) {
  const requests = new Map<string, { count: number; resetAt: number }>();
 
  return async (c: Context, next: Next) => {
    const ip = c.req.header('cf-connecting-ip') || 'unknown';
    const now = Date.now();
    const record = requests.get(ip);
 
    if (!record || now > record.resetAt) {
      requests.set(ip, { count: 1, resetAt: now + windowMs });
    } else if (record.count >= maxRequests) {
      return c.json({ error: 'عدد كبير جداً من الطلبات' }, 429);
    } else {
      record.count++;
    }
 
    await next();
  };
}

import { validateJson, requestLogger } from './middleware';
 
// أضف بعد cors()
app.use('/*', requestLogger());
app.use('/tasks/*', validateJson());

# إنشاء مجلد الترحيل
wrangler d1 migrations create task-db init

# تطبيق محلياً
wrangler d1 migrations apply task-db --local
 
# تطبيق على الإنتاج
wrangler d1 migrations apply task-db --remote

wrangler deploy

curl https://task-api.YOUR_SUBDOMAIN.workers.dev/tasks

routes = [
  { pattern = "api.yourdomain.com/*", zone_name = "yourdomain.com" }
]

wrangler deploy

# بث السجلات الحية من الإنتاج
wrangler tail

wrangler dev --inspect