Файлы и ввод-вывод

Пора вывести программу за пределы собственной памяти. До сих пор каждый пример курса начинался и заканчивался в оперативной памяти: срезы, карты, каналы — всё это исчезало вместе с процессом. Файл — первый внешний мир, с которым программа говорит напрямую, и чтение файлов в Go устроено так, что вы уже знаете половину языка, на котором этот разговор идёт. Запрос «чтение файлов go» на самом деле распадается на три навыка: выполнить один вызов целиком (os.ReadFile), работать потоком через контракт io.Reader и ускорить оба пути буферизацией bufio. Этим трём навыкам и посвящён урок.

Начнём с карты местности. В стандартной библиотеке за ввод-вывод отвечает связка пакетов: os даёт доступ к файловой системе — открыть, создать, прочитать целиком, записать целиком, спросить размер; io описывает два главных контракта — Reader и Writer — и сигналы вроде io.EOF; bufio оборачивает любой поток буфером, чтобы не дёргать диск (или сеть) на каждый байт. Эти три слоя лежат друг на друге: os.File умеет и Reader, и Writer, bufio принимает любого Reader и отдаёт тоже Reader, а функция вроде fmt.Fprintf согласна писать в ANY Writer — в файл, в сеть, в буфер в памяти. Поэтому «прочитать файл» и «прочитать HTTP-ответ» — это один и тот же цикл с разными источниками.

Договоримся о честности песочницы заранее, как в прошлом уроке. Резервный движок знает только fmt, strings, strconv, math, sort, errors и time — пакет os, bufio и io он не исполняет вовсе, и мы зафиксируем точные тексты отказов. Основной движок (yaegi) исполняет настоящие файловые операции: os.WriteFile, os.ReadFile, bufio.Scanner — файлы реально создаются в /tmp, и вывод раннеров детерминирован. А там, где файлы недоступны, мы построим Reader своими руками из строки — чистый Go без единого импорта из «файловой» тройки: контракт io.Reader — это несколько строк кода, и никто не мешает реализовать его на строке. Такой ручной Reader исполняется обоими движками и станет нашим полигоном.

Вспомним контракт из урока про интерфейсы — теперь он понадобится ежедневно. io.Reader — это один метод: Read(p []byte) (n int, err error). Смысл подписи: потребитель вызывает Read и ПЕРЕДАЁТ свой буфер p — «вот память, заполняй»; Read кладёт туда сколько смог и возвращает n — сколько байт реально записал; err — ошибка, и её особая форма io.EOF означает «данные кончились, это не сбой». Ключевые правила контракта: n может быть меньше len(p) — и это норма, а не ошибка; буфер отдаёт потребитель, поэтому размер порции выбирает тот, кто читает; io.EOF возвращается только вместе с n = 0 — «прочитал что-то и заодно EOF» контракт запрещает. io.Writer — зеркало: Write(p []byte) (n int, err error) — «вот байты, возьми сколько сможешь и скажи».

Отсюда канонический цикл чтения, который вы будете писать всю карьеру: объявить буфер, вызывать Read в цикле, прибавлять n к счётчику, при err != nil — выйти, причём io.EOF — это выход ШТАТНЫЙ, а всё остальное — по-настоящему ошибка. Именно этот цикл мы собирали в десятом уроке поверх strings.NewReader; сегодня источник станет файлом, но цикл не изменится ни на букву — в этом и смысл контракта. Файл, сетевое соединение, HTTP-тело, gz-архив, криптографический поток — всё говорит на одной сигнатуре Read, и функция, написанная против io.Reader, работает со всеми источниками сразу.

Почему нельзя «просто прочитать всё сразу»? Можно — os.ReadFile так и делает, — но у потока может не быть конца или его размер может быть гигабайтом: сетевое соединение бесконечно, конвейер (pipe) отдаёт байты по мере появления. Контракт Read придуман именно для таких источников: вы никогда не просите больше, чем ваш буфер, и никогда не держите в памяти больше одной порции. А буфер — это срез байт, и вот где байтовое мышление прошлого урока включается на полную: make([]byte, 4096) — это заголовок на 24 байта плюс массив на четыре килобайта, и передача его в Read не копирует массив — Read заполняет ВАШУ память, а не свою.

Когда файл небольшой и вам нужны все его байты сразу, ручной цикл не нужен — стандартная библиотека даёт две функции-однострочника. os.ReadFile(path) открывает файл, читает его целиком в память и возвращает пару (data []byte, err error); os.WriteFile(path, data, perm) создаёт (или усекает!) файл и пишет байты целиком, perm — права доступа, обычно 0644: владелец может всё, остальные — только читать. Это «простой путь» урока: два вызова закрывают девять из десяти бытовых задач — прочитать конфиг, сохранить отчёт, перегнать небольшой файл в строку string(data) или обратно []byte(s).

Три детали, на которых спотыкаются. Первая: ReadFile возвращает []byte, а не string — файл с точки зрения Go это БАЙТЫ, и только вы решаете, интерпретировать ли их как текст UTF-8 через string(data); конверсия копирует содержимое, у файла в гигабайт это второй гигабайт памяти. Вторая: os.WriteFile ПЕРЕЗАПИСЫВАЕТ файл с нуля — если там было длинное содержимое, а вы пишете короткое, хвост не «допишется», а исчезнет: файл усекается до нуля перед записью. Дописать в конец (append) через WriteFile нельзя — для этого открывают файл через os.OpenFile с флагом os.O_APPEND, о чём мы поговорим в блоке про os.Open. Третья: err надо проверять на ОБА вызова — ReadFile честно вернёт пустой срез и ошибку, если файла нет, и ошибка эта — обычное значение, которое функция возвращает парой с данными, как мы учились в уроке про обёртывание ошибок.

Где проходит граница применимости простого пути? В памяти. os.ReadFile держит весь файл в памяти разом: лог на сто мегабайт — сто мегабайт, лог на десять гигабайт — уже проблема, и не только памяти: пока файл читается целиком, вы не обработали НИ ОДНОЙ строки, хотя они были готовы с самого начала. Для больших файлов и потоков без конца нужен цикл Read или bufio — об этом ниже. Правило выбора простое: знаете размер и он помещается в память — ReadFile; не знаете или не помещается — поток.

os.ReadFile хорош, пока файл целиком помещается в память. Как только вы хотите читать по кусочку, писать по кусочку или дописывать в конец — нужна ручка на файл: os.File. Две функции её выдают: os.Open(path) открывает файл ТОЛЬКО на чтение, os.Create(path) создаёт файл или усекает существующий в ноль и открывает на запись (права 0666 — уточняются маской umask процесса). Обе возвращают пару `(os.File, error)`, и первая проверка после вызова — err != nil: файла может не существовать, прав может не хватить, путь может оказаться каталогом. Тонкость, которую стоит запомнить: *os.File — это не «файл на диске», а дескриптор открытого файла в вашей программе; сам файл лежит на месте, ручка — в памяти, и её, как всякий ресурс операционной системы, надо закрывать.

Закрытие в Go делают идиомой defer f.Close() сразу после успешного открытия: отложенный вызов сработает при выходе из функции — хоть по return, хоть по панике — и дескриптор вернётся системе. Почему это важно: число открытых дескрипторов на процесс ограничено, программа, теряющая ручки в цикле, упадёт с «too many open files» на тысячах итераций; к тому же незакрытый файл на запись может потерять последние байты, если ОС держала их в своих буферах. А вот обратное заблуждение опаснее: Close — это НЕ запись данных. Данные, застрявшие в буфере bufio.Writer, при Close не дописываются — сначала Flush, потом Close, и к этому мы вернёмся в блоке про буферизацию.

Третий член семейства — os.OpenFile(path, flag, perm) — общий случай: флаги os.O_RDONLY, os.O_WRONLY, os.O_RDWR, os.O_APPEND, os.O_CREATE комбинируются через вертикальную черту, и так делается, например, дозапись в лог: os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644). В уроке нам хватит Open и Create, но знать про OpenFile стоит хотя бы для того, чтобы читать чужой код: это он, а не WriteFile, обеспечивает append-семантику.

Чтение текстового файла построчно — самая частая операция над файлами вообще, и писать её через голый Read с ручным поиском переводов строки никто не хочет. Для этого в пакете bufio живёт Scanner: sc := bufio.NewScanner(f) принимает ЛЮБОГО Reader (файл — Reader, мы это уже знаем) и разбивает поток на «токены» — по умолчанию строки. Цикл выглядит как заклинание: for sc.Scan() { fmt.Println(sc.Text()) } — Scan подготавливает следующую строку и возвращает true, пока строки есть; Text() отдаёт её без завершающего перевода строки. У Scanner есть и Bytes() — те же байты без копирования в строку, — и Err() — ошибка, если цикл кончился НЕ из-за конца данных: Scan возвращает false и на EOF, и на сбое, различать их обязаны вы, вызывая Err после цикла.

Что здесь такого волшебного? Буферизация. Scanner читает из файла не по байту, а большими кусками (стартовый буфер — 4 килобайта, растёт до 64К), ищет '\n' в куске и отдаёт строки из своего внутреннего буфера — диск дёргается в тысячи раз реже. Это та же экономия, что у шин на материнской плате из прошлого урока: за один дорогой ход забираем много дешёвых байт. Но у буфера есть потолок: по умолчанию одна строка не может быть длиннее 64 килобайт (bufio.MaxScanTokenSize), и Scan молча вернёт false с ошибкой «token too long». Логи JSON-строкой на мегабайт Scanner проглотить не сможет, пока вы не увеличите потолок через sc.Buffer(make([]byte, 0, 10241024), 10241024) — известная грабля, о которой честно предупреждает документация.

Scanner — читатель, писателем служит bufio.Writer, но перед ним мы прогоним Scanner по настоящему файлу: откроем через os.Open, поставим defer Close и пройдём циклом. Обратите внимание на типы в цепочке: os.Open вернула *os.File, NewScanner приняла её как io.Reader — файл не знал, что его обернули, а Scanner не знает, что внутри файл: контракт в действии.

Чтение мы ускорили буфером, теперь запись. bufio.NewWriter(f) оборачивает любого Writer в буфер на 4096 байт по умолчанию: все Write и fmt.Fprintf кладут байты НЕ в файл, а в этот буфер в памяти; диск получает данные, когда буфер заполнился, — по 4 килобайта за ход. Экономия та же, что у Scanner, в обратную сторону: тысячи мелких записей складываются в несколько больших. Записываете по одному числу в цикле из десяти тысяч итераций? Без буфера — десять тысяч системных вызовов; с буфером — три. Это самый дешёвый прирост производительности в вводе-выводе, доступный одной строкой кода.

Но у буфера есть обратная сторона, и она — главная ловушка урока: байты в буфере — это ещё НЕ файл. Пока буфер не полон, файл про них не знает. Забыли дописать — данные потеряны при выходе из программы. Метод Flush() выталкивает всё накопленное в настоящий Writer — его вызывают перед завершением записи ВСЕГДА; правильная последовательность на выходе: Flush, потом Close. Проверить, сколько байт ещё сидит в буфере, можно через w.Buffered(), а убедиться, что всё вытолкнуто, — через w.Flush() и проверку его ошибки: Flush тоже возвращает err, и молча проглотить его — значит не заметить сбой записи на самом ответственном шаге.

Тонкость с размерами: bufio.NewWriterSize(f, 1024) делает буфер нужного размера, а если одиночная запись БОЛЬШЕ буфера, Writer не глотает её частями, а пишет напрямую мимо буфера — в файл. Поэтому буферизация ускоряет именно много мелких записей и почти не влияет на несколько больших. И держите в голове asymmetry: у Scanner ошибка достаётся через Err() ПОСЛЕ цикла, у Writer — из каждого вызова Write и из Flush; у обоих ошибка НЕ возвращается там, где вы интуитивно ждёте её увидеть.

Прежде чем читать файл, полезно знать, СКОЛЬКО его. os.Stat(path) возвращает структуру FileInfo с методами Size() (размер в байтах), IsDir(), ModTime() и именем; для несуществующего пути Stat вернёт ошибку — так в Go проверяют существование файла. Size помогает принять решение о стратегии: файл на сотню килобайт — os.ReadFile и не думать, файл на гигабайт — только потоки, файл в сети — размер заранее неизвестен вовсе, значит ReadFile по определению не подходит. Второе применение Stat — метаданные: время модификации для кешей, признак каталога при обходе дерева через os.ReadDir.

Соберём полную лестницу инструментов урока в один список выбора. Нужно все байты сразу и файл небольшой — os.ReadFile. Нужно записать всё сразу — os.WriteFile с правами 0644. Нужно читать поток по строкам — os.Open плюс bufio.Scanner (не забыть Err после цикла). Нужно писать много мелких кусочков — os.Create плюс bufio.NewWriter, в конце Flush и Close. Нужно дописывать в существующий файл — os.OpenFile с os.O_APPEND. Нужен сам размер или существование — os.Stat. Каждая ступенька стоит одной проверки ошибки дороже предыдущей, и именно эта лестница, а не отдельные функции, и есть ответ на запрос «чтение файлов go»: язык даёт вам и однострочник, и полный контроль, выбор — за размером задачи.

И последнее — про обработку ошибок, без которой ни одна ступенька не работает. Ошибки файлов говорят сами за себя: прочтите их текст — «open /tmp/x.txt: no such file or directory» содержит операцию, путь и причину; вам остаётся решить, что делать: завершиться с сообщением пользователю, пропустить файл в цикле или попробовать другой путь. Оборачивать ошибку контекстом полезно: fmt.Errorf("читаю конфиг %s: %w", path, err) сохранит причину для errors.Is и добавит, ЧТО вы делали — через полгода это спасёт час отладки. Единственная ошибка, которую НЕ надо считать провалом, — io.EOF из цикла чтения: это штатный сигнал конца, и смешивать её с настоящими сбоями — самая частая ошибка новичка в этом жанре.

Соберём урок в одну карту. Контракты: io.Reader — Read(p []byte) (n int, err error) с буфером от потребителя и io.EOF как штатным концом, io.Writer — Write с честным n; любой файл, сеть и буфер говорят на этой паре сигнатур. Простой путь: os.ReadFile и os.WriteFile — файл целиком, но память платит за всё, а WriteFile усекает. Ручки: os.Open, os.Create, defer Close сразу после проверки ошибки, os.OpenFile для append. Буферизация: bufio.Scanner для строк (Scan/Text/Err, потолок 64К), bufio.Writer для записи (4096 по умолчанию, Flush обязателен, запись больше буфера идёт напрямую). Метаданные: os.Stat и Size для выбора стратегии. Мост из прошлого урока работает на каждом шаге: буфер — это срез с заголовком на 24 байта, строка — байты UTF-8, len считает именно их, а Reader на строке — двадцать строк чистого Go.

Двадцать первый урок — JSON: кодирование и декодирование. Файлы дали нам байты, но байты без формы — просто содержимое; encoding/json научит складывать структуры в текст и доставать их обратно: struct tags, Marshal, Unmarshal, вложенные структуры. Связка прямая: прочитали конфиг os.ReadFile — развернули байты в структуру Unmarshal'ом; собрали данные — Marshal и os.WriteFile. Байтовое мышление этого урока останется с вами: JSON — это те же байты UTF-8, просто с договорённостью о форме.

До встречи на странице курса. Если захочется перечитать основу контрактов — урок про интерфейсы: io.Reader/Writer мы разбирали именно там, а сегодня файлы превратили теорию в инструмент. Если захочется вернуться к байтам и заголовкам — урок про unsafe и память: буфер, который вы передаёте в Read, — это тот самый срез с заголовком на 24 байта, чей вес мы измеряли Sizeof'ом.