Codegen: 개념, 코드 생성 및 Fabric 아키텍처

Codegen이란?

Codegen(Code Generator의 약어)은 React Native에 포함된 명령줄 유틸리티로, JavaScript와 네이티브 플랫폼(iOS, Android) 간의 상호작용을 위한 브리징 코드를 자동으로 생성합니다. Codegen은 새로운 React Native 아키텍처의 필수적인 부분이며 Fabric(렌더러)과 TurboModules(네이티브 모듈) 모두에 사용됩니다.

Codegen의 주요 아이디어는 책임의 분리입니다. 개발자는 함수가 수행해야 할 작업(시그니처)을 설명하고 Codegen은 이를 네이티브 측에 전달하는 방법을 생성합니다. 이렇게 하면 JSI용 C++ 래퍼, iOS용 Objective-C 스텁, Android용 Java 클래스를 수동으로 작성할 필요가 없어집니다. 단일 진실 공급원인 TypeScript 사양은 모든 수준에서 타입이 일치하도록 보장하여 JS와 네이티브 코드 간의 타입 불일치와 관련된 전체 오류 클래스를 제거합니다.

Codegen은 새로운 React Native 아키텍처(0.70+)의 첫 번째 안정 버전과 함께 도입되었으며 이후 네이티브 모듈 생성을 위한 필수 도구가 되었습니다. Codegen이 없으면 개발자는 JSI Host Objects를 수동으로 작성해야 했으며, 이를 위해서는 C++에 대한 깊은 지식과 JavaScript 엔진의 내부 구조 이해가 필요했습니다.

진화: 수동 브리지에서 자동 생성까지

Codegen 이전에는 React Native용 네이티브 모듈 개발에 세 단계가 필요했습니다. JavaScript 인터페이스 작성, Java/Objective-C로 네이티브 모듈 구현, 수동으로 브리지 작성입니다. 메서드 시그니처가 변경되면 세 파일을 모두 동기적으로 업데이트해야 했습니다. Codegen은 이 루틴을 자동화하여 TypeScript 사양만 변경하면 나머지는 모두 다시 생성됩니다.

빌드 시스템과의 통합

Codegen은 Metro와 CocoaPods를 통해 React Native 빌드 프로세스에 통합됩니다. 빌드를 시작하면 Codegen이 TypeScript 사양을 분석하고 C++ 및 플랫폼 파일을 생성하여 빌드 디렉터리에 배치합니다. 즉, 생성된 코드는 항상 현재 사양과 일치하며 수동 업데이트가 필요하지 않습니다.

Codegen 작동 방식

Codegen 워크플로는 세 단계로 구성됩니다. 사양 구문 분석, 중간 표현 구축, 대상 파일 생성입니다. 각 단계는 분리되어 있어 새로운 플랫폼이나 생성 언어에 대한 지원을 쉽게 추가할 수 있습니다.

첫 번째 단계에서 Codegen은 TypeScript 또는 Flow 형식의 사양 파일을 읽습니다. 사양은 네이티브 모듈 인터페이스(메서드 이름, 매개변수 타입, 반환 타입)를 설명합니다. Codegen은 기본 타입(number, string, boolean)뿐만 아니라 복잡한 타입(객체, 배열, Promise, Callback)도 지원합니다. 사양은 프로젝트의 특수 디렉터리에 있는 .ts 또는 .js 파일에 저장됩니다.

두 번째 단계에서 Codegen은 구문 분석된 사양에서 추상 구문 트리(AST)를 구축합니다. AST는 특정 생성 언어에 종속되지 않는 중립적인 형식으로 데이터 구조를 나타냅니다. 이를 통해 단일 AST에서 Fabric용 C++ 코드, iOS용 Objective-C, Android용 Java를 생성할 수 있으며 모든 플랫폼을 지원하기 위해 추가 작업이 필요하지 않습니다.

세 번째 단계에서 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')

이 예제에서 사양은 두 개의 메서드(add 및 multiply)가 있는 NativeCalculator 모듈을 설명합니다. 둘 다 Double을 받아들이고 Double을 반환합니다. TurboModuleRegistry의 문자열 'NativeCalculator'는 네이티브 측에서 사용될 모듈 이름을 지정합니다. Codegen은 이 사양을 기반으로 Fabric 및 TurboModules에 필요한 모든 파일을 생성합니다.

Fabric 아키텍처의 Codegen

Fabric(새 React Native 렌더러)의 맥락에서 Codegen은 특별한 역할을 합니다. Fabric은 모든 네이티브 UI 구성 요소가 JSI를 통해 생성 및 관리될 수 있는 C++ 표현을 가져야 합니다. Codegen은 구성 요소 사양을 기반으로 이러한 C++ 표현을 자동으로 생성합니다.

UI 구성 요소 생성

UI 구성 요소의 경우 Codegen은 C++ Shadow Node 클래스뿐만 아니라 플랫폼별 표현도 생성합니다. 예를 들어 iOS의 사용자 정의 Button 구성 요소의 경우 Codegen은 구성 요소를 Fabric에 등록하고 C++ Shadow Node에 연결하는 Objective-C 클래스를 만듭니다. 개발자는 TypeScript 사양에서 구성 요소 속성(색상, 크기, 핸들러)만 설명하면 됩니다.

속성 타입 지정

Codegen은 직접 및 역방향 데이터 전송을 모두 지원합니다. 직접 이벤트(onPress 등)는 JS로 전달될 때 자동으로 직렬화되는 필드가 있는 C++ 구조체로 생성됩니다. EventEmitter를 사용하면 네이티브 측에서 JS의 요청 없이 JS로 이벤트를 보낼 수 있습니다. Codegen은 양방향에 대해 타입이 지정된 래퍼를 생성하여 필드 이름 불일치 오류를 제거합니다.

타사 라이브러리를 위한 Codegen

라이브러리 개발자는 npm 패키지와 함께 Codegen 사양을 제공할 수 있습니다. 라이브러리를 설치하면 Codegen이 자동으로 사양을 감지하고 현재 플랫폼용 브리징 코드를 생성합니다. 이는 네이티브 라이브러리에 특히 중요합니다. 라이브러리 사용자는 C++, Objective-C 또는 Java를 이해할 필요 없이 TypeScript 타입을 가져와서 준비된 구성 요소를 사용하기만 하면 됩니다.

Codegen이 생성하는 파일

Codegen은 세 가지 대상 환경(C++(JSI), Objective-C(iOS), Java(Android))에 대한 파일을 생성합니다. 각 파일은 엄격하게 정의된 역할과 구조를 가지고 있습니다. 어떤 파일이 생성되는지 이해하면 디버깅과 필요에 따라 생성된 코드의 수동 조정에 도움이 됩니다.

C++ 파일(JSI)

각 네이티브 모듈에 대해 Codegen은 두 개의 C++ 파일을 만듭니다. Host Object 클래스 선언이 있는 헤더 파일(.h)과 플랫폼에서 해당 함수를 호출하는 메서드가 있는 구현 파일(.cpp)입니다. 헤더 파일에는 jsi::HostObject에서 상속된 클래스가 포함되며 모듈 함수에 액세스하기 위해 재정의된 get 메서드가 있습니다. 구현 파일에는 JS에서 호출될 때 네이티브 모듈로 실행을 위임하는 람다 함수가 포함됩니다.

iOS 파일(Objective-C)

iOS의 경우 Codegen은 Objective-C 프로토콜과 카테고리를 생성합니다. 프로토콜은 네이티브 모듈이 구현해야 하는 메서드를 선언합니다. RCTCxxBridge의 카테고리에는 RCTTurboModuleManager에 모듈을 등록하는 브리징 코드가 포함됩니다. 이를 통해 표준 RCTBridge 메커니즘을 통해 C++ JSI에서 Objective-C 모듈 메서드를 호출할 수 있습니다.

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 워크플로 예제

Keychain에 데이터를 저장하기 위한 네이티브 모듈을 만들어 Codegen의 전체 워크플로를 살펴보겠습니다. 이는 iOS 및 Android 네이티브 API에 대한 액세스가 필요한 일반적인 작업입니다.

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 타입으로 가져옵니다. 생성된 .d.ts 파일 덕분에 IDE가 자동으로 메서드 시그니처를 제안합니다. 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를 통한 타입 검사만 남깁니다.