Codegen: τι είναι, δημιουργία κώδικα και αρχιτεκτονική Fabric

Τι είναι το Codegen;

Codegen (συντομογραφία του Code Generator) είναι ένα εργαλείο γραμμής εντολών που αποτελεί μέρος του React Native και δημιουργεί αυτόματα συνδετικό κώδικα για επικοινωνία μεταξύ JavaScript και native πλατφορμών (iOS, Android). Το Codegen είναι αναπόσπαστο μέρος της νέας αρχιτεκτονικής React Native και χρησιμοποιείται τόσο για το Fabric (renderer) όσο και για τα TurboModules (native modules).

Η κύρια ιδέα του Codegen έγκειται στον διαχωρισμό ευθυνών: ο προγραμματιστής περιγράφει «τι» πρέπει να κάνει η συνάρτηση (την υπογραφή της), και το Codegen δημιουργεί «πώς» θα μεταδοθεί αυτό στη native πλευρά. Αυτό εξαλείφει την ανάγκη χειροκίνητης γραφής C++ συνδετικού κώδικα για JSI, Objective-C stub για iOS και Java κλάσεων για Android. Μία μοναδική πηγή αλήθειας — η προδιαγραφή TypeScript — εγγυάται ότι οι τύποι σε όλα τα επίπεδα ταιριάζουν, εξαλείφοντας μια ολόκληρη κατηγορία σφαλμάτων που σχετίζονται με ασυμφωνία τύπων μεταξύ JS και native κώδικα.

Το Codegen παρουσιάστηκε μαζί με την πρώτη σταθερή έκδοση της νέας αρχιτεκτονικής React Native (0.70+) και από τότε έχει γίνει υποχρεωτικό εργαλείο για τη δημιουργία native modules. Χωρίς Codegen, ο προγραμματιστής θα έπρεπε να γράφει χειροκίνητα JSI Host Objects, που απαιτεί βαθιά γνώση C++ και κατανόηση της εσωτερικής λειτουργίας των JavaScript μηχανών.

Εξέλιξη: από τη χειροκίνητη γέφυρα στην αυτόματη δημιουργία

Πριν από την εμφάνιση του Codegen, η ανάπτυξη ενός native module για React Native περιλάμβανε τρία βήματα: γραφή της διεπαφής JavaScript, υλοποίηση του native module σε Java/Objective-C και χειροκίνητη γραφή της γέφυρας. Κατά την αλλαγή της υπογραφής μιας μεθόδου, έπρεπε να ενημερωθούν συγχρονισμένα και τα τρία αρχεία. Το Codegen αυτοματοποιεί αυτή τη ρουτίνα: οι αλλαγές γίνονται μόνο στην προδιαγραφή TypeScript, και όλα τα υπόλοιπα δημιουργούνται ξανά.

Ενσωμάτωση με το σύστημα build

Το Codegen ενσωματώνεται στη διαδικασία build του React Native μέσω Metro και CocoaPods. Κατά την εκκίνηση του build, το Codegen αναλύει τις προδιαγραφές TypeScript, δημιουργεί C++ και αρχεία πλατφόρμας και τα τοποθετεί στον κατάλογο build. Αυτό σημαίνει ότι ο δημιουργημένος κώδικας αντιστοιχεί πάντα στις τρέχουσες προδιαγραφές και δεν απαιτεί χειροκίνητη ενημέρωση.

Πώς λειτουργεί το Codegen;

Η διαδικασία λειτουργίας του Codegen αποτελείται από τρία στάδια: ανάλυση προδιαγραφών, δημιουργία ενδιάμεσης αναπαράστασης και δημιουργία αρχείων προορισμού. Κάθε στάδιο είναι απομονωμένο, επιτρέποντας εύκολη προσθήκη υποστήριξης για νέες πλατφόρμες ή γλώσσες δημιουργίας.

Στο πρώτο στάδιο, το Codegen διαβάζει αρχεία προδιαγραφών σε μορφή TypeScript ή Flow. Η προδιαγραφή περιγράφει τη διεπαφή του native module: ονόματα μεθόδων, τύπους παραμέτρων και επιστρεφόμενων τιμών. Το 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
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')

Σε αυτό το παράδειγμα, η προδιαγραφή περιγράφει το module NativeCalculator με δύο μεθόδους: add και multiply. Και οι δύο δέχονται Double και επιστρέφουν Double. Η συμβολοσειρά 'NativeCalculator' στο TurboModuleRegistry υποδεικνύει το όνομα του module που θα χρησιμοποιηθεί στη native πλευρά. Το Codegen βάσει αυτής της προδιαγραφής θα δημιουργήσει όλα τα απαραίτητα αρχεία για Fabric και TurboModules.

Codegen στην αρχιτεκτονική Fabric

Στο πλαίσιο του Fabric (νέος renderer του React Native), το Codegen παίζει ιδιαίτερο ρόλο. Το Fabric απαιτεί κάθε native UI component να έχει μια αναπαράσταση C++ που μπορεί να δημιουργηθεί και να διαχειρίζεται μέσω JSI. Το Codegen δημιουργεί αυτές τις αναπαραστάσεις C++ αυτόματα βάσει των προδιαγραφών των components.

Δημιουργία για UI components

Για τα UI components, το Codegen δημιουργεί όχι μόνο την κλάση C++ Shadow Node, αλλά και αναπαραστάσεις πλατφόρμας. Για παράδειγμα, για ένα προσαρμοσμένο component Button στο iOS, το Codegen θα δημιουργήσει μια κλάση Objective-C που καταχωρεί το component στο Fabric και το συνδέει με το C++ Shadow Node. Ο προγραμματιστής χρειάζεται μόνο να περιγράψει τις ιδιότητες του component (χρώμα, μέγεθος, χειριστές) στην προδιαγραφή TypeScript.

Τυποποίηση ιδιοτήτων

Το Codegen υποστηρίζει άμεση και αντίστροφη μεταφορά δεδομένων. Το Direct Event (π.χ. onPress) δημιουργείται ως δομή C++ με πεδία που αυτόματα σειριοποιούνται κατά τη μεταφορά στο JS. Το EventEmitter επιτρέπει στη native πλευρά να στέλνει συμβάντα στο JS χωρίς αίτημα από το JS. Το Codegen δημιουργεί τυποποιημένους περιτυλιγμένους κώδικες και για τις δύο κατευθύνσεις, εξαλείφοντας σφάλματα ασυμφωνίας ονομάτων πεδίων.

Codegen για βιβλιοθήκες τρίτων

Οι προγραμματιστές βιβλιοθηκών μπορούν να παρέχουν προδιαγραφές Codegen μαζί με το πακέτο npm. Κατά την εγκατάσταση της βιβλιοθήκης, το Codegen ανιχνεύει αυτόματα τις προδιαγραφές και δημιουργεί συνδετικό κώδικα για την τρέχουσα πλατφόρμα. Αυτό είναι ιδιαίτερα σημαντικό για native βιβλιοθήκες, καθώς ο χρήστης της βιβλιοθήκης δεν χρειάζεται να γνωρίζει C++, Objective-C ή Java — αρκεί να εισάγει τύπους TypeScript και να χρησιμοποιεί έτοιμα components.

Ποια αρχεία δημιουργεί το Codegen;

Το Codegen δημιουργεί αρχεία για τρία περιβάλλοντα προορισμού: C++ (JSI), Objective-C (iOS) και Java (Android). Κάθε αρχείο έχει αυστηρά καθορισμένο ρόλο και δομή. Η κατανόηση των αρχείων που δημιουργούνται βοηθά στον εντοπισμό σφαλμάτων και, εάν χρειαστεί, στη χειροκίνητη διόρθωση του δημιουργημένου κώδικα.

Αρχεία C++ (JSI)

Για κάθε native module, το Codegen δημιουργεί δύο αρχεία C++: αρχείο κεφαλίδας (.h) με δήλωση της κλάσης Host Object και αρχείο υλοποίησης (.cpp) με μεθόδους που καλούν τις αντίστοιχες λειτουργίες στην πλατφόρμα. Το αρχείο κεφαλίδας περιέχει μια κλάση που κληρονομεί από jsi::HostObject με παρακάμπτουσα μέθοδο get για πρόσβαση στις λειτουργίες του module. Το αρχείο υλοποίησης περιέχει συναρτήσεις lambda που κατά την κλήση από JS εκχωρούν την εκτέλεση στο native module.

Αρχεία iOS (Objective-C)

Για iOS, το Codegen δημιουργεί ένα πρωτόκολλο Objective-C και μια κατηγορία. Το πρωτόκολλο δηλώνει μεθόδους που πρέπει να υλοποιηθούν από το native module. Η κατηγορία στο RCTCxxBridge περιέχει συνδετικό κώδικα που καταχωρεί το module στο RCTTurboModuleManager. Αυτό επιτρέπει την κλήση μεθόδων του Objective-C module από C++ JSI μέσω του τυπικού μηχανισμού RCTBridge.

Αρχεία Android (Java)

Για Android, το Codegen δημιουργεί μια διεπαφή Java και μια αφηρημένη κλάση. Η διεπαφή περιέχει δηλώσεις μεθόδων του module με σωστούς τύπους Java. Η αφηρημένη κλάση υλοποιεί τη διεπαφή TurboModule και περιέχει βασική λογική για την καταχώρηση του module στο 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        // Υλοποίηση JSI C++

Ολόκληρη αυτή η δομή δημιουργείται αυτόματα κατά το build του έργου. Ο προγραμματιστής δεν πρέπει να επεξεργάζεται τα δημιουργημένα αρχεία — στο επόμενο build θα αντικατασταθούν. Εάν απαιτείται αλλαγή της συμπεριφοράς του module, οι αλλαγές γίνονται μόνο στον πηγαίο κώδικα της native υλοποίησης (Java/Objective-C) ή στην προδιαγραφή TypeScript.

Παραδείγματα ροής εργασίας Codegen

Ας εξετάσουμε τον πλήρη κύκλο εργασίας με το Codegen στο παράδειγμα δημιουργίας ενός native module για αποθήκευση δεδομένων στο Keychain. Αυτή είναι μια τυπική εργασία που απαιτεί πρόσβαση στο native API iOS και Android.

Βήμα 1: Προδιαγραφή

Ο προγραμματιστής δημιουργεί ένα αρχείο προδιαγραφής που περιγράφει τη διεπαφή του module 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 εκτελείται αυτόματα κατά το build του έργου React Native. Εάν χρειάζεται χειροκίνητη εκτέλεση, χρησιμοποιείται η εντολή npx react-native codegen. Το Codegen αναλύει την προδιαγραφή και δημιουργεί όλα τα απαραίτητα αρχεία στο build/generated/. Ο προγραμματιστής βλέπει το αποτέλεσμα ως δημιουργημένα αρχεία C++, Objective-C και Java, αλλά δεν πρέπει να τα επεξεργάζεται.

# Εκτέλεση Codegen χειροκίνητα
npx react-native codegen --target-path ./build/generated

# Μετά τη δημιουργία — build του έργου
npx react-native run-ios
npx react-native run-android

Βήμα 3: Χρήση σε JS

Μετά τη δημιουργία και το build, ο προγραμματιστής εισάγει το module ως έναν κανονικό τύπο 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.