Codegen: mi ez, kódgenerálás és a Fabric architektúrája

Mi az a Codegen?

A Codegen (a Code Generator rövidítése) egy parancssori eszköz, amely a React Native része, és automatikusan generálja az összekötő kódot a JavaScript és a natív platformok (iOS, Android) közötti kommunikációhoz. A Codegen a React Native új architektúrájának elválaszthatatlan része, és mind a Fabric (renderelő), mind a TurboModules (natív modulok) esetében használatos.

A Codegen fő ötlete a felelősségek szétválasztásában rejlik: a fejlesztő leírja „mit” kell a függvénynek tennie (a szignatúráját), a Codegen pedig generálja „hogyan” kerül átadásra a natív oldalra. Ez kiküszöböli a C++ összekötő kód JSI-hez, az Objective-C stubok iOS-hez és a Java osztályok Androidhoz való kézi írásának szükségességét. Egyetlen igazságforrás — a TypeScript specifikáció — garantálja, hogy a típusok minden szinten megegyeznek, ami kiküszöböli a JS és a natív kód közötti típuseltérésekkel kapcsolatos hibák egész osztályát.

A Codegent a React Native új architektúrájának (0.70+) első stabil verziójával együtt mutatták be, és azóta kötelező eszközzé vált a natív modulok létrehozásához. Codegen nélkül a fejlesztőnek kézzel kellene JSI Host Objects-eket írnia, ami mély C++ ismereteket és a JavaScript-motorok belső működésének megértését igényli.

Evolúció: a kézi hídtól az automatikus generálásig

A Codegen megjelenése előtt a React Native natív modul fejlesztése három lépésből állt: JavaScript interfész írása, natív modul implementációja Java/Objective-C nyelven és a híd kézi megírása. Egy metódus szignatúrájának megváltoztatásakor mindhárom fájlt szinkronban kellett frissíteni. A Codegen automatizálja ezt a rutint: a változtatásokat csak a TypeScript specifikációban kell elvégezni, a többi újragenerálódik.

Integráció a build rendszerrel

A Codegen a Metro és a CocoaPods segítségével integrálódik a React Native build folyamatába. A build elindításakor a Codegen elemzi a TypeScript specifikációkat, generálja a C++ és platform fájlokat, és elhelyezi azokat a build könyvtárban. Ez azt jelenti, hogy a generált kód mindig megfelel az aktuális specifikációknak, és nem igényel kézi frissítést.

Hogyan működik a Codegen?

A Codegen működési folyamata három szakaszból áll: a specifikációk elemzése, a köztes reprezentáció felépítése és a célfájlok generálása. Minden szakasz elkülönített, ami lehetővé teszi új platformok vagy generálási nyelvek támogatásának egyszerű hozzáadását.

Az első szakaszban a Codegen beolvassa a specifikációs fájlokat TypeScript vagy Flow formátumban. A specifikáció leírja a natív modul interfészét: a metódusok nevét, a paraméterek típusait és visszatérési értékeket. A Codegen támogatja a primitív típusokat (number, string, boolean), valamint az összetett típusokat — objektumok, tömbök, Promise és Callback. A specifikációk .ts vagy .js kiterjesztésű fájlokban tárolódnak a projekt egy speciális könyvtárában.

A második szakaszban a Codegen absztrakt szintaxis fát (AST) épít a beolvasott specifikációkból. Az AST az adatstruktúrát semleges formátumban, egy adott generálási nyelvhez nem kötve reprezentálja. Ez lehetővé teszi a C++ kód generálását a Fabric számára, az Objective-C-t iOS-hez és a Java-t Androidhoz egyetlen AST-ből — nincs szükség további munkára az összes platform támogatásához.

A harmadik szakaszban a Codegen sablonmotort (Mustache-alapú) használ a célplatformok fájljainak generálásához. Minden sablon egy adott fájltípusért felelős: C++ header fájl (.h), implementáció (.cpp), Objective-C protokoll (.h) vagy implementáció (.mm), Java osztály. A sablonok a React Native-nal együtt érkeznek, de testreszabhatók a projekt specifikus igényei szerint.

A Codegen működési sémája

// NativeCalculator.ts — natív modul specifikációja
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')

Ebben a példában a specifikáció a NativeCalculator modult írja le két metódussal: add és multiply. Mindkettő Double-t fogad és Double-t ad vissza. A 'NativeCalculator' sztring a TurboModuleRegistry-ben jelzi a modul nevét, amely a natív oldalon használatos lesz. A Codegen e specifikáció alapján generálja az összes szükséges fájlt a Fabric és a TurboModules számára.

Codegen a Fabric architektúrában

A Fabric (új React Native renderelő) kontextusában a Codegen különleges szerepet játszik. A Fabric megköveteli, hogy minden natív UI komponensnek legyen C++ reprezentációja, amely JSI-n keresztül létrehozható és kezelhető. A Codegen ezeket a C++ reprezentációkat automatikusan generálja a komponens specifikációk alapján.

Generálás UI komponensekhez

Az UI komponensekhez a Codegen nemcsak a C++ Shadow Node osztályt generálja, hanem a platform reprezentációkat is. Például egy egyedi Button komponenshez iOS-en a Codegen létrehoz egy Objective-C osztályt, amely regisztrálja a komponenst a Fabricben és összeköti a C++ Shadow Node-dal. A fejlesztőnek csak a komponens tulajdonságait (szín, méret, kezelők) kell leírnia a TypeScript specifikációban.

Tulajdonságok típusozása

A Codegen támogatja a közvetlen és fordított adatátvitelt. A Direct Event (pl. onPress) C++ struktúrákként generálódik mezőkkel, amelyek automatikusan szerializálódnak a JS-be történő átvitelkor. Az EventEmitter lehetővé teszi a natív oldal számára, hogy eseményeket küldjön a JS-be a JS kérése nélkül. A Codegen típusozott burkolókat generál mindkét irányhoz, kiküszöbölve a mezőnevek eltéréséből adódó hibákat.

Codegen harmadik féltől származó könyvtárakhoz

A könyvtárfejlesztők Codegen specifikációkat szállíthatnak az npm csomaggal együtt. A könyvtár telepítésekor a Codegen automatikusan észleli a specifikációkat és generálja az összekötő kódot az aktuális platformhoz. Ez különösen fontos a natív könyvtárak esetében, mivel a könyvtár felhasználójának nem kell ismernie a C++, Objective-C vagy Java nyelvet — elég importálni a TypeScript típusokat és használni a kész komponenseket.

Milyen fájlokat generál a Codegen?

A Codegen három célkörnyezethez generál fájlokat: C++ (JSI), Objective-C (iOS) és Java (Android). Minden fájlnak szigorúan meghatározott szerepe és struktúrája van. Annak megértése, hogy milyen fájlok jönnek létre, segít a hibakeresésben és szükség esetén a generált kód kézi korrekciójában.

C++ fájlok (JSI)

Minden natív modulhoz a Codegen két C++ fájlt hoz létre: egy header fájlt (.h) a Host Object osztály deklarációjával és egy implementációs fájlt (.cpp) a platformon a megfelelő függvényeket meghívó metódusokkal. A header fájl tartalmaz egy osztályt, amely a jsi::HostObject-ből származik, felülírt get metódussal a modul függvényeihez való hozzáféréshez. Az implementációs fájl lambda függvényeket tartalmaz, amelyek JS-ből történő meghíváskor a natív modulra delegálják a végrehajtást.

iOS fájlok (Objective-C)

iOS-hez a Codegen Objective-C protokollt és kategóriát generál. A protokoll deklarálja a natív modul által implementálandó metódusokat. Az RCTCxxBridge kategória tartalmazza az összekötő kódot, amely regisztrálja a modult a RCTTurboModuleManager-ben. Ez lehetővé teszi az Objective-C modul metódusainak meghívását C++ JSI-ből a standard RCTBridge mechanizmuson keresztül.

Android fájlok (Java)

Androidhoz a Codegen Java interfészt és absztrakt osztályt generál. Az interfész tartalmazza a modul metódusainak deklarációit a helyes Java típusokkal. Az absztrakt osztály implementálja a TurboModule interfészt és tartalmazza a modul ReactPackage-ben való regisztrálásának alapvető logikáját. A fejlesztő ebből az osztályból származtat, és csak a metódusok üzleti logikáját implementálja.

A generált fájlok struktúrája

// Könyvtárstruktúra a Codegen futtatása után
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protokoll
            NativeCalculatorSpec.mm    // JSI implementáció
        android/
            NativeCalculatorSpec.java  // Java interfész
            NativeCalculatorModuleBase.java  // Alaposztály
        cxx/
            NativeCalculator.h         // C++ Host Object header
            NativeCalculator.cpp        // C++ JSI implementáció

Ez az egész struktúra automatikusan létrejön a projekt buildelésekor. A fejlesztő ne szerkessze a generált fájlokat — a következő buildnél felülíródnak. Ha módosítani kell a modul viselkedését, a változtatásokat csak a natív implementáció forráskódjában (Java/Objective-C) vagy a TypeScript specifikációban kell elvégezni.

Codegen munkafolyamat példák

Tekintsük át a Codegen-nel való teljes munkaciklust egy Keychain-ben adatokat tároló natív modul létrehozásának példáján. Ez egy tipikus feladat, amely hozzáférést igényel az iOS és Android natív API-hoz.

1. lépés: Specifikáció

A fejlesztő létrehoz egy specifikációs fájlt, amely leírja a KeychainStorage modul interfészét. A save és read metódusok sztringet fogadnak és Promise-t adnak vissza, mivel a Keychain-nel való munka egyes platformokon aszinkron lehet.

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. lépés: Codegen futtatása

A Codegen automatikusan elindul a React Native projekt buildelésekor. Ha kézi futtatásra van szükség, az npx react-native codegen parancs használatos. A Codegen elemzi a specifikációt és létrehozza az összes szükséges fájlt a build/generated/ könyvtárban. A fejlesztő látja az eredményt generált C++, Objective-C és Java fájlok formájában, de nem szerkesztheti azokat.

# Codegen kézi futtatása
npx react-native codegen --target-path ./build/generated

# Generálás után — építsd a projektet
npx react-native run-ios
npx react-native run-android

3. lépés: Használat JS-ben

A generálás és build után a fejlesztő importálja a modult mint egy szokásos TypeScript típust. Az IDE automatikusan javasolja a metódusok szignatúráit a generált .d.ts fájloknak köszönhetően. A TypeScript garantálja, hogy a paraméterek és visszatérési értékek típusai megegyeznek a natív implementációval — ha a specifikációban string szerepel, a natív oldal pontosan egy sztringet kap.

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

Ebben a példában látható, hogy a JS kód nem tartalmaz semmilyen platformjelzést — ugyanaz iOS és Android esetében is. Az összes platformspecifikáció a Codegen által generált kódban van elrejtve. A Codegen átveszi a hidak létrehozásával kapcsolatos összes rutinmunkát, csak az üzleti logikát és a TypeScripten keresztüli típusellenőrzést hagyva a fejlesztőnek.