مهاجرت به ایمنی تهی

در این صفحه نحوه و زمان مهاجرت کد خود به ایمنی تهی توضیح داده شده است. در اینجا مراحل اساسی برای مهاجرت هر بسته ای که در اختیار دارید آورده شده است:

1. منتظر بسته هایی باشید که برای مهاجرت به آنها وابسته هستید.
2. کد بسته خود را ترجیحاً با استفاده از ابزار مهاجرت تعاملی مهاجرت کنید.
3. کد بسته خود را به صورت آماری تجزیه و تحلیل کنید.
4. تست کنید تا اطمینان حاصل کنید که تغییرات شما کار می کند.
5. اگر بسته در حال حاضر در pub. dev است ، نسخه ایمن Null-Safe را به عنوان نسخه prerelease منتشر کنید.

نکته: اگر برنامه یا کتابخانه شما بزرگ است ، مهاجرت به تدریج ایمنی تهی را برای پروژه های بزرگ دارت بررسی کنید.

مهاجرت یک برنامه از نظر فنی همانند مهاجرت یک بسته است. قبل از مهاجرت یک برنامه ، اطمینان حاصل کنید که تمام وابستگی های شما آماده است.

برای نگاهی غیررسمی به تجربه استفاده از ابزار مهاجرت ، این فیلم را تماشا کنید:

1. صبر کنید تا مهاجرت کنید

ما اکیداً توصیه می کنیم که کد مهاجرت را به ترتیب انجام دهد و برگهای نمودار وابستگی ابتدا مهاجرت می کنند. به عنوان مثال ، اگر بسته C به بسته B بستگی دارد ، که به بسته A بستگی دارد ، ابتدا باید به ایمنی تهی منتقل شود ، سپس B ، سپس C.

اگرچه می توانید قبل از وابستگی های خود از امنیت تهی مهاجرت کنید ، اما ممکن است هنگام مهاجرت وابستگی های خود ، کد خود را تغییر دهید. به عنوان مثال ، اگر پیش بینی می کنید که یک تابع یک پارامتر قابل برگشت را در نظر بگیرد ، اما بسته آن را غیر قابل تهی مهاجرت می کند ، پس از عبور از یک آرگومان قابل برگشت به یک خطای کامپایل تبدیل می شود.

شما می توانید بسته های خود را قبل از بسته بندی هایی که به آن وابسته هستند ، مهاجرت کنید. بسته ایمن تهی شما توسط بسته ها و برنامه هایی که هنوز از ایمنی تهی استفاده نمی کنند ، قابل استفاده است ، تا زمانی که از DART 2. 12 یا بالاتر استفاده کنند. به عنوان مثال ، کتابخانه های اصلی DART و Flutter Null ایمن هستند ، و هنوز هم توسط برنامه هایی که به ایمنی تهی مهاجرت نکرده اند ، قابل استفاده هستند.

این بخش به شما می گوید چگونه با کمک فرمان DART Pub Opdated در حالت ایمنی تهی ، وابستگی های بسته خود را بررسی و به روز کنید. دستورالعمل ها فرض می کنند که کد شما تحت کنترل منبع است ، به طوری که می توانید به راحتی هرگونه تغییر را خنثیسازی کنید.

به آخرین نسخه پایدار دارت بروید

به آخرین نسخه پایدار یا DART SDK یا Flutter SDK بروید.

بررسی کنید که DART 2. 12 یا بالاتر دارید:

وضعیت وابستگی را بررسی کنید

با استفاده از دستور زیر وضعیت مهاجرت وابستگی های بسته خود را دریافت کنید:

اگر خروجی می گوید که همه بسته ها از ایمنی تهی پشتیبانی می کنند ، می توانید مهاجرت را شروع کنید. در غیر این صورت ، در صورت وجود از ستون قابل حل برای یافتن نسخه های ایمن تهی استفاده کنید.

چرا همه وابستگی ها برای پشتیبانی از ایمنی تهی نیاز دارند؟هنگامی که همه وابستگی های مستقیم یک برنامه از ایمنی تهی پشتیبانی می کنند ، می توانید برنامه را با ایمنی تهی صدا اجرا کنید. هنگامی که همه وابستگی های DEV از ایمنی تهی پشتیبانی می کنند ، می توانید تست ها را با ایمنی تهی صدا اجرا کنید. شما همچنین ممکن است به دلایل دیگر مانند تولید کد ، به وابستگی های انحرافی تهی نیاز داشته باشید.

در اینجا نمونه ای از خروجی برای یک بسته ساده آورده شده است. نسخه Green Checkmarked برای هر بسته از ایمنی تهی پشتیبانی می کند:

خروجی نشان می دهد که همه وابستگی های این بسته دارای مقدماتی قابل حل هستند که از ایمنی تهی پشتیبانی می کنند.

اگر وابستگی های بسته شما هنوز از امنیت تهی پشتیبانی نمی کند ، ما شما را ترغیب می کنیم تا به صاحب بسته دسترسی پیدا کنید. می توانید اطلاعات تماس را در صفحه بسته در pub. dev پیدا کنید.

وابستگی ها را به روز کنید

قبل از مهاجرت کد بسته خود ، وابستگی های آن را به نسخه های ایمن تهی به روز کنید:

برای ارتقاء به آخرین نسخه هایی که از ایمنی تهی استفاده می کنند ، به روزرسانی Dart Pub ارتقاء دهید. توجه: این دستور پرونده pubspec. yaml شما را تغییر می دهد.

اجرای میخانه دارت را دریافت کنید.

2. مهاجرت کنید

بیشتر تغییراتی که کد شما نیاز به امنیت تهی دارد به راحتی قابل پیش بینی است. به عنوان مثال ، اگر یک متغیر می تواند تهی باشد ، نوع آن به A نیاز دارد؟پسوند. اگر یک پارامتر نامگذاری شده نباید باطل باشد ، مورد نیاز آن را علامت گذاری کنید یا مقدار پیش فرض آن را به آن بدهید.

شما دو گزینه برای مهاجرت دارید:

• از ابزار مهاجرت استفاده کنید ، که می تواند بیشترین تغییرات را به راحتی قابل پیش بینی برای شما ایجاد کند.

نکته: برای کمک بیشتر در هنگام مهاجرت ، سؤالات متداول ایمنی را بررسی کنید.

با استفاده از ابزار مهاجرت

ابزار مهاجرت بسته ای از کد DART NULL-UNSAFE را می گیرد و آن را به ایمنی تهی تبدیل می کند. می توانید با افزودن نشانگرهای اشاره ای به کد دارت خود ، تبدیل ابزار را راهنمایی کنید.

قبل از شروع ابزار ، مطمئن شوید که آماده هستید:

• از آخرین نسخه پایدار DART SDK استفاده کنید.
• برای اطمینان از اینکه همه وابستگی ها ایمن و به روز هستند ، از Dart Pub Opdated-Mode = Null-Safety استفاده کنید.

ابزار مهاجرت را با اجرای دستور DART MINGRATE در دایرکتوری که شامل پرونده pubspec. yaml بسته است ، شروع کنید:

اگر بسته شما برای مهاجرت آماده است ، ابزار خطی مانند موارد زیر را تولید می کند:

برای دیدن یک رابط کاربری تعاملی که در آن می توانید روند مهاجرت را راهنمایی کنید ، از آن URL در یک مرورگر Chrome بازدید کنید:

برای هر حاشیه نویسی متغیر و نوع ، می توانید ببینید که ابزاری از چه تهویه ای است. به عنوان مثال ، در تصویر قبلی ، این ابزار نشان می دهد که لیست INTS (قبلاً لیستی از int) در خط 1 قابل تهی است ، و بنابراین باید لیستی از int باشد؟بشر

درک نتایج مهاجرت

برای دیدن دلایل هر تغییر (یا عدم تغییر) ، روی شماره خط آن در صفحه ویرایش های پیشنهادی کلیک کنید. دلایل موجود در صفحه جزئیات ویرایش.

به عنوان مثال ، کد زیر را از قبل از ایمنی تهی در نظر بگیرید:

مهاجرت پیش فرض هنگامی که این کد خارج از یک تابع است (در یک تابع متفاوت است) سازگار با عقب است اما ایده آل نیست:

با کلیک بر روی پیوند خط 3 ، می توانید دلایل ابزار مهاجرت را برای افزودن مشاهده کنید! بشراز آنجا که می دانید صفر نمی تواند تهی باشد ، می توانید نتیجه مهاجرت را بهبود بخشید.

بهبود نتایج مهاجرت

هنگامی که تجزیه و تحلیل از ناپایداری اشتباه ناشی می شود ، می توانید ویرایش های پیشنهادی آن را با درج نشانگرهای اشاره موقت نادیده بگیرید:

در صفحه جزئیات ویرایش ابزار مهاجرت ، می توانید نشانگرهای اشاره ای را با استفاده از دکمه های افزودنی /*؟* / اشاره و اضافه کردن /*!* / / hint وارد کنید.

این دکمه ها بلافاصله نظرات خود را به پرونده شما اضافه می کنند ، و هیچ خنثی کننده ای وجود ندارد. اگر هیچ اشاره ای را که ابزار درج شده است نمی خواهید ، می توانید از ویرایشگر کد معمول خود برای حذف آن استفاده کنید.

می توانید از ویرایشگر برای اضافه کردن نشانگرهای اشاره استفاده کنید ، حتی در حالی که ابزار هنوز در حال اجرا است. از آنجا که کد شما هنوز ایمنی تهی را انتخاب نکرده است ، شما نمی توانید از ویژگی های جدید ایمنی تهی استفاده کنید. با این حال ، می توانید تغییراتی مانند اصلاح مجدد ایجاد کنید که به ویژگی های ایمنی تهی بستگی ندارد.

هنگامی که ویرایش کد خود را به پایان رسانده اید ، روی منابع از منابع کلیک کنید تا تغییرات خود را انتخاب کنید.

جدول زیر نشانگرهای اشاره ای را نشان می دهد که می توانید برای تغییر ویرایش های پیشنهادی ابزار مهاجرت استفاده کنید.

یک اشاره واحد می تواند جلوه های موج دار دیگری در جای دیگر کد داشته باشد. در مثال از قبل ، اضافه کردن دستی A /*!* / نشانگر که در آن صفر به مقدار خود اختصاص داده شده است (در خط 2) باعث می شود ابزار مهاجرت نوع صفر را به جای int استنباط کند؟بشراین تغییر نوع می تواند بر کدهایی که مستقیم یا غیرمستقیم از صفر استفاده می کند ، تأثیر بگذارد.

با اشاره فوق ، ابزار مهاجرت ویرایش های پیشنهادی خود را تغییر می دهد ، همانطور که قطعه های کد زیر نشان می دهد. خط 3 دیگر A ندارد! بعد از صفر ، و در خط 4 صفر استنباط شده است که لیستی از int است ، نه int؟بشر

انتخاب پرونده ها

اگرچه توصیه می کنیم همه به یکباره مهاجرت کنید ، اما گاهی اوقات عملی نیست ، به خصوص در یک برنامه یا بسته بزرگ. برای امتناع از یک فایل یا دایرکتوری ، روی کادر سبز آن کلیک کنید. بعداً ، هنگامی که تغییرات را اعمال می کنید ، هر پرونده انتخاب شده به جز نظر نسخه 2. 9 بدون تغییر خواهد بود.

برای کسب اطلاعات بیشتر در مورد مهاجرت افزایشی ، به ایمنی تهی ناخوشایند مراجعه کنید.

اعمال تغییرات

وقتی همه تغییراتی را که ابزار مهاجرت پیشنهاد می کند دوست دارید ، روی اعمال مهاجرت کلیک کنید. ابزار مهاجرت نشانگرهای اشاره را حذف می کند و کد مهاجرت را ذخیره می کند. این ابزار همچنین حداقل محدودیت SDK را در PubSpec به روز می کند ، که بسته را به ایمنی تهی می رساند.

مرحله بعدی تجزیه و تحلیل کد شما است. اگر معتبر است ، کد خود را آزمایش کنید. سپس ، اگر کد خود را در pub. dev منتشر کرده اید ، یک پیش نمایش ناموجود را منتشر کنید.

مهاجرت با دست

اگر ترجیح می دهید از ابزار مهاجرت استفاده نکنید ، می توانید به صورت دستی مهاجرت کنید.

ما توصیه می کنیم که ابتدا کتابخانه های برگ را مهاجرت کنید - لیبرهایی که پرونده های دیگر را از بسته وارد نمی کنند. سپس کتابخانه هایی را که مستقیماً به کتابخانه های برگ وابسته هستند ، مهاجرت کنید. با مهاجرت کتابخانه هایی که بیشترین وابستگی های داخل بسته را دارند ، پایان دهید.

به عنوان مثال ، بگویید که شما یک پرونده lib/src/upil. dart دارید که بسته های دیگر (تهی) و کتابخانه های اصلی را وارد می کند ، اما این دستورالعمل های وارداتی ندارد. در ابتدا مهاجرت UTIL. DART را در نظر بگیرید ، و سپس پرونده های ساده ای را که فقط به UTIL. DART بستگی دارد ، مهاجرت کنید. اگر هر کتابخانه واردات چرخه ای (به عنوان مثال ، واردات B را وارد می کند که C را وارد می کند ، و C واردات را وارد می کند) ، مهاجرت آن کتابخانه ها را در نظر بگیرید.

برای مهاجرت یک بسته با دست ، این مراحل را دنبال کنید:

پرونده pubspec. yaml بسته را ویرایش کنید ، حداقل محدودیت SDK را حداقل در 2. 12. 0 تنظیم کنید:

Dark Dart Pub با محدودیت SDK پایین تر از حداقل 2. 12. 0 نسخه زبان پیش فرض هر کتابخانه را در بسته بندی به حداقل 2. 12 تنظیم می کند و همه آنها را به ایمنی تهی می رساند.

بسته را در IDE خود باز کنید. شما به احتمال زیاد خطاهای تجزیه و تحلیل زیادی را مشاهده خواهید کرد. خوب است

با استفاده از آنالایزر برای شناسایی خطاهای استاتیک ، کد هر پرونده دارت را مهاجرت کنید. خطاهای استاتیک را با اضافه کردن از بین ببرید؟،، مورد نیاز ، و دیر ، در صورت لزوم.

برای کمک بیشتر در مورد کد مهاجرت با دست ، ایمنی تهی ناخوشایند را مشاهده کنید.

3. تجزیه و تحلیل

بسته های خود را به روز کنید (با استفاده از Dart Pub در IDE یا خط فرمان خود را دریافت کنید). سپس از IDE یا خط فرمان خود برای انجام تجزیه و تحلیل استاتیک روی کد خود استفاده کنید:

4. آزمون

اگر کد شما از تجزیه و تحلیل عبور می کند ، تست ها را اجرا کنید:

ممکن است لازم باشد تست هایی را که انتظار مقادیر تهی دارند ، به روز کنید.

اگر نیاز به ایجاد تغییرات بزرگ در کد خود دارید ، ممکن است نیاز به تغییر مجدد آن داشته باشید. در این صورت ، قبل از استفاده مجدد از ابزار مهاجرت ، تغییر کد خود را برگردانید.

5. انتشار

ما شما را تشویق می کنیم که بسته هایی را که احتمالاً به عنوان پیش نمایشی - به محض مهاجرت منتشر می کنید ، منتشر کنید:

نسخه بسته را به روز کنید

نسخه بسته را به روز کنید تا نشان دهنده تغییر شکستن باشد:

اگر بسته شما در حال حاضر در 1. 0. 0 یا بیشتر است ، نسخه اصلی را افزایش دهید. به عنوان مثال ، اگر نسخه قبلی 2. 3. 2 باشد ، نسخه جدید 3. 0. 0 است.

اگر بسته شما هنوز به 1. 0. 0 نرسیده است ، نسخه جزئی را افزایش داده یا نسخه را به 1. 0. 0 به روز کنید. به عنوان مثال ، اگر نسخه قبلی 0. 3. 2 باشد ، نسخه جدید یا 0. 4. 0 یا 1. 0. 0 است.

pubspec خود را بررسی کنید

قبل از انتشار یک نسخه ایمنی تهی پایدار از یک بسته ، ما اکیداً توصیه می کنیم این قوانین PUBSPEC را دنبال کنید:

• محدودیت SDK پایین DART را بر روی کمترین نسخه پایدار که در برابر آن آزمایش کرده اید تنظیم کنید (حداقل 2. 12. 0).
• از نسخه های پایدار از همه وابستگی های مستقیم استفاده کنید.

به ایمنی تهی خوش آمدید

اگر این کار را تا کنون انجام داده اید ، باید یک بسته دارت کاملاً مهاجرت و ایمن داشته باشید. اگر تمام بسته هایی که به آنها وابسته هستید نیز منتقل می شوند ، برنامه شما با توجه به خطاهای مرجع تهی صدا است.

از همه تیم دارت ، از اینکه کد خود را مهاجرت کردید متشکرم.

به جز آنچه در غیر این صورت ذکر شد ، این سایت تحت مجوز بین المللی Creative Commons Attribution 4. 0 مجوز دارد و نمونه های کد تحت مجوز 3 بند BSD مجوز دارند.