GraphQL API مع Kotlin: دليل تعليمي عملي خطوة بخطوة

مقدمة: لماذا يعتبر GraphQL و Kotlin ثنائياً مثالياً؟

في تطوير الويب الحديث، يحدد اختيار الأداة المناسبة لإنشاء API سرعة التطوير وسهولة الصيانة. GraphQL هي لغة استعلام تسمح للعملاء بطلب البيانات التي يحتاجونها فقط، مما يخلص من مشكلة over-fetching و under-fetching المميزة لـ REST. Kotlin، بدوره، هو لغة حديثة وموجزة وآمنة، وهي مثالية لتطوير الباك إند، خاصةً عند استخدامها مع Spring Boot.

في هذا البرنامج التعليمي، سنقوم عملياً بإنشاء GraphQL API كامل باستخدام Kotlin. ستتعلم كيفية إعداد الخادم، وتحديد المخطط (schema)، وتنفيذ الاستعلامات (queries) والتحويرات (mutations)، بالإضافة إلى اختبار API النهائي. في نهاية المقال، سيكون لديك مشروع عملي يمكنك استخدامه كأساس لتطبيقاتك الخاصة.

1. إعداد المشروع والتبعيات (dependencies)

أولاً، سنقوم بإنشاء مشروع Spring Boot جديد مع دعم GraphQL. سنستخدم Spring for GraphQL — التكامل الرسمي الذي يجعل العمل في غاية البساطة.

1.1. إنشاء المشروع

يمكنك استخدام Spring Initializr أو أي بيئة تطوير متكاملة IDE (مثل IntelliJ IDEA). أضف التبعيات التالية:

• Spring Web
• Spring for GraphQL
• Spring Data JPA
• H2 Database (للبساطة)

في ملف build.gradle.kts يجب أن تكون الأسطر التالية موجودة:

dependencies {    implementation("org.springframework.boot:spring-boot-starter-web")    implementation("org.springframework.boot:spring-boot-starter-graphql")    implementation("org.springframework.boot:spring-boot-starter-data-jpa")    runtimeOnly("com.h2database:h2")    testImplementation("org.springframework.boot:spring-boot-starter-test")}

1.2. الإعدادات (Configuration)

سنقوم بإنشاء كيان (entity) بسيط باسم Book ومستودع (repository) للعمل مع قاعدة البيانات.

// Book.kt@Entitydata class Book(    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)    val id: Long = 0,    val title: String,    val author: String,    val year: Int)

// BookRepository.ktinterface BookRepository : JpaRepository<Book, Long>

2. إنشاء مخطط GraphQL ووحدة التحكم (Controller)

يستخدم GraphQL كتابة (typing) صارمة. يحدد المخطط (schema) البيانات المتاحة وكيف يمكن طلبها. في Spring for GraphQL، يمكن وصف المخطط باستخدام التعليقات التوضيحية (annotations).

2.1. تعريف المخطط عبر الكود

سنقوم بإنشاء كلاس وحدة تحكم (controller class) سيعالج استعلامات GraphQL. نستخدم التعليق التوضيحي @QueryMapping لقراءة البيانات و @MutationMapping للتعديلات.

// BookController.kt@Controllerclass BookController(private val repository: BookRepository) {

    @QueryMapping    fun allBooks(): List<Book> = repository.findAll()

    @QueryMapping    fun bookById(@Argument id: Long): Book? = repository.findById(id).orElse(null)

    @MutationMapping    fun addBook(@Argument title: String, @Argument author: String, @Argument year: Int): Book {        val book = Book(title = title, author = author, year = year)        return repository.save(book)    }

    @MutationMapping    fun deleteBook(@Argument id: Long): Boolean {        if (repository.existsById(id)) {            repository.deleteById(id)            return true        }        return false    }}

2.2. البديل: ملف المخطط .graphqls

يمكنك أيضاً تعريف المخطط في ملف منفصل باسم schema.graphqls داخل مجلد resources/graphql:

type Query {    allBooks: [Book]    bookById(id: ID!): Book}

type Mutation {    addBook(title: String!, author: String!, year: Int!): Book    deleteBook(id: ID!): Boolean}

type Book {    id: ID!    title: S