بناء واجهات برمجة تطبيقات خلفية سحابية آمنة الأنواع مع Encore.ts: من الصفر إلى الإنتاج

# macOS
brew install encoredev/tap/encore
 
# Linux
curl -L https://encore.dev/install.sh | bash
 
# Windows (WSL2)
curl -L https://encore.dev/install.sh | bash

encore version

encore app create task-api --example=ts/empty
cd task-api

mkdir task

// task/encore.service.ts
import { Service } from "encore.dev/service";
 
export default new Service("task");

// task/task.ts
import { api } from "encore.dev/api";
 
// تعريف واجهة المهمة
interface Task {
  id: number;
  title: string;
  description: string;
  completed: boolean;
  createdAt: string;
}
 
// تخزين في الذاكرة (سنضيف قاعدة بيانات لاحقاً)
let tasks: Task[] = [];
let nextId = 1;
 
// إنشاء مهمة جديدة
export const create = api(
  { expose: true, method: "POST", path: "/tasks" },
  async (req: { title: string; description: string }): Promise<Task> => {
    const task: Task = {
      id: nextId++,
      title: req.title,
      description: req.description,
      completed: false,
      createdAt: new Date().toISOString(),
    };
    tasks.push(task);
    return task;
  }
);
 
// عرض جميع المهام
export const list = api(
  { expose: true, method: "GET", path: "/tasks" },
  async (): Promise<{ tasks: Task[] }> => {
    return { tasks };
  }
);
 
// الحصول على مهمة بالمعرّف
export const get = api(
  { expose: true, method: "GET", path: "/tasks/:id" },
  async (req: { id: number }): Promise<Task> => {
    const task = tasks.find((t) => t.id === req.id);
    if (!task) {
      throw new Error(`المهمة ${req.id} غير موجودة`);
    }
    return task;
  }
);

encore run

curl -X POST http://localhost:4000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "تعلم Encore", "description": "بناء واجهة برمجة تطبيقات للمهام"}'

// task/db.ts
import { SQLDatabase } from "encore.dev/storage/sqldb";
 
// الإعلان عن قاعدة البيانات — يوفرها Encore تلقائياً
const db = new SQLDatabase("taskdb", {
  migrations: "./migrations",
});
 
export default db;

mkdir -p task/migrations

-- task/migrations/001_create_tasks.up.sql
CREATE TABLE tasks (
    id BIGSERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT NOT NULL DEFAULT '',
    completed BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);
 
CREATE INDEX idx_tasks_completed ON tasks(completed);

// task/task.ts
import { api } from "encore.dev/api";
import db from "./db";
 
interface Task {
  id: number;
  title: string;
  description: string;
  completed: boolean;
  createdAt: string;
}
 
interface CreateParams {
  title: string;
  description: string;
}
 
interface ListResponse {
  tasks: Task[];
}
 
// إنشاء مهمة جديدة
export const create = api(
  { expose: true, method: "POST", path: "/tasks" },
  async (req: CreateParams): Promise<Task> => {
    const row = await db.queryRow`
      INSERT INTO tasks (title, description)
      VALUES (${req.title}, ${req.description})
      RETURNING id, title, description, completed, created_at
    `;
    return rowToTask(row!);
  }
);
 
// عرض جميع المهام
export const list = api(
  { expose: true, method: "GET", path: "/tasks" },
  async (): Promise<ListResponse> => {
    const rows = await db.query`
      SELECT id, title, description, completed, created_at
      FROM tasks
      ORDER BY created_at DESC
    `;
    const tasks: Task[] = [];
    for await (const row of rows) {
      tasks.push(rowToTask(row));
    }
    return { tasks };
  }
);
 
// الحصول على مهمة بالمعرّف
export const get = api(
  { expose: true, method: "GET", path: "/tasks/:id" },
  async (req: { id: number }): Promise<Task> => {
    const row = await db.queryRow`
      SELECT id, title, description, completed, created_at
      FROM tasks WHERE id = ${req.id}
    `;
    if (!row) throw new Error(`المهمة ${req.id} غير موجودة`);
    return rowToTask(row);
  }
);
 
// تحديث مهمة
export const update = api(
  { expose: true, method: "PUT", path: "/tasks/:id" },
  async (req: {
    id: number;
    title?: string;
    description?: string;
    completed?: boolean;
  }): Promise<Task> => {
    const row = await db.queryRow`
      UPDATE tasks SET
        title = COALESCE(${req.title ?? null}, title),
        description = COALESCE(${req.description ?? null}, description),
        completed = COALESCE(${req.completed ?? null}, completed)
      WHERE id = ${req.id}
      RETURNING id, title, description, completed, created_at
    `;
    if (!row) throw new Error(`المهمة ${req.id} غير موجودة`);
    return rowToTask(row);
  }
);
 
// حذف مهمة
export const remove = api(
  { expose: true, method: "DELETE", path: "/tasks/:id" },
  async (req: { id: number }): Promise<void> => {
    await db.exec`DELETE FROM tasks WHERE id = ${req.id}`;
  }
);
 
// دالة مساعدة لتحويل صف قاعدة البيانات إلى مهمة
function rowToTask(row: any): Task {
  return {
    id: row.id,
    title: row.title,
    description: row.description,
    completed: row.completed,
    createdAt: row.created_at.toISOString(),
  };
}

// task/events.ts
import { Topic } from "encore.dev/pubsub";
 
// تعريف نوع الحدث
export interface TaskCompletedEvent {
  taskId: number;
  title: string;
  completedAt: string;
}
 
// إنشاء الموضوع
export const taskCompleted = new Topic<TaskCompletedEvent>("task-completed", {
  deliveryGuarantee: "at-least-once",
});

// في task/task.ts — أضف هذا الاستيراد في الأعلى
import { taskCompleted } from "./events";
 
// حدّث دالة update لنشر الأحداث
export const update = api(
  { expose: true, method: "PUT", path: "/tasks/:id" },
  async (req: {
    id: number;
    title?: string;
    description?: string;
    completed?: boolean;
  }): Promise<Task> => {
    const row = await db.queryRow`
      UPDATE tasks SET
        title = COALESCE(${req.title ?? null}, title),
        description = COALESCE(${req.description ?? null}, description),
        completed = COALESCE(${req.completed ?? null}, completed)
      WHERE id = ${req.id}
      RETURNING id, title, description, completed, created_at
    `;
    if (!row) throw new Error(`المهمة ${req.id} غير موجودة`);
    const task = rowToTask(row);
 
    // نشر حدث إذا تم تعليم المهمة كمكتملة
    if (req.completed === true) {
      await taskCompleted.publish({
        taskId: task.id,
        title: task.title,
        completedAt: new Date().toISOString(),
      });
    }
 
    return task;
  }
);

mkdir notification

// notification/encore.service.ts
import { Service } from "encore.dev/service";
 
export default new Service("notification");

// notification/notification.ts
import { Subscription } from "encore.dev/pubsub";
import { taskCompleted, TaskCompletedEvent } from "../task/events";
 
// الاشتراك في أحداث اكتمال المهام
const _ = new Subscription(taskCompleted, "notify-on-complete", {
  handler: async (event: TaskCompletedEvent) => {
    console.log(
      `مهمة مكتملة: "${event.title}" (المعرّف: ${event.taskId}) في ${event.completedAt}`
    );
    // في الإنتاج، سترسل بريداً إلكترونياً أو رسالة Slack، إلخ.
  },
});

// task/cron.ts
import { CronJob } from "encore.dev/cron";
import db from "./db";
 
// التنفيذ كل يوم الساعة 9:00 صباحاً بتوقيت UTC
const dailySummary = new CronJob("daily-task-summary", {
  title: "ملخص المهام اليومي",
  schedule: "0 9 * * *",
  endpoint: sendDailySummary,
});
 
async function sendDailySummary() {
  const row = await db.queryRow`
    SELECT
      COUNT(*) FILTER (WHERE completed = false) as pending,
      COUNT(*) FILTER (WHERE completed = true) as done,
      COUNT(*) as total
    FROM tasks
  `;
 
  console.log(
    `الملخص اليومي — قيد الانتظار: ${row!.pending}، مكتملة: ${row!.done}، الإجمالي: ${row!.total}`
  );
}

// auth/encore.service.ts
import { Service } from "encore.dev/service";
 
export default new Service("auth");

// auth/auth.ts
import { authHandler } from "encore.dev/auth";
import { Header } from "encore.dev/api";
 
interface AuthParams {
  authorization: Header<"Authorization">;
}
 
interface AuthData {
  userId: string;
  role: string;
}
 
// تعريف معالج المصادقة
export const auth = authHandler(
  async (params: AuthParams): Promise<AuthData> => {
    const token = params.authorization?.replace("Bearer ", "");
 
    if (!token) {
      throw new Error("رمز التفويض مفقود");
    }
 
    // في الإنتاج، تحقق من JWT أو ابحث عن مفتاح API
    // لهذا الدرس، نستخدم تحققاً بسيطاً
    if (token === "admin-secret-key") {
      return { userId: "admin", role: "admin" };
    }
 
    throw new Error("رمز غير صالح");
  }
);

// في task/task.ts — حدّث نقطة نهاية create
export const create = api(
  { expose: true, auth: true, method: "POST", path: "/tasks" },
  async (req: CreateParams): Promise<Task> => {
    // req يتضمن الآن بيانات المصادقة
    // ... نفس التنفيذ
  }
);

// task/task.test.ts
import { describe, it, expect } from "vitest";
import { create, list, get, update, remove } from "./task";
 
describe("واجهة برمجة تطبيقات المهام", () => {
  it("يجب أن ينشئ مهمة", async () => {
    const task = await create({
      title: "مهمة اختبار",
      description: "مهمة للاختبار",
    });
 
    expect(task.title).toBe("مهمة اختبار");
    expect(task.description).toBe("مهمة للاختبار");
    expect(task.completed).toBe(false);
    expect(task.id).toBeGreaterThan(0);
  });
 
  it("يجب أن يعرض المهام", async () => {
    const result = await list();
    expect(result.tasks.length).toBeGreaterThan(0);
  });
 
  it("يجب أن يحدّث مهمة", async () => {
    const task = await create({
      title: "للإكمال",
      description: "ستُكمل",
    });
 
    const updated = await update({
      id: task.id,
      completed: true,
    });
 
    expect(updated.completed).toBe(true);
  });
 
  it("يجب أن يحذف مهمة", async () => {
    const task = await create({
      title: "للحذف",
      description: "ستُحذف",
    });
 
    await remove({ id: task.id });
 
    await expect(get({ id: task.id })).rejects.toThrow();
  });
});

encore test ./task/...

encore gen client task-api --output=./client --lang=typescript

import Client from "./client";
 
const client = new Client({ baseURL: "http://localhost:4000" });
 
// مكتمل الأنواع — الإكمال التلقائي في المحرر يعمل بشكل مثالي
const task = await client.task.create({
  title: "من الواجهة الأمامية",
  description: "تم إنشاؤه عبر العميل المُولّد",
});
 
const allTasks = await client.task.list();

git add -A
git commit -m "feat: واجهة برمجة تطبيقات إدارة المهام مع قاعدة بيانات وpub/sub وcron"
git push encore main

encore app open