Codegen: ما هو، توليد الكود وهندسة Fabric

ما هو Codegen؟

Codegen (اختصار لمولد الكود) هو أداة سطر أوامر مضمنة في React Native تقوم تلقائيًا بتوليد كود الربط للتفاعل بين JavaScript والمنصات الأصلية (iOS وAndroid). Codegen جزء لا يتجزأ من الهندسة المعمارية الجديدة لـ React Native ويُستخدم لكل من Fabric (عارض) وTurboModules (الوحدات الأصلية).

الفكرة الرئيسية لـ Codegen هي فصل المسؤوليات: يصف المطور «ماذا» يجب أن تفعل الدالة (توقيعها)، ويقوم Codegen بتوليد «كيف» سيتم تمريرها إلى الجانب الأصلي. هذا يلغي الحاجة إلى كتابة أغلفة C++ يدويًا لـ JSI ووصلات Objective-C لنظام iOS وفئات Java لنظام Android. مصدر واحد للحقيقة — مواصفات TypeScript — يضمن تطابق الأنواع على جميع المستويات، مما يستبعد فئة كاملة من الأخطاء المرتبطة بعدم تطابق الأنواع بين JS والكود الأصلي.

تم تقديم Codegen مع أول إصدار مستقر للهندسة المعمارية الجديدة لـ React Native (0.70+) ومنذ ذلك الحين أصبح أداة إلزامية لإنشاء الوحدات الأصلية. بدون Codegen، سيضطر المطورون إلى كتابة JSI Host Objects يدويًا، مما يتطلب معرفة عميقة بـ C++ وفهم البنية الداخلية لـ محركات JavaScript.

التطور: من الجسر اليدوي إلى التوليد التلقائي

قبل ظهور Codegen، كان تطوير وحدة أصلية لـ React Native يتضمن ثلاث خطوات: كتابة واجهة JavaScript، تنفيذ الوحدة الأصلية بلغة Java/Objective-C، وكتابة الجسر يدويًا. عند تغيير توقيع إحدى الطرق، كان يجب تحديث الملفات الثلاثة بشكل متزامن. Codegen يؤتمت هذه الروتين: يتم إجراء التغييرات فقط على مواصفات TypeScript، ويتم إعادة توليد كل شيء آخر.

التكامل مع نظام البناء

يتكامل Codegen مع عملية بناء React Native عبر Metro وCocoaPods. عند بدء البناء، يحلل Codegen مواصفات TypeScript، ويولد ملفات C++ وملفات المنصة، ويضعها في دليل البناء. هذا يعني أن الكود المولد يطابق دائمًا المواصفات الحالية ولا يتطلب تحديثات يدوية.

كيف يعمل Codegen؟

تتكون عملية Codegen من ثلاث مراحل: تحليل المواصفات، بناء تمثيل وسيط، وتوليد الملفات المستهدفة. كل مرحلة معزولة، مما يسهل إضافة دعم لمنصات جديدة أو لغات توليد.

في المرحلة الأولى، يقرأ Codegen ملفات المواصفات بتنسيق TypeScript أو Flow. تصف المواصفة واجهة الوحدة الأصلية: أسماء الطرق، أنواع المعاملات، وأنواع القيم المعادة. يدعم Codegen الأنواع البدائية (number, string, boolean) وكذلك الأنواع المعقدة — الكائنات، المصفوفات، Promise وCallback. تُخزن المواصفات في ملفات .ts أو .js في دليل خاص بالمشروع.

في المرحلة الثانية، يبني Codegen شجرة بناء مجردة (AST) من المواصفات المقروءة. تمثل AST بنية البيانات بتنسيق محايد غير مرتبط بلغة توليد محددة. هذا يسمح بتوليد كود C++ لـ Fabric وObjective-C لنظام iOS وJava لنظام Android من AST واحدة — لا حاجة لأي عمل إضافي لدعم جميع المنصات.

في المرحلة الثالثة، يستخدم Codegen محرك قوالب (قائم على Mustache) لتوليد ملفات المنصات المستهدفة. كل قالب مسؤول عن نوع ملف محدد: ملف رأس C++ (.h)، تنفيذ (.cpp)، بروتوكول Objective-C (.h) أو تنفيذ (.mm)، فئة Java. القوالب تأتي مع React Native، ولكن يمكن تخصيصها لاحتياجات المشروع المحددة.

مخطط عمل Codegen

// NativeCalculator.ts — native module specification
import { TurboModule, TurboModuleRegistry } from 'react-native'
import { Double } from 'react-native/Libraries/Types/CodegenTypes'

export interface NativeCalculatorSpec extends TurboModule {
    add(a: Double, b: Double): Double
    multiply(a: Double, b: Double): Double
}

export default TurboModuleRegistry.<NativeCalculatorSpec>('NativeCalculator')

في هذا المثال، تصف المواصفة وحدة NativeCalculator بطريقتين: add وmultiply. كلاهما يقبل Double ويعيد Double. السلسلة 'NativeCalculator' في TurboModuleRegistry تحدد اسم الوحدة الذي سيُستخدم على الجانب الأصلي. Codegen بناءً على هذه المواصفة سيولد جميع الملفات اللازمة لـ Fabric وTurboModules.

Codegen في هندسة Fabric

في سياق Fabric (عارض React Native الجديد)، يلعب Codegen دورًا خاصًا. يتطلب Fabric أن يكون لكل مكون واجهة مستخدم أصلي تمثيل C++ يمكن إنشاؤه وإدارته عبر JSI. يولد Codegen تمثيلات C++ هذه تلقائيًا بناءً على مواصفات المكونات.

التوليد لمكونات واجهة المستخدم

بالنسبة لمكونات واجهة المستخدم، يولد Codegen ليس فقط فئة Shadow Node بلغة C++ ولكن أيضًا تمثيلات خاصة بالمنصة. على سبيل المثال، لمكون Button مخصص على iOS، ينشئ Codegen فئة Objective-C تسجل المكون في Fabric وتربطه بـ Shadow Node بلغة C++. يحتاج المطور فقط إلى وصف خصائص المكون (اللون، الحجم، المعالجات) في مواصفات TypeScript.

كتابة الخصائص

يدعم Codegen نقل البيانات المباشر والعكسي. يتم توليد الأحداث المباشرة (مثل onPress) كهياكل C++ مع حقول يتم تسلسلها تلقائيًا عند تمريرها إلى JS. EventEmitter يسمح للجانب الأصلي بإرسال الأحداث إلى JS دون طلب من JS. يولد Codegen أغلفة مكتوبة لكلا الاتجاهين، مما يستبعد أخطاء عدم تطابق أسماء الحقول.

Codegen للمكتبات الخارجية

يمكن لمطوري المكتبات تضمين مواصفات Codegen مع حزمة npm الخاصة بهم. عند تثبيت المكتبة، يكتشف Codegen تلقائيًا المواصفات ويولد كود الربط للمنصة الحالية. هذا مهم بشكل خاص لـ المكتبات الأصلية، حيث لا يحتاج مستخدم المكتبة إلى فهم C++ أو Objective-C أو Java — يكفي استيراد أنواع TypeScript واستخدام المكونات الجاهزة.

ما الملفات التي يولدها Codegen؟

يولد Codegen ملفات لثلاث بيئات مستهدفة: C++ (JSI)، Objective-C (iOS)، وJava (Android). كل ملف له دور وبنية محددة بدقة. يساعد فهم الملفات التي يتم إنشاؤها في التصحيح، وعند الضرورة، في التعديل اليدوي للكود المولد.

ملفات C++ (JSI)

لكل وحدة أصلية، ينشئ Codegen ملفين بلغة C++: ملف رأس (.h) بإعلان فئة Host Object وملف تنفيذ (.cpp) بطرق تستدعي الوظائف المقابلة على المنصة. يحتوي ملف الرأس على فئة موروثة من jsi::HostObject مع طريقة get مُعاد تعريفها للوصول إلى وظائف الوحدة. ملف التنفيذ يحتوي على دوال لامبدا التي، عند استدعائها من JS، تفوض التنفيذ إلى الوحدة الأصلية.

ملفات iOS (Objective-C)

بالنسبة لنظام iOS، يولد Codegen بروتوكول Objective-C وفئة تصنيف. يعلن البروتوكول عن الطرق التي يجب تنفيذها بواسطة الوحدة الأصلية. تحتوي فئة التصنيف على RCTCxxBridge على كود الربط الذي يسجل الوحدة في RCTTurboModuleManager. هذا يسمح باستدعاء طرق وحدة Objective-C من C++ JSI عبر آلية RCTBridge القياسية.

ملفات Android (Java)

بالنسبة لنظام Android، يولد Codegen واجهة Java وفئة مجردة. تحتوي الواجهة على إعلانات الطرق مع أنواع Java الصحيحة. تنفذ الفئة المجردة واجهة TurboModule وتحتوي على المنطق الأساسي لتسجيل الوحدة في ReactPackage. يرث المطور من هذه الفئة وينفذ فقط منطق الأعمال للطرق.

هيكل الملفات المولدة

// Directory structure after Codegen run
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protocol
            NativeCalculatorSpec.mm    // JSI implementation
        android/
            NativeCalculatorSpec.java  // Java interface
            NativeCalculatorModuleBase.java  // Base class
        cxx/
            NativeCalculator.h         // C++ Host Object header
            NativeCalculator.cpp        // C++ JSI implementation

يتم إنشاء هذا الهيكل بأكمله تلقائيًا أثناء بناء المشروع. لا يجب على المطورين تعديل الملفات المولدة — سيتم استبدالها في البناء التالي. إذا كان هناك حاجة لتغيير سلوك الوحدة، يتم إجراء التعديلات فقط على الكود المصدري للتنفيذ الأصلي (Java/Objective-C) أو على مواصفات TypeScript.

أمثلة على سير عمل Codegen

لنستعرض دورة العمل الكاملة لـ Codegen من خلال إنشاء وحدة أصلية لتخزين البيانات في Keychain. هذه مهمة نموذجية تتطلب الوصول إلى API الأصلي لنظامي iOS وAndroid.

الخطوة 1: المواصفة

ينشئ المطور ملف مواصفة يصف واجهة وحدة KeychainStorage. تقبل طريقتا save وread سلسلة وتعيدان Promise، حيث أن العمل مع Keychain قد يكون غير متزامن على بعض المنصات.

import { TurboModule, TurboModuleRegistry } from 'react-native'

export interface KeychainStorageSpec extends TurboModule {
    save(key: string, value: string): Promise<void>
    read(key: string): Promise<string | null>
    delete(key: string): Promise<boolean>
}

export default TurboModuleRegistry.<KeychainStorageSpec>('KeychainStorage')

الخطوة 2: تشغيل Codegen

يتم تشغيل Codegen تلقائيًا عند بناء مشروع React Native. إذا كان هناك حاجة لتشغيله يدويًا، يُستخدم الأمر npx react-native codegen. Codegen يحلل المواصفة وينشئ جميع الملفات اللازمة في build/generated/. يرى المطور ملفات C++ وObjective-C وJava المولدة، لكن لا يجب عليه تعديلها.

# Run Codegen manually
npx react-native codegen --target-path ./build/generated

# After generation — build the project
npx react-native run-ios
npx react-native run-android

الخطوة 3: الاستخدام في JS

بعد التوليد والبناء، يستورد المطور الوحدة كنوع TypeScript عادي. يقترح IDE تلقائيًا توقيعات الطرق بفضل ملفات .d.ts المولدة. TypeScript يضمن أن أنواع المعاملات والقيم المعادلة تطابق التنفيذ الأصلي — إذا كانت المواصفة تشير إلى string، فسيستقبل الجانب الأصلي سلسلة بالضبط.

import KeychainStorage from './NativeKeychainStorage'

async function storeToken(token: string) {
    await KeychainStorage.save('auth_token', token)
}

async function getToken(): Promise<string | null> {
    return KeychainStorage.read('auth_token')
}

يوضح هذا المثال أن كود JS لا يحتوي على أي تعليمات خاصة بالمنصة — فهو نفسه لنظامي iOS وAndroid. جميع التفاصيل الخاصة بالمنصة مخفية داخل كود Codegen المولد. Codegen يتولى كل العمل الروتيني لإنشاء الجسور، تاركًا للمطور فقط منطق الأعمال والتحقق من الأنواع عبر TypeScript.