Как работает метод НайтиПоНомеру и зачем нужен параметр ДатаИнтервала

При изучении чужого кода или разработке собственных механизмов обмена данными программисты 1С часто сталкиваются с конструкциями вида Документы.СчетФактураВыданный.НайтиПоНомеру(НомерДок, '20220109'). На первый взгляд может показаться странным использование конкретной даты, например, 9 января 2022 года. Почему выбрано именно это число? Влияет ли оно на точность поиска? Разберем детально механику работы этого метода, чтобы исключить любые сомнения.

Суть метода НайтиПоНомеру и его параметры

Метод НайтиПоНомеру предназначен для быстрого поиска ссылки на документ по его текстовому или числовому номеру. Рассмотрим синтаксис этого метода:

НайтиПоНомеру(<Номер>, <ДатаИнтервала>)

1. <Номер> — это искомый номер документа. Крайне важно помнить, что тип передаваемого значения должен строго совпадать с типом номера, установленным в метаданных документа (Строка или Число).
2. <ДатаИнтервала> — необязательный параметр типа Дата. Именно он вызывает больше всего вопросов у начинающих разработчиков. Эта дата указывает системе, в каком временном промежутке (интервале уникальности) следует искать документ.

Проанализируем ситуацию, когда в коде указан литерал даты '20220109'. Это стандартный формат записи даты в языке 1С: 'ГГГГММДД'. В данном случае это 9 января 2022 года.

Как параметр ДатаИнтервала связан с периодичностью

Для того чтобы понять, почему конкретный день и месяц часто не имеют значения, нам необходимо заглянуть в конфигуратор. У каждого документа на закладке «Нумерация» есть свойство Периодичность. Оно определяет, как часто сбрасывается счетчик номеров документов.

Рассмотрим основные варианты периодичности:

• В пределах года: Номера уникальны только в рамках одного календарного года. С 1 января нумерация начинается заново. В этом случае, если мы укажем '20220109', система поймет, что поиск нужно вести среди всех документов за весь 2022 год (с 01.01.2022 по 31.12.2022).
• В пределах месяца: Номера уникальны внутри каждого месяца. Здесь дата '20220109' ограничит поиск только январем 2022 года.
• В пределах дня: Поиск будет идти строго за указанное число.
• Непериодический: В этом случае параметр ДатаИнтервала полностью игнорируется платформой, так как номера уникальны во всей таблице за все время существования базы.

Таким образом, если у документа СчетФактураВыданный установлена периодичность «В пределах года», то для платформы нет никакой разницы, напишете вы '20220101', '20220109' или '20221231'. Результат будет идентичным — поиск в интервале 2022 года.

Почему в коде встречаются «странные» даты?

Выясним причину появления даты '20220109' в примере. Чаще всего это происходит по одной из трех причин:

1. Первый рабочий день: Программист мог использовать дату первого рабочего дня года просто «из головы».
2. Контекст обработки: Если обработка писалась для исправления данных за конкретный период, разработчик мог вставить любую дату, входящую в этот период.
3. Случайный выбор: Поскольку для годовой периодичности важен только год, конкретика дня и месяца не играет роли, и автор кода мог не уделять этому значения.

Технические нюансы и правильная обработка результата

При использовании НайтиПоНомеру важно учитывать несколько критических моментов, которые помогут избежать ошибок в логике программы.

1. Соответствие типов и префиксов. Если в вашей базе включена префиксация (например, номера выглядят как «МС00001»), то поиск по номеру «1» или числу 1 не даст результата. Нужно передавать полную строку с учетом лидирующих нулей и префиксов организации или подразделения.

2. Проверка на пустую ссылку. Метод всегда возвращает объект типа ДокументСсылка. Если документ не найден, система не выдаст ошибку и не вернет Неопределено. Она вернет пустую ссылку. Проверять результат нужно только так:

Результат = Документы.СчетФактураВыданный.НайтиПоНомеру(НужныйНомер, ДатаДляПоиска);
Если Результат.Пустая() Тогда
    Сообщить("Документ с таким номером в данном периоде не найден!");
КонецЕсли;

3. Проблема дублей. В редких случаях (например, при программной записи документов с отключенной проверкой уникальности) в одном периоде могут оказаться два документа с одинаковым номером. Метод НайтиПоНомеру вернет только одну, самую первую найденную ссылку. Если вам нужно найти все дубли, придется использовать объект Запрос.

Сравнение производительности

Проанализируем ситуацию с точки зрения быстродействия. Метод НайтиПоНомеру работает чрезвычайно эффективно. Это связано с тем, что платформа 1С на уровне базы данных поддерживает специальные индексы по полям «Номер» и «Период». Использование этого метода предпочтительнее, чем написание запроса вручную, если вам нужно найти один конкретный документ по его номеру в известном периоде.

Практический пример: универсальный поиск за текущий год

Посмотрим на пример кода, который делает поиск более универсальным, не привязываясь к «жестким» литералам даты, что считается хорошим тоном в разработке:

// Ищем документ по номеру в текущем календарном году
ИскомыйНомер = "А-45";
ДатаПоиска = ТекущаяДата(); // Платформа сама определит год из текущей даты
НайденнаяСсылка = Документы.РеализацияТоваровУслуг.НайтиПоНомеру(ИскомыйНомер, ДатаПоиска);

Если Не НайденнаяСсылка.Пустая() Тогда
    // Работаем с документом
    Сообщить("Документ найден: " + Строка(НайденнаяСсылка));
КонецЕсли;

В данном примере мы используем ТекущаяДата(), что позволяет коду корректно работать и в 2023, и в 2024 годах без необходимости ручной правки литералов в тексте модуля.

Резюме

Подведем итог нашему разбору. Параметр ДатаИнтервала в методе НайтиПоНомеру — это не дата, с которой начинается поиск, а указатель на временной интервал уникальности. Если вы видите в коде '20220109', знайте: программа просто «сообщает» платформе, что искать нужно в том году (или месяце), в который попадает этот день. Для обеспечения долговечности кода рекомендуется использовать расчетные даты или параметры, чтобы избежать необходимости ежегодного обновления «зашитых» в код строковых литералов.