Codegen: какво е, генериране на код и архитектура на Fabric

Какво е Codegen?

Codegen (съкращение от Code Generator) е инструмент от команден ред, който е част от React Native и автоматично генерира свързващ код за комуникация между JavaScript и native платформи (iOS, Android). Codegen е неразделна част от новата архитектура на React Native и се използва както за Fabric (рендерер), така и за TurboModules (native модули).

Основната идея на Codegen се състои в разделението на отговорностите: разработчикът описва „какво” трябва да прави функцията (нейния подпис), а Codegen генерира „как” ще бъде предадено това на native страната. Това елиминира необходимостта от ръчно писане на C++ свързващ код за JSI, Objective-C заглушки за iOS и Java класове за Android. Единен източник на истина — TypeScript спецификацията — гарантира, че типовете на всички нива съвпадат, което елиминира цял клас грешки, свързани с несъответствие на типове между JS и native код.

Codegen беше представен заедно с първата стабилна версия на новата архитектура на React Native (0.70+) и оттогава стана задължителен инструмент за създаване на native модули. Без Codegen разработчикът би трябвало ръчно да пише JSI Host Objects, което изисква задълбочени познания по C++ и разбиране на вътрешното устройство на JavaScript двигателите.

Еволюция: от ръчен мост към автоматично генериране

Преди появата на Codegen, разработката на native модул за React Native включваше три стъпки: писане на JavaScript интерфейс, имплементация на native модул на Java/Objective-C и ръчно писане на мост. При промяна на сигнатурата на метод трябваше синхронно да се актуализират и трите файла. Codegen автоматизира тази рутина: промените се правят само в TypeScript спецификацията, а всичко останало се генерира наново.

Интеграция със системата за изграждане

Codegen се интегрира в процеса на изграждане на React Native чрез Metro и CocoaPods. При стартиране на изграждането, Codegen анализира TypeScript спецификациите, генерира C++ и платформени файлове и ги поставя в build директорията. Това означава, че генерираният код винаги съответства на текущите спецификации и не изисква ръчна актуализация.

Как работи Codegen?

Процесът на работа на Codegen се състои от три етапа: парсване на спецификации, изграждане на междинно представяне и генериране на целеви файлове. Всеки етап е изолиран, което позволява лесно добавяне на поддръжка за нови платформи или езици за генериране.

На първия етап Codegen чете файловете със спецификации във формат TypeScript или Flow. Спецификацията описва интерфейса на native модула: имена на методи, типове на параметри и връщани стойности. 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 — спецификация на native модул
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 показва името на модула, което ще се използва от native страната. Codegen на базата на тази спецификация ще генерира всички необходими файлове за Fabric и TurboModules.

Codegen в архитектурата на Fabric

В контекста на Fabric (новия рендерер на React Native), Codegen играе особена роля. Fabric изисква всеки native 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 позволява на native страната да изпраща събития към JS без заявка от страна на JS. Codegen генерира типизирани обвивки за двете посоки, елиминирайки грешки от несъответствие на имената на полетата.

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

Разработчиците на библиотеки могат да доставят Codegen спецификации заедно с npm пакета. При инсталиране на библиотека, Codegen автоматично открива спецификациите и генерира свързващ код за текущата платформа. Това е особено важно за native библиотеки, тъй като потребителят на библиотеката не трябва да знае C++, Objective-C или Java — достатъчно е да импортира TypeScript типове и да използва готови компоненти.

Какви файлове генерира Codegen?

Codegen генерира файлове за три целеви среди: C++ (JSI), Objective-C (iOS) и Java (Android). Всеки файл има строго определена роля и структура. Разбирането кои файлове се създават помага при отстраняване на грешки и, ако е необходимо, при ръчна корекция на генерирания код.

C++ файлове (JSI)

За всеки native модул, Codegen създава два C++ файла: заглавен файл (.h) с декларация на класа Host Object и файл за имплементация (.cpp) с методи, които извикват съответните функции на платформата. Заглавният файл съдържа клас, наследяващ jsi::HostObject с предефиниран метод get за достъп до функциите на модула. Файлът за имплементация съдържа ламбда функции, които при извикване от JS делегират изпълнението на native модула.

iOS файлове (Objective-C)

За iOS, Codegen генерира Objective-C протокол и категория. Протоколът декларира методите, които трябва да бъдат имплементирани от native модула. Категорията на RCTCxxBridge съдържа свързващ код, който регистрира модула в RCTTurboModuleManager. Това позволява извикване на методите на Objective-C модула от C++ JSI чрез стандартния механизъм RCTBridge.

Android файлове (Java)

За Android, Codegen генерира Java интерфейс и абстрактен клас. Интерфейсът съдържа декларации на методите на модула с правилни Java типове. Абстрактният клас имплементира интерфейса TurboModule и съдържа основна логика за регистриране на модула в 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 имплементация

Цялата тази структура се създава автоматично при изграждане на проекта. Разработчикът не трябва да редактира генерираните файлове — при следващото изграждане те ще бъдат презаписани. Ако е необходима промяна в поведението на модула, промените се правят само в изходния код на native имплементацията (Java/Objective-C) или в TypeScript спецификацията.

Примери на работния поток на Codegen

Нека разгледаме пълния цикъл на работа с Codegen на примера за създаване на native модул за съхранение на данни в Keychain. Това е типична задача, която изисква достъп до native 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 гарантира, че типовете на параметрите и връщаните стойности съвпадат с native имплементацията — ако в спецификацията е посочен string, native страната ще получи точно низ.

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.