Упражнение. Обновление веб-API с помощью GitHub Copilot

Завершено

Давайте рассмотрим, как изменить репозиторий Python с помощью расширенных методов GitHub Copilot для конечной точки API. Получите более практический опыт с помощью этого репозитория, содержащего веб-приложение Python, в котором размещен Travel Weather API.

Что такое API?

API выступает в качестве посредника, который позволяет различным приложениям взаимодействовать друг с другом. Например, веб-сайт о погоде может предоставлять исторические данные или функции прогноза через свой API. С помощью API можно внедрить данные на веб-сайт или создать приложение, которое объединяет данные погоды с другими функциями.

Расширение веб-API

API уже перечисляет регионы и возвращает ежемесячные данные о погоде для региона, города и месяца. Добавьте GET /regions/{region} для возврата массива JSON городов, доступных для этого региона. Для предоставленного набора данных GET /regions/Spain должен возвращать ["Seville"]. Сохраните существующие эндпоинты, включая эндпоинт ежемесячной погоды.

В этом упражнении используйте рабочее пространство Codespace с предварительно настроенной средой в вашем браузере. В упражнении требуется редактор Codespaces с выполненным входом, в котором текущая учетная запись, версия редактора и политика организации делают доступными необходимый сеанс Copilot и выбор агента. Если необходимая функция недоступна, перед продолжением устраните это требование. Не изменяйте параметры политики, не используйте неограниченные разрешения или не рассматривайте непроверенный рабочий процесс как эквивалентный.

Important

Если вы хотите изменить файлы, выберите Agent явным образом в представлении чата. В этом интерактивном упражнении используйте Manual permissions, если они доступны и разрешены вашей организацией. Просмотрите действия, запрашивающие утверждение, и проверьте все полученные изменения. Разрешения, предоставленные вручную, не требуют подтверждения для каждого изменения файла, и изменения уже можно сохранить до выбора Keep. Запрос на узкое изменение не обеспечивает соблюдение ограничений доступа к файлам.

Шаг 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.
    

    Проверьте план и отправьте отзыв, если он не соответствует этим требованиям. Выберите «Утвердить только план». Не выбирайте Implement Plan в этом упражнении, так как вы реализуете маршрут со встроенным чатом в следующих шагах.

  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())
    

Встроенный чат использует активный контекст редактора. Не предполагайте, что вложения к отдельному запросу чата также присоединяются к встроенному чату. Если для изменения требуется больше контекста, перейдите в представление чата с соответствующими файлами, подключенными и выберите агент.

Имена регионов должны соответствовать ключам в предоставленном наборе данных, включая регистр. Ожидаемый ответ Spain — ["Seville"]. Если имя отсутствует, возвращается HTTP 404 с {"detail": "Region not found"}.

Important

Этот проект создает и кэширует схему OpenAPI при импорте main.py. Маршрут, добавленный под блоком создания схемы, может работать как конечная точка HTTP, но отсутствует в интерактивной документации. Исправьте порядок элементов исходного кода; не изменяйте созданный .well-known/openapi.jsonобъект.

Проверьте маршрут вручную

Контейнер устанавливает зависимости проекта в настроенную среду Python. При подключении к пространству кода настроенная команда запуска запускает Uvicorn на порту 8000 с автоматической перезагрузкой.

  1. Проверьте терминал запуска для успешного запуска приложения. Перед продолжением устраните любую ошибку. Запись порта только не доказывает, что приложение запущено.
  2. Откройте представление «Порты», найдите порт 8000, помеченный как «Приложение», и сохраните для него видимость Private.
  3. Откройте приложение, доступное через проброс порта, в браузере. Корневой адрес перенаправляет в интерактивную документацию по API /docs.
  4. Сохраните main.py и дождитесь успешного завершения автоматической перезагрузки.
  5. Обновите страницу приложения с переадресацией /docs.
  6. Разверните GET /regions/{region}, выберите "Попробуйте", введите Spain и выберите "Выполнить".
  7. Подтвердите HTTP 200 и массив JSON ["Seville"]. Если операция отсутствует, убедитесь, что маршрут находится до создания схемы. Если запрос завершается сбоем, проверьте выходные данные сервера и поделитесь соответствующей ошибкой с Copilot.

Сервер обычно уже запущен. Не запускайте вторую копию на порту 8000 и не используйте localhost:8000 локальной машины. Сохраненные Python изменения активируют автоматическую перезагрузку существующего сервера.

Шаг 2. Создание и запуск тестов

Откройте существующий test_main.py в корневом каталоге репозитория. В сеансе Copilot выберите Агент и прикрепите 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 и клиент TestClient для FastAPI в 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. Обновление документации по проекту с помощью Agent

  1. Откройте чат, запустите сеанс Copilot для текущего проекта, выберите Agent и просмотрите разрешения сеанса.

  2. Подключите README.md, weather.json, requirements.txt, main.py, test_main.py и эффективную конфигурацию .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. Сохраните запланированные правки. Keep не является фиксацией Git. Сделайте коммит и выполните push позже с помощью шагов по сохранению из сводки.

Поздравляем с завершением этого упражнения. Вы использовали GitHub Copilot для планирования, реализации и ревью нового маршрута API, написания и выполнения тестов для проверки его поведения, регистрации OpenAPI и сохранения ежемесячной конечной точки погоды, а также использовали Agent для улучшения документации по проекту.

Завершив упражнение в GitHub, вернитесь сюда, чтобы выполнить следующие задачи:

  • пройти быструю проверку знаний;
  • подвести итоги по изученному материалу;
  • Значок за прохождение этого модуля.