معالجة رموز Kotlin (KSP): دليل شامل مع أمثلة

1. ما هي KSP ولماذا تحتاجها؟

معالجة رموز Kotlin (KSP) هي مكتبة وإضافة للمترجم (compiler plugin) للغة Kotlin، طورتها شركة JetBrains. مهمتها الأساسية هي توفير واجهة برمجة تطبيقات (API) بسيطة وسريعة وموثوقة للمطورين لتحليل كود Kotlin المصدر أثناء مرحلة الترجمة (compile time) وتوليد كود جديد بناءً عليه (code generation). تعتبر KSP بديلاً مباشراً للآلية القديمة javax.annotation.processing (Java Annotation Processing) التي صُممت لجافا وتعاني من قيود عند العمل مع Kotlin.

لماذا تحتاج KSP؟ في التطوير الحديث باستخدام Kotlin، غالباً ما نحتاج إلى إنشاء كود متكرر (boilerplate code) تلقائياً: مثل كلاسات DTO، وكلاسات التخطيط (mappers)، وتطبيقات Parcelable، وكيانات Room، ومحولات Moshi، وغيرها الكثير. تتيح لك KSP القيام بذلك أثناء مرحلة الترجمة، دون استخدام الانعكاس (reflection) في وقت التشغيل (runtime)، مما يحسن أداء التطبيق. على عكس KAPT (Kotlin Annotation Processing Tool)، تعمل KSP مباشرة مع شجرة AST الخاصة بـ Kotlin، متجاوزة المرحلة الوسيطة لجافا، مما يوفر زيادة في السرعة تتراوح بين 2 إلى 4 أضعاف. كما تدعم KSP بشكل أفضل تراكيب Kotlin اللغوية الجديدة (مثل دوال suspend، والكلاسات المضمنة inline classes، وكلاسات القيمة value classes) ولا تتطلب إنشاء كلاسات جافا وهمية (Java stubs).

تعتبر KSP مثالية لإنشاء مكتبات توليد الأكواد الخاصة بك، والأطر (frameworks) المشابهة لـ Dagger و Room و Glide، وأدوات البرمجة الوصفية (metaprogramming). تُستخدم KSP بنشاط في النظام البيئي لـ Kotlin: في Compose و Room و Moshi و Koin و Apollo GraphQL والعديد من المكتبات الشهيرة الأخرى.

2. التثبيت

لا يتم تثبيت KSP عبر pip أو npm، بل عبر نظام البناء Gradle. لمشروع Kotlin، ستحتاج إلى إضافة إضافة KSP (plugin) وإصدارها المطابق لإصدار Kotlin.

الأمر الدقيق للإضافة في ملف build.gradle.kts (المشروع الجذر):

// build.gradle.kts (المستوى الجذر)
plugins {
    id("org.jetbrains.kotlin.jvm") version "1.9.22" apply false
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

// build.gradle.kts (وحدة التطبيق)
plugins {
    id("org.jetbrains.kotlin.jvm")
    id("com.google.devtools.ksp")
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.22")
    implementation("com.squareup:kotlinpoet:1.16.0") // لتوليد الكود
    ksp("com.example:my-processor:1.0.0") // المعالج الخاص بك
}

لـ Gradle Groovy (build.gradle):