Блюпринты: масштабируем структуру

Блюпринт — это «мини-приложение»: группа связанных маршрутов, шаблонов и статики, которую регистрируют в основном приложении. Способ разбить большой проект на модули.

Когда всех маршрутов десятки, один файл становится свалкой. Блюпринт группирует связанное: auth (вход/регистрация), posts (блог), admin (панель) — каждый в своём модуле. Фабрика просто регистрирует их. Это структурный аналог наследования шаблонов.

Представь приложение на 80 маршрутов в одном views.py — навигироваться невозможно. Блюпринты решают это так же, как папки решают хаос файлов: группируют по смыслу. Каждый блюпринт — самостоятельный набор маршрутов с возможным префиксом URL и своими шаблонами.

# blog/auth.py
from flask import Blueprint
auth = Blueprint("auth", __name__, url_prefix="/auth")

@auth.route("/login")
def login():
    return "Вход"

@auth.route("/register")
def register():
    return "Регистрация"

Фабрика регистрирует блюпринты — и только тогда их маршруты «оживают»:

# __init__.py
def create_app():
    app = Flask(__name__)
    from .auth import auth
    from .views import posts
    app.register_blueprint(auth)     # /auth/login, /auth/register
    app.register_blueprint(posts)    # /posts/...
    return app

Важная деталь: endpoint внутри блюпринта именуется с префиксом — url_for("auth.login"), а не "login". Это даёт пространства имён: в разных блюпринтах могут быть функции index без конфликта.

Блюпринты — это масштабирование структуры по тому же принципу, по которому папки масштабируют файловую систему: группировка по смыслу. Большой проект естественно делится на предметные области — auth, posts, admin, api, — и каждой даёшь свой блюпринт со своим url_prefix и, при желании, своими шаблонами и статикой. Фабрика затем просто регистрирует их все. Важный механизм — пространства имён endpoint: внутри блюпринта функции живут под его именем, поэтому url_for зовётся как 'auth.login', и в разных блюпринтах могут спокойно сосуществовать одноимённые функции index без конфликтов. Импортируй блюпринты внутри create_app, а не на верхнем уровне модуля — так ты избегаешь циклических импортов, ради чего фабрика отчасти и существует.

Как работает под капотом

Блюпринт сам по себе ничего не делает — он лишь копит маршруты в отложенном виде. Реальная регистрация происходит при register_blueprint: тогда маршруты с учётом url_prefix добавляются в общую URL-карту приложения.

  Blueprint("auth", url_prefix="/auth")
     │ накапливает: login → /login, register → /register
     ▼ register_blueprint(auth) в фабрике
  URL-карта приложения:
     /auth/login    → auth.login
     /auth/register → auth.register
  endpoint'ы в пространстве имён "auth.*"

Смоделируем блюпринт как отложенный набор маршрутов с префиксом.

class Blueprint:
    def __init__(self, name, url_prefix=""):
        self.name = name
        self.url_prefix = url_prefix
        self.routes = {}
    def route(self, path):
        def deco(func):
            self.routes[path] = func
            return func
        return deco

app_map = {}
def register(bp):
    for path, func in bp.routes.items():
        full = bp.url_prefix + path
        app_map[full] = bp.name + "." + func.__name__

auth = Blueprint("auth", "/auth")
@auth.route("/login")
def login(): return "вход"
@auth.route("/register")
def register_v(): return "рег"

register(auth)
for url, endpoint in app_map.items():
    print(url, "->", endpoint)

Запусти: маршруты блюпринта попали в общую карту с префиксом /auth и именами вида auth.login. Точно так Flask собирает приложение из блюпринтов в фабрике.

Частые ошибки

• Забыть register_blueprint. Маршруты определены, но не зарегистрированы — 404.
• url_for без имени блюпринта. Нужно "auth.login", иначе BuildError.
• Импортировать блюпринты на верхнем уровне __init__. Импортируй внутри create_app, избегая циклов.

Best practices

• Один блюпринт — одна предметная область (auth, posts, admin, api).
• Задавай url_prefix на уровне блюпринта, а не повторяй в каждом маршруте.
• Регистрируй блюпринты внутри фабрики, импортируя их там же.

Что запомнить

• Блюпринт группирует связанные маршруты, шаблоны и статику в модуль.
• register_blueprint в фабрике встраивает маршруты в URL-карту с префиксом.
• Endpoint'ы блюпринта живут в пространстве имён: url_for('auth.login').
• Блюпринты импортируют внутри create_app, избегая циклов.

Итог: блюпринт группирует маршруты в модуль с префиксом и пространством имён, а фабрика их регистрирует. Это масштабирует структуру без хаоса. Дальше — обработка ошибок и страницы 404/500.