بناء واجهات برمجة تطبيقات جاهزة للإنتاج باستخدام Fastify و TypeScript

mkdir fastify-tasks-api && cd fastify-tasks-api
npm init -y

npm install fastify @fastify/cors @fastify/rate-limit @fastify/jwt @fastify/swagger @fastify/swagger-ui @sinclair/typebox drizzle-orm postgres dotenv

npm install -D typescript @types/node tsx vitest drizzle-kit

npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "test": "vitest",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}

DATABASE_URL=postgres://postgres:postgres@localhost:5432/fastify_tasks
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production
PORT=3000
HOST=0.0.0.0
NODE_ENV=development

// src/config/env.ts
import { Type, type Static } from "@sinclair/typebox";
import { Value } from "@sinclair/typebox/value";
import "dotenv/config";
 
const EnvSchema = Type.Object({
  DATABASE_URL: Type.String(),
  JWT_SECRET: Type.String({ minLength: 32 }),
  JWT_REFRESH_SECRET: Type.String({ minLength: 32 }),
  PORT: Type.Number({ default: 3000 }),
  HOST: Type.String({ default: "0.0.0.0" }),
  NODE_ENV: Type.Union([
    Type.Literal("development"),
    Type.Literal("production"),
    Type.Literal("test"),
  ]),
});
 
type Env = Static<typeof EnvSchema>;
 
const rawEnv = {
  ...process.env,
  PORT: Number(process.env.PORT) || 3000,
};
 
if (!Value.Check(EnvSchema, rawEnv)) {
  const errors = [...Value.Errors(EnvSchema, rawEnv)];
  console.error("❌ متغيرات بيئة غير صالحة:");
  errors.forEach((err) => console.error(`  ${err.path}: ${err.message}`));
  process.exit(1);
}
 
export const env: Env = rawEnv as Env;

docker run -d --name fastify-pg \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=fastify_tasks \
  -p 5432:5432 \
  postgres:16-alpine

// src/db/schema.ts
import {
  pgTable,
  uuid,
  varchar,
  text,
  timestamp,
  boolean,
  pgEnum,
} from "drizzle-orm/pg-core";
 
export const taskStatusEnum = pgEnum("task_status", [
  "todo",
  "in_progress",
  "done",
  "cancelled",
]);
 
export const taskPriorityEnum = pgEnum("task_priority", [
  "low",
  "medium",
  "high",
  "urgent",
]);
 
export const users = pgTable("users", {
  id: uuid("id").defaultRandom().primaryKey(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  passwordHash: varchar("password_hash", { length: 255 }).notNull(),
  name: varchar("name", { length: 100 }).notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().notNull(),
});
 
export const projects = pgTable("projects", {
  id: uuid("id").defaultRandom().primaryKey(),
  name: varchar("name", { length: 200 }).notNull(),
  description: text("description"),
  ownerId: uuid("owner_id")
    .references(() => users.id)
    .notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().notNull(),
});
 
export const tasks = pgTable("tasks", {
  id: uuid("id").defaultRandom().primaryKey(),
  title: varchar("title", { length: 300 }).notNull(),
  description: text("description"),
  status: taskStatusEnum("status").default("todo").notNull(),
  priority: taskPriorityEnum("priority").default("medium").notNull(),
  dueDate: timestamp("due_date"),
  completed: boolean("completed").default(false).notNull(),
  projectId: uuid("project_id")
    .references(() => projects.id)
    .notNull(),
  assigneeId: uuid("assignee_id").references(() => users.id),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().notNull(),
});

// src/db/index.ts
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { env } from "../config/env.js";
import * as schema from "./schema.js";
 
const client = postgres(env.DATABASE_URL);
export const db = drizzle(client, { schema });
export type Database = typeof db;

// drizzle.config.ts
import { defineConfig } from "drizzle-kit";
 
export default defineConfig({
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

npm run db:generate
npm run db:migrate

// src/utils/errors.ts
export class AppError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public code: string
  ) {
    super(message);
    this.name = "AppError";
  }
}
 
export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(404, `${resource} with id '${id}' not found`, "NOT_FOUND");
  }
}
 
export class UnauthorizedError extends AppError {
  constructor(message = "Authentication required") {
    super(401, message, "UNAUTHORIZED");
  }
}
 
export class ForbiddenError extends AppError {
  constructor(message = "Insufficient permissions") {
    super(403, message, "FORBIDDEN");
  }
}
 
export class ConflictError extends AppError {
  constructor(message: string) {
    super(409, message, "CONFLICT");
  }
}
 
export class ValidationError extends AppError {
  constructor(message: string) {
    super(400, message, "VALIDATION_ERROR");
  }
}

// src/plugins/auth.ts
import fp from "fastify-plugin";
import fjwt from "@fastify/jwt";
import { type FastifyInstance, type FastifyRequest } from "fastify";
import { env } from "../config/env.js";
import { UnauthorizedError } from "../utils/errors.js";
 
declare module "fastify" {
  interface FastifyInstance {
    authenticate: (
      request: FastifyRequest
    ) => Promise<void>;
  }
}
 
declare module "@fastify/jwt" {
  interface FastifyJWT {
    payload: { userId: string; email: string };
    user: { userId: string; email: string };
  }
}
 
export default fp(async (fastify: FastifyInstance) => {
  await fastify.register(fjwt, {
    secret: env.JWT_SECRET,
    sign: { expiresIn: "15m" },
  });
 
  fastify.decorate(
    "authenticate",
    async (request: FastifyRequest) => {
      try {
        await request.jwtVerify();
      } catch {
        throw new UnauthorizedError("رمز غير صالح أو منتهي الصلاحية");
      }
    }
  );
});

// src/modules/auth/auth.schema.ts
import { Type, type Static } from "@sinclair/typebox";
 
export const RegisterBody = Type.Object({
  email: Type.String({ format: "email" }),
  password: Type.String({ minLength: 8, maxLength: 128 }),
  name: Type.String({ minLength: 1, maxLength: 100 }),
});
 
export const LoginBody = Type.Object({
  email: Type.String({ format: "email" }),
  password: Type.String(),
});
 
export const AuthResponse = Type.Object({
  accessToken: Type.String(),
  refreshToken: Type.String(),
  user: Type.Object({
    id: Type.String(),
    email: Type.String(),
    name: Type.String(),
  }),
});
 
export type RegisterBodyType = Static<typeof RegisterBody>;
export type LoginBodyType = Static<typeof LoginBody>;
export type AuthResponseType = Static<typeof AuthResponse>;

// src/modules/tasks/tasks.schema.ts
import { Type, type Static } from "@sinclair/typebox";
 
export const TaskParams = Type.Object({
  id: Type.String({ format: "uuid" }),
});
 
export const TaskQuerystring = Type.Object({
  status: Type.Optional(
    Type.Union([
      Type.Literal("todo"),
      Type.Literal("in_progress"),
      Type.Literal("done"),
      Type.Literal("cancelled"),
    ])
  ),
  priority: Type.Optional(
    Type.Union([
      Type.Literal("low"),
      Type.Literal("medium"),
      Type.Literal("high"),
      Type.Literal("urgent"),
    ])
  ),
  projectId: Type.Optional(Type.String({ format: "uuid" })),
  page: Type.Optional(Type.Number({ minimum: 1, default: 1 })),
  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 20 })),
});
 
export const CreateTaskBody = Type.Object({
  title: Type.String({ minLength: 1, maxLength: 300 }),
  description: Type.Optional(Type.String()),
  status: Type.Optional(
    Type.Union([
      Type.Literal("todo"),
      Type.Literal("in_progress"),
      Type.Literal("done"),
      Type.Literal("cancelled"),
    ])
  ),
  priority: Type.Optional(
    Type.Union([
      Type.Literal("low"),
      Type.Literal("medium"),
      Type.Literal("high"),
      Type.Literal("urgent"),
    ])
  ),
  dueDate: Type.Optional(Type.String({ format: "date-time" })),
  projectId: Type.String({ format: "uuid" }),
  assigneeId: Type.Optional(Type.String({ format: "uuid" })),
});
 
export const UpdateTaskBody = Type.Partial(CreateTaskBody);
 
export const TaskResponse = Type.Object({
  id: Type.String(),
  title: Type.String(),
  description: Type.Union([Type.String(), Type.Null()]),
  status: Type.String(),
  priority: Type.String(),
  dueDate: Type.Union([Type.String(), Type.Null()]),
  completed: Type.Boolean(),
  projectId: Type.String(),
  assigneeId: Type.Union([Type.String(), Type.Null()]),
  createdAt: Type.String(),
  updatedAt: Type.String(),
});
 
export const TaskListResponse = Type.Object({
  data: Type.Array(TaskResponse),
  total: Type.Number(),
  page: Type.Number(),
  limit: Type.Number(),
});
 
export type TaskParamsType = Static<typeof TaskParams>;
export type TaskQuerystringType = Static<typeof TaskQuerystring>;
export type CreateTaskBodyType = Static<typeof CreateTaskBody>;
export type UpdateTaskBodyType = Static<typeof UpdateTaskBody>;

// src/modules/tasks/tasks.service.ts
import { eq, and, sql, type SQL } from "drizzle-orm";
import { type Database } from "../../db/index.js";
import { tasks } from "../../db/schema.js";
import {
  type CreateTaskBodyType,
  type UpdateTaskBodyType,
  type TaskQuerystringType,
} from "./tasks.schema.js";
import { NotFoundError } from "../../utils/errors.js";
 
export class TasksService {
  constructor(private db: Database) {}
 
  async list(query: TaskQuerystringType) {
    const page = query.page ?? 1;
    const limit = query.limit ?? 20;
    const offset = (page - 1) * limit;
 
    const conditions: SQL[] = [];
    if (query.status) conditions.push(eq(tasks.status, query.status));
    if (query.priority) conditions.push(eq(tasks.priority, query.priority));
    if (query.projectId) conditions.push(eq(tasks.projectId, query.projectId));
 
    const where = conditions.length > 0 ? and(...conditions) : undefined;
 
    const [data, countResult] = await Promise.all([
      this.db
        .select()
        .from(tasks)
        .where(where)
        .limit(limit)
        .offset(offset)
        .orderBy(tasks.createdAt),
      this.db
        .select({ count: sql<number>`count(*)` })
        .from(tasks)
        .where(where),
    ]);
 
    return {
      data,
      total: Number(countResult[0].count),
      page,
      limit,
    };
  }
 
  async getById(id: string) {
    const result = await this.db
      .select()
      .from(tasks)
      .where(eq(tasks.id, id))
      .limit(1);
 
    if (result.length === 0) {
      throw new NotFoundError("Task", id);
    }
    return result[0];
  }
 
  async create(data: CreateTaskBodyType) {
    const result = await this.db
      .insert(tasks)
      .values({
        title: data.title,
        description: data.description,
        status: data.status ?? "todo",
        priority: data.priority ?? "medium",
        dueDate: data.dueDate ? new Date(data.dueDate) : null,
        projectId: data.projectId,
        assigneeId: data.assigneeId,
      })
      .returning();
 
    return result[0];
  }
 
  async update(id: string, data: UpdateTaskBodyType) {
    await this.getById(id);
 
    const result = await this.db
      .update(tasks)
      .set({
        ...data,
        dueDate: data.dueDate ? new Date(data.dueDate) : undefined,
        updatedAt: new Date(),
      })
      .where(eq(tasks.id, id))
      .returning();
 
    return result[0];
  }
 
  async delete(id: string) {
    await this.getById(id);
    await this.db.delete(tasks).where(eq(tasks.id, id));
  }
}

// src/modules/tasks/tasks.routes.ts
import { type FastifyInstance } from "fastify";
import { TasksService } from "./tasks.service.js";
import {
  TaskParams,
  TaskQuerystring,
  CreateTaskBody,
  UpdateTaskBody,
  TaskResponse,
  TaskListResponse,
  type TaskParamsType,
  type TaskQuerystringType,
  type CreateTaskBodyType,
  type UpdateTaskBodyType,
} from "./tasks.schema.js";
import { db } from "../../db/index.js";
 
export default async function tasksRoutes(fastify: FastifyInstance) {
  const service = new TasksService(db);
 
  fastify.addHook("onRequest", fastify.authenticate);
 
  // GET /tasks
  fastify.get<{ Querystring: TaskQuerystringType }>(
    "/",
    {
      schema: {
        querystring: TaskQuerystring,
        response: { 200: TaskListResponse },
        tags: ["Tasks"],
        summary: "قائمة جميع المهام مع فلاتر اختيارية",
      },
    },
    async (request) => {
      return service.list(request.query);
    }
  );
 
  // GET /tasks/:id
  fastify.get<{ Params: TaskParamsType }>(
    "/:id",
    {
      schema: {
        params: TaskParams,
        response: { 200: TaskResponse },
        tags: ["Tasks"],
        summary: "الحصول على مهمة بالمعرف",
      },
    },
    async (request) => {
      return service.getById(request.params.id);
    }
  );
 
  // POST /tasks
  fastify.post<{ Body: CreateTaskBodyType }>(
    "/",
    {
      schema: {
        body: CreateTaskBody,
        response: { 201: TaskResponse },
        tags: ["Tasks"],
        summary: "إنشاء مهمة جديدة",
      },
    },
    async (request, reply) => {
      const task = await service.create(request.body);
      return reply.status(201).send(task);
    }
  );
 
  // PATCH /tasks/:id
  fastify.patch<{ Params: TaskParamsType; Body: UpdateTaskBodyType }>(
    "/:id",
    {
      schema: {
        params: TaskParams,
        body: UpdateTaskBody,
        response: { 200: TaskResponse },
        tags: ["Tasks"],
        summary: "تحديث مهمة",
      },
    },
    async (request) => {
      return service.update(request.params.id, request.body);
    }
  );
 
  // DELETE /tasks/:id
  fastify.delete<{ Params: TaskParamsType }>(
    "/:id",
    {
      schema: {
        params: TaskParams,
        tags: ["Tasks"],
        summary: "حذف مهمة",
      },
    },
    async (request, reply) => {
      await service.delete(request.params.id);
      return reply.status(204).send();
    }
  );
}

// src/app.ts
import Fastify, { type FastifyInstance } from "fastify";
import cors from "@fastify/cors";
import rateLimit from "@fastify/rate-limit";
import swagger from "@fastify/swagger";
import swaggerUi from "@fastify/swagger-ui";
import authPlugin from "./plugins/auth.js";
import tasksRoutes from "./modules/tasks/tasks.routes.js";
import { AppError } from "./utils/errors.js";
import { env } from "./config/env.js";
 
export async function buildApp(): Promise<FastifyInstance> {
  const app = Fastify({
    logger: {
      level: env.NODE_ENV === "production" ? "info" : "debug",
      transport:
        env.NODE_ENV === "development"
          ? { target: "pino-pretty", options: { colorize: true } }
          : undefined,
    },
  });
 
  // --- الإضافات ---
  await app.register(cors, {
    origin: env.NODE_ENV === "production"
      ? ["https://yourdomain.com"]
      : true,
    credentials: true,
  });
 
  await app.register(rateLimit, {
    max: 100,
    timeWindow: "1 minute",
  });
 
  await app.register(authPlugin);
 
  // --- توثيق Swagger ---
  await app.register(swagger, {
    openapi: {
      info: {
        title: "Fastify Tasks API",
        version: "1.0.0",
        description: "واجهة برمجة تطبيقات لإدارة المهام جاهزة للإنتاج",
      },
      components: {
        securitySchemes: {
          bearerAuth: {
            type: "http",
            scheme: "bearer",
            bearerFormat: "JWT",
          },
        },
      },
      security: [{ bearerAuth: [] }],
    },
  });
 
  await app.register(swaggerUi, {
    routePrefix: "/docs",
  });
 
  // --- المسارات ---
  await app.register(tasksRoutes, { prefix: "/api/tasks" });
 
  // --- فحص الصحة ---
  app.get("/health", async () => ({
    status: "ok",
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
  }));
 
  // --- معالج الأخطاء العام ---
  app.setErrorHandler((error, request, reply) => {
    if (error instanceof AppError) {
      return reply.status(error.statusCode).send({
        error: error.code,
        message: error.message,
        statusCode: error.statusCode,
      });
    }
 
    if (error.validation) {
      return reply.status(400).send({
        error: "VALIDATION_ERROR",
        message: error.message,
        statusCode: 400,
      });
    }
 
    request.log.error(error);
    return reply.status(500).send({
      error: "INTERNAL_SERVER_ERROR",
      message:
        env.NODE_ENV === "production"
          ? "حدث خطأ غير متوقع"
          : error.message,
      statusCode: 500,
    });
  });
 
  return app;
}

// src/server.ts
import { buildApp } from "./app.js";
import { env } from "./config/env.js";
 
async function start() {
  const app = await buildApp();
 
  try {
    await app.listen({ port: env.PORT, host: env.HOST });
    app.log.info(`الخادم يعمل على http://${env.HOST}:${env.PORT}`);
    app.log.info(`توثيق API على http://${env.HOST}:${env.PORT}/docs`);
  } catch (err) {
    app.log.error(err);
    process.exit(1);
  }
}
 
start();

npm run dev

// أضف إلى src/server.ts بعد app.listen()
 
const signals: NodeJS.Signals[] = ["SIGINT", "SIGTERM"];
 
for (const signal of signals) {
  process.on(signal, async () => {
    app.log.info(`تم استلام ${signal}، جارٍ الإيقاف الآمن...`);
    await app.close();
    process.exit(0);
  });
}
 
process.on("unhandledRejection", (err) => {
  app.log.error(err, "رفض غير معالج");
  process.exit(1);
});

// src/modules/tasks/__tests__/tasks.routes.test.ts
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { buildApp } from "../../../app.js";
import { type FastifyInstance } from "fastify";
 
describe("Tasks Routes", () => {
  let app: FastifyInstance;
  let authToken: string;
 
  beforeAll(async () => {
    app = await buildApp();
 
    const registerRes = await app.inject({
      method: "POST",
      url: "/api/auth/register",
      payload: {
        email: "test@example.com",
        password: "securepassword123",
        name: "Test User",
      },
    });
 
    const body = JSON.parse(registerRes.body);
    authToken = body.accessToken;
  });
 
  afterAll(async () => {
    await app.close();
  });
 
  it("should return 401 without auth token", async () => {
    const response = await app.inject({
      method: "GET",
      url: "/api/tasks",
    });
 
    expect(response.statusCode).toBe(401);
  });
 
  it("should create a task", async () => {
    const response = await app.inject({
      method: "POST",
      url: "/api/tasks",
      headers: {
        authorization: `Bearer ${authToken}`,
      },
      payload: {
        title: "كتابة التوثيق",
        description: "كتابة توثيق API لوحدة المهام",
        priority: "high",
        projectId: "some-project-id",
      },
    });
 
    expect(response.statusCode).toBe(201);
    const task = JSON.parse(response.body);
    expect(task.title).toBe("كتابة التوثيق");
    expect(task.priority).toBe("high");
  });
 
  it("should validate request body", async () => {
    const response = await app.inject({
      method: "POST",
      url: "/api/tasks",
      headers: {
        authorization: `Bearer ${authToken}`,
      },
      payload: {
        description: "بدون عنوان",
      },
    });
 
    expect(response.statusCode).toBe(400);
  });
 
  it("should return health check", async () => {
    const response = await app.inject({
      method: "GET",
      url: "/health",
    });
 
    expect(response.statusCode).toBe(200);
    const body = JSON.parse(response.body);
    expect(body.status).toBe("ok");
  });
});

// vitest.config.ts
import { defineConfig } from "vitest/config";
 
export default defineConfig({
  test: {
    globals: true,
    environment: "node",
    include: ["src/**/*.test.ts"],
    coverage: {
      provider: "v8",
      reporter: ["text", "html"],
    },
  },
});

npm test

# مرحلة البناء
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
# مرحلة الإنتاج
FROM node:20-alpine AS runner
WORKDIR /app
 
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 fastify
 
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/drizzle ./drizzle
 
RUN npm ci --omit=dev
 
USER fastify
EXPOSE 3000
 
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 
CMD ["node", "dist/server.js"]

version: "3.8"
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/fastify_tasks
      - JWT_SECRET=dev-secret-that-is-at-least-32-chars-long
      - JWT_REFRESH_SECRET=dev-refresh-secret-32-chars-long-too
      - NODE_ENV=production
    depends_on:
      db:
        condition: service_healthy
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: fastify_tasks
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
 
volumes:
  pgdata:

schema: {
  response: {
    200: TaskResponse  // هذا يفعّل fast-json-stringify
  }
}

const client = postgres(env.DATABASE_URL, {
  max: 20,            // الحد الأقصى لحجم المجمع
  idle_timeout: 30,   // إغلاق الاتصالات الخاملة بعد 30 ثانية
  connect_timeout: 10 // مهلة الاتصالات الجديدة
});

import { readFileSync } from "fs";
 
const app = Fastify({
  http2: true,
  https: {
    key: readFileSync("./certs/key.pem"),
    cert: readFileSync("./certs/cert.pem"),
  },
});