Flutter / واجهات شاملة وأدلة الأهداف / الدرس 18
إعداد الإصدار وقابلية الملاحظة
اجعل اختيار البيئة صريحا واحفظ سياق الرموز التشخيصية ولا تنشر ادعاءات توافق دون دليل.
في هذه الصفحة
أهداف الدرس
- الإصدار قرار إعداد ومصدر
- تحقق من الإعداد العام بدلا من إخفائه
- التقط الأخطاء عند حدها غير المتزامن المناسب
الإصدار قرار إعداد ومصدر
قد يختلف سلوك المصدر نفسه بحسب نمط البناء ونقطة الدخول وقيم وقت الترجمة والمتغيرات الأصلية والأصول والتوقيع. سجّل هذه المدخلات مع قفل الاعتماديات وقيود SDK المراجعة لربط الإصدار بأثره الفعلي. لا يثبت تشغيل debug محلي أن إصدارا موقعا يُثبّت أو أن كل متغير يستخدم الوجهة المقصودة. ميّز هويات التطوير والإنتاج في سير المشروع المصرح به. تصف الأمثلة عقود الإعداد فقط؛ ولا تبني أو توقع أو ترفع أو تتصل بخدمة نشر.
تحقق من الإعداد العام بدلا من إخفائه
قد تختار قيم بيئة وقت الترجمة تسمية عامة أو سياسة وجهة، لكنها إعداد عميل مضمّن وليست مخزن أسرار. يقبل المقتطف الأول تسميتين مصطنعتين ويفشل مبكرا عند قيمة غير مدعومة. الفشل الواضح أكثر أمانا من إرسال الحركة بصمت إلى نظام إنتاج افتراضي. ينبغي لتطبيق الإنتاج فحص مخطط الوجهة ومضيفيها المسموحين عند الحد المناسب ومطابقة المتغير الأصلي لهوية التطبيق المتوقعة. وأبق الأسرار ذات الصلاحية خارج الآثار الموزعة مهما بدت أسماء متغيراتها داخلية.
const environment = String.fromEnvironment('APP_ENV', defaultValue: 'lab');
String checkedEnvironment() {
if (environment != 'lab' && environment != 'staging') {
throw StateError('Unsupported APP_ENV');
}
return environment;
}
void main() { print(checkedEnvironment()); }
With no compile-time APP_ENV supplied, the program prints lab.
لا يجري اتصال بأي وجهة. وتحتاج قيم البيئة المقدمة عبر بيئة البناء الفعلية إلى تحقق مستقل للمتغيرات.
التقط الأخطاء عند حدها غير المتزامن المناسب
قد تسلك أخطاء إطار Flutter والأخطاء غير المتزامنة خارج ردوده مسارات إبلاغ مختلفة. يوضح المقتطف الثاني إعداد FlutterError.onError وPlatformDispatcher.instance.onError مفاهيميا. احفظ العرض التشخيصي المعتاد أو المراجع للإطار ومرّر سجلات منقحة عبر مهايئ الإبلاغ. لا ترم خطأ تكراريا من المعالج ولا ترسل حمولات خاصة كاملة كسياق. تعني true من معالج dispatcher أن الخطأ عولج بحسب واجهته؛ فاختر السياسة عمدا كي لا تُبتلع الأخطاء بلا سجل مفيد. لا يجهز المقتطف حساب قياس خارجي.
import 'dart:ui';
import 'package:flutter/foundation.dart';
void installErrorHandlers(void Function(Object, StackTrace?) record) {
FlutterError.onError = (details) {
FlutterError.presentError(details);
record(details.exception, details.stack);
};
PlatformDispatcher.instance.onError = (error, stack) {
record(error, stack);
return true;
};
}
Configured callbacks forward framework and dispatcher errors to the supplied local adapter.
يجب أن ينفذ المهايئ تنقيحا ومعالجة فشل مراجعين. لم يُرسل حدث قياس ولم يُثبت معالج تشغيل هنا.
احفظ الرموز وهوية الإصدار قابلين للاستعمال
يصعب تفسير سجل تعطل دون هوية الأثر المقابلة. احفظ إصدار التطبيق ومعرّف البناء والهدف ومعلومات الرموز بحسب سير المنصة الموثق. وعند استخدام التشويش أو فصل معلومات التشخيص، احتفظ بآثار الرموز المطابقة بسياسة حفظ مضبوطة؛ فقد يضلل ملف غير مطابق التشخيص. سجّل فئات عمليات آمنة وسياقا عاما يكفي لإعادة الإنتاج. ولا تجمع مزيدا من محتوى المستخدم لمجرد أن مكتبة التسجيل تسمح به. ينبغي للملاحظة خدمة سؤال تشخيص محدد مع دورة حياة بيانات مراجعة.
حدّد فحوص الإصدار بحسب الهدف والميزة
تسمي مصفوفة إصدار مفيدة متغيرات الأهداف المدعومة والتدفقات الأساسية التي تعبر حدودها: البدء والتنقل والنماذج المترجمة والتعافي دون اتصال والأذونات والقدرات الأصلية. أبق الاختبارات النقية واختبارات العناصر سريعة وأضف تكامل الهدف عندما تعتمد الميزة على الأصل أو المتصفح. راجع الإتاحة والنص الكبير كمتطلبات إصدار عادية. لا تستنتج دعم كل الأهداف من محاكي واحد أو كل المتصفحات من بيئة واحدة. القيد الموثق أنفع من ادعاء غامض بأن المشروع جاهز للإنتاج.
انشر بيان تحقق يمكن الاعتماد عليه
ينبغي لبيان التحقق تسمية التغيير وما نُفذ والإصدارات والهدف والحدود المهمة غير المختبرة. في هذه الدورة تفحص بنية JSON والمحاذاة بين اللغتين بصورة مستقلة، بينما تبقى أمثلة Dart وعناصر Flutter والقنوات الأصلية والأجهزة وبناء الإصدار غير منفذة. أرفق في مشروعك نتائج فعلية ومصدر الأثر بدلا من نسخ التوقعات كدليل. وعند فشل إصدار احفظ أول خطأ ذي صلة والمتغير الدقيق قبل تنظيف واسع أو تحديث اعتماد قد يمحو إعادة الإنتاج الأصلية.
الأخطاء الشائعة وإصلاحها
يستخدم البناء بيئة خاطئة بصمت
- لماذا يحدث؟
- أخفى بديل الإعداد قيمة متغير غائبة أو غير مدعومة.
- كيف تصلحه؟
- تحقق من القيم المسموحة وطابق هوية متغير Dart والأصل.
- كيف تتجنب تكراره؟
- افحص الإعداد العام لكل أثر مصرح به.
لا يمكن تفسير رموز التعطل بثبات
- لماذا يحدث؟
- لم تُحفظ الرموز المطابقة وهوية الأثر.
- كيف تصلحه؟
- استخدم رموز الإصدار نفسه وسير المنصة الموثق.
- كيف تتجنب تكراره؟
- احفظ المصدر ذا الإصدار مع آثار رموز مضبوطة.
يخفي معالج الخطأ الفشل دون سجل
- لماذا يحدث؟
- يدعي المعالج المعالجة ومسار الإبلاغ غير فعال أو تكراري.
- كيف تصلحه؟
- اجعل المعالجة محلية ومتينة بتنقيح وتشخيص بديل مراجعين.
- كيف تتجنب تكراره؟
- اختبر المهايئ بأخطاء مصطنعة قبل التكامل.
اختبر فهمك
1. هل يمكن لـ APP_ENV حمل مفتاح خدمة ذي صلاحيات بأمان لأنه مضمّن عند الترجمة؟
اعرض الحل المشروح
لا. يبقى إعداد العميل المترجم جزءا من أثر موزع وليس حد أسرار. أبق العمليات المميزة خلف خدمة خادم مفوضة وعامل إعداد وقت البناء كبيانات اختيار عامة ذات تحقق صريح.
2. ماذا يقول تقرير صادق بعد فحص JSON والترجمة فقط؟
اعرض الحل المشروح
يذكر اكتمال فحوص المحتوى والمخطط والمحاذاة بين اللغتين، ويترك ترجمة SDK وتنفيذ العناصر والتكامل الأصلي وسلوك إصدار الجهاز غير متحققة صراحة. تشرح النتائج المتوقعة عقدا لكنها لا تستبدل دليل تنفيذ مسجلا.
أهم ما تعلمته
- الإصدار قرار إعداد ومصدر
- انشر بيان تحقق يمكن الاعتماد عليه