Rust / المتوسط / الدرس 10

الوحدات والحزم والتوثيق

نظّم حزمة Rust حول ظهور مضبوط واعتماديات صريحة وأمثلة يمكن فحصها ضمن العقد العام.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-25

في هذه الصفحة

أهداف الدرس

تمييز مسارات الوحدات وحدود crate وأهداف الحزمة.
استخدام الخصوصية لحفظ الخصائص خلف المنشئات.
توثيق الملكية والأخطاء وافتراضات المترجم المدعوم.

الوحدة نطاق أسماء وحد خصوصية

تنظم الوحدات عناصر داخل crate وليست تلقائيًا اعتماديات أو أهداف ترجمة منفصلة. قد يعرّف بيان الحزمة مكتبة وبرامج، وتشير الاعتماديات إلى حزم أخرى بأسماء وحداتها. تعلن mod وحدة وتجلب use مسارًا دون تغيير الملكية أو الظهور. تحدد crate وself وsuper علاقات المسارات. افهم الشجرة قبل نقل الملفات؛ فلا يجعل المجلد وحده العناصر عامة أو يختار هدفًا تنفيذيًا.

إظهار العمليات بدل التمثيل

العناصر خاصة افتراضيًا وتكشف pub العنصر وفق ظهور مساره المحيط. لا تجعل البنية العامة حقولها عامة تلقائيًا. يخفي المثال Counter.value داخل الوحدة ويعرض الإنشاء والمراقبة، فلا يسنِد المستدعي الخارجي الحقل مباشرة. يتيح ذلك إضافة الفحص لاحقًا دون تغيير كل مستدعٍ. لا تستبدل الخصوصية الاختبارات لكنها تحدّ من تجاوز الخصائص. لا توسع الظهور أكثر من حاجة المستهلك.

rust نوع عام بتمثيل خاص

mod counters {
    pub struct Counter { value: u32 }
    impl Counter {
        pub fn new(value: u32) -> Self { Self { value } }
        pub fn value(&self) -> u32 { self.value }
    }
}
fn main() {
    let counter = counters::Counter::new(5);
    println!("{}", counter.value());
}

الناتج المتوقع

ينشئ المستدعي القيمة ويفحصها بأساليب عامة، ولا يصل إلى الحقل الخاص إلا داخل وحدته.

وضوح الأسماء المستوردة

تقصّر use المسار وقد تعيد تسمية عنصر لتجنب اللبس. تعيد pub use تصدير واجهة كي لا يعرف المستهلك ترتيب الوحدات الداخلي. يشكل المسار المعاد التزام توافق، فلا تكسره لمجرد نقل التنفيذ. يستورد المثال دالة من وحدة داخلية ويستدعيها مباشرة. تبقي الوحدات الداخلية المثال مكتملًا، وتستطيع المشاريع فصلها وفق قواعد الملفات. لا تنسخ نص التنفيذ إلى أهداف متعددة بدل تصميم الحزمة.

rust استيراد عملية عامة بمسار

mod arithmetic {
    pub fn batches(count: u32, width: u32) -> Option<u32> {
        if width == 0 { return None; }
        Some(count / width + u32::from(count % width != 0))
    }
}
use arithmetic::batches;
fn main() { println!("{:?}", batches(9, 4)); }

الناتج المتوقع

Some(3)

تحتاج تسعة عناصر ثلاث دفعات بعرض أربعة، وترفض الدالة الصفر قبل القسمة.

الاعتماديات خيارات شيفرة تنفذ ضمن البناء

سجّل edition وrust-version وميّز اعتماديات التشغيل والتطوير والبناء. قد تنفذ اعتمادية بناء شيفرة أثناء الترجمة عبر نص بناء؛ فإضافة حزمة تتجاوز استيراد اسم. لا تتطلب الدروس حزمًا خارجية. احفظ الحل بإدارة Cargo.lock وفق المشروع واستخدم --offline إذا توافرت الأدوات والمخازن. تختار الميزات قدرات اختيارية وقد تغير الشبكة؛ فوثّق التركيبات المهمة بدل اعتبار نجاح محلي ممثلًا لكل المستهلكين.

التوثيق يشرح الالتزامات

يمكن أن تتضمن تعليقات التوثيق أمثلة يفحصها cargo test كاختبارات توثيق. اشرح معنى المدخلات وملكية القيم واستعارتها واحتمال panic ومعنى الأخطاء. تحتاج واجهات unsafe قسم Safety يصف التزامات المستدعي. لا تعرض مقطعًا تابعًا كبرنامج مستقل. أظهر مسار الاستيراد وافتراض الإصدار كي لا يعتمد المثال على تفاصيل خاصة. يدل فشل المثال على انجراف الواجهة أو شرحها لا إزعاج تنسيق فقط.

الأخطاء الشائعة وإصلاحها

تعذر الوصول خارجيًا إلى حقل بنية عامة.

لماذا يحدث؟: يبقى الحقل خاصًا ما لم يُكشف صراحة.
كيف تصلحه؟: استخدم أسلوبًا عامًا مناسبًا أو ظهورًا مقصودًا للحقل.
كيف تتجنب تكراره؟: أظهر عمليات المجال قبل الحقول الخام.

نقل ملف يكسر مسار استيراد.

لماذا يحدث؟: اختلف ترتيب الملفات عن شجرة الوحدات المعلنة.
كيف تصلحه؟: حدّث تصريحات الوحدات واحفظ إعادة التصدير المقصودة.
كيف تتجنب تكراره؟: اختبر المسارات العامة من مستهلك منفصل.

بناء دون اتصال يحتاج تنزيلًا.

لماذا يحدث؟: ليست اعتمادية أو أدوات مختارة مخزنة.
كيف تصلحه؟: جهّز الاعتماديات والأدوات المعتمدة قبل التحقق دون اتصال.
كيف تتجنب تكراره؟: أظهر متطلبات الاعتماديات والأدوات.

اختبر فهمك

1. يحتاج مستهلك قراءة Counter.value دون تجاوز الفحص. اختر حقلًا عامًا أو قارئًا وفسّر تغييرًا مستقبليًا.

اعرض الحل المشروح

أبقِ الحقل خاصًا واعرض value(&self) -> u32. يمكن لاحقًا تغيير التمثيل المفحوص مع حفظ العقد. يسمح الحقل العام القابل للتعديل بتجاوز الإنشاء وقواعد التغيير. اختبر السلوك العام بدل تخطيط الحقل الخاص.

2. حوّل batches إلى عملية مكتبية موثقة. سمّ ثلاث حالات للمثال والتزامًا يذكره الشرح.