ما بعد SemVer: هندسة تحديثات OTA مضادة للرصاص لتطبيقات React Native باستخدام Expo Fingerprint

لقد عشنا جميعاً قصة الرعب الخاصة بـ React Native. إنها الساعة 4:30 مساءً من يوم الخميس. تقوم بدفع تحديث Over-the-Air (OTA) عبر EAS لإصلاح bug بسيط في الـ UI. يشير الـ Semantic Versioning إلى أنه مجرد patch من (1.4.1 إلى 1.4.2). ولكن في أعماق الـ dependency tree، قامت transitive dependency بسحب native change بسيط.

بعد عشر دقائق، تضيء أداة الـ crash reporting لديك مثل شجرة عيد الميلاد. يحاول الـ JavaScript bundle استدعاء native method غير موجودة في الـ active binary على أجهزة المستخدمين. انهيار قاتل (fatal crash) عند التشغيل.

في العالم الهجين لـ React Native، تعتبر جدولة الإصدارات الدلالية (SemVer) كذبة. فكود الـ JS الخاص بك والـ Native runtime يعملان على دورات حياة مختلفة تماماً. لسنوات، قمنا بترقيع هذا الأمر باستخدام runtime versions يدوية أو سكربتات git-diff هشة.

في هذا المقال، أريد أن أشارك كيف حل فريقي هذه المشكلة مرة واحدة وإلى الأبد. لقد انتقلنا إلى zero-trust native pipeline باستخدام @expo/fingerprint. إليك كيف يمكنك بناء pipeline تحديثات OTA مضاد للرصاص يضمن برمجياً ألا تنهار تحديثاتك أبداً بسبب عدم تطابق في الـ native runtimes.

مشكلة الـ Native Runtime

لفهم سبب حاجتنا إلى Fingerprint، يجب أن ننظر إلى ما يشكل "native change" في مشروع Expo الحديث. الأمر لا يقتصر فقط على تعديل الملفات داخل /ios أو /android. يتم تحفيز الـ native change بواسطة:

1. ترقية حزمة تحتوي على native code (مثل react-native-reanimated).
2. تعديل ملف app.json (Expo Config) بطريقة تغير من Expo Config Plugins (مثل تغيير الصلاحيات أو أيقونات التطبيق).
3. ترقية الـ Expo SDK نفسه.
4. تعديل الـ native code المحلي أو قوالب الإعدادات (configuration templates).

إذا تغير أي من هذه العناصر، يجب على الـ JS bundle الخاص بك أن يستهدف native binary جديداً. إذا قمت بدفع تحديث OTA إلى binary تم بناؤه قبل هذه التغييرات، فسينهار التطبيق.

تاريخياً، حلت Expo هذه المشكلة باستخدام Runtime Versions المحددة في app.json:

{
  "expo": {
    "runtimeVersion": "1.0.0"
  }
}

لكن الـ manual runtime versioning يعتمد على الانضباط البشري. فالمطورون ينسون ترقية الإصدار (bump). أو يقومون بترقيته دون داعٍ، مما يجبر المستخدمين على تنزيل تحديث ضخم وجديد من متجر التطبيقات في حين أن تحديث OTA بسيط بحجم 100KB كان سيكفي.

ما هو Expo Fingerprint؟

@expo/fingerprint هي أداة طورها فريق Expo تقوم بتوليد hash حتمي (deterministic hash) للحالة الـ native الخاصة بمشروعك (native state).

حيث تقوم بتحليل ملف package.json وملفات الـ Lockfiles (yarn.lock و package-lock.json) و app.json و config plugins وأي مجلدات native خام (/ios و /android). وتتجاهل تماماً التغييرات التي تقتصر على JS/TS.

• إذا قمت بتغيير React component: فإن الـ fingerprint يبقى كما هو.
• إذا قمت بتثبيت lucide-react-native (JS بحت): فإن الـ fingerprint يبقى كما هو.
• إذا قمت بتثبيت react-native-skia (native code): فإن الـ fingerprint يتغير.

يصبح هذا الـ hash الحتمي الوحيد هو الـ runtimeVersion الخاص بك. من خلال ضبط الـ runtime version على الـ fingerprint hash لبيئتك الـ native، فإنك تضمن أن تحديث EAS Update سيستهدف فقط ويتم تنزيله بواسطة الـ native binaries التي تشترك في نفس القدرات الـ native تماماً.

دليل التنفيذ خطوة بخطوة

دعنا نبني CI/CD pipeline مؤتماً يستخدم Expo Fingerprint لتحديد ما إذا كنا سنقوم بإرسال EAS Update (تغيير JS آمن) أو تحفيز EAS Build جديد (تم اكتشاف native change).

1. إعداد Expo لاستخدام Fingerprint Runtime Versions

أولاً، قم بتثبيت أداة الـ CLI في مشروعك:

npx expo install @expo/fingerprint

بعد ذلك، نحتاج إلى توجيه Expo لاستخدام الـ fingerprint كـ runtime version الخاص بنا. قم بتحديث إعدادات app.json لاستخدام سياسة الـ fingerprint الديناميكية:

{
  "expo": {
    "runtimeVersion": {
      "policy": "fingerprint"
    }
  }
}

في الكواليس، عندما تقوم بتشغيل eas build أو eas update، سيقوم EAS تلقائياً بتوليد الـ fingerprint hash لمساحة العمل المحلية (local workspace) الخاصة بك ودمجه في الـ build configurations الخاصة بك.

2. صياغة الـ CI/CD Pipeline المضاد للرصاص

الآن، دعنا نصمم GitHub Actions workflow. هدفنا بسيط:

1. عند كل push إلى فرع main، قم بحساب الـ native fingerprint للـ commit الحالي.
2. جلب الـ fingerprint للإصدار الإنتاجي (production release) الحالي.
3. إذا تطابقا: ادفع تحديث OTA عبر eas update فوراً.
4. إذا اختلفا: قم بتحفيز بناء native جديد عبر eas build وإرساله إلى المتاجر، لأن الـ native dependencies قد تغيرت.

إليك سكربت جاهز للإنتاج (scripts/check-native-diff.js) للتعامل برمجياً مع المقارنة باستخدام الـ API الخاص بـ @expo/fingerprint:

const { createFingerprintAsync } = require('@expo/fingerprint');
const { execSync } = require('child_process');
const fs = require('fs');

async function run() {
  console.log('Calculating current project fingerprint...');
  const currentFingerprint = await createFingerprintAsync(process.cwd());
  const currentHash = currentFingerprint.hash;
  console.log(`Current Fingerprint: ${currentHash}`);

  // In a real pipeline, you would fetch the remote fingerprint of your production branch via EAS API.
  // For this demonstration, we query the latest deployed update metadata on EAS.
  try {
    const easMetadataRaw = execSync(
      'npx eas-cli update:view --json --non-interactive --channel production',
      { encoding: 'utf-8' }
    );
    const metadata = JSON.parse(easMetadataRaw);
    const latestDeployedRuntime = metadata[0]?.runtimeVersion;

    console.log(`Latest Deployed Runtime Version on EAS: ${latestDeployedRuntime}`);

    if (currentHash === latestDeployedRuntime) {
      console.log('SUCCESS: No native changes detected. Safe to release via OTA Update.');
      process.exit(0); // Exit code 0 signals safe for EAS Update
    } else {
      console.log('WARNING: Native fingerprint mismatch detected. Native build required.');
      process.exit(1); // Exit code 1 signals native rebuild required
    }
  } catch (error) {
    console.error('Failed to compare fingerprints. Defaulting to safe native build route.', error);
    process.exit(1);
  }
}

run();

3. ربط كل شيء في GitHub Actions

الآن نكتب ملف الـ workflow ‏(.github/workflows/deploy.yml) لتنظيم مصفوفة القرار هذه:

name: Deploy Pipeline

on:
  push:
    branches:
      - main

jobs:
  evaluate_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Setup EAS CLI
        uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}

      - name: Check Native Fingerprint Diff
        id: fingerprint_check
        continue-on-error: true
        run: node scripts/check-native-diff.js

      - name: Deploy OTA Update (Safe Path)
        if: steps.fingerprint_check.outcome == 'success'
        run: |
          echo "No native changes detected. Triggering EAS Update..."
          npx eas-cli update --branch production --message "Automated OTA release"

      - name: Trigger Store Builds (Native Path)
        if: steps.fingerprint_check.outcome == 'failure'
        run: |
          echo "Native changes detected. Triggering App Store & Play Store builds..."
          npx eas-cli build --platform all --profile production --auto-submit --non-interactive

الطفرات المعمارية التي شهدناها

لقد ألغى تطبيق هذه البنية الهيكلية العديد من نقاط الألم التي كنا نفترض أنها مجرد "جزء لا يتجزأ من تطوير React Native":

1. ترقية الـ Dependencies بمبدأ Zero-Trust

قبل Fingerprint، كان المطورون مرعوبين من تحديث الحزم في الـ PRs الصغيرة. الآن، يمكن للمطور ترقية الـ package.json بكل ثقة. إذا قام عن طريق الخطأ بسحب native dependency، فإن الـ CI pipeline سيكتشف ذلك تلقائياً، ويحظر مسار الـ OTA، ويقوم بجدولة بناء كامل للـ native binary. لا حاجة لأي إشراف بشري.

2. عزلة الـ Monorepo

إذا كنت تعمل في monorepo، فأنت تعلم أن التغييرات في أدوات مساحة العمل المشتركة غالباً ما تؤدي إلى false positives في الـ pipelines البسيطة المعتمدة على git-diff. يتميز Expo Fingerprint بالذكاء؛ فهو يقوم فقط بعمل hash للملفات التي تؤثر فعلياً على خطوة الـ bundling والـ compilation في React Native، مما يعني أن تحديثات الـ UI packages أو الأدوات في أجزاء أخرى من الـ monorepo لن تحفز بناء native غير ضروري.

3. تخصيص إعدادات الـ Fingerprint الخاصة بك

في بعض الأحيان، قد ترغب في تجاهل ملفات معينة يتتبعها @expo/fingerprint بشكل افتراضي، أو تتبع شيء مخصص بشكل صريح (مثل ملف إعدادات SDK native خام). يمكنك بسهولة ضبط هذا بدقة عن طريق إنشاء ملف fingerprint.config.js:

/** @type {import('@expo/fingerprint').Config} */
module.exports = {
  // Ignore internal development files that don't affect release binaries
  ignorePaths: [
    '**/android/build/**',
    '**/ios/build/**',
    '**/.github/**'
  ]
};

القاعدة الذهبية لـ Expo Pipelines الحديثة

إذا خرجت بشيء واحد من هذا المقال، فليكن هذا: لا تترك إدارة مطابقة إصدارات الـ native للبشر.

لدينا compilers للتحقق من الـ type safety؛ ويجب أن يكون لدينا أدوات native hashing للتحقق من الـ runtime safety. من خلال اعتماد @expo/fingerprint وجعله يقود برمجياً استراتيجية نشر EAS الخاصة بك، فإنك تستعيد راحة بالك—وأمسيات أيام الخميس الخاصة بك.