Сучасні CI-CD пайплайни для Python проєктів з REST API за допомогою UV

1. Вступ до UV: Автоматизація створення REST API сервісів

Створення REST API сервісів є критично важливою частиною сучасної розробки програмного забезпечення, і інструменти, такі як UV, допомагають спростити та оптимізувати цей процес. UV — це сучасний менеджер пакетів для Python, написаний на Rust, який пропонує надійне керування залежностями, інтеграцію з віртуальними середовищами та високу швидкість порівняно з традиційними інструментами, такими як pip. Це робить його ідеальним для проєктів, що вимагають масштабованості та послідовності. Для прикладу ми використовуватимемо бібліотеку FastAPI. Інформація надана на основі офіційної документації UV.

Ініціалізація проєкту з UV

UV дозволяє швидко ініціалізувати REST API проєкт із попередньо визначеною структурою та основними файлами, які вже налаштовані. Щоб розпочати новий проєкт, просто виконайте команду:

uv init --app

Ця команда створює організовану структуру, що включає директорію додатку для коду та файл pyproject.toml для керування залежностями. Якщо ви хочете вказати ім'я для проєкту, можна використати:

uv init project_name

Після ініціалізації ви можете додати основну залежність FastAPI за допомогою:

uv add fastapi --extra standard

Ці команди автоматично налаштовують віртуальне середовище, синхронізують залежності та створюють файл uv.lock для забезпечення відтворюваності.

Керування залежностями та версіями

UV пропонує корисні команди для розширеного керування залежностями та версіями Python:

• Додавання залежностей: щоб встановити бібліотеку, просто використовуйте:

uv add library_name

• Щоб встановити всі залежності, визначені в pyproject.toml:

uv sync

Розширені команди для якості коду

Щоб покращити якість коду, UV дозволяє інтеграцію з інструментами, такими як Ruff (лінтер) та Pyright (перевірник типів):

• Встановіть Ruff серед ваших бібліотек для розробки:

uv add ruff --dev

• Налаштуйте Pyright:

uv add pyright --dev

Ці інструменти можна налаштувати безпосередньо у файлі pyproject.toml, щоб забезпечити послідовне оформлення коду та виявляти помилки до виконання.

Переваги автоматизації з UV

Використання UV значно знижує час на ручну настройку, автоматизує керування залежностями та забезпечує послідовність середовищ. Завдяки своїй швидкості та надійності, UV є особливо корисним для команд, які працюють над колабораційними або розподіленими проєктами. Завдяки цим інструментам і командам, розробники можуть зосередитися на розробці продукту, а не на налаштуванні середовища.

2. Налаштування CI/CD Pipeline з GitLab та UV

Безперервна інтеграція є фундаментальним стовпом у сучасній розробці програмного забезпечення. GitLab, в поєднанні з UV, пропонує потужне рішення для ефективного керування CI/CD пайплайнами. Завдяки своїй швидкості та надійності у керуванні залежностями, UV ідеально інтегрується з робочими процесами GitLab.

Налаштування GitLab для безперервної інтеграції

Типова конфігурація .gitlab-ci.yml з UV включає використання попередньо налаштованих Docker-образів. UV надає оптимізовані образи для Python, такі як ghcr.io/astral-sh/uv, які містять усе необхідне для початку. Наприклад:

variables:  
 UV_VERSION: 0.5  
 PYTHON_VERSION: 3.12  
 BASE_LAYER: ubuntu:24.04  
stages:  
 - analysis  
uv:  
 stage: analysis  
 image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER  
 script:  
 - uv sync --frozen

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

Автоматизація процесів CI/CD за допомогою UV

UV спрощує не тільки керування залежностями, але й налаштування пайплайнів. Ви можете використовувати команду uv cache prune — ci, щоб зменшити розмір кешу та покращити загальну продуктивність. Крім того, опція — system дозволяє встановлювати пакунки безпосередньо в системне середовище, якщо це необхідно.

Кешування для оптимальної продуктивності

Збереження кешу між запусками пайплайну є важливим для зменшення часу побудови.
Here is an example:

uv-install:  
 variables:  
 UV_CACHE_DIR: .uv-cache  
 cache:  
 key:  
 files:  
 - uv.lock  
 paths:  
 - $UV_CACHE_DIR  
 script:  
 - uv sync --frozen  
 - uv cache prune --ci

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

Кращі практики для ефективних пайплайнів

• Ізоляція залежностей: Використовуйте віртуальні середовища, які автоматично створюються за допомогою UV.
• Оптимізація Docker-образів: Обирайте легкі варіанти, такі як alpine-версії.
• Керування змінними середовища: Чітко визначайте версії та конфігурації вгорі файлу .gitlab-ci.yml.

3. Керування Dockerfile та Docker Compose з UV

Створення оптимізованих Dockerfile є важливим кроком для забезпечення ефективного розгортання Python-додатків. UV, завдяки своїй інтеграції з Docker, значно спрощує процес налаштування та керування контейнеризованими середовищами.

Автоматизоване створення Dockerfile за допомогою UV

UV надає попередньо налаштовані Docker-образи, які включають його виконуваний файл, що дозволяє швидко розпочати. Наприклад, базовий Dockerfile може мати таку структуру:

FROM ghcr.io/astral-sh/uv:debianWORKDIR /appCOPY pyproject.toml uv.lock ./RUN --mount=type=cache,target=/root/.cache/uv \  
 uv sync --frozen --no-install-projectCOPY . .RUN uv sync --frozenCMD ["python", "main.py"]

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

Налаштування середовищ з Docker Compose

Docker Compose дозволяє організовувати кілька контейнерів для складних середовищ. UV може бути використано для керування віртуальними середовищами в контейнерах, забезпечуючи послідовність між середовищами розробки та виробництва. Конфігурація docker-compose.yml може виглядати так:

services:  
 app:  
 build:  
 context: .  
 dockerfile: Dockerfile  
 volumes:  
 - .:/app  
 environment:  
 - UV_COMPILE_BYTECODE=1  
 command: ["uvicorn", "main:app", "--reload", "--host", "0.0.0.0"]

Такий підхід дозволяє розробникам відразу бачити зміни в коді без необхідності перебудовувати образ. Крім того, використання uvicorn замість fastapi дозволяє налаштовувати використану двері.

Інтеграція з UV для розгортання

UV підтримує компіляцію байт-коду Python, що покращує час запуску для виробничих додатків. Ви можете активувати цю функцію через:

ENV UV_COMPILE_BYTECODE=1

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

Практичні приклади

FastAPI додаток можна розгорнути, використовуючи оптимізований Dockerfile:

FROM python:3.12-slim AS builderWORKDIR /appCOPY pyproject.toml uv.lock ./RUN uv sync --frozen --no-install-projectCOPY . .RUN uv sync --frozenFROM python:3.12-slimCOPY --from=builder /app /appCMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

Такий підхід гарантує легкий та високопродуктивний образ.

4. Кейс: Повна реалізація REST API сервісу з UV, GitLab та Docker

Опис проєкту та цілі

Сучасний REST API додаток потребує добре структурованого процесу розробки та інструментів, які забезпечать ефективність та масштабованість. У цьому кейсі ми покажемо, як за допомогою UV, GitLab CI/CD та Docker був створений надійний FastAPI сервіс. Основною метою було автоматизувати весь життєвий цикл проєкту, від початкової конфігурації до розгортання в продакшн, з мінімізацією часу на ручну настройку.

Кроки від ініціалізації до розгортання

1. Ініціалізація проєкту. Проєкт було розпочато за допомогою команди uv init — app, яка створила структуру за замовчуванням, включаючи основні файли, такі як pyproject.toml. Далі FastAPI було додано як основну залежність за допомогою стандартної команди uv add fastapi — extra.
2. Налаштування CI/CD пайплайну. Пайплайн GitLab був налаштований за допомогою оптимізованого файлу .gitlab-ci.yml.
   Змінні, такі як UVVERSION та PYTHONVERSION, були визначені для забезпечення послідовності між середовищами. Кеш залежностей керувався через команду uv cache prune — ci, що дозволило зменшити часи збірки.
3. Створення Docker-образу. Для розділення етапів побудови та виконання використовувався багатоступеневий Dockerfile. Під час етапу побудови UV ефективно синхронізував залежності, в той час як на фінальному етапі було створено легкий образ, готовий до продакшн.
4. Розгортання в продакшн. Додаток було розгорнуто на Docker-сервері за допомогою команди docker run. Конфігурація включала змінні середовища для оптимізації продуктивності, такі як UVCOMPILEBYTECODE=1.

Зіткнення з проблемами та прийняті рішення

• Керування залежностями: Для синхронізації залежностей між різними середовищами було використано UV кеш та файл uv.lock.
• Оптимізація Docker-образу: Використання багатоступеневих збірок значно зменшило розмір фінальних образів.
• Продуктивність CI/CD пайплайну: Інтеграція кешу та використання попередньо налаштованих Docker-образів покращили часи виконання.

Результати та висновки

Впровадження призвело до високої автоматизації процесу розробки, зменшивши часи збірки на 40% порівняно з традиційними рішеннями. Інтеграція між UV, GitLab та Docker забезпечила послідовність між середовищами розробки та продакшн, покращуючи загальну якість програмного забезпечення.

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

Перекладено з: Modern CI-CD Pipelines of REST API Python Project with UV