Eloquent тормозит: как найти N+1 и лишние запросы в Laravel 13

Eloquent тормозит: как найти N+1 и лишние запросы в Laravel 13
содержание

Введение

Знакомая история: страница заказов раньше открывалась мгновенно, но по мере роста таблиц стала отвечать секундами, а в мониторинге MySQL на один HTTP-запрос приходятся сотни одинаковых запросов. Обычно виновата проблема N+1: один запрос забирает список, а затем для каждой строки уходит ещё по одному запросу за связанными данными. Дальше по частоте идут лишние колонки, подсчёты в цикле, недостающие индексы и OFFSET на больших таблицах.

Статья ведёт по всему пути: как увидеть запросы, как избавиться от N+1, как читать EXPLAIN и чем обходить миллионы строк. Пример сквозной: модели Order, Customer, OrderItem и страница списка заказов с именем клиента и числом позиций. В конце собран чек-лист.

Числа взяты из реального прогона: Laravel 13.34, PHP 8.3.35, MySQL 8.4.11 в Docker, 1 000 000 заказов, 20 000 клиентов, 500 000 позиций (у первых 100 000 заказов по пять). База работает в соседнем контейнере, так что сетевая задержка почти нулевая; на настоящем сервере каждый лишний запрос стоит дороже. Абсолютные значения зависят от железа, но соотношения между вариантами остаются показательными.

Как увидеть запросы

Оптимизировать вслепую бессмысленно, сначала нужны измерения. Самый прямой способ — DB::listen(): колбэк вызывается после каждого запроса, а событие QueryExecuted содержит SQL, привязки и время выполнения.

// app/Providers/AppServiceProvider.php
use Illuminate\Database\Connection;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;

public function boot(): void
{
    if ($this->app->environment('local')) {
        DB::listen(function (QueryExecuted $query) {
            Log::debug($query->toRawSql(), ['ms' => $query->time]);
        });
    }

    // сработает один раз, когда суммарное время запросов превысит порог
    DB::whenQueryingForLongerThan(500, function (Connection $connection, QueryExecuted $event) {
        Log::warning('Запросы к БД заняли больше 500 мс', ['last_sql' => $event->sql]);
    });
}

В тестах удобнее DB::enableQueryLog() и DB::getQueryLog(). Оба метода присутствуют в классе соединения, но в документации Laravel 13 их нет, поэтому полагаться на них нужно с открытыми глазами. Следующий тест упадёт, как только число запросов начнёт расти:

public function test_orders_index_makes_constant_number_of_queries(): void
{
    Order::factory()->count(30)->create();

    DB::enableQueryLog();
    $this->get('/orders')->assertOk();

    // 2 запроса независимо от числа заказов
    $this->assertCount(2, DB::getQueryLog());
}
Инструмент Что даёт Когда брать
DB::listen() SQL, время, счётчик в коде лог на dev, свой счётчик
DB::enableQueryLog() список запросов в памяти тесты на число запросов
Laravel Debugbar вкладка Queries, дубликаты ручной просмотр страниц
Telescope история запросов, медленные наблюдение за окружением
preventLazyLoading() исключение при lazy loading автоматический поиск N+1

Для быстрой оценки хватит Debugbar: если простая страница делает больше десятка запросов, а многие из них почти одинаковы, стоит разобраться, откуда они берутся.

Чтобы заметить сам факт «страница долго сидит в базе», подойдёт DB::whenQueryingForLongerThan() из примера выше. Обработчик вызывается однократно — когда суммарное время всех запросов соединения превысило порог — и получает соединение вместе с последним событием запроса.

N+1 на живом примере

Допустим, контроллер берёт сто заказов, а в шаблоне выводятся клиент и число позиций:

$orders = Order::orderBy('id')->limit(100)->get();      // 1 запрос

foreach ($orders as $order) {
    echo $order->customer->name;    // +1 запрос на каждый заказ
    echo $order->items->count();    // +1 запрос на каждый заказ
}
// итого 1 + 100 + 100 = 201 запрос

// лечение: связи загружаются заранее, по одному запросу на связь
$orders = Order::with(['customer', 'items'])->orderBy('id')->limit(100)->get();   // 3 запроса

В логе или Debugbar N+1 узнаётся по десяткам одинаковых запросов, которые отличаются лишь значением в where id = ?. Здесь так и есть: 100 запросов к customers по одному id и 100 к order_items по одному order_id.

Связь customer при выборке не загружалась, поэтому Eloquent обращается к ней в момент первого чтения свойства — это lazy loading, ленивая загрузка. Лекарство — жадная загрузка (eager loading) через with(): для каждой связи выполняется один запрос where id in (…).

Получилось 3 запроса, но items подтягивает все позиции ради единственного числа. Точнее сработает подход из раздела о счётчиках ниже. Вот результаты прогона на сотне заказов:

Вариант Запросов Время, мс
Lazy loading: customer и items->count() 201 145,6
Lazy loading только customer 101 65,1
with(['customer', 'items']) 3 11,3
with('customer') 2 4,3
with('customer:id,name') и withCount('items') 2 5,5

Вложенные связи указываются через точку. На двадцати заказах с позициями и товарами ленивая загрузка выполнила 121 запрос (79,5 мс), а with('items.product') — 3 запроса (5,3 мс).

Выбор колонок и «забытый» ключ

Внутри with() можно сразу указать нужные колонки: with('customer:id,name'). Но ключи связи в списке обязаны быть: для belongsTo это id родителя, для hasMany — внешний ключ. Если их пропустить, связь сломается без всяких ошибок:

Order::with('items:id,quantity')->find(1);              // items пуст: нет order_id
Order::with('items:id,order_id,quantity')->find(1);     // работает
Order::with('customer:name')->find(1)->customer;        // null: нет id

with, load и loadMissing

Когда модели уже получены (например, из пагинатора или через route model binding), with() не применить. Тут нужна ленивая жадная загрузка:

$orders = Order::orderBy('id')->limit(100)->get();
$orders->load('customer');           // всегда делает запрос
$orders->loadMissing('customer');    // только для тех моделей, где связь ещё не загружена

На сотне заказов load() даёт те же 2 запроса (4,4 мс), что и with('customer').

Ловим N+1 автоматически

Просмотром страниц N+1 находится лишь там, куда заглянул сам разработчик. Надёжнее вообще запретить lazy loading: Model::preventLazyLoading() вызывается в AppServiceProvider::boot(), после чего любое обращение к незагруженной связи бросает LazyLoadingViolationException:

Model::preventLazyLoading(! $this->app->isProduction());

В прогоне сообщение выглядело так: «Attempted to lazy load [customer] on model [App\Models\Order] but lazy loading is disabled». На dev и в тестах исключение превращает N+1 в красный тест. На production такой режим опасен: забытая связь уронит страницу, которая раньше просто работала медленно. Документация тоже показывает вариант с отключением в production, а handleLazyLoadingViolationUsing() позволяет ограничиться записью в лог:

Model::preventLazyLoading();

// use Illuminate\Database\Eloquent\Model;
// use Illuminate\Database\LazyLoadingViolationException;
Model::handleLazyLoadingViolationUsing(function (Model $model, string $relation) {
    if (app()->isProduction()) {
        Log::warning('Lazy loading', ['model' => $model::class, 'relation' => $relation]);
        return;
    }

    throw new LazyLoadingViolationException($model, $relation);
});

Ловим нарушения в тестах

Запрет из boot() действует и в тестах, однако тогда падать будут и обращения к связям внутри фабрик и хелперов. Если защита нужна только для самих тестов страниц, её можно включить в setUp() базового класса feature-тестов:

protected function setUp(): void
{
    parent::setUp();

    Model::preventLazyLoading();   // N+1 на странице превращается в упавший тест
}

Теперь каждый тест, открывающий страницу списка, сам сообщит о забытом with(), а число запросов дополнительно проверяется через getQueryLog(). Приёмы дополняют друг друга: первый ловит обращения к связям, второй — рост числа запросов из других источников (подсчёты в цикле, повторные find()).

shouldBeStrict

Есть ещё Model::shouldBeStrict(). В коде 13.x один его вызов включает preventLazyLoading(), preventSilentlyDiscardingAttributes() и preventAccessingMissingAttributes(): под запретом оказываются не только lazy loading, но и молчаливое отбрасывание не-fillable атрибутов, и чтение отсутствующих атрибутов. Отдельно метод в документации не описан, а раздел «Configuring Eloquent Strictness» перечисляет эти три запрета по одному, так что включать shouldBeStrict() стоит, понимая, что именно он даёт.

Автоматическая жадная загрузка

С Laravel 12.8 доступен обратный подход: Model::automaticallyEagerLoadRelationships() в boot(). Когда код впервые обращается к незагруженной связи, Eloquent загружает её сразу для всей коллекции, из которой пришла модель. Для отдельной коллекции есть $collection->withRelationshipAutoloading().

В прогоне цикл из начала статьи (customer и items->count()) с включённой функцией сделал 3 запроса вместо 201 (11,8 мс). Вместе с preventLazyLoading() исключения не последовало: автозагрузка срабатывает раньше проверки. Дальше идёт авторский вывод, а не утверждение из документации: N+1 исчезает без правок кода, но проблема становится невидимой, а связи всё равно грузятся целиком (как в варианте с items->count() выше). Для диагностики лучше подходит preventLazyLoading(), а автозагрузку разумно держать как страховку на уже существующем коде.

Счётчики и агрегаты без загрузки моделей

Чтобы узнать число связанных записей, сами записи загружать не нужно: withCount() добавляет подзапрос в основной SELECT. Есть и родственные методы — withExists(), withSum(), withAvg(), withMin(), withMax():

$orders = Order::query()
    ->withCount('items')                                     // items_count
    ->withExists('items')                                    // items_exists
    ->withSum('items', 'quantity')                           // items_sum_quantity
    ->withCount(['items as big_items_count' => fn ($q) => $q->where('quantity', '>', 1)])
    ->orderBy('id')->limit(100)->get();                      // 1 запрос

Все четыре агрегата приходят одним запросом (3,6 мс на сотне заказов); для первого заказа получилось items_sum_quantity = 11 и big_items_count = 4. Если withCount() сочетается с select(), агрегаты нужно вызывать после select(), иначе их колонки в выборку не попадут.

Выражение $order->items->count() загружает все позиции ради одного числа: count() считает уже полученную коллекцию, а не строки в БД. Для одной модели вместо него подойдут $order->items()->count() (один count(*)) и $order->items()->exists() для проверки наличия.

Задача Метод
Связь нужна для всех моделей запроса with()
Модели уже получены load() или loadMissing()
Нужно только число, наличие или сумма withCount(), withExists(), withSum()
Связь нужна почти везде automaticallyEagerLoadRelationships() как страховка

Лишние данные

Передача ненужного тоже стоит денег. Несколько правил:

  • select('id', 'total') вместо select *, особенно если в таблице есть text и json;
  • pluck('name', 'id') для справочников и выпадающих списков: модели не создаются;
  • exists() вместо count() > 0 и first();
  • toBase() или DB::table() для отчётов, где методы модели не нужны;
  • тяжёлые редко меняющиеся справочники (страны, категории, настройки) — в кэш, чтобы не читать их на каждый запрос.

На 20 000 заказов select * занял 171 мс и 24,2 МБ, select id, total — 152 мс и 21,8 МБ, а toBase() — 12 мс и 9,9 МБ. Если тяжёлых колонок в таблице нет, select() почти ничего не экономит: основные затраты уходят на гидратацию моделей (превращение строк в объекты), а toBase() её пропускает.

EXPLAIN и индексы

Прежде чем разбирать запрос, его нужно увидеть. План стоит смотреть на данных, похожих на боевые: на пустой dev-базе оптимизатор строит план по статистике таблицы, и медленный запрос кажется быстрым. toSql() возвращает шаблон с ?, а dumpRawSql() и ddRawSql() из документации Laravel 13 выводят SQL с подставленными значениями. Метод toRawSql() есть в билдере, но в документации не описан; в прогоне он работает.

Возьмём пример: последние оплаченные заказы начиная с середины 2024 года.

$orders = Order::where('status', 'paid')
    ->where('created_at', '>=', '2024-06-01')
    ->orderByDesc('created_at')
    ->limit(50);

DB::select('EXPLAIN '.$orders->toSql(), $orders->getBindings());

Без индекса (в таблице только первичный ключ и индекс внешнего ключа customer_id) вывод такой:

type: ALL   key: NULL   rows: 996746   Extra: Using where; Using filesort

Как читать ключевые столбцы EXPLAIN (см. документацию MySQL 8.4): type показывает способ доступа (ALL — полный перебор таблицы, лучше ref и range), key — выбранный индекс, rows — оценку числа просматриваемых строк, Extra — детали (Using filesort означает сортировку вне индекса). Запрос выполнялся 669 мс. Составной индекс строится по правилу: сначала колонки с проверкой на равенство (status), затем колонка диапазона и сортировки (created_at).

Schema::table('orders', function (Blueprint $table) {
    $table->index(['status', 'created_at']);
});

После миграции EXPLAIN выдаёт type: range, key: orders_status_created_at_index и Extra: Using index condition; Backward index scan — сортировка идёт по индексу в обратном порядке. Время упало до 1,4 мс. Индексы на внешние ключи, кстати, создаются автоматически при foreignId()->constrained(); подробнее — в статье про проверку внешних ключей в MySQL.

Индекс есть, но не используется

Чаще всего индекс ломает функция над колонкой. whereDate('created_at', '2024-06-15') превращается в date(created_at) = '2024-06-15', и искать по индексу created_at MySQL уже не может. При индексе (status, created_at) в прогоне работала только часть status (rows около 498 тысяч), запрос шёл 69 мс. Замена условия диапазоном вернула поиск в индекс:

->whereBetween('created_at', ['2024-06-15 00:00:00', '2024-06-15 23:59:59'])   // 8,2 мс, rows: 720

Из того же разряда LIKE '%текст' (ведущий %), сравнение колонки со значением другого типа (строки с числом) и неверный порядок колонок в составном индексе.

Большие таблицы

Пагинация

paginate() выполняет count(*) и запрос с LIMIT … OFFSET …, а OFFSET вынуждает сервер прочитать и выбросить все пропущенные строки. Замеры на 1 млн заказов с сортировкой по id, по сто записей на страницу:

Метод Страница 1 Страница 5000 Страница 10 000
paginate(100) 85,5 мс 246,4 мс 438,2 мс
simplePaginate(100) 2,3 мс 166,8 мс 498,3 мс
cursorPaginate(100) 3,4 мс 6,7 мс 4,1 мс

Для cursorPaginate() в колонках указано положение курсора: начало, id > 499900 и id > 999900. Вместо OFFSET он строит where id > ?, то есть в SQL получается select * from orders where (id > 999900) order by id asc limit 101. simplePaginate() избавляется от count(*) (это заметно на первой странице), но OFFSET сохраняет.

Использование выглядит как Order::orderBy('id')->cursorPaginate(100), а ссылки «дальше» и «назад» несут закодированный курсор в параметре cursor.

В документации у курсора есть ограничения: обязателен order by, сортировка идёт по уникальной колонке или их комбинации, null в этих колонках не поддерживается, номеров страниц нет — только «вперёд» и «назад». Быстрее всего он работает, когда колонки сортировки проиндексированы.

Обход таблицы целиком

Для пакетной обработки данные читаются порциями. Ниже замеры прохода по всему 1 млн заказов (порция 1000, один прогон):

Способ Запросов Время Пик памяти
get() 1 16,5 с 1217 МБ
chunk(1000) 1001 169 с 3,0 МБ
chunkById(1000) 1001 9,5 с 3,3 МБ
lazyById(1000) 1001 9,6 с 4,3 МБ
cursor() 1 29,0 с 66 МБ

get() помещается в память только на «толстом» сервере. chunk() держит память в узде, но внутри использует OFFSET, и чем ближе конец таблицы, тем дороже каждая порция. chunkById() и lazyById() строят условие id > последний id и работают равномерно. lazyById() при этом отдаёт плоский поток LazyCollection, с которым удобнее в цикле. cursor() делает один запрос, но драйвер PDO буферизует результат, потому память растёт (66 МБ на миллион строк), а eager loading для него недоступен.

Правило выбора короткое: для фоновых задач с обновлением записей — chunkById(); для потокового чтения в цикле, экспорта и отчётов — lazyById(); chunk() без изменения фильтруемых колонок допустим на небольших таблицах; cursor() подходит для сотен тысяч строк без связей. Размер порции (здесь 1000) задаёт баланс между числом запросов и расходом памяти, поэтому подбирать его лучше замером на собственных данных.

У chunk() есть и вторая беда: если менять колонку, по которой идёт фильтр, он пропускает записи. Документация предупреждает о «unexpected and inconsistent results». Из 2500 заказов со статусом new в тесте обновление через chunk() затронуло только 1500:

Order::where('id', '<=', 10000)->where('status', 'new')
    ->chunk(500, function ($orders) {
        foreach ($orders as $order) {
            $order->update(['status' => 'paid']);   // строка выпадает из выборки
        }
    });
// обработано 1500, осталось 1000 заказов new

Дело в том, что обработанные строки исчезают из выборки, а OFFSET следующей порции отсчитывается уже по ней. chunkById() на тех же данных обработал все 2500 и оставил 0.

Наконец, chunkById() и lazyById() добавляют собственное условие по id, поэтому свои orWhere нужно группировать в замыкание: иначе приоритет and над or искажает выборку:

// неверно: where status = 'new' or status = 'paid' and id > 4
Order::where('status', 'new')->orWhere('status', 'paid')->chunkById(1000, $callback);

// верно: where (status = 'new' or status = 'paid') and id > 4
Order::where(fn ($q) => $q->where('status', 'new')->orWhere('status', 'paid'))
    ->chunkById(1000, $callback);

Чек-лист «Eloquent тормозит»

  1. Посчитать запросы на проблемной странице (DB::listen, Debugbar).
  2. Найти повторяющиеся запросы с разными id — это N+1.
  3. Включить preventLazyLoading() на dev и в тестах, на production — логирование.
  4. Вылечить N+1: with(), для готовых моделей load()/loadMissing().
  5. Заменить загрузку ради числа на withCount(), withExists(), withSum().
  6. Выбрать нужные колонки (с ключами связи), для отчётов — toBase().
  7. Прогнать медленный запрос через EXPLAIN: type: ALL и Using filesort — кандидат на индекс.
  8. Проверить, не мешает ли индексу функция над колонкой (whereDate, LIKE '%…').
  9. Большие списки — cursorPaginate(), пакетную обработку — chunkById() или lazyById().

Итог

Оптимизация Eloquent укладывается в три шага: измерить число запросов, убрать лишние (with, withCount, выбор колонок), а оставшиеся проверить через EXPLAIN и индексы. На больших таблицах вместо OFFSET и get() выручают cursorPaginate() и chunkById()/lazyById(), а от N+1 в автоматическом режиме страхует preventLazyLoading().

Похожие