Типичные ошибки: стили, строки и ссылки

Стиль в xlsx — это запись в общей таблице стилей книги, и NewStyle лишь добавляет туда запись и возвращает её номер. Дедупликации нет: два одинаковых вызова дают две записи, а вызов в цикле по ячейкам — таблицу на тысячи строк и файл, который Excel открывает мучительно. Ошибки excelize со стилями лечатся одним правилом: один NewStyle на вид оформления, кэш идентификаторов на время работы генератора. Вторая ловушка — применение: SetCellStyle работает и с ячейкой, и с диапазоном, поэтому заливка шапки A1:F1 — это один вызов, а не шесть. Третья — условное форматирование: у него свой конструктор NewConditionalStyle из урока про условное форматирование, и попытка передать туда идентификатор обычного стиля приводит к молчаливому нулю оформления. Четвёртая — форматы чисел: они задаются полем NumFmt или пользовательской строкой в структуре Style, а не строкой вроде «0.00» отдельным вызовом, и путаница здесь даёт ячейки, которые выглядят правильно, но не суммируются.

Индексация в excelize — с единицы, и первая строка листа — это A1, а не A0: сдвиг на единицу всплывает в координатах, номерах строк в журналах ошибок и границах циклов. Хвостовые пустые ячейки вы уже встречали в уроке про импорт: срез строки из GetRows короче ширины листа, и прямое обращение по индексу паникует на первой же строке с дырой. Объединённые ячейки — отдельная история: значение живёт только в верхней левой ячейке диапазона, остальные пусты, и чтение правой части MergeCell даёт пустую строку даже там, где на экране Excel видно содержимое. Для работы с объединениями есть GetMergeCells — список всех диапазонов листа со стартовой и конечной осями и методом чтения значения. Отдельные грабли — вставка строк: InsertRows двигает содержимое, но ссылки в формулах за сдвинутыми строками, как правило, не пересчитывает, поэтому после вставки стоит открывать файл и проверять итоги. И последнее: колонки и строки в API именуются по-разному — буквы для колонок и числа для строк, и перепутанный порядок аргументов даёт запись не туда без всякой ошибки.

Книга excelize держит распакованные части архива в памяти и временные ресурсы, поэтому Close ставится через defer сразу после создания или открытия — это такой же рефлекс, как defer rows.Close у курсора базы. После Close файл не читается: вызов GetRows вернёт ошибку про закрытый архив, и это не паника, а тихая ошибка, которую легко пропустить, если её игнорировать. SaveAs проверяется в месте вызова: несуществующая директория, занятый файл или недопустимое имя листа вернут ошибку, а без проверки отчёт молча не сохранится, и обработчик ответит клиенту успехом. Открытие чужого файла — OpenFile — читает весь архив в память, и на гигантских файлах это лимит окружения, о котором мы говорили в уроке про производительность; защищённые книги открываются опцией с паролем. Формулы со ссылками на лист, чьё имя содержит пробел, требуют апострофов: формула со ссылкой на Итоги 2024 без кавычек-апострофов не сработает, а после RenameSheet стоит проверить ссылки на переименованный лист — часть этой работы библиотека берёт на себя, но проверка файла после переименования дешевле ночного инцидента.

Почти каждый вызов excelize возвращает ошибку, и главная граблина — не в библиотеке, а в игнорировании: SetCellValue с опечаткой в имени листа вернёт ошибку, которую проглотило подчёркивание, и файл соберётся с дырой там, где по плану была колонка. Рабочая дисциплина простая: ошибки обрабатываются в месте вызова либо через маленькую обёртку, которая логирует координату и шаг генерации; подчёркивание допустимо только там, где отказ ячейки не влияет на результат, и это решение осознанное. Ошибки стоит разделять на два сорта: ошибки данных — битое значение, нестандартный формат — и ошибки библиотеки — неверное имя листа, нечитаемый файл; первые логируются и копятся, вторые останавливают генерацию. Отдельная линия обороны — тесты: чтение файла обратно ловит пропавшую колонку и пустую шапку на этапе CI, а не на телефоне заказчика. Грабли excelize в проверке ошибок не выглядят эффектно, но именно они отличают генератор, который доверяют ночным расписаниям, от генератора, за которым следят вручную.