مكتبة GraphQL لـ TypeScript: دليل شامل للأدوات

مكتبة GraphQL لـ TypeScript: نهج حديث لـ API

GraphQL هي لغة استعلام لـ API تتيح للعملاء طلب البيانات الضرورية فقط. عند دمجها مع TypeScript، فإنها توفر نظام أنواع قوي يضمن الأمان والإكمال التلقائي. على موقع pythonlib.ru، سنستعرض المكتبة الرئيسية للعمل مع GraphQL في TypeScript وهي type-graphql، بالإضافة إلى البدائل.

لماذا TypeScript + GraphQL؟

يضيف TypeScript الكتابة الثابتة (static typing)، وهو أمر بالغ الأهمية للمشاريع الكبيرة. مخطط GraphQL (schema) الموصوف عبر فئات TypeScript يصبح مصدرًا واحدًا للحقيقة: التغييرات في الكود تتم مزامنتها تلقائيًا مع API. هذا يزيل التناقضات بين التوثيق والسلوك الفعلي للخادم.

المكتبة الرئيسية: TypeGraphQL

type-graphql هو إطار عمل لإنشاء GraphQL API على TypeScript باستخدام الديكورات (decorators). يتبع مبدأ code-first: حيث تحدد المخطط من خلال الكود، وليس من خلال SDL (لغة تعريف المخطط).

التثبيت

npm install type-graphql graphql reflect-metadata

أضف إلى ملف tsconfig.json:

{  "emitDecoratorMetadata": true,  "experimentalDecorators": true}

مثال: تعريف النوع والمحلل (resolver)

لنقم بإنشاء نموذج بسيط لمستخدم ومحلل لجلب البيانات.

import { ObjectType, Field, ID, Resolver, Query } from "type-graphql";

@ObjectType()class User {  @Field(() => ID)  id: number;

  @Field()  name: string;

  @Field({ nullable: true })  email?: string;}

@Resolver()class UserResolver {  @Query(() => [User])  users(): User[] {    return [      { id: 1, name: "آنا", email: "anna@example.com" },      { id: 2, name: "بوريس", email: null }    ];  }}

بناء وتشغيل الخادم

import { buildSchema } from "type-graphql";import { ApolloServer } from "@apollo/server";import { startStandaloneServer } from "@apollo/server/standalone";

async function main() {  const schema = await buildSchema({    resolvers: [UserResolver]  });

  const server = new ApolloServer({ schema });  const { url } = await startStandaloneServer(server, { listen: { port: 4000 } });  console.log(`الخادم قيد التشغيل: ${url}`);}

main();

المكتبات البديلة

• NestJS + GraphQL — التكامل مع إطار العمل الشهير. يستخدم @nestjs/graphql المبني على type-graphql.
• GraphQL Nexus — مكتبة code-first بدون ديكورات، تستخدم سلاسل الدوال (method chaining).
• Pothos GraphQL — مكتبة code-first حديثة مع دعم ممتاز لـ TypeScript.

الإمكانيات المتقدمة لـ TypeGraphQL

الوسائط والتحولات (Arguments and Mutations)

import { Arg, Mutation } from "type-graphql";

@Resolver()class UserResolver {  @Mutation(() => User)  createUser(@Arg("name") name: string, @Arg("email") email: string): User {    return { id: 3, name, email };  }}

التحقق من الصحة باستخدام class-validator

import { Length, IsEmail } from "class-validator";import { InputType, Field } from "type-graphql";

@InputType()class CreateUserInput {  @Field()  @Length(2, 30)  name: string;

  @Field()  @IsEmail()  email: string;}

التفويض (Authorization) عبر middleware

import { UseMiddleware } from "type-graphql";

function AuthMiddleware(): MiddlewareFn {  return async ({ context }, next) => {    if (!context.user) throw new Error("غير مصرح به");    return next();  };}

@Resolver()class UserResolver {  @Query(() => User)  @UseMiddleware(AuthMiddleware)  me(): User {    return { id: 1, name: "المستخدم الحالي", email: "user@example.com" };  }}

التكامل مع