Codegen: چیست، تولید کد و معماری Fabric

Codegen چیست؟

Codegen (مخفف Code Generator) یک ابزار خط فرمان است که بخشی از React Native بوده و به طور خودکار کد اتصال برای ارتباط بین JavaScript و پلتفرم‌های بومی (iOS، Android) تولید می‌کند. Codegen بخش جدایی‌ناپذیر معماری جدید React Native است و هم برای Fabric (رندرکننده) و هم برای TurboModules (ماژول‌های بومی) استفاده می‌شود.

ایده اصلی Codegen در تقسیم مسئولیت‌ها نهفته است: توسعه‌دهنده «چه کاری» باید انجام دهد (امضای آن) را توصیف می‌کند و Codegen «چگونه» به سمت بومی منتقل شود را تولید می‌کند. این کار نیاز به نوشتن دستی کدهای اتصال C++ برای JSI، stubهای 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 از طریق Metro و CocoaPods در فرآیند ساخت React Native ادغام می‌شود. هنگام اجرای ساخت، Codegen مشخصات TypeScript را تحلیل می‌کند، فایل‌های C++ و پلتفرمی را تولید کرده و آنها را در دایرکتوری build قرار می‌دهد. این بدان معناست که کد تولید شده همیشه با مشخصات فعلی مطابقت دارد و نیاز به به‌روزرسانی دستی ندارد.

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 — مشخصات ماژول بومی
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 نیاز دارد که هر کامپوننت بومی UI یک نمایش C++ داشته باشد که بتواند از طریق JSI ایجاد و مدیریت شود. Codegen این نمایش‌های C++ را به طور خودکار بر اساس مشخصات کامپوننت‌ها تولید می‌کند.

تولید برای کامپوننت‌های UI

برای کامپوننت‌های UI، Codegen نه تنها کلاس C++ Shadow Node، بلکه نمایش‌های پلتفرمی را نیز تولید می‌کند. به عنوان مثال، برای کامپوننت سفارشی Button در iOS، Codegen یک کلاس Objective-C ایجاد می‌کند که کامپوننت را در Fabric ثبت کرده و آن را به C++ Shadow Node متصل می‌کند. توسعه‌دهنده فقط باید ویژگی‌های کامپوننت (رنگ، اندازه، مدیریت‌کننده‌ها) را در مشخصات TypeScript توصیف کند.

تایپ‌بندی ویژگی‌ها

Codegen از انتقال مستقیم و معکوس داده پشتیبانی می‌کند. Direct Event (مثلاً onPress) به عنوان ساختارهای C++ با فیلدهایی تولید می‌شود که هنگام انتقال به JS به طور خودکار سریالایز می‌شوند. EventEmitter به سمت بومی اجازه می‌دهد بدون درخواست از JS، رویدادهایی را به JS ارسال کند. Codegen wrapperهای تایپ‌شده برای هر دو جهت تولید کرده و خطاهای عدم تطابق نام فیلدها را حذف می‌کند.

Codegen برای کتابخانه‌های شخص ثالث

توسعه‌دهندگان کتابخانه می‌توانند مشخصات Codegen را همراه با بسته npm ارائه دهند. هنگام نصب کتابخانه، Codegen به طور خودکار مشخصات را شناسایی کرده و کد اتصال را برای پلتفرم فعلی تولید می‌کند. این به ویژه برای کتابخانه‌های بومی مهم است، زیرا کاربر کتابخانه نیازی به دانستن C++، Objective-C یا Java ندارد — کافی است تایپ‌های TypeScript را import کرده و از کامپوننت‌های آماده استفاده کند.

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 و یک دسته (category) تولید می‌کند. پروتکل متدهایی را اعلام می‌کند که باید توسط ماژول بومی پیاده‌سازی شوند. دسته روی RCTCxxBridge شامل کد اتصالی است که ماژول را در RCTTurboModuleManager ثبت می‌کند. این امکان فراخوانی متدهای ماژول Objective-C را از C++ JSI از طریق مکانیزم استاندارد RCTBridge فراهم می‌کند.

فایل‌های Android (Java)

برای Android، Codegen یک رابط Java و یک کلاس انتزاعی تولید می‌کند. رابط شامل اعلام متدهای ماژول با تایپ‌های صحیح Java است. کلاس انتزاعی رابط TurboModule را پیاده‌سازی کرده و منطق پایه برای ثبت ماژول در ReactPackage را شامل می‌شود. توسعه‌دهنده از این کلاس ارث‌بری کرده و فقط منطق تجاری متدها را پیاده‌سازی می‌کند.

ساختار فایل‌های تولید شده

// ساختار دایرکتوری پس از اجرای Codegen
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // پروتکل Objective-C
            NativeCalculatorSpec.mm    // پیاده‌سازی JSI
        android/
            NativeCalculatorSpec.java  // رابط Java
            NativeCalculatorModuleBase.java  // کلاس پایه
        cxx/
            NativeCalculator.h         // هدر C++ Host Object
            NativeCalculator.cpp        // پیاده‌سازی JSI C++

تمام این ساختار هنگام ساخت پروژه به طور خودکار ایجاد می‌شود. توسعه‌دهنده نباید فایل‌های تولید شده را ویرایش کند — در ساخت بعدی بازنویسی خواهند شد. اگر نیاز به تغییر رفتار ماژول باشد، تغییرات فقط در کد منبع پیاده‌سازی بومی (Java/Objective-C) یا در مشخصات TypeScript اعمال می‌شوند.

نمونه‌های گردش کار Codegen

بیایید چرخه کامل کار با Codegen را با مثال ایجاد یک ماژول بومی برای ذخیره داده‌ها در Keychain بررسی کنیم. این یک وظیفه معمولی است که نیاز به دسترسی به API بومی iOS و Android دارد.

مرحله ۱: مشخصات

توسعه‌دهنده یک فایل مشخصات ایجاد می‌کند که رابط ماژول 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')

مرحله ۲: راه‌اندازی Codegen

Codegen به طور خودکار هنگام ساخت پروژه React Native راه‌اندازی می‌شود. اگر نیاز به راه‌اندازی دستی باشد، از دستور npx react-native codegen استفاده می‌شود. Codegen مشخصات را تجزیه کرده و تمام فایل‌های لازم را در build/generated/ ایجاد می‌کند. توسعه‌دهنده نتیجه را به صورت فایل‌های تولید شده C++، Objective-C و Java می‌بیند، اما نباید آنها را ویرایش کند.

# اجرای دستی Codegen
npx react-native codegen --target-path ./build/generated

# پس از تولید — پروژه را بسازید
npx react-native run-ios
npx react-native run-android

مرحله ۳: استفاده در JS

پس از تولید و ساخت، توسعه‌دهنده ماژول را مانند یک نوع TypeScript معمولی import می‌کند. 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 برای توسعه‌دهنده باقی می‌گذارد.