Codegen: nó là gì, tạo mã và kiến trúc Fabric

Codegen là gì?

Codegen (viết tắt của Code Generator) là một tiện ích dòng lệnh có trong React Native, tự động tạo mã cầu nối cho tương tác giữa JavaScript và các nền tảng gốc (iOS, Android). Codegen là một phần không thể thiếu của kiến trúc React Native mới và được sử dụng cho cả Fabric (trình kết xuất) và TurboModules (mô-đun gốc).

Ý tưởng chính của Codegen là phân tách trách nhiệm: nhà phát triển mô tả một hàm nên làm «gì» (chữ ký của nó), và Codegen tạo ra «cách» nó sẽ được truyền đến phía gốc. Điều này loại bỏ nhu cầu viết thủ công wrapper C++ cho JSI, sơ khai Objective-C cho iOS và lớp Java cho Android. Một nguồn sự thật duy nhất — đặc tả TypeScript — đảm bảo rằng các kiểu khớp nhau ở mọi cấp độ, loại bỏ toàn bộ lớp lỗi liên quan đến không khớp kiểu giữa JS và mã gốc.

Codegen được giới thiệu cùng với phiên bản ổn định đầu tiên của kiến trúc React Native mới (0.70+) và từ đó đã trở thành công cụ bắt buộc để tạo mô-đun gốc. Nếu không có Codegen, các nhà phát triển sẽ phải viết thủ công JSI Host Objects, đòi hỏi kiến thức sâu về C++ và hiểu biết về cấu trúc bên trong của công cụ JavaScript.

Tiến hóa: từ cầu nối thủ công đến tạo tự động

Trước Codegen, phát triển mô-đun gốc cho React Native bao gồm ba bước: viết giao diện JavaScript, triển khai mô-đun gốc bằng Java/Objective-C và viết cầu nối thủ công. Khi chữ ký phương thức thay đổi, cả ba tệp phải được cập nhật đồng bộ. Codegen tự động hóa quy trình này: các thay đổi chỉ được thực hiện trong đặc tả TypeScript, và mọi thứ khác được tạo lại.

Tích hợp với hệ thống xây dựng

Codegen tích hợp vào quy trình xây dựng React Native thông qua Metro và CocoaPods. Khi bắt đầu xây dựng, Codegen phân tích các đặc tả TypeScript, tạo tệp C++ và nền tảng, đồng thời đặt chúng vào thư mục xây dựng. Điều này có nghĩa là mã được tạo luôn khớp với các đặc tả hiện tại và không yêu cầu cập nhật thủ công.

Codegen hoạt động như thế nào?

Quy trình làm việc của Codegen bao gồm ba giai đoạn: phân tích cú pháp đặc tả, xây dựng biểu diễn trung gian và tạo tệp đích. Mỗi giai đoạn được cô lập, giúp dễ dàng thêm hỗ trợ cho các nền tảng hoặc ngôn ngữ tạo mới.

Ở giai đoạn đầu tiên, Codegen đọc các tệp đặc tả ở định dạng TypeScript hoặc Flow. Đặc tả mô tả giao diện mô-đun gốc: tên phương thức, kiểu tham số và kiểu trả về. Codegen hỗ trợ các kiểu nguyên thủy (number, string, boolean) cũng như các kiểu phức tạp — đối tượng, mảng, Promise và Callback. Các đặc tả được lưu trữ trong tệp .ts hoặc .js trong một thư mục đặc biệt của dự án.

Ở giai đoạn thứ hai, Codegen xây dựng Cây cú pháp trừu tượng (AST) từ các đặc tả đã phân tích. AST biểu diễn cấu trúc dữ liệu ở định dạng trung tính không gắn với bất kỳ ngôn ngữ tạo cụ thể nào. Điều này cho phép tạo mã C++ cho Fabric, Objective-C cho iOS và Java cho Android từ một AST duy nhất — không cần thêm công việc nào để hỗ trợ tất cả các nền tảng.

Ở giai đoạn thứ ba, Codegen sử dụng công cụ mẫu (dựa trên Mustache) để tạo tệp cho các nền tảng đích. Mỗi mẫu xử lý một loại tệp cụ thể: tiêu đề C++ (.h), triển khai (.cpp), giao thức Objective-C (.h) hoặc triển khai (.mm), lớp Java. Các mẫu được cung cấp cùng với React Native, nhưng có thể được tùy chỉnh cho nhu cầu cụ thể của dự án.

Sơ đồ hoạt động của 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')

Trong ví dụ này, đặc tả mô tả mô-đun NativeCalculator với hai phương thức: add và multiply. Cả hai đều chấp nhận Double và trả về Double. Chuỗi 'NativeCalculator' trong TurboModuleRegistry chỉ định tên mô-đun sẽ được sử dụng ở phía gốc. Codegen dựa trên đặc tả này sẽ tạo tất cả các tệp cần thiết cho Fabric và TurboModules.

Codegen trong kiến trúc Fabric

Trong bối cảnh Fabric (trình kết xuất React Native mới), Codegen đóng một vai trò đặc biệt. Fabric yêu cầu mọi thành phần giao diện người dùng gốc phải có biểu diễn C++ có thể được tạo và quản lý thông qua JSI. Codegen tự động tạo các biểu diễn C++ này dựa trên đặc tả thành phần.

Tạo cho thành phần giao diện

Đối với thành phần giao diện, Codegen không chỉ tạo lớp Shadow Node C++ mà còn tạo cả biểu diễn dành riêng cho nền tảng. Ví dụ, đối với thành phần Button tùy chỉnh trên iOS, Codegen tạo một lớp Objective-C đăng ký thành phần trong Fabric và liên kết nó với Shadow Node C++. Nhà phát triển chỉ cần mô tả thuộc tính thành phần (màu sắc, kích thước, trình xử lý) trong đặc tả TypeScript.

Kiểu thuộc tính

Codegen hỗ trợ cả truyền dữ liệu trực tiếp và ngược. Sự kiện trực tiếp (ví dụ onPress) được tạo dưới dạng cấu trúc C++ với các trường tự động được tuần tự hóa khi truyền vào JS. EventEmitter cho phép phía gốc gửi sự kiện đến JS mà không cần yêu cầu từ JS. Codegen tạo wrapper có kiểu cho cả hai hướng, loại bỏ lỗi không khớp tên trường.

Codegen cho thư viện bên thứ ba

Nhà phát triển thư viện có thể cung cấp đặc tả Codegen cùng với gói npm của họ. Khi cài đặt thư viện, Codegen tự động phát hiện các đặc tả và tạo mã cầu nối cho nền tảng hiện tại. Điều này đặc biệt quan trọng đối với thư viện gốc, vì người dùng thư viện không cần hiểu C++, Objective-C hay Java — họ chỉ cần nhập kiểu TypeScript và sử dụng các thành phần có sẵn.

Codegen tạo ra những tệp nào?

Codegen tạo tệp cho ba môi trường đích: C++ (JSI), Objective-C (iOS) và Java (Android). Mỗi tệp có vai trò và cấu trúc được xác định chặt chẽ. Hiểu những tệp nào được tạo ra giúp ích cho việc gỡ lỗi và nếu cần, điều chỉnh thủ công mã đã tạo.

Tệp C++ (JSI)

Đối với mỗi mô-đun gốc, Codegen tạo hai tệp C++: tệp tiêu đề (.h) với khai báo lớp Host Object và tệp triển khai (.cpp) với các phương thức gọi các hàm tương ứng trên nền tảng. Tệp tiêu đề chứa một lớp kế thừa từ jsi::HostObject với phương thức get được ghi đè để truy cập các hàm của mô-đun. Tệp triển khai chứa các hàm lambda mà khi được gọi từ JS sẽ ủy quyền thực thi cho mô-đun gốc.

Tệp iOS (Objective-C)

Đối với iOS, Codegen tạo một giao thức Objective-C và một danh mục. Giao thức khai báo các phương thức phải được triển khai bởi mô-đun gốc. Danh mục trên RCTCxxBridge chứa mã cầu nối đăng ký mô-đun trong RCTTurboModuleManager. Điều này cho phép gọi các phương thức mô-đun Objective-C từ C++ JSI thông qua cơ chế RCTBridge tiêu chuẩn.

Tệp Android (Java)

Đối với Android, Codegen tạo một giao diện Java và một lớp trừu tượng. Giao diện chứa các khai báo phương thức với kiểu Java chính xác. Lớp trừu tượng triển khai giao diện TurboModule và chứa logic cơ bản để đăng ký mô-đun trong ReactPackage. Nhà phát triển kế thừa từ lớp này và chỉ triển khai logic nghiệp vụ của các phương thức.

Cấu trúc tệp được tạo

// 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

Toàn bộ cấu trúc này được tạo tự động trong quá trình xây dựng dự án. Nhà phát triển không nên chỉnh sửa các tệp đã tạo — chúng sẽ bị ghi đè ở lần xây dựng tiếp theo. Nếu cần thay đổi hành vi của mô-đun, các sửa đổi chỉ được thực hiện trong mã nguồn triển khai gốc (Java/Objective-C) hoặc trong đặc tả TypeScript.

Ví dụ về quy trình làm việc của Codegen

Hãy xem qua quy trình làm việc đầy đủ của Codegen bằng cách tạo một mô-đun gốc để lưu trữ dữ liệu trong Keychain. Đây là một tác vụ điển hình yêu cầu truy cập API gốc của iOS và Android.

Bước 1: Đặc tả

Nhà phát triển tạo một tệp đặc tả mô tả giao diện mô-đun KeychainStorage. Các phương thức save và read chấp nhận một chuỗi và trả về Promise, vì làm việc với Keychain có thể không đồng bộ trên một số nền tảng.

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

Bước 2: Chạy Codegen

Codegen chạy tự động khi xây dựng dự án React Native. Nếu cần chạy thủ công, lệnh npx react-native codegen được sử dụng. Codegen phân tích đặc tả và tạo tất cả các tệp cần thiết trong build/generated/. Nhà phát triển thấy các tệp C++, Objective-C và Java đã tạo, nhưng không nên chỉnh sửa chúng.

# 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

Bước 3: Sử dụng trong JS

Sau khi tạo và xây dựng, nhà phát triển nhập mô-đun như một kiểu TypeScript thông thường. IDE tự động gợi ý chữ ký phương thức nhờ các tệp .d.ts đã tạo. TypeScript đảm bảo rằng kiểu tham số và giá trị trả về khớp với triển khai gốc — nếu đặc tả chỉ định string, phía gốc sẽ nhận được chính xác một chuỗi.

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

Ví dụ này cho thấy mã JS không chứa bất kỳ hướng dẫn dành riêng cho nền tảng nào — nó giống nhau cho cả iOS và Android. Tất cả chi tiết dành riêng cho nền tảng đều được ẩn bên trong mã do Codegen tạo. Codegen xử lý tất cả công việc thông thường của việc tạo cầu nối, để lại cho nhà phát triển chỉ logic nghiệp vụ và kiểm tra kiểu thông qua TypeScript.