Установка excelize и первый файл

Установка excelize укладывается в две команды терминала, как любая библиотека Go. Если модуля в папке ещё нет, сначала go mod init с именем модуля — например example.com/report: без go.mod менеджер зависимостей не знает, куда записывать пакеты. Затем go get github.com/xuri/excelize/v2 — менеджер скачает последнюю стабильную версию и зафиксирует её в go.mod, а контрольные суммы появятся в go.sum. Читается путь импорта так: xuri — аккаунт автора на GitHub, excelize — репозиторий, /v2 — мажорная версия по правилам семантического версионирования Go: вторая версия библиотеки обязана жить за суффиксом, и без него компилятор не найдёт пакет. Имя пакета при этом осталось коротким — excelize: импортируете длинный путь, а в коде пишете excelize.NewFile, без алиасов. Требования к минимальной версии Go меняются между релизами, поэтому перед установкой гляньте раздел Requirements в README выбранного тега — это честнее, чем гадать по ошибкам компилятора.

Теперь excelize пример целиком — программа, которую вы будете писать в каждом скрипте курса с минимальными вариациями. Логика ровно из прошлого урока: NewFile создаёт книгу в памяти с листом Sheet1 по умолчанию, SetCellValue кладёт значения в ячейки, SaveAs сериализует книгу на диск, Close прибирает за дескриптором. Обратите внимание на обработку ошибки SaveAs: запись на диск может провалиться по массе причин — нет прав на папку, путь занят каталогом, диск переполнен, — и молча проглотить эту ошибку значит оставить пользователя с файлом, которого нет. В скриптах честным решением будет паника: утилита без результата бессмысленна, и упасть с понятным сообщением — быстрее, чем отработать впустую. В сервисах вместо panic вернут ошибку наверх с контекстом, но привычка проверять err у каждого вызова, который может провалиться, ставится именно здесь. Отдельное слово об именах файлов: если отчёт генерируется по расписанию, добавляйте в имя дату или период — report-2024-06.xlsx информативнее report.xlsx и никогда не затирает соседний, потому что SaveAs перезаписывает молча. Файл в текущей папке удобен для скрипта и плох для сервиса: там используйте путь из конфигурации и создавайте каталог заранее, потому что SaveAs не умеет mkdir и вернёт ошибку на отсутствующей папке.

Файл создан — теперь посмотрите на него глазами, для этого и писалась честная теория первого урока. Переименуйте report.xlsx в zip и распакуйте: увидите xl/workbook.xml со списком листов, где Book указывает единственный Sheet1, и xl/worksheets/sheet1.xml, где в строке с номером 1 лежат две ячейки — r=A1 со ссылкой на строку в общей таблице строк и r=A2 с числом 1250000 как есть, без кавычек. Это и есть главное следствие двоичного устройства формата, о котором мы говорили: текст уехал в xl/sharedStrings.xml, а числа хранятся числами — Excel будет считать с ними, как с числами, а не как с текстом, который притворяется числом. Откройте файл в LibreOffice, таблицах Google или самом Excel — всё выглядит ожидаемо, потому что excelize пишет корректный OOXML, а не файл, который Excel вылечит предупреждением. Такая проверка занимает минуту и экономит часы: дифф между ожидаемым и фактическим содержимым архива — самый быстрый способ понять, что именно вы записали. Пригодится и обратная привычка: присылайте распакованный файл, когда просите помощи у коллеги — вместо скриншота Excel-а он отвечает на вопрос «что реально лежит в ячейках» без вариантов толкования.

Типичные ошибки при установке excelize сводятся к трём семьям. Первая — старый путь импорта: github.com/360EntSecGroup-Skylar/excelize из статей до 2021 года не резолвится, и никакой go mod tidy его не спасёт — меняйте на github.com/xuri/excelize/v2. Вторая — сеть: в закрытых контурах go get не может дотянуться до прокси по умолчанию, поэтому настройте GOPROXY на внутренний прокси-сервер или вендорьте зависимости через go mod vendor, чтобы сборка не ходила в интернет. Третья — версия Go: новые релизы excelize поднимают минимальную версию языка, и ошибка выглядит как загадочный ругательный листинг на свежий синтаксис внутри зависимостей — лечится либо обновлением Go, либо закреплением более старого тега библиотеки, который ваши версии поддерживают. Отдельно напомним про go mod tidy: он вычищает неиспользуемые зависимости и дописывает недостающие после ручных правок go.mod, поэтому в конце любой возни с зависимостями стоит прогнать его перед коммитом.

Первый файл — это скелет, на который дальше наращиваются мышцы. Следующий урок про листы книги научит создавать вкладки с русскими названиями вместо Sheet1, переключать активный лист и удалять лишнее — без этого любой отчёт выглядит как черновик. Потом разберём запись ячеек всерьёз: у SetCellValue за внешней простотой скрываются правила типов, из-за которых теряются ведущие нули артикулов и точность длинных номеров. Стили — шрифты, заливки, границы — добавят файлу презентабельность, формулы посчитают итоги на стороне Excel, а потоковые режимы позволят выгружать миллионы строк без переполнения памяти. Финальная точка курса — итоговый проект: генератор отчёта продаж с вкладками, итогами и диаграммой, где каждый вызов из этого урока встретится вам снова. Никакой спешки: скелет должен дожить до конца курса без изменений, поэтому проверьте его ещё раз перед следующим уроком. Если хочется углубиться в механику модулей Go — версионирования, replace-директив, приватных репозиториев — вернитесь к материалам базового курса: подробный разбор пакетов и модулей есть в уроке про пакеты и модули продвинутого трека, а мы остаёмся в рамках одной зависимости и двигаемся дальше.