Codegen: шта је то, генерисање кода и архитектура Fabric-а

Шта је Codegen?

Codegen (скраћеница од Code Generator) је алат командне линије који је део React Native-а и аутоматски генерише везивни код за интеракцију између JavaScript-а и изворних платформи (iOS, Android). Codegen је неодвојиви део нове архитектуре React Native-а и користи се како за Fabric (рендерер), тако и за TurboModules (изворни модули).

Основна идеја Codegen-а лежи у подели одговорности: програмер описује „шта” функција треба да ради (њен потпис), а Codegen генерише „како” ће то бити пренето на изворну страну. Ово елиминише потребу за ручним писањем C++ везивног кода за JSI, 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 се интегрише у процес изградње React Native-а преко Metro-а и CocoaPods-а. При покретању изградње, 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 генерише типизоване омотаче за оба смера, елиминишући грешке неусклађености назива поља.

Codegen за библиотеке трећих страна

Програмери библиотека могу испоручивати Codegen спецификације заједно са npm пакетом. При инсталацији библиотеке, Codegen аутоматски открива спецификације и генерише везивни код за текућу платформу. Ово је посебно важно за изворне библиотеке, јер корисник библиотеке не мора да зна C++, Objective-C или Java — довољно је да увезе TypeScript типове и користи готове компоненте.

Које датотеке генерише 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 протокол и категорију. Протокол декларише методе које морају бити имплементиране од стране изворног модула. Категорија на RCTCxxBridge садржи везивни код који региструје модул у RCTTurboModuleManager-у. Ово омогућава позивање метода Objective-C модула из C++ JSI-ја кроз стандардни механизам RCTBridge.

Android датотеке (Java)

За Android, Codegen генерише Java интерфејс и апстрактну класу. Интерфејс садржи декларације метода модула са исправним Java типовима. Апстрактна класа имплементира интерфејс TurboModule и садрži основну логику за регистрацију модула у 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        // C++ JSI имплементација

Цела ова структура се креира аутоматски приликом изградње пројекта. Програмер не треба да уређује генерисане датотеке — при следећој изградњи биће преписане. Ако је потребно променити понашање модула, измене се уносе само у изворни код изворне имплементације (Java/Objective-C) или у TypeScript спецификацију.

Примери радног процеса Codegen-а

Размотримо комплетан циклус рада са Codegen-ом на примеру креирања изворног модула за чување података у Keychain-у. Ово је типичан задатак који захтева приступ изворном API-ју iOS-а и Android-а.

Корак 1: Спецификација

Програмер креира датотеку спецификације која описује интерфејс модула 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')

Корак 2: Покретање 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

Корак 3: Коришћење у JS-у

Након генерисања и изградње, програмер увози модул као обичан TypeScript тип. 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.