Find и курсор: чтение списков

Вызов выглядит так: cursor, err := coll.Find(ctx, filter). Контекст задаёт дедлайн, фильтр — условия поиска (сейчас достаточно bson.M{"status": "paid"}), опции через options.Find() добавят сортировку, лимит и проекцию — но об этом дальше по курсу. Возвращаемая пара уже знакома по вставкам: курсор и ошибка. Ошибка из Find — это ошибки самой команды: сеть, таймаут, опечатка в операторе фильтра; проверяйте её сразу и без вопросов. Дальше начинается работа с *mongo.Cursor. Первая партия документов приезжает вместе с ответом на find — по умолчанию до 101 документа; если выборка больше, драйвер запрашивает следующие партии командой getMore, и именно во время этих доборок могут всплыть ошибки сети. Поэтому после цикла обязана стоять проверка cursor.Err() — она вернёт последнюю ошибку, виденную курсором, или nil. Сам цикл — обычный for с условием cursor.Next(ctx): метод блокируется до следующего документа и возвращает true, пока есть что читать, false — когда данные кончились или случилась ошибка. Текущий документ курсор отдаёт через cursor.Decode(&doc) — та же распаковка BSON в структуру по bson-тегам, что у FindOne. Пустая выборка — не ошибка: ни одного Next true не случится, цикл не выполнится ни разу, err останется nil; где ErrNoDocuments, о котором писал шестой урок, там не нужен.

All — короткий путь, и в большинстве сервисных сценариев он правильный: страница каталога, список ролей пользователя, справочник городов. Данные гарантированно помещаются в память — скажем, до десятков тысяч строк, — и вам нужен срез, чтобы отдать его в JSON, отсортировать или посчитать len. Всё, что делает All, легко написать вручную циклом, но шаблон повторяется на каждом углу, и драйвер оформил его методом. Три детали, о которых стоит знать. Первая: All полностью перезаписывает целевой срез — передавать его можно смело, старые значения исчезнут. Вторая: если курсор уже частично итерировался вручную, All включит в результат только непрочитанные документы — смешивать ручной цикл и All в одном курсоре не стоит, это путь к «половинным» спискам. Третья: All закрывает курсор сам — даже если контекст отменён посреди чтения, закрытие уедет через context.Background(), чтобы серверный курсор не остался висеть. Отсюда же ответ на частый вопрос: ставить ли defer cursor.Close рядом с All — можно и полезно, Close идемпотентен, второй вызов ничего не изменит; правило проекта «каждый Find получает defer Close» выполняется без исключений и не конфликтует с All. Если же выборка измеряется миллионами документов, All перестаёт быть коротким путём и становится проблемой: дальше — про ручную итерацию.

Ручной цикл нужен там, где документы не должны копиться: потоковая обработка, запись в другой канал, агрегация на лету с сбросом результата после каждого элемента. Схема одна и та же, и её стоит выучить до автоматизма. for cursor.Next(ctx) { ... } — тело выполняется для каждого документа; внутри cursor.Decode(&order) распаковывает текущий документ, после чего вы делаете своё дело: пишете в канал, обновляете индекс, отправляете письмо. Выход из цикла — не всегда конец данных: Next возвращает false и на исчерпании, и на ошибке. Различить их — работа cursor.Err(): после цикла nil означает «данные кончились штатно», не-nil — «поток оборвался». Проверка не опциональна: без неё оборванная сеть выглядит как аккуратный ранний конец списка, и отчёт покажет половину заказов без единого сообщения об ошибке. Внутри тела тоже можно ошибиться — Decode вернёт ошибку несовместимого типа; обрабатывайте её так же честно, как и сетевую. Отдельный сценарий — tailable-курсоры, которые не закрываются после исчерпания и ждут новых документов; для них существует неблокирующий TryNext, а основная работа с потоками событий живёт в Change Streams — девятнадцатом уроке, до которого мы дойдём после агрегаций. Для обычных списков правило простое: Next блокирующий, false — сигнал выйти, cursor.Err() — сигнал разобраться.

Поток документов настраивается, и главное колесо — размер партии. По умолчанию первый ответ find несёт до 101 документа, а каждая следующая порция ограничена шестнадцатью мегабайтами BSON — сервер упакует в неё столько документов, сколько влезет. Если документы тяжёлые, порция может состоять из двух-трёх штук; если лёгкие — из тысяч. Опцией options.Find().SetBatchSize(n) вы задаёте свою величину, и вот когда это осмысленно. Меньше партии — для узких клиентов и тяжёлых документов: каждая итерация тянет меньше памяти, но чаще ходит по сети, и общее число обращений к серверу растёт. Больше — для выгрузок лёгких документов: меньше округов, выше пропускная способность; но и буфер между чтениями толще. Ручной цикл с Next выбирает документы из текущей партии без сети и отправляется за новой только при её исчерпании, поэтому BatchSize — настройка не памяти вашего процесса, а округов. С cursor.All связь прямая: он всё равно вычитает всё до конца, и партия влияет только на число сетевых вызовов по пути. Не путайте с лимитом: Limit ограничивает количество документов результата, BatchSize — только способ доставки; страница каталога на двадцать записей обычно укладывается в дефолт и в настройках не нуждается.

Что происходит, если Close забыли? Курсор — не объект в памяти драйвера, а ресурс на сервере: MongoDB держит состояние выборки — позицию, буферы, блокировки — и ждёт, когда клиент запросит следующую партию или закроет курсор. Дефолтный таймаут бездействия — десять минут: только спустя их сервер сам приберёт забытый курсор, и всё это время он занимает память и слот в списке открытых курсоров. Один забытый курсор в тесте — мелочь; утечка в горячем хендлере, который выполняется по сто раз в минуту и падает на середине итерации без defer Close, — уже десятки тысяч мёртвых курсоров до конца смены. Хронический симптом — ошибки вида cursor not found: клиент почему-то обращается к курсору, который сервер уже зачистил, — значит, где-то курсор жив дольше положенного или его таскают между горутинами. Отсюда три привычки. Первая: defer cursor.Close(ctx) пишется в ту же секунду, что и сам Find, — механически, как defer resp.Body.Close() в HTTP. Вторая: курсор не переезжает между горутинами — итерирует тот, кто создал. Третья: долгие фоновые выгрузки, которые реально живут дольше десяти минут, получают опцию NoCursorTimeout — осознанно, с комментарием, потому что она отключает страховку сервера. А главный аварийный рубильник — killCursors через mongosh, когда нужно прибрать чужой мусор прямо сейчас.