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 — native module specification
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 автоматически обнаруживает спецификации и генерирует связующий код для текущей платформы. Это особенно важно для native-библиотек, так как пользователю библиотеки не нужно разбираться в 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 и содержит базовую логику для регистрации модуля в ReactPackage. Разработчик наследует от этого класса и реализует только бизнес-логику методов.

Структура сгенерированных файлов

// Directory structure after Codegen run
build/
    generated/
        ios/
            NativeCalculatorSpec.h     // Objective-C protocol
            NativeCalculatorSpec.mm    // JSI implementation
        android/
            NativeCalculatorSpec.java  // Java interface
            NativeCalculatorModuleBase.java  // Base class
        cxx/
            NativeCalculator.h         // C++ Host Object header
            NativeCalculator.cpp        // C++ JSI implementation

Вся эта структура создаётся автоматически при сборке проекта. Разработчик не должен редактировать сгенерированные файлы — при следующей сборке они будут перезаписаны. Если требуется изменить поведение модуля, изменения вносятся только в исходный код нативной реализации (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 файлов, но не должен их редактировать.

# Run Codegen manually
npx react-native codegen --target-path ./build/generated

# After generation — build the project
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.