Codegen: nedir, kod üretimi ve Fabric mimarisi

Codegen Nedir?

Codegen (Code Generator'ın kısaltması), React Native'e dahil olan ve JavaScript ile yerel platformlar (iOS, Android) arasındaki etkileşim için otomatik olarak köprü kodu üreten bir komut satırı aracıdır. Codegen, yeni React Native mimarisinin ayrılmaz bir parçasıdır ve hem Fabric (işleyici) hem de TurboModules (yerel modüller) için kullanılır.

Codegen'in ana fikri sorumlulukların ayrılmasıdır: geliştirici bir fonksiyonun «ne» yapması gerektiğini (imzasını) tanımlar, Codegen ise bunun yerel tarafa «nasıl» iletileceğini üretir. Bu, JSI için C++ sarmalayıcıları, iOS için Objective-C saplamaları ve Android için Java sınıflarını manuel olarak yazma ihtiyacını ortadan kaldırır. Tek bir gerçek kaynağı — TypeScript özelliği — tüm seviyelerde türlerin eşleşmesini garanti ederek JS ve yerel kod arasındaki tür uyuşmazlıklarıyla ilgili tüm hata sınıfını ortadan kaldırır.

Codegen, yeni React Native mimarisinin (0.70+) ilk kararlı sürümüyle birlikte tanıtıldı ve o zamandan beri yerel modül oluşturmak için zorunlu bir araç haline geldi. Codegen olmasaydı, geliştiricilerin manuel olarak JSI Host Objects yazması gerekirdi; bu da C++ hakkında derin bilgi ve JavaScript motorlarının iç yapısını anlamayı gerektirirdi.

Evrim: manuel köprüden otomatik üretime

Codegen'den önce, React Native için yerel bir modül geliştirmek üç adımı içeriyordu: JavaScript arayüzü yazma, Java/Objective-C ile yerel modülü uygulama ve manuel olarak köprü yazma. Bir metodun imzası değiştiğinde, üç dosyanın da eşzamanlı olarak güncellenmesi gerekiyordu. Codegen bu rutini otomatikleştirir: değişiklikler yalnızca TypeScript özelliğinde yapılır ve geri kalan her şey yeniden oluşturulur.

Derleme sistemiyle entegrasyon

Codegen, Metro ve CocoaPods aracılığıyla React Native derleme sürecine entegre olur. Derleme başlatıldığında, Codegen TypeScript özelliklerini analiz eder, C++ ve platform dosyalarını oluşturur ve bunları derleme dizinine yerleştirir. Bu, oluşturulan kodun her zaman mevcut özelliklerle eşleştiği ve manuel güncelleme gerektirmediği anlamına gelir.

Codegen Nasıl Çalışır?

Codegen iş akışı üç aşamadan oluşur: özelliklerin ayrıştırılması, ara bir temsilin oluşturulması ve hedef dosyaların üretilmesi. Her aşama izole edilmiştir, bu da yeni platformlar veya üretim dilleri için destek eklemeyi kolaylaştırır.

İlk aşamada, Codegen TypeScript veya Flow formatındaki özellik dosyalarını okur. Özellik, yerel modül arayüzünü tanımlar: metot adları, parametre türleri ve dönüş türleri. Codegen, ilkel türleri (number, string, boolean) ve karmaşık türleri (nesneler, diziler, Promise ve Callback) destekler. Özellikler, projenin özel bir dizinindeki .ts veya .js dosyalarında saklanır.

İkinci aşamada, Codegen ayrıştırılan özelliklerden bir Soyut Sözdizimi Ağacı (AST) oluşturur. AST, veri yapısını belirli bir üretim diline bağlı olmayan nötr bir formatta temsil eder. Bu, tek bir AST'den Fabric için C++ kodu, iOS için Objective-C ve Android için Java üretilmesini sağlar — tüm platformları desteklemek için ek bir çalışma gerekmez.

Üçüncü aşamada, Codegen hedef platform dosyalarını oluşturmak için bir şablon motoru (Mustache tabanlı) kullanır. Her şablon belirli bir dosya türünü işler: C++ başlık (.h), uygulama (.cpp), Objective-C protokolü (.h) veya uygulaması (.mm), Java sınıfı. Şablonlar React Native ile birlikte gelir, ancak projenin belirli ihtiyaçları için özelleştirilebilir.

Codegen Çalışma Diyagramı

// 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')

Bu örnekte, özellik iki metoda sahip NativeCalculator modülünü tanımlar: add ve multiply. Her ikisi de Double kabul eder ve Double döndürür. TurboModuleRegistry'deki 'NativeCalculator' dizesi, yerel tarafta kullanılacak modül adını belirtir. Codegen bu özelliğe dayanarak Fabric ve TurboModules için gerekli tüm dosyaları oluşturacaktır.

Fabric Mimarisinde Codegen

Fabric (yeni React Native işleyici) bağlamında, Codegen özel bir rol oynar. Fabric, her yerel UI bileşeninin JSI aracılığıyla oluşturulabilen ve yönetilebilen bir C++ temsiline sahip olmasını gerektirir. Codegen, bileşen özelliklerine dayanarak bu C++ temsillerini otomatik olarak oluşturur.

UI bileşenleri için üretim

UI bileşenleri için Codegen yalnızca C++ Shadow Node sınıfını değil, aynı zamanda platforma özgü temsilleri de oluşturur. Örneğin, iOS'ta özel bir Button bileşeni için Codegen, bileşeni Fabric'e kaydeden ve onu C++ Shadow Node'a bağlayan bir Objective-C sınıfı oluşturur. Geliştiricinin yalnızca TypeScript özelliğinde bileşen özelliklerini (renk, boyut, işleyiciler) tanımlaması gerekir.

Özellik tiplemesi

Codegen, hem doğrudan hem de ters veri aktarımını destekler. Doğrudan Olaylar (örneğin onPress), JS'ye iletildiğinde otomatik olarak serileştirilen alanlara sahip C++ yapıları olarak oluşturulur. EventEmitter, yerel tarafın JS'den bir talep olmadan JS'ye olaylar göndermesine olanak tanır. Codegen her iki yön için de tipli sarmalayıcılar oluşturarak alan adı uyuşmazlığı hatalarını ortadan kaldırır.

Üçüncü taraf kütüphaneler için Codegen

Kütüphane geliştiricileri, npm paketleriyle birlikte Codegen özellikleri sağlayabilir. Kütüphane yüklendiğinde, Codegen özellikleri otomatik olarak algılar ve mevcut platform için köprü kodu oluşturur. Bu, yerel kütüphaneler için özellikle önemlidir, çünkü kütüphane kullanıcılarının C++, Objective-C veya Java'yı anlaması gerekmez — sadece TypeScript türlerini içe aktarır ve hazır bileşenleri kullanırlar.

Codegen Hangi Dosyaları Üretir?

Codegen üç hedef ortam için dosya üretir: C++ (JSI), Objective-C (iOS) ve Java (Android). Her dosyanın kesin olarak tanımlanmış bir rolü ve yapısı vardır. Hangi dosyaların oluşturulduğunu anlamak, hata ayıklamada ve gerekirse oluşturulan kodun manuel olarak ayarlanmasında yardımcı olur.

C++ Dosyaları (JSI)

Her yerel modül için Codegen iki C++ dosyası oluşturur: Host Object sınıf bildirimi içeren bir başlık dosyası (.h) ve platformdaki ilgili işlevleri çağıran metotlar içeren bir uygulama dosyası (.cpp). Başlık dosyası, jsi::HostObject'ten türetilmiş ve modül işlevlerine erişmek için geçersiz kılınmış get metodu olan bir sınıf içerir. Uygulama dosyası, JS'den çağrıldığında yürütmeyi yerel modüle devreden lambda işlevleri içerir.

iOS Dosyaları (Objective-C)

iOS için Codegen bir Objective-C protokolü ve bir kategori oluşturur. Protokol, yerel modül tarafından uygulanması gereken metotları bildirir. RCTCxxBridge üzerindeki kategori, modülü RCTTurboModuleManager'a kaydeden köprü kodunu içerir. Bu, standart RCTBridge mekanizması aracılığıyla C++ JSI'den Objective-C modül metotlarının çağrılmasını sağlar.

Android Dosyaları (Java)

Android için Codegen bir Java arayüzü ve bir soyut sınıf oluşturur. Arayüz, doğru Java türleriyle metot bildirimlerini içerir. Soyut sınıf, TurboModule arayüzünü uygular ve modülü ReactPackage'e kaydetmek için temel mantığı içerir. Geliştirici bu sınıftan türetilir ve yalnızca metotların iş mantığını uygular.

Oluşturulan dosya yapısı

// 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

Bu yapının tamamı proje derlemesi sırasında otomatik olarak oluşturulur. Geliştiriciler oluşturulan dosyaları düzenlememelidir — bir sonraki derlemede üzerine yazılacaktır. Modül davranışının değiştirilmesi gerekiyorsa, değişiklikler yalnızca yerel uygulama kaynak kodunda (Java/Objective-C) veya TypeScript özelliğinde yapılır.

Codegen İş Akışı Örnekleri

Keychain'de veri depolamak için yerel bir modül oluşturarak Codegen'in tam iş akışını inceleyelim. Bu, iOS ve Android yerel API'sine erişim gerektiren tipik bir görevdir.

Adım 1: Özellik

Geliştirici, KeychainStorage modül arayüzünü tanımlayan bir özellik dosyası oluşturur. save ve read metotları bir dize kabul eder ve Promise döndürür, çünkü Keychain ile çalışmak bazı platformlarda eşzamansız olabilir.

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')

Adım 2: Codegen'i Çalıştırma

Codegen, bir React Native projesi derlenirken otomatik olarak çalışır. Manuel olarak çalıştırılması gerekiyorsa, npx react-native codegen komutu kullanılır. Codegen özelliği ayrıştırır ve build/generated/ içinde gerekli tüm dosyaları oluşturur. Geliştirici oluşturulan C++, Objective-C ve Java dosyalarını görür ancak bunları düzenlememelidir.

# 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

Adım 3: JS'de Kullanım

Oluşturma ve derlemeden sonra geliştirici modülü normal bir TypeScript türü olarak içe aktarır. IDE, oluşturulan .d.ts dosyaları sayesinde otomatik olarak metot imzalarını önerir. TypeScript, parametre ve dönüş türlerinin yerel uygulamayla eşleşmesini garanti eder — özellik string belirtiyorsa, yerel taraf tam olarak bir dize alacaktır.

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')
}

Bu örnek, JS kodunun platforma özel hiçbir talimat içermediğini gösterir — iOS ve Android için aynıdır. Tüm platforma özel ayrıntılar, Codegen tarafından oluşturulan kodun içinde gizlidir. Codegen, köprüler oluşturma konusundaki tüm rutin işleri halleder ve geliştiriciye yalnızca iş mantığı ve TypeScript aracılığıyla tür denetimini bırakır.