GraphQL API مع C#: دليل تعليمي خطوة بخطوة لمطوري .NET

مقدمة إلى GraphQL على منصة .NET

GraphQL هي لغة استعلام لواجهات API، تتيح للعملاء الحصول فقط على البيانات التي يحتاجونها حقًا. على عكس REST، حيث يكون هيكل الاستجابة محددًا بشكل صارم من قبل الخادم، تسمح GraphQL بتشكيل الاستعلامات بمرونة. في هذا البرنامج التعليمي، سنقوم بإنشاء واجهة GraphQL API كاملة بلغة C# باستخدام إطار العمل Hot Chocolate - الحل الأكثر شيوعًا لـ .NET.

سننتقل من مرحلة التثبيت إلى إنشاء استعلامات معقدة مع التعديلات (mutations) والاشتراكات (subscriptions). المقالة موجهة للمطورين الملمين بأساسيات C# و ASP.NET Core.

1. إعداد المشروع وتثبيت التبعيات

للبدء، سننشئ مشروع ASP.NET Core جديد. يمكنك استخدام Visual Studio أو Rider أو سطر الأوامر.

dotnet new web -n GraphQLDemocd GraphQLDemo

الآن سنقوم بتثبيت حزمة Hot Chocolate - الأداة الرئيسية للعمل مع GraphQL في .NET:

dotnet add package HotChocolate.AspNetCore

بالإضافة إلى ذلك، للعمل مع الاستعلامات عبر GraphQL IDE (Banana Cake Pop)، سنقوم بتثبيت:

dotnet add package HotChocolate.AspNetCore.Playground

1.1 التهيئة الأساسية لـ Program.cs

افتح ملف Program.cs وقم بتهيئة الخدمات:

var builder = WebApplication.CreateBuilder(args);

builder.Services    .AddGraphQLServer()    .AddQueryType<Query>();

var app = builder.Build();

app.MapGraphQL();

app.Run();

لاحظ: نحن نسجل Query - وهو النوع الجذري لقراءة البيانات. حاليًا هو فارغ، لكننا سنملؤه.

2. إنشاء نموذج البيانات وأول استعلام

تعمل GraphQL مع الأنواع. لننشئ نموذجًا بسيطًا Book:

public class Book{    public int Id { get; set; }    public string Title { get; set; }    public string Author { get; set; }    public int Year { get; set; }}

الآن سنحدد الفئة Query التي ستعيد البيانات:

public class Query{    private static List<Book> _books = new()    {        new Book { Id = 1, Title = "1984", Author = "George Orwell", Year = 1949 },        new Book { Id = 2, Title = "Clean Code", Author = "Robert C. Martin", Year = 2008 }    };

    public IQueryable<Book> GetBooks() => _books.AsQueryable();

    public Book? GetBookById(int id) => _books.FirstOrDefault(b => b.Id == id);}

قم بتشغيل التطبيق وافتح http://localhost:5000/graphql. سترى Banana Cake Pop - بيئة تطوير متكاملة مدمجة لاختبار الاستعلامات. جرب تنفيذ:

{  books {    title    author  }}

ستحصل فقط على الحقول التي طلبتها - هذه هي قوة GraphQL.

3. التعديلات (Mutations) لتغيير البيانات

التعديلات هي ما يعادل POST/PUT/DELETE في REST. تسمح بتغيير البيانات على الخادم. سنضيف إمكانية إضافة كتب جديدة.

3.1 تعريف نوع الإدخال

لننشئ فئة لبيانات الإدخال الخاصة بالتعديل:

public class AddBookInput{    public string Title { get; set; }    public string Author { get; set; }    public int Year { get; set; }}

3.2 تنفيذ التعديل

أضف الفئة Mutation:

public class Mutation{    private static List<Book> _books = new()    {        new Book { Id = 1, Title = "1984", Author = "George Orwell", Year = 1949 },        new Book { Id = 2, Title = "Clean Code", Author = "Robert C. Martin", Year = 2008 }    };

    public Book AddBook(AddBookInput input)    {        var newBook = new Book        {            Id = _books.Max(b => b.Id) + 1,            Title = input.Title,            Author = input.Author,            Year = input.Year        };        _books.Add(newBook);        return newBook;    }