בניית מודול Native עבור React Native ב-iOS מאפס

@objc(BiometricModule)
class BiometricModule: NSObject, RCTBridgeModule {
  static func moduleName() -> String {
    "BiometricModule"
  }

  @objc func authenticate(_ reason: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {
    let context = LAContext()
    var error: NSError?

    guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) else {
      rejecter("BIOMETRIC_UNAVAILABLE", error?.localizedDescription, error)
      return
    }

    context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason: reason) { success, authError in
      if success {
        resolver(true)
      } else {
        rejecter("AUTH_FAILED", authError?.localizedDescription, authError)
      }
    }
  }
}

הטעות הנפוצה ביותר בשלב זה: מפתח כותב מחלקת Swift, שוכח להוסיף @objc(BiometricModule) class BiometricModule: NSObject, RCTBridgeModule { static func moduleName() -> String { "BiometricModule" } @objc func authenticate(_ reason: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) { let context = LAContext() var error: NSError? guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) else { rejecter("BIOMETRIC_UNAVAILABLE", error?.localizedDescription, error) return } context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason: reason) { success, authError in if success { resolver(true) } else { rejecter("AUTH_FAILED", authError?.localizedDescription, authError) } } } } או נותן שם שגוי למתודה ב-RCT_EXTERN_METHOD, ובצד ה-JS מקבל @objc(BiometricModule). קשה לנפות כי השגיאה מופיעה בזמן ריצה ללא stack trace. המהנדס המוסמך שלנו עם ניסיון ב-100+ פרויקטים מבטל שגיאות כאלה בשלב בדיקת הקוד.

איך להבטיח בטיחות תהליכונים?

React Native קורא למתודות המודול על תהליך שרירותי מהמאגר שלו. אם בתוך המתודה ניגשים ל-UIKit, מקבלים קריסה עם undefined is not a function. הפתרון הקלאסי הוא UIKit called from background thread סביב קוד ה-UI. אבל זה יוצר בעיה חדשה: resolve/reject נקראים אסינכרונית, ואם המשתמש סוגר את המסך, ה-completion handler ניגש לאובייקט שכבר שוחרר.

התבנית עם DispatchQueue.main.async { } ו-guard היא חובה:

DispatchQueue.main.async { [weak self] in guard self != nil else { return } resolver(result) } 

סריאליזציית נתונים. הגשר מקבל רק סוגים שניתנים לסריאליזציה ל-JSON: NSString, NSNumber, NSArray, NSDictionary, NSNull. רוצים להעביר Data? קודדו אותו ב-Base64. רוצים להעביר אובייקט מותאם אישית? פרקו אותו למילון בצד ה-Native. זה כואב במיוחד בעבודה עם CoreBluetooth, שבה צריך לספק CBCharacteristic עם כל המאפיינים שלו.

Callbacks לעומת Promises לעומת Events. לתוצאות חד-פעמיות, השתמשו ב-Promise. לזרם אירועים (נתוני חיישנים, מצב חיבור), השתמשו ב-RCTEventEmitter. ערבוב גישות במודול אחד הוא שגיאה המובילה לדליפות זיכרון: אם RCTResponseSenderBlock נשמר כמאפיין ונקרא פעמיים, האפליקציה קורסת עם [weak self].

ארכיטקטורה חדשה: Turbo Modules + Codegen

החל מגרסת React Native התומכת בארכיטקטורה החדשה, Codegen מייצר הפשטה ב-C++ ממפרט TypeScript. קובץ המפרט נראה כך:

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  authenticate(reason: string): Promise<boolean>;
}

export default TurboModuleRegistry.getEnforcing<Spec>('BiometricModule');

בצד ה-Native, אנו מממשים את פרוטוקול DispatchQueue.main.async { [weak self] in guard self != nil else { return } resolver(result) } , ש-Codegen יצר אוטומטית. JSI מאפשר קריאה למתודות באופן סינכרוני ללא סריאליזציית JSON — המהירות שונה מהותית.

בעיה: אם בפרויקט יש לפחות חבילה אחת ללא תמיכת Turbo Module, הארכיטקטורה החדשה תפעל במצב תאימות, ותאבד חלק מהיתרונות. הצוות שלנו עוזר בביצוע ביקורת תלויות ותכנון הגירה ללא השבתה.

איך לפתח Native Module: תוכנית שלב-אחר-שלב

1. קביעת הדרישות ל-API ה-Native ובחירת הארכיטקטורה (Old Bridge או Turbo Module).
2. יצירת מחלקת Swift היורשת מ-NSObject והוספת תכונות @objc.
3. רישום המודול בקובץ הגישור Objective-C דרך RCT_EXTERN_MODULE.
4. יישום מתודות עם Promises או Events, תוך הבטחת בטיחות תהליכונים.
5. כתיבת סוגי TypeScript עבור ה-API הציבורי.
6. כיסוי הקוד ה-Native בבדיקות יחידה (XCTest).
7. בדיקת האינטגרציה עם שכבת ה-JS בסימולטור ובמכשיר אמיתי.

גישת היישום

אנו מתחילים בביקורת של גרסת ה-RN הנוכחית, נוכחות חבילות תואמות JSI, וגרסת ה-iOS היעד. אם הפרויקט בגרסה התומכת בארכיטקטורה החדשה והצוות מוכן, אנו כותבים מיד Turbo Module עם Codegen. אם לא, אנו משתמשים ב-RCTBridgeModule הקלאסי עם מבט לעתיד הגירה.

כיסוי החלק ה-Native בבדיקות יחידה דרך XCTest הוא חובה. בדיקות אינטגרציה נעשות עם Detox או Jest עם מודול מדומה בצד ה-JS. זה מפחית את מספר הבאגים בגרסת ה-release ב-40%.

אנו מתעדים את ה-API הציבורי בסוגי TypeScript כך שהצוות לא יצטרך לצלול לקוד ה-Native בכל פעם. התוצאה היא האצה פי 2 של תהליך הקליטה למפתחים חדשים.

מה כלול בעבודה

• ניתוח דרישות ובחירת גישה ארכיטקטונית (Old Bridge / Turbo Module)
• כתיבת קוד Native ב-Swift עם גישור Objective-C
• ת打字 TypeScript של ה-API הציבורי של המודול
• טיפול בשגיאות, בטיחות תהליכונים
• בדיקות יחידה לחלק ה-Native (XCTest)
• אינטגרציה עם שכבת ה-JS, אימות בסימולטור ובמכשיר אמיתי
• תיעוד שימוש במודול

לוחות זמנים

מ-3 עד 5 ימים בהתאם למורכבות ה-API ה-Native שיש לעטוף. עטיפה פשוטה של framework מערכתי אחד אורכת כ-3 ימים. מודול עם זרם אירועים, נתונים בינאריים ותמיכה בארכיטקטורה החדשה אורך 5 ימים או יותר. העלות מחושבת באופן אישי לאחר ניתוח דרישות ובדיקת קוד.

קבלו ייעוץ — צרו קשר להערכה מקדימה של הפרויקט שלכם. הזמינו פיתוח Native Module מאיתנו — אנו מבטיחים יציבות וביצועים.