Codegen: ano ito, pagbuo ng code at arkitektura ng Fabric

Ano ang Codegen?

Codegen (pinaikling mula sa Code Generator) ay isang command line tool na bahagi ng React Native na awtomatikong bumubuo ng nag-uugnay na code para sa komunikasyon sa pagitan ng JavaScript at native platforms (iOS, Android). Ang Codegen ay isang mahalagang bahagi ng bagong arkitektura ng React Native at ginagamit pareho para sa Fabric (renderer) at TurboModules (native modules).

Ang pangunahing ideya ng Codegen ay ang paghihiwalay ng mga responsibilidad: inilalarawan ng developer kung “anu” ang dapat gawin ng function (ang lagda nito), at ang Codegen ay bumubuo kung “paano” ito ipapadala sa native na panig. Tinatanggal nito ang pangangailangan na manu-manong sumulat ng C++ na nag-uugnay para sa JSI, Objective-C stubs para sa iOS at Java classes para sa Android. Isang pinagmumulan ng katotohanan — ang TypeScript specification — ay ginagarantiya na ang mga uri sa lahat ng antas ay tugma, na nag-aalis ng isang buong klase ng mga error na may kaugnayan sa hindi pagkakatugma ng uri sa pagitan ng JS at native code.

Ang Codegen ay ipinakilala kasama ng unang stable na bersyon ng bagong arkitektura ng React Native (0.70+) at mula noon ay naging mandatory tool para sa paggawa ng native modules. Kung wala ang Codegen, ang developer ay kailangang manu-manong sumulat ng JSI Host Objects, na nangangailangan ng malalim na kaalaman sa C++ at pag-unawa sa panloob na gawain ng JavaScript engines.

Ebolusyon: mula sa manwal na tulay hanggang sa awtomatikong pagbuo

Bago ang pagdating ng Codegen, ang pag-develop ng native module para sa React Native ay may kasamang tatlong hakbang: pagsulat ng JavaScript interface, implementasyon ng native module sa Java/Objective-C at manwal na pagsulat ng tulay. Kapag binago ang lagda ng pamamaraan, kailangang i-update nang sabay-sabay ang lahat ng tatlong file. Ang Codegen ay nag-automate ng rutinang ito: ang mga pagbabago ay ginagawa lamang sa TypeScript specification, at ang lahat ng iba ay binuo muli.

Integrasyon sa build system

Ang Codegen ay isinasama sa proseso ng build ng React Native sa pamamagitan ng Metro at CocoaPods. Kapag sinimulan ang build, sinusuri ng Codegen ang TypeScript specifications, bumubuo ng C++ at platform files at inilalagay ang mga ito sa build directory. Nangangahulugan ito na ang nabuong code ay palaging tumutugma sa kasalukuyang mga specification at hindi nangangailangan ng manwal na pag-update.

Paano gumagana ang Codegen?

Ang proseso ng trabaho ng Codegen ay binubuo ng tatlong yugto: pag-parse ng mga specification, pagbuo ng intermediate representation at pagbuo ng target files. Ang bawat yugto ay nakahiwalay, na nagpapahintulot sa madaling pagdagdag ng suporta para sa mga bagong platform o wika ng pagbuo.

Sa unang yugto, binabasa ng Codegen ang specification files sa TypeScript o Flow format. Inilalarawan ng specification ang interface ng native module: mga pangalan ng pamamaraan, mga uri ng parameter at mga return value. Sinusuportahan ng Codegen ang primitive types (number, string, boolean), pati na rin ang complex types — mga object, array, Promise at Callback. Ang mga specification ay nakaimbak sa mga file na may extension na .ts o .js sa isang espesyal na directory ng proyekto.

Sa ikalawang yugto, ang Codegen ay bumubuo ng abstract syntax tree (AST) mula sa mga binasang specification. Kinakatawan ng AST ang istraktura ng data sa isang neutral na format, hindi nakatali sa isang partikular na wika ng pagbuo. Pinapayagan nito ang pagbuo ng C++ code para sa Fabric, Objective-C para sa iOS at Java para sa Android mula sa isang AST — walang karagdagang trabaho na kinakailangan upang suportahan ang lahat ng platform.

Sa ikatlong yugto, ang Codegen ay gumagamit ng template engine (batay sa Mustache) para sa pagbuo ng target platform files. Ang bawat template ay responsable para sa isang partikular na uri ng file: C++ header file (.h), implementasyon (.cpp), Objective-C protocol (.h) o implementasyon (.mm), Java class. Ang mga template ay kasama ng React Native, ngunit maaaring i-customize para sa mga tiyak na pangangailangan ng proyekto.

Skema ng trabaho ng Codegen

// NativeCalculator.ts — specification ng native module
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')

Sa halimbawang ito, inilalarawan ng specification ang module na NativeCalculator na may dalawang pamamaraan: add at multiply. Parehong tumatanggap ng Double at nagbabalik ng Double. Ang string na 'NativeCalculator' sa TurboModuleRegistry ay nagpapahiwatig ng pangalan ng module na gagamitin sa native na panig. Ang Codegen batay sa specification na ito ay bubuo ng lahat ng kinakailangang file para sa Fabric at TurboModules.

Codegen sa arkitektura ng Fabric

Sa konteksto ng Fabric (bagong renderer ng React Native), ang Codegen ay may espesyal na papel. Ang Fabric ay nangangailangan na ang bawat native UI component ay may C++ representation na maaaring malikha at mapamahalaan sa pamamagitan ng JSI. Ang Codegen ay bumubuo ng mga C++ representation na ito nang awtomatiko batay sa mga specification ng component.

Pagbuo para sa UI components

Para sa UI components, ang Codegen ay hindi lamang bumubuo ng C++ Shadow Node class, kundi pati na rin ng platform representations. Halimbawa, para sa isang custom na Button component sa iOS, ang Codegen ay gagawa ng Objective-C class na nagrerehistro ng component sa Fabric at nag-uugnay nito sa C++ Shadow Node. Ang developer ay kailangan lamang ilarawan ang mga property ng component (kulay, laki, handlers) sa TypeScript specification.

Tipification ng mga property

Sinusuportahan ng Codegen ang direkta at baligtad na paglipat ng data. Ang Direct Event (halimbawa onPress) ay binuo bilang C++ structures na may mga field na awtomatikong serialized kapag inilipat sa JS. Ang EventEmitter ay nagpapahintulot sa native na panig na magpadala ng mga event sa JS nang walang kahilingan mula sa JS. Ang Codegen ay bumubuo ng mga naka-type na wrapper para sa parehong direksyon, na tinatanggal ang mga error ng hindi pagkakatugma ng pangalan ng field.

Codegen para sa third-party libraries

Ang mga developer ng library ay maaaring magbigay ng Codegen specifications kasama ng npm package. Kapag nag-i-install ng library, awtomatikong na-detect ng Codegen ang mga specification at bumubuo ng nag-uugnay na code para sa kasalukuyang platform. Ito ay lalong mahalaga para sa native libraries, dahil ang user ng library ay hindi kailangang malaman ang C++, Objective-C o Java — sapat na ang mag-import ng TypeScript types at gumamit ng mga handa nang component.

Anong mga file ang ginagawa ng Codegen?

Ang Codegen ay bumubuo ng mga file para sa tatlong target na kapaligiran: C++ (JSI), Objective-C (iOS) at Java (Android). Ang bawat file ay may mahigpit na tinukoy na papel at istraktura. Ang pag-unawa kung anong mga file ang ginagawa ay tumutulong sa debugging at, kung kinakailangan, manwal na pagwawasto ng nabuong code.

C++ files (JSI)

Para sa bawat native module, ang Codegen ay gumagawa ng dalawang C++ file: header file (.h) na may deklarasyon ng Host Object class at implementasyon file (.cpp) na may mga pamamaraan na tumatawag sa kaukulang function sa platform. Ang header file ay naglalaman ng class na nagmamana ng jsi::HostObject na may override na get method para sa access sa mga function ng module. Ang implementasyon file ay naglalaman ng lambda functions na kapag tinawag mula sa JS ay nagde-delegate ng execution sa native module.

iOS files (Objective-C)

Para sa iOS, ang Codegen ay bumubuo ng Objective-C protocol at category. Ang protocol ay nagdedeklara ng mga pamamaraan na dapat implementahin ng native module. Ang category sa RCTCxxBridge ay naglalaman ng nag-uugnay na code na nagrerehistro ng module sa RCTTurboModuleManager. Pinapayagan nito ang pagtawag ng mga pamamaraan ng Objective-C module mula sa C++ JSI sa pamamagitan ng standard na RCTBridge mechanism.

Android files (Java)

Para sa Android, ang Codegen ay bumubuo ng Java interface at abstract class. Ang interface ay naglalaman ng mga deklarasyon ng pamamaraan ng module na may tamang Java types. Ang abstract class ay nag-iimplementa ng TurboModule interface at naglalaman ng pangunahing logic para sa pagrerehistro ng module sa ReactPackage. Ang developer ay nagmamana ng class na ito at nag-iimplementa lamang ng business logic ng mga pamamaraan.

Istraktura ng nabuong mga file

// Istraktura ng directory pagkatapos ng Codegen run
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protocol
            NativeCalculatorSpec.mm    // Implementasyon ng JSI
        android/
            NativeCalculatorSpec.java  // Java interface
            NativeCalculatorModuleBase.java  // Base class
        cxx/
            NativeCalculator.h         // C++ Host Object header
            NativeCalculator.cpp        // Implementasyon ng C++ JSI

Ang buong istrakturang ito ay awtomatikong nalilikha kapag binubuo ang proyekto. Ang developer ay hindi dapat mag-edit ng nabuong mga file — sa susunod na build ay mapapalitan ang mga ito. Kung kailangang baguhin ang pag-uugali ng module, ang mga pagbabago ay ginagawa lamang sa source code ng native implementasyon (Java/Objective-C) o sa TypeScript specification.

Mga halimbawa ng workflow ng Codegen

Tingnan natin ang kumpletong cycle ng trabaho sa Codegen sa halimbawa ng paggawa ng native module para sa pag-imbak ng data sa Keychain. Ito ay isang tipikal na gawain na nangangailangan ng access sa native API ng iOS at Android.

Hakbang 1: Specification

Ang developer ay gumagawa ng specification file na naglalarawan ng interface ng KeychainStorage module. Ang mga pamamaraan na save at read ay tumatanggap ng string at nagbabalik ng Promise, dahil ang pagtatrabaho sa Keychain ay maaaring asynchronous sa ilang platform.

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

Hakbang 2: Pagpapatakbo ng Codegen

Ang Codegen ay awtomatikong tumatakbo kapag binubuo ang React Native project. Kung kailangan itong patakbuhin nang manwal, ginagamit ang command na npx react-native codegen. Ang Codegen ay pumaparse ng specification at gumagawa ng lahat ng kinakailangang file sa build/generated/. Nakikita ng developer ang resulta sa anyo ng nabuong C++, Objective-C at Java files, ngunit hindi dapat i-edit ang mga ito.

# Patakbuhin ang Codegen nang manwal
npx react-native codegen --target-path ./build/generated

# Pagkatapos ng pagbuo — buoin ang proyekto
npx react-native run-ios
npx react-native run-android

Hakbang 3: Paggamit sa JS

Pagkatapos ng pagbuo at build, ini-import ng developer ang module bilang isang regular na TypeScript type. Ang IDE ay awtomatikong nagmumungkahi ng mga lagda ng pamamaraan salamat sa nabuong .d.ts files. Ang TypeScript ay ginagarantiya na ang mga uri ng parameter at return value ay tugma sa native implementasyon — kung sa specification ay nakasaad na string, ang native na panig ay makakatanggap ng eksaktong 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')
}

Sa halimbawang ito ay makikita na ang JS code ay hindi naglalaman ng anumang indikasyon ng platform — pareho para sa iOS at Android. Ang lahat ng platform specifics ay nakatago sa loob ng code na binuo ng Codegen. Ang Codegen ay sumasalo ng lahat ng routine na trabaho sa paggawa ng mga tulay, na iniiwan sa developer ang business logic at type checking sa pamamagitan ng TypeScript.