تمرين - تحديث واجهة برمجة تطبيقات الويب باستخدام GitHub Copilot

مكتمل

دعونا نستكشف كيف يمكنك تعديل مستودع Python باستخدام تقنيات GitHub Copilot المتقدمة لنقطة نهاية واجهة برمجة التطبيقات. اكتساب المزيد من الخبرة العملية باستخدام هذا المستودع الذي يحتوي على تطبيق ويب Python يستضيف واجهة برمجة تطبيقات طقس السفر.

ما هي واجهة برمجة التطبيقات؟

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

توسيع واجهة برمجة تطبيقات الويب

تسرد واجهة برمجة التطبيقات بالفعل المناطق وتعيد بيانات الطقس الشهرية لمنطقة ومدينة وشهر. أضف GET /regions/{region} لإرجاع صفيف JSON للمدن المتوفرة لتلك المنطقة. بالنسبة لمجموعة البيانات المتوفرة، GET /regions/Spain يجب أن ترجع ["Seville"]. الاحتفاظ بنقاط النهاية الموجودة، بما في ذلك نقطة نهاية الطقس الشهرية.

لهذا التمرين، استخدم Codespace مع البيئة التي تم تكوينها مسبقا في المستعرض الخاص بك. يتطلب التمرين محرر Codespaces مصادقا يتيح فيه الحساب الحالي وإصدار المحرر ونهج المؤسسة جلسة Copilot المطلوبة واختيار العامل. إذا لم تتوفر ميزة مطلوبة، فحل هذه المتطلبات الأساسية قبل المتابعة؛ لا تغير إعدادات النهج، أو تستخدم أذونات غير مقيدة، أو تعامل مع سير عمل لم يتم التحقق منه على أنه مكافئ.

مهم

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

الخطوة 1: تخطيط مسار جديد وإضافته

  1. افتح الدردشة، وابدأ جلسة Copilot للمشروع الحالي، وحدد اسأل. إرفاق main.pyو weather.jsonو test_main.pyثم إرسال هذا الطلب:

    Explain how the existing routes use the weather data and identify the current
    tests. Confirm which cities the Spain entry contains. Don't change files.
    
  2. قارن التفسير بالملفات المرفقة. في نفس جلسة Copilot، أدخل طلب التخطيط هذا:

    /plan Add GET /regions/{region} to return the city names from weather.json.
    Preserve the existing region-list and monthly weather endpoints. Use the
    existing app and data and the dataset's case-sensitive names. Return HTTP 404
    with detail "Region not found" for an unknown region. Register the
    route before the OpenAPI schema is generated. Include tests for the new
    route and a regression test for the existing monthly weather response.
    Propose the changes without implementing them.
    

    راجع الخطة وإرسال الملاحظات إذا لم تكن تفي بهذه المتطلبات. حدد الموافقة على الخطة فقط. لا تحدد تنفيذ الخطة في هذا التمرين، لأنك ستنفذ المسار باستخدام الدردشة المضمنة في الخطوات التالية.

  3. افتح main.py وقم بتحديث استيراد FastAPI الحالي الخاص به، مع الاحتفاظ ب FastAPI:

    from fastapi import FastAPI, HTTPException
    
  4. حدد موقع مسار قائمة المنطقة (GET /regions) والكتلة # Generate the OpenAPI schema: الموجودة. يجب أن يكون المسار الجديد بعد مسار قائمة المنطقة وقبل كتلة إنشاء المخطط هذه.

  5. ضع المؤشر عند نقطة الإدراج المطلوبة. افتح الدردشة المضمنة باستخدام Ctrl+I على Windows أو Command+I على macOS، واستخدم هذه المطالبة باللغة الطبيعية:

    Add GET /regions/{region} in main.py. Return the city names from the
    existing data dictionary loaded from weather.json for the requested region.
    Return HTTP 404 with detail "Region not found" if the region is absent.
    Preserve the existing routes, including the monthly weather endpoint, and
    the dataset's case-sensitive names. Place the new route before the block
    that generates the OpenAPI schema.
    
  6. راجع التحرير المقترح قبل الاحتفاظ به. تأكد من أنه يستخدم الموجود app والمحمل data، ولا يعيد تحميل المثبت أو ينشئ تطبيقا آخر، ويضيف هذا المسار أو يحل محله مرة واحدة فقط:

    @app.get("/regions/{region}")
    def cities(region: str):
        if region not in data:
            raise HTTPException(status_code=404, detail="Region not found")
        return list(data[region].keys())
    

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

يجب أن تتطابق أسماء المناطق مع المفاتيح الموجودة في مجموعة البيانات المتوفرة، بما في ذلك الحالة. الاستجابة المتوقعة لأسبانيا هي ["Seville"]. يرجع الاسم غير الموجود HTTP 404 مع {"detail": "Region not found"}.

مهم

ينشئ هذا المشروع مخطط OpenAPI الخاص به ويخزنه مؤقتا عند main.py استيراده. قد يعمل المسار المضاف أسفل كتلة إنشاء المخطط كنقطة نهاية HTTP ولكنه مفقود من الوثائق التفاعلية. تصحيح ترتيب المصدر؛ لا تقم بتحرير الذي تم .well-known/openapi.jsonإنشاؤه .

التحقق من المسار يدويا

تثبت الحاوية متطلبات المشروع في بيئة Python التي تم تكوينها. عند إرفاقه بمساحة التعليمات البرمجية، يقوم أمر بدء التشغيل المكون بتشغيل Uvicorn على المنفذ 8000 مع إعادة التحميل التلقائي.

  1. تحقق من المحطة الطرفية لبدء التشغيل لبدء تشغيل التطبيق بنجاح. حل أي خطأ قبل المتابعة. لا يثبت إدخال المنفذ وحده أن التطبيق قيد التشغيل.
  2. افتح طريقة عرض المنافذ ، وحدد موقع المنفذ 8000 المسمى Application، واحتفظ برؤيته خاصة.
  3. افتح التطبيق الذي تمت إعادة توجيهه في المستعرض. يعيد الجذر التوجيه إلى وثائق واجهة برمجة التطبيقات التفاعلية في /docs.
  4. احفظ main.py وانتظر حتى تنتهي إعادة التحميل التلقائي بنجاح.
  5. تحديث صفحة التطبيق الذي تمت إعادة توجيهه /docs .
  6. قم بتوسيع GET /regions/{region}، وحدد Try it out، وأدخل Spain، وحدد Execute.
  7. تأكيد HTTP 200 ومصفوفة ["Seville"]JSON . إذا كانت العملية مفقودة، فتحقق من أن المسار قبل إنشاء المخطط. إذا فشل الطلب، فافحص إخراج الخادم وشارك الخطأ ذي الصلة مع Copilot.

عادة ما يكون الخادم قيد التشغيل بالفعل. لا تبدأ نسخة ثانية على المنفذ 8000، ولا تستخدم الجهاز localhost:8000المحلي الخاص بك. تؤدي التغييرات Python المحفوظة إلى إعادة التحميل التلقائي للخادم الحالي.

الخطوة 2: إنشاء الاختبارات وتشغيلها

افتح الموجود test_main.py في جذر المستودع. في جلسة Copilot، حدد Agent وأرفق test_main.pyو main.pyوweather.json. استخدم هذا الطلب:

Extend the existing test_main.py using its existing TestClient and client.
Keep its current tests. Verify that GET /regions/Spain returns HTTP 200 and
exactly ["Seville"], an unknown region returns HTTP 404 with the agreed error
detail, POST to the city-list route returns HTTP 405, and the new path is present
in /openapi.json. Also verify that GET /regions/Spain/Seville/January still
returns HTTP 200 with exactly {"high": 61, "low": 41}. Don't change the fixture
or weaken assertions to make tests pass.

راجع النتيجة واحتفظ بالاختبارات والواردات TestClientclientالموجودة. الاختبارات الخمسة التالية هي إضافة مناسبة:

def test_cities_spain():
    response = client.get("/regions/Spain")
    assert response.status_code == 200
    assert response.json() == ["Seville"]


def test_cities_unknown_region():
    response = client.get("/regions/__unknown__")
    assert response.status_code == 404
    assert response.json() == {"detail": "Region not found"}


def test_cities_rejects_post():
    response = client.post("/regions/Spain")
    assert response.status_code == 405


def test_cities_in_openapi():
    response = client.get("/openapi.json")
    assert response.status_code == 200
    assert "get" in response.json()["paths"]["/regions/{region}"]


def test_monthly_weather_preserved():
    response = client.get("/regions/Spain/Seville/January")
    assert response.status_code == 200
    assert response.json() == {"high": 61, "low": 41}

قم بتشغيل المجموعة من جذر المستودع في Codespace:

/home/vscode/venv/bin/python -m pytest -q

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

يتضمن المشروع بالفعل pytest وHTTPX وFastAPI TestClient في test_main.py. أعد استخدامها. تقوم هذه الاختبارات بتشغيل التطبيق قيد المعالجة، لذلك لا تعتمد على عنوان URL للمستعرض الذي تمت إعادة توجيهه أو عملية Uvicorn قيد التشغيل. لا تقم بترقية تبعية فردية لمجرد أن Copilot يقترح القيام بذلك.

إذا فشل الاختبار، فامنح Copilot الاختبار الفاشل والإخراج الفعلي والنتيجة المتوقعة. على سبيل المثال:

The fixture's Spain entry contains only Seville. Correct the city-list test to
expect exactly ["Seville"]. Preserve the fixture and the endpoint contract.

الخطوة 3: استخدام العامل لتحديث وثائق المشروع

  1. افتح الدردشة، وابدأ جلسة Copilot للمشروع الحالي، وحدد عامل، وراجع أذونات الجلسة.

  2. إرفاق README.mdو main.pyweather.jsonو test_main.pyrequirements.txtو التكوين الفعال.devcontainer.

  3. إرسال هذه المطالبة:

    Update only README.md to explain how another learner can run this project in
    its configured Codespace. Read the attached source and configuration.
    Document the existing Python environment, automatic Uvicorn startup, private
    port-8000 preview, the city-list endpoint with its Spain example, and the command
    for running the existing tests. Don't change source code, dependencies, or the
    container configuration.
    
  4. راجع ميزة README وكل ملف آخر تم تغييره أو إلغاء تعقبه في التحكم بالمصادر. تصحيح المطالبات والتغييرات غير المدعومة خارج النطاق المطلوب. المطالبة الضيقة ليست عنصر تحكم في الوصول، وقد تحذف قائمة الملفات التي تم تغييرها الخاصة بالعامل التغييرات التي تم إجراؤها من خلال أوامر المحطة الطرفية.

  5. تأكد من أن أمر الاختبار الموثق يعمل في البيئة المكونة. تحقق من أن README يصف بدء تشغيل Uvicorn التلقائي الحالي ولا يوجه القراء لبدء تشغيل خادم مكرر. إذا كان يتضمن أمر استرداد يدوي، يجب أن يخبر القراء أولا بإيقاف العملية الحالية.

  6. الاحتفاظ بالتحريرات المقصودة. الاحتفاظ ليس تثبيت Git. الالتزام والدفع لاحقا باستخدام خطوات الاحتفاظ بالملخص.

تهانينا على إكمال هذا التمرين. لقد استخدمت GitHub Copilot لتخطيط مسار واجهة برمجة تطبيقات جديد وتنفيذه ومراجعته، وكتبت الاختبارات وقمت بتشغيلها للتحقق من سلوكها، وتسجيل OpenAPI، والحفاظ على نقطة نهاية الطقس الشهرية، واستخدمت عامل لتحسين وثائق المشروع.

عند الانتهاء من التمرين في GitHub، ارجع إلى هنا من أجل:

  • اختبار سريع للمعلومات
  • ملخص ما تعلمته
  • شارة إكمال هذه الوحدة