Kotlin Academy · درس

إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet

استخدم KotlinPoet داخل معالج KSP لإنشاء شيفرة Kotlin آمنة للأنواع.

الدرس 3 من 414 خطوة

إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet درس مجاني في Kotlin Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Kotlin Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ما KotlinPoet؟

KotlinPoet هي واجهة برمجة تطبيقات Kotlin من Square لإنشاء ملفات المصدر .kt برمجيًا. وهي تنتج تعليمات برمجية بلغة Kotlin منسقة جيدًا واصطلاحية، وتتكامل طبيعيًا مع CodeGenerator الخاص بـ KSP.

إضافة التبعية

أضفوا KotlinPoet إلى وحدة المعالج:

dependencies {
    implementation("com.squareup:kotlinpoet:1.17.0")
    implementation("com.squareup:kotlinpoet-ksp:1.17.0") // KSP extensions
}

FileSpec: جذر الملف الذي تم إنشاؤه

تمثل FileSpec.builder(packageName, fileName) نقطة الدخول. أضيفوا إليها الأنواع والدوال والخصائص، ثم اكتبوا النتيجة عبر CodeGenerator الخاص بـ KSP:

val file = FileSpec.builder("com.example.generated", "MyFactory")
    .addType( /* TypeSpec here */ )
    .build()

TypeSpec: تعريف فئة

استخدم TypeSpec.classBuilder() للفئات، وobjectBuilder() للكائنات، وinterfaceBuilder() للواجهات. وسّط استدعاءات الباني لإضافة الدوال والخصائص والواجهات الفائقة:

val classSpec = TypeSpec.classBuilder("MyFactory")
    .addModifiers(KModifier.PUBLIC)
    .addFunction( /* FunSpec */ )
    .build()

FunSpec: إنشاء دالة

تنشئ FunSpec.builder(name) دالة. استخدم addParameter() وreturns() وaddStatement() لبناء توقيعها وجسمها:

val funSpec = FunSpec.builder("create")
    .addParameter("name", String::class)
    .returns(String::class)
    .addStatement("return "Hello, %L!", name")
    .build()

PropertySpec: إنشاء خاصية

استخدم PropertySpec.builder(name, type) لإنشاء الخصائص. حدّد KModifier.PRIVATE أو KModifier.OVERRIDE، أو استخدم mutable() من أجل var:

val propSpec = PropertySpec.builder("tag", String::class)
    .initializer("%S", "MyClass")
    .addModifiers(KModifier.PRIVATE)
    .build()

محدّدات تنسيق التعليمات البرمجية

تستخدم KotlinPoet محدّدات التنسيق في addStatement() وinitializer():

%L — قيمة حرفية (من دون علامات اقتباس)
%S — قيمة نصية حرفية (مع علامات اقتباس)
%T — اسم نوع (يعالج عمليات الاستيراد تلقائيًا)
%N — اسم (لمواصفة أو سلسلة نصية)

الاستيرادات التلقائية باستخدام %T

عند استخدام %T مع ClassName، تضيف KotlinPoet تلقائيًا الاستيراد المطلوب. ولن تضطروا أبدًا إلى كتابة عبارات الاستيراد يدويًا:

val listType = ClassName("kotlin.collections", "List")
val funSpec = FunSpec.builder("items")
    .returns(listType.parameterizedBy(String::class.asTypeName()))
    .addStatement("return emptyList()")
    .build()

الكتابة إلى CodeGenerator الخاص بـ KSP

استخدم جسر kotlinpoet-ksp لكتابة FileSpec الذي تم إنشاؤه عبر CodeGenerator الخاص بـ KSP، مع الحفاظ على البيانات الوصفية للبناء التزايدي:

file.writeTo(
    codeGenerator = codeGenerator,
    aggregating = false
)

إنشاء دوال الإضافات

استخدم FunSpec.builder(name).receiver(type) لإنشاء دوال الإضافات:

val extFun = FunSpec.builder("toJson")
    .receiver(ClassName("com.example", "User"))
    .returns(String::class)
    .addStatement("return Gson().toJson(this)")
    .build()

حالة استخدام عملية: منشئ المصانع

يضيف معالج KSP تعليقًا توضيحيًا @AutoFactory إلى فئات البيانات، ويستخدم KotlinPoet لإنشاء كائن مصنع مرافق لكل فئة منها. ويوضع الملف الذي تم إنشاؤه في الحزمة نفسها التي توجد فيها الفئة الأصلية.

اختبار التعليمات البرمجية التي تم إنشاؤها

استخدم FileSpec.toString() الخاص بـ KotlinPoet في اختبارات الوحدة للتحقق من نص المصدر الذي تم إنشاؤه، من دون كتابته على القرص. ويمكن لمكتبة kotlin-compile-testing-ksp ترجمة التعليمات البرمجية التي تم إنشاؤها وتنفيذها في الاختبارات.

تحقق سريع

في KotlinPoet، أي محدّد تنسيق يضيف الاستيراد اللازم تلقائيًا لفئة مشار إليها؟

أجب عليها في الدرس التفاعلي

مراجعة: توليد ملفات المصدر Kotlin باستخدام KotlinPoet

أهم النقاط:

FileSpec ← ملف على مستوى الحزمة؛ TypeSpec ← فئة/كائن/واجهة؛ FunSpec ← دالة؛ PropertySpec ← خاصية
استخدم %T لمراجع الأنواع — تُضاف الاستيرادات تلقائيًا
اكتب باستخدام file.writeTo(codeGenerator) في معالجات KSP
استخدم FileSpec.toString() لاختبار الوحدة للمخرجات المُولَّدة

البدء مجانًا

تعلم Kotlin مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات: 51
الدروس: 203

ابدأ التعلم مجانًا عرض الدورة الكاملة

الأسئلة الشائعة

هل درس «إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet» مجاني؟

نعم — نص درس «إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Kotlin Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ماذا ستتعلم في «إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet»؟

استخدم KotlinPoet داخل معالج KSP لإنشاء شيفرة Kotlin آمنة للأنواع. تتمرن على Kotlin Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Kotlin Academy؟

لا تُشترط خبرة سابقة. Kotlin Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Kotlin Academy هذا؟

نعم. كل درس في Kotlin Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

‏KSP مقابل KAPT: لماذا KSP أسرع
كتابة أول SymbolProcessor لك
إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet
دمج معالجات KSP في عملية بناء Gradle

← العودة إلى Kotlin Academy