Go API: краткий обзор для разработчиков Go

Go API esbuild представляет собой нативный интерфейс библиотеки сборки, реализованный на языке Go и работающий поверх той же высокопроизводительной ядровой реализации, что используется в CLI-инструменте. Ключевая особенность заключается в отсутствии межпроцессного взаимодействия: вместо запуска отдельного бинарного процесса логика выполняется непосредственно в рамках Go-программы, что снижает накладные расходы и ускоряет повторные сборки.

Основной пакет API располагается в пространстве github.com/evanw/esbuild/pkg/api, где сосредоточены структуры конфигурации, функции сборки и механизмы расширения через плагины.

Пакет api и структура конфигурации

Центральной точкой входа выступает пакет api, предоставляющий декларативные структуры для управления процессом сборки.

Основная конфигурационная структура:

  • BuildOptions — определяет параметры сборки
  • TransformOptions — управляет трансформацией отдельных модулей
  • Plugin — интерфейс расширения поведения сборщика

BuildOptions включает ключевые поля:

  • EntryPoints — список входных файлов
  • Outdir или Outfile — направление вывода
  • Bundle — включение бандлинга зависимостей
  • Platform — browser, node или neutral
  • Format — формат результата (esm, cjs, iife)
  • Target — целевая версия ECMAScript
  • Loader — настройка обработки типов файлов

Конфигурация строится полностью в Go-структурах, что исключает необходимость JSON или CLI-строк.

Основная функция Build

Функция api.Build выполняет полный цикл сборки: анализ зависимостей, трансформацию модулей и генерацию выходных файлов.

Поведение Build:

  • синхронная или псевдосинхронная компиляция
  • построение графа зависимостей
  • применение трансформеров (JS, TS, JSX)
  • генерация бандла

Пример типового использования API:

  • формирование BuildOptions
  • вызов api.Build(options)
  • получение результата через BuildResult

BuildResult содержит:

  • список Errors и Warnings
  • метаданные о бандле
  • статистику времени выполнения
  • информацию о выходных файлах

Ошибки представлены структурированно, без строкового парсинга, что упрощает интеграцию в инструменты разработки.

Трансформация через Transform API

Функция api.Transform предназначена для обработки отдельного кода без полной сборки проекта.

Используется в сценариях:

  • транспиляция TypeScript в JavaScript
  • преобразование JSX в JS
  • минимизация фрагментов кода
  • анализ кода перед исполнением

Параметры:

  • TransformOptions
  • входной код в виде строки или байтов
  • опциональное имя файла для корректного source map

Результат содержит:

  • преобразованный код
  • source map
  • предупреждения и ошибки

В отличие от Build, данный метод не строит граф зависимостей, что делает его существенно быстрее для единичных операций.

Инкрементальные сборки и Context API

Одной из ключевых возможностей Go API является поддержка инкрементальной компиляции через Context.

api.Context создаёт долгоживущий объект сборки, который сохраняет:

  • граф зависимостей
  • промежуточные результаты парсинга
  • кеш трансформаций

После создания контекста доступны операции:

  • Rebuild() — повторная сборка с минимальными изменениями
  • Dispose() — освобождение ресурсов

Инкрементальная модель устраняет необходимость повторного анализа всего проекта при изменении одного файла. Обновляется только затронутая часть графа.

Особенно эффективно это используется в:

  • dev-серверах
  • системах hot reload
  • CI с частичными изменениями

Плагины в Go API

Плагинная система реализована через интерфейс Plugin, который позволяет вмешиваться в процесс разрешения модулей и загрузки контента.

Ключевые точки расширения:

  • OnResolve — перехват разрешения путей
  • OnLoad — загрузка и генерация содержимого модулей

Плагины могут:

  • заменять импорты на виртуальные модули
  • подгружать код из базы данных или сети
  • модифицировать исходники до трансформации
  • реализовывать нестандартные загрузчики форматов

Плагины выполняются внутри Go-процесса, что даёт доступ к:

  • стандартной библиотеке Go
  • конкурентности через goroutines
  • низкоуровневым оптимизациям памяти

Это делает Go API значительно более гибким по сравнению с JavaScript-плагинами CLI-версии.

Сравнение Go API и CLI-использования

Go API и CLI используют одно и то же ядро esbuild, однако различаются по архитектуре интеграции.

Ключевые различия:

  • Go API работает внутри процесса приложения
  • CLI запускает отдельный бинарный процесс
  • Go API обеспечивает прямой доступ к структурам данных
  • CLI ориентирован на файловый ввод/вывод

Преимущества Go API:

  • минимальная задержка запуска
  • отсутствие сериализации конфигурации
  • глубокая интеграция с серверной логикой
  • возможность динамической сборки на лету

CLI сохраняет преимущества:

  • простота использования
  • независимость от Go-окружения
  • удобство в build scripts и CI

Параллелизм и модель исполнения

Внутренняя реализация esbuild построена на конкурентной модели Go, активно использующей:

  • goroutines для распараллеливания загрузки модулей
  • worker pool для трансформации AST
  • lock-free структуры данных в критических участках

Go API не требует ручного управления потоками: параллелизм управляется самим esbuild. Разработчик лишь задаёт входные параметры, а планирование задач выполняется внутри ядра.

Это обеспечивает стабильную масштабируемость при увеличении количества модулей без необходимости изменения кода интеграции.

Обработка ошибок и диагностическая модель

Ошибки в Go API представлены как структурированные объекты, содержащие:

  • текст сообщения
  • позицию в исходном файле
  • стек модулей
  • категорию (ошибка или предупреждение)

Такая модель позволяет:

  • формировать кастомные логгеры
  • интегрировать результаты в IDE
  • строить визуальные отчёты сборки

Диагностика не ограничивается строковым выводом, что упрощает автоматическую обработку результатов в инструментах анализа кода.

Оглавление