Codegen: bu nədir, kod generasiyası və Fabric arxitekturası

Codegen nədir?

Codegen (Code Generator sözünün qısaltması) React Native-in tərkibinə daxil olan əmr sətri yardımçı proqramıdır. O, JavaScript və native platformalar (iOS, Android) arasında qarşılıqlı əlaqə üçün birləşdirici kodu avtomatik generasiya edir. Codegen React Native-in yeni arxitekturasının ayrılmaz hissəsidir və həm Fabric (renderer), həm də TurboModules (native modullar) üçün istifadə olunur.

Codegen-in əsas ideyası məsuliyyətin bölünməsidir: tərtibatçı funksiyanın “nə” etməli olduğunu (onun imzasını) təsvir edir, Codegen isə “necə” native tərəfə ötürüləcəyini generasiya edir. Bu, JSI üçün C++ əlaqə kodlarının, iOS üçün Objective-C stub-larının və Android üçün Java siniflərinin əl ilə yazılması ehtiyacını aradan qaldırır. Vahid həqiqət mənbəyi — TypeScript spesifikasiyası — tiplərin bütün səviyyələrdə uyğun olmasını təmin edir və JS ilə native kod arasında tip uyğunsuzluğu ilə bağlı səhvləri aradan qaldırır.

Codegen React Native-in yeni arxitekturasının ilk stabil versiyası (0.70+) ilə birlikdə təqdim edildi və o vaxtdan bəri native modulların yaradılması üçün məcburi alətə çevrildi. Codegen olmadan tərtibatçı JSI Host Objects-ləri əl ilə yazmalı olardı ki, bu da dərin C++ bilikləri və JavaScript mühərriklərinin daxili quruluşunun anlaşılmasını tələb edir.

Təkamül: əl körpüsündən avtomatik generasiyaya

Codegen meydana çıxmazdan əvvəl React Native üçün native modulun hazırlanması üç addımı əhatə edirdi: JavaScript interfeysinin yazılması, Java/Objective-C-də native modulun implementasiyası və körpünün əl ilə yazılması. Metod imzası dəyişdikdə hər üç faylı sinxron şəkildə yeniləmək lazım idi. Codegen bu rutini avtomatlaşdırır: dəyişikliklər yalnız TypeScript spesifikasiyasına edilir, qalan hər şey yenidən generasiya olunur.

Quraşdırma sistemi ilə inteqrasiya

Codegen React Native-in quraşdırma prosesinə Metro və CocoaPods vasitəsilə inteqrasiya olunur. Quraşdırma işə salındıqda Codegen TypeScript spesifikasiyalarını analiz edir, C++ və platforma fayllarını generasiya edir və onları build qovluğuna yerləşdirir. Bu o deməkdir ki, generasiya edilmiş kod həmişə cari spesifikasiyalara uyğundur və əl ilə yeniləmə tələb etmir.

Codegen necə işləyir?

Codegen-in iş prosesi üç mərhələdən ibarətdir: spesifikasiyaların pars edilməsi, aralıq təmsilin qurulması və hədəf faylların generasiyası. Hər bir mərhələ təcrid olunmuşdur ki, bu da yeni platformaların və ya generasiya dillərinin dəstəyini asanlıqla əlavə etməyə imkan verir.

Birinci mərhələdə Codegen TypeScript və ya Flow formatında spesifikasiya fayllarını oxuyur. Spesifikasiya native modulun interfeysini təsvir edir: metod adları, parametr tipləri və qaytarılan dəyərlər. Codegen primitiv tipləri (number, string, boolean), həmçinin mürəkkəb tipləri — obyektlər, massivlər, Promise və Callback-i dəstəkləyir. Spesifikasiyalar layihənin xüsusi qovluğunda .ts və ya .js genişlənməsi olan fayllarda saxlanılır.

İkinci mərhələdə Codegen oxunan spesifikasiyalardan abstrakt sintaksis ağacı (AST) qurur. AST məlumat strukturunu neytral formatda, konkret generasiya dilinə bağlı olmayan şəkildə təmsil edir. Bu, vahid AST-dan Fabric üçün C++, iOS üçün Objective-C və Android üçün Java kodu generasiya etməyə imkan verir — bütün platformaları dəstəkləmək üçün heç bir əlavə iş tələb olunmur.

Üçüncü mərhələdə Codegen hədəf platformaların fayllarını generasiya etmək üçün şablon mühərrikindən (Mustache əsasında) istifadə edir. Hər bir şablon konkret fayl tipinə cavabdehdir: C++ başlıq faylı (.h), implementasiya (.cpp), Objective-C protokolu (.h) və ya implementasiya (.mm), Java sinfi. Şablonlar React Native ilə birlikdə gəlir, lakin layihənin xüsusi ehtiyacları üçün fərdiləşdirilə bilər.

Codegen-in iş sxemi

// NativeCalculator.ts — native modul spesifikasiyası
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 nümunədə spesifikasiya NativeCalculator modulunu iki metodla təsvir edir: add və multiply. Hər ikisi Double qəbul edir və Double qaytarır. TurboModuleRegistry-də 'NativeCalculator' sətri native tərəfdə istifadə olunacaq modul adını göstərir. Codegen bu spesifikasiya əsasında Fabric və TurboModules üçün bütün lazımi faylları generasiya edəcək.

Fabric arxitekturasında Codegen

Fabric (React Native-in yeni rendereri) kontekstində Codegen xüsusi rol oynayır. Fabric hər bir native UI komponentinin JSI vasitəsilə yaradıla və idarə oluna bilən C++ təmsilçiliyinə malik olmasını tələb edir. Codegen bu C++ təmsilçiliklərini komponent spesifikasiyaları əsasında avtomatik generasiya edir.

UI komponentləri üçün generasiya

UI komponentləri üçün Codegen təkcə C++ Shadow Node sinfini deyil, həm də platforma təmsilçiliklərini generasiya edir. Məsələn, iOS-da fərdi Button komponenti üçün Codegen komponenti Fabric-də qeydiyyatdan keçirən və onu C++ Shadow Node ilə birləşdirən Objective-C sinfi yaradacaq. Tərtibatçı yalnız komponentin xüsusiyyətlərini (rəng, ölçü, hadisə idarəçiləri) TypeScript spesifikasiyasında təsvir etməlidir.

Xüsusiyyətlərin tipizasiyası

Codegen birbaşa və əks məlumat ötürülməsini dəstəkləyir. Direct Event (məsələn, onPress) sahələri olan C++ strukturları kimi generasiya olunur və JS-ə ötürülərkən avtomatik serializasiya edilir. EventEmitter native tərəfə JS-dən sorğu olmadan JS-ə hadisələr göndərməyə imkan verir. Codegen hər iki istiqamət üçün tipləşdirilmiş sarğılar generasiya edərək sahə adlarının uyğunsuzluğu səhvlərini aradan qaldırır.

Üçüncü tərəf kitabxanaları üçün Codegen

Kitabxana tərtibatçıları Codegen spesifikasiyalarını npm paketi ilə birlikdə təqdim edə bilərlər. Kitabxana quraşdırıldıqda Codegen avtomatik olaraq spesifikasiyaları aşkarlayır və cari platforma üçün birləşdirici kod generasiya edir. Bu, xüsusilə native kitabxanalar üçün vacibdir, çünki kitabxana istifadəçisi C++, Objective-C və ya Java bilməli deyil — TypeScript tiplərini idxal etmək və hazır komponentlərdən istifadə etmək kifayətdir.

Codegen hansı faylları generasiya edir?

Codegen üç hədəf mühit üçün fayllar generasiya edir: C++ (JSI), Objective-C (iOS) və Java (Android). Hər bir faylın ciddi şəkildə müəyyən edilmiş rolu və strukturu var. Hansı faylların yaradıldığını başa düşmək debug zamanı və zəruri hallarda generasiya edilmiş kodun əl ilə düzəldilməsində kömək edir.

C++ faylları (JSI)

Hər bir native modul üçün Codegen iki C++ faylı yaradır: Host Object sinfinin elanı ilə başlıq (.h) və platformada müvafiq funksiyaları çağıran metodlarla implementasiya faylı (.cpp). Başlıq faylı jsi::HostObject-dən miras alan sinfi, modulun funksiyalarına giriş üçün get metodu ilə birlikdə ehtiva edir. Implementasiya faylı JS-dən çağırıldıqda icranı native modula həvalə edən lambda funksiyalarını ehtiva edir.

iOS faylları (Objective-C)

iOS üçün Codegen Objective-C protokolu və kateqoriyası generasiya edir. Protokol native modul tərəfindən implementasiya edilməli olan metodları elan edir. RCTCxxBridge-dəki kateqoriya modulu RCTTurboModuleManager-də qeydiyyatdan keçirən birləşdirici kodu ehtiva edir. Bu, Objective-C modulunun metodlarını C++ JSI-dən standart RCTBridge mexanizmi vasitəsilə çağırmağa imkan verir.

Android faylları (Java)

Android üçün Codegen Java interfeysi və abstrakt sinif generasiya edir. İnterfeys modulun metodlarının elanlarını düzgün Java tipləri ilə ehtiva edir. Abstrakt sinif TurboModule interfeysini implementasiya edir və modulun ReactPackage-də qeydiyyatı üçün əsas məntiqi ehtiva edir. Tərtibatçı bu sinifdən miras alır və yalnız metodların biznes məntiqini implementasiya edir.

Generasiya edilmiş faylların strukturu

// Codegen işə salındıqdan sonra qovluq strukturu
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protokolu
            NativeCalculatorSpec.mm    // JSI implementasiyası
        android/
            NativeCalculatorSpec.java  // Java interfeysi
            NativeCalculatorModuleBase.java  // Baza sinfi
        cxx/
            NativeCalculator.h         // C++ Host Object başlığı
            NativeCalculator.cpp        // C++ JSI implementasiyası

Bütün bu struktur layihənin qurulması zamanı avtomatik yaradılır. Tərtibatçı generasiya edilmiş faylları redaktə etməməlidir — növbəti qurulmada onlar yenidən yazılacaq. Modulun davranışını dəyişmək lazımdırsa, dəyişikliklər yalnız native implementasiyanın mənbə koduna (Java/Objective-C) və ya TypeScript spesifikasiyasına edilir.

Codegen iş axını nümunələri

Codegen ilə tam iş dövrünü Keychain-də məlumat saxlamaq üçün native modul yaratmaq nümunəsində nəzərdən keçirək. Bu, iOS və Android native API-lərinə giriş tələb edən tipik bir tapşırıqdır.

Addım 1: Spesifikasiya

Tərtibatçı KeychainStorage modulunun interfeysini təsvir edən spesifikasiya faylı yaradır. save və read metodları sətir qəbul edir və Promise qaytarır, çünki Keychain ilə iş bəzi platformalarda asinxron ola bilər.

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

Addım 2: Codegen-in işə salınması

Codegen React Native layihəsinin qurulması zamanı avtomatik işə düşür. Əl ilə işə salmaq lazım olduqda npx react-native codegen əmrindən istifadə olunur. Codegen spesifikasiyanı pars edir və bütün lazımi faylları build/generated/ qovluğunda yaradır. Tərtibatçı generasiya edilmiş C++, Objective-C və Java fayllarını görür, lakin onları redaktə etməməlidir.

# Codegen-i əl ilə işə sal
npx react-native codegen --target-path ./build/generated

# Generasiyadan sonra — layihəni qur
npx react-native run-ios
npx react-native run-android

Addım 3: JS-də istifadə

Generasiya və qurulmadan sonra tərtibatçı modulu adi TypeScript tipi kimi idxal edir. IDE generasiya edilmiş .d.ts faylları sayəsində metod imzalarını avtomatik təklif edir. TypeScript parametr və qaytarılan dəyər tiplərinin native implementasiya ilə uyğunluğunu təmin edir — spesifikasiyada string göstərilibsə, native tərəf məhz sətri alacaq.

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 nümunədə görünür ki, JS kodu heç bir platforma göstəricisi ehtiva etmir — iOS və Android üçün eynidir. Bütün platforma spesifikası Codegen tərəfindən generasiya edilmiş kodun daxilində gizlədilib. Codegen körpülərin yaradılması üzrə bütün rutin işi öz üzərinə götürür, tərtibatçıya yalnız biznes məntiqini və TypeScript vasitəsilə tip yoxlamasını buraxır.