Как написать первый веб-сервис на Flask: пошаговая инструкция

Что получится в итоге

К концу инструкции у вас будет запущенный локально веб-сервис с двумя маршрутами: один отдаёт приветствие, другой принимает данные через POST и возвращает JSON. Сервис обрабатывает ошибки и логирует запросы. Этого достаточно, чтобы понять механику Flask и начать строить на ней что-то своё — от внутреннего API до бэкенда для мобильного приложения.

Что нужно до начала

Убедитесь, что всё из списка на месте. Если чего-то не хватает — установите до первого шага, иначе застрянете на полпути.

• Python 3.10 или новее. Проверьте командой python3 --version. Если версия ниже 3.10 — обновите через официальный сайт python.org.
• pip — менеджер пакетов Python. Обычно идёт в комплекте. Проверка: pip3 --version.
• Терминал. На macOS и Linux — стандартный. На Windows подойдёт PowerShell или WSL.
• Текстовый редактор или IDE. VS Code, PyCharm, даже nano — что угодно, лишь бы вы могли редактировать .py-файлы.

Инструкция написана для Flask 3.x. Если вы устанавливаете Flask позже 2025 года, сверьтесь с официальной документацией — интерфейс стабилен, но детали могут измениться.

Шаг 1. Создайте проект и виртуальное окружение

Виртуальное окружение изолирует зависимости: пакеты вашего проекта не перемешаются с системными.

# Создаём папку проекта и переходим в неё
mkdir flask-demo
cd flask-demo

# Создаём виртуальное окружение
python3 -m venv .venv

# Активируем (macOS / Linux)
source .venv/bin/activate

# Активируем (Windows PowerShell)
# .venv\Scripts\Activate.ps1

Проверка: в начале строки терминала появится (.venv). Если нет — окружение не активировано, повторите команду активации.

Шаг 2. Установите Flask

pip install flask

Проверка: выполните pip show flask. В выводе должна быть строка Version: 3.x.x. Если pip ругается на права доступа — убедитесь, что виртуальное окружение активно.

Шаг 3. Напишите минимальное приложение

Создайте файл app.py в корне проекта:

from flask import Flask

app = Flask(__name__)


@app.route("/")
def index():
    """Корневой маршрут — простое приветствие."""
    return {"message": "Сервис работает"}


if __name__ == "__main__":
    app.run(debug=True, port=5000)

Flask автоматически сериализует словарь в JSON и ставит заголовок Content-Type: application/json. Ничего дополнительного импортировать не нужно.

Проверка: запустите python3 app.py. В терминале появится строка * Running on http://127.0.0.1:5000. Откройте этот адрес в браузере — вы увидите JSON {"message": "Сервис работает"}.

Шаг 4. Добавьте POST-эндпоинт

Большинство реальных сервисов не только отдают данные, но и принимают их. Добавьте в app.py второй маршрут:

from flask import Flask, request, jsonify

app = Flask(__name__)


@app.route("/")
def index():
    return {"message": "Сервис работает"}


@app.route("/echo", methods=["POST"])
def echo():
    """Принимает JSON и возвращает его обратно с меткой времени."""
    data = request.get_json(silent=True)
    if data is None:
        return jsonify({"error": "Тело запроса не содержит валидный JSON"}), 400

    from datetime import datetime, timezone
    return jsonify({
        "received": data,
        "processed_at": datetime.now(timezone.utc).isoformat()
    }), 200


if __name__ == "__main__":
    app.run(debug=True, port=5000)

Проверка: перезапустите сервис (Ctrl+C, затем python3 app.py). Отправьте запрос через curl:

curl -X POST http://127.0.0.1:5000/echo \
  -H "Content-Type: application/json" \
  -d '{"name": "Мир"}'

Ожидаемый ответ — JSON с полем received, содержащим ваши данные, и полем processed_at с UTC-временем.

Шаг 5. Обработайте ошибки

По умолчанию Flask возвращает HTML-страницу на 404 и 500. Для API это неудобно — клиент ждёт JSON. Добавьте обработчики в app.py перед блоком if __name__:

@app.errorhandler(404)
def not_found(error):
    return jsonify({"error": "Маршрут не найден"}), 404


@app.errorhandler(500)
def internal_error(error):
    return jsonify({"error": "Внутренняя ошибка сервера"}), 500

Проверка: перезапустите сервис и откройте http://127.0.0.1:5000/несуществующий. Вместо HTML-страницы вы получите JSON с ключом error.

Шаг 6. Добавьте логирование

Без логов вы не узнаете, что пошло не так на проде. Flask использует стандартный модуль logging Python. Добавьте в начало файла, после создания app:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)

Теперь в функции echo можно писать:

app.logger.info("Получен запрос на /echo с данными: %s", data)

Проверка: отправьте POST-запрос снова. В терминале, где запущен Flask, появится строка лога с содержимым запроса.

Структура файла целиком

Вот итоговый app.py — один файл, который можно скопировать и запустить:

import logging
from datetime import datetime, timezone

from flask import Flask, request, jsonify

app = Flask(__name__)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)


@app.route("/")
def index():
    return {"message": "Сервис работает"}


@app.route("/echo", methods=["POST"])
def echo():
    data = request.get_json(silent=True)
    if data is None:
        return jsonify({"error": "Тело запроса не содержит валидный JSON"}), 400
    app.logger.info("Получен запрос на /echo с данными: %s", data)
    return jsonify({
        "received": data,
        "processed_at": datetime.now(timezone.utc).isoformat()
    }), 200


@app.errorhandler(404)
def not_found(error):
    return jsonify({"error": "Маршрут не найден"}), 404


@app.errorhandler(500)
def internal_error(error):
    return jsonify({"error": "Внутренняя ошибка сервера"}), 500


if __name__ == "__main__":
    app.run(debug=True, port=5000)

Если не получилось

Пять ошибок, с которыми сталкиваются чаще всего:

Flask в режиме debug=True перезапускается при каждом сохранении файла и показывает трейсбек прямо в браузере. Это удобно при разработке, но на проде debug-режим обязан быть выключен: он раскрывает внутренности приложения любому, кто откроет страницу ошибки.

^{Виртуальное окружение (venv) — изолированная копия интерпретатора Python с собственным набором пакетов. Позволяет держать разные проекты с разными версиями библиотек на одной машине, не создавая конфликтов.}

Что дальше

Работающий сервис — только начало. Вот конкретные следующие шаги:

• Подключите базу данных. Flask не навязывает ORM — чаще всего используют SQLAlchemy через расширение Flask-SQLAlchemy. Начните с SQLite: никакой установки, файл базы лежит рядом с приложением.
• Вынесите конфигурацию. Порт, режим отладки, секретные ключи — всё это не должно жить в коде. Используйте переменные окружения или файл .env с расширением python-dotenv.
• Разверните на сервере. Встроенный сервер Flask не предназначен для продакшена. Для боевого запуска используют WSGI-серверы — Gunicorn на Linux или Waitress на Windows — за обратным прокси вроде Nginx.
• Напишите тесты. Flask предоставляет тестовый клиент: app.test_client() позволяет отправлять запросы к приложению без запуска сервера.

Мерьте время ответа эндпоинтов с самого начала. Когда сервис вырастет, привычка логировать длительность запроса сэкономит часы на отладке.