Налаштування розробки бекенду

Ця сторінка містить кроки, необхідні для початку розробки Gramps Web API, бекенду (серверної компоненти) Gramps Web.

Попередні вимоги

Рекомендується використовувати Visual Studio Code з devcontainers для налаштування розробки. Цей підхід створить попередньо налаштоване середовище розробки з усіма необхідними інструментами. Щоб почати, вам знадобляться такі компоненти:

• Docker
• Visual Studio Code з встановленим розширенням Dev Containers
• Git

Ви можете використовувати Linux, macOS або Windows як операційну систему.

Початок роботи

1. Відкрийте репозиторій Gramps Web API і натисніть "fork"
2. Клонуйте свій форк репозиторію на локальний комп'ютер за допомогою Git
3. Відкрийте клонований репозиторій у Visual Studio Code. Коли з'явиться запит, виберіть "Reopen in Container" або вручну відкрийте палітру команд (Ctrl+Shift+P або Cmd+Shift+P) і виберіть "Dev Containers: Rebuild and Reopen in Container".

4. Дочекайтеся, поки dev container побудується та запуститься. Це може зайняти кілька хвилин, особливо вперше.

   Після успішного завершення побудови Dev Container команда поверне:

   Успішно встановлено gramps-webapi-x.x.x.

   Info

   Щоб перебудувати контейнер у Visual Studio Code:

   • Якщо ви в контейнері, використовуйте команду палітри "Rebuild in container".

   • Якщо ви в режимі перегляду папок (тобто не в контейнері), використовуйте команду палітри "Rebuild and Reopen in Container".

Завдання

Якщо ви лише модифікуєте код бекенду, вам не обов'язково запускати веб-сервер - модульні тести використовують тестовий клієнт Flask, який дозволяє симулювати запити до API без необхідності запуску сервера.

Однак запуск сервера корисний, якщо ви

• хочете випробувати свої зміни з реальними HTTP-запитами (див. ручні запити),
• хочете попередньо переглянути вплив змін на повну програму Gramps Web, або
• також хочете одночасно вносити зміни у фронтенд (див. налаштування розробки фронтенду).

Запуск сервера спрощений у dev container за допомогою попередньо визначених завдань. Ви можете виконувати ці завдання з палітри команд (Ctrl+Shift+P або Cmd+Shift+P), вибравши "Tasks: Run Task", а потім вибравши одне з наступних: - "Serve Web API" - запускає сервер розробки Flask на порту 5555 з увімкненим веденням журналу налагодження - "Start Celery worker" - запускає робітника Celery для обробки фонових завдань.

Налагодження

Налагодження може бути іноді складним, особливо коли потрібно відстежити складну поведінку або виявити тонкі проблеми. Щоб полегшити це, ви можете налагоджувати як запущений екземпляр API, так і окремі тестові випадки безпосередньо в Visual Studio Code.

Налагодження Gramps Web API

Щоб налагодити запущений API:

1. Відкрийте Visual Studio Code і перейдіть до перегляду Run and Debug.
2. Виберіть конфігурацію "Web API" з випадаючого меню.
3. Розпочніть налагодження.
4. Коли ви надсилаєте запити до бекенду (або вручну, або через GUI Gramps Web), виконання зупиниться на будь-яких точках зупинки, які ви встановили в коді.
   Це дозволяє вам перевіряти змінні, контроль виконання та інші деталі виконання.

Налагодження тестових випадків

Щоб налагодити конкретний тестовий випадок:

1. Відкрийте тестовий файл, який ви хочете налагодити (наприклад, test_people.py).
2. У Visual Studio Code відкрийте перегляд Run and Debug.
3. Виберіть конфігурацію "Current Test File".
4. Розпочніть налагодження — виконання зупиниться на будь-яких точках зупинки, встановлених у цьому тестовому файлі.

Ця налаштування дозволяє вам крокувати через логіку тесту, перевіряти значення змінних і краще розуміти невдачі тестів або несподівані результати.