محتويات الدورة

بايثون / أنظمة قابلة للصيانة / الدرس 18

الحزم القابلة للصيانة والحدود الآمنة والواجهات

صمم واجهة عامة صغيرة مستقرة، وحزمها عن قصد، وتعامل مع البيانات الخارجية وتشغيل العمليات كحدود ثقة صريحة.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى
في هذه الصفحة

أهداف الدرس

  • الواجهة العامة وعد
  • الحفاظ على الثقة عبر الإصدارات

الواجهة العامة وعد

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

التحزيم يسجل حقائق البناء والمشروع

يمكن أن تصف pyproject.toml خلفية البناء والبيانات الوصفية وتوافق بايثون والاعتماديات وفق المعايير. يفصل تخطيط src الشفرة القابلة للاستيراد عن أدوات المستودع ويكشف الاستيراد العرضي منه. تختلف بيانات التوزيعة عن اسم حزمة الاستيراد. ابن أثرا محليا وثبته في بيئة نظيفة عند مراجعة إصدار واختبر الشفرة المثبتة؛ لا يكفي الاستيراد من المستودع لإثبات صحة التحزيم. قد يحتاج البناء اعتمادية موثوقة. تبقى الأمثلة قياسية ولا تثبت أو تنشر شيئا، فالنشر إجراء إصدار مستقل مأذون.

التحقق من حد بيانات ضيق

يتحقق المثال من سجل طلب محلل ويرفض الحقول الزائدة بدلا من قبول أخطاء الأسماء بصمت. يرفض type(quantity) is int القيم المنطقية عن قصد، لأن bool فرع من int لكن الكمية المنطقية لا معنى لها هنا. ينشئ المحلل نتيجة جديدة بدلا من حفظ قاموس المستدعي. تحتاج الحدود الفعلية أيضا إلى حجم وتفويض مناسبين. JSON تنسيق بيانات، بينما تنفذ eval تعبيرات وقد ينفذ تحميل pickle شفرة مصنوعة. لا تستخدم آليات تنفيذ لتفسير مدخل غير موثوق، ولا يغني التحليل الآمن عن التحقق المعنوي.

python التحقق من حد بيانات ضيق — مثال محلول
def parse_order(data):
    if not isinstance(data, dict) or set(data) != {"quantity"}:
        raise ValueError("expected quantity field only")
    quantity = data["quantity"]
    if type(quantity) is not int or quantity < 0:
        raise ValueError("quantity must be a nonnegative integer")
    return {"quantity": quantity}

print(parse_order({"quantity": 3}))
try:
    parse_order({"quantity": True})
except ValueError as error:
    print(error)
الناتج المتوقع
{'quantity': 3}
quantity must be a nonnegative integer

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

تمرير قيم الاستعلام وضبط التنفيذ

يفصل الاستعلام بنية SQL عن القيم باستخدام ربط معاملات المشغل. لا تركب المقاطع المقتبسة بالجمع أو f-strings. يستخدم المثال SQLite في الذاكرة واستعلاما ذا معامل لاسم يحوي فاصلة عليا. تعامل القيمة كبيانات، لكن الربط لا يمنح تفويضا ولا يحول أسماء الجداول العشوائية إلى معاملات. وللعمليات فضل برنامجا ثابتا وقائمة وسائط مع shell=False إلا لحد مبرر بعناية. لا تنفذ نص أوامر غير موثوق، وحد الزمن والمخرجات، وأبعد الأسرار عن الوسائط والسجلات.

python تمرير قيم الاستعلام وضبط التنفيذ — مثال محلول
import sqlite3

connection = sqlite3.connect(":memory:")
try:
    connection.execute("CREATE TABLE people (name TEXT NOT NULL)")
    connection.execute("INSERT INTO people (name) VALUES (?)", ("O'Neil",))
    row = connection.execute(
        "SELECT name FROM people WHERE name = ?", ("O'Neil",)
    ).fetchone()
    print(row[0])
finally:
    connection.close()
الناتج المتوقع
O'Neil

يربط الإدراج والبحث الاسم كقيمة، فلا تغير الفاصلة العليا صياغة SQL. توجد القاعدة في الذاكرة فقط وتغلق صراحة.

الحفاظ على الثقة عبر الإصدارات

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

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

اجتياز قيمة منطقية تحقق الكمية الصحيحة

لماذا يحدث؟
تقبل isinstance(value, int) النوع bool أيضا.
كيف تصلحه؟
استخدم نوعا مطابقا تماما عندما يمنع المجال المنطقية.
كيف تتجنب تكراره؟
اختبر True وFalse عند الحدود.

إفساد اسم يحوي فاصلة عليا لاستعلام SQL

لماذا يحدث؟
جُمعت القيم داخل صياغة SQL.
كيف تصلحه؟
اربط القيم بصياغة المعاملات المدعومة.
كيف تتجنب تكراره؟
ثبت بنية الاستعلام واختبر علامات الترقيم.

غياب وحدة مطلوبة من الحزمة المثبتة

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

اختبر فهمك

1. ماذا يتضمن عقد محلل عام لكائن طلب صغير؟

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

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

2. لماذا يفيد استبدال pickle بـJSON لكنه لا يكفي عند حد غير موثوق؟

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

يتجنب JSON سلوك تنفيذ الكائنات في pickle، لكنه قد يكون ضخما أو خاطئ البنية أو غير مأذون أو فاسد المعنى. طبق حدود الحجم والتحقق والتفويض قبل الآثار. صحة الصياغة والإذن بالفعل ضمانان منفصلان.

أهم ما تعلمته

  • تشمل الواجهة المستقرة الأخطاء والملكية والتوافق.
  • اختبر الحزمة المبنية وسلوك المصدر.
  • افصل البيانات عن التعليمات التنفيذية عند كل حد.

المراجع الرسمية