Documentation
¶
Overview ¶
Package importer — реестр форматов наполнения (jsonc/json, yaml/yml, ndjson): упорядоченное дерево значений, семантика секций, Issues-модель и дословные тексты ошибок формата (docs/plan/01-architecture.md §2.5). Оркестратор Import работает поверх сервисного слоя (разбор файла → применение секции catalog → upsert записей), экспорт — round-trip во всех форматах реестра (записи и каталог).
Index ¶
- func ReadDocument(root value, snap *catalog.Snapshot) (doc *Document, issues []Issue)
- func ReadRecordJSON(data []byte, snap *catalog.Snapshot) (service.DeviceInput, error)
- func ReadRecordLine(snap *catalog.Snapshot, v value, line int) (Record, bool, []Issue)
- type Document
- type Format
- type ImportOption
- type Importer
- func (m *Importer) Export(ctx context.Context, w io.Writer, format Format, kind *domain.Kind) error
- func (m *Importer) ExportCatalog(ctx context.Context, w io.Writer, format Format) error
- func (m *Importer) Import(ctx context.Context, r io.Reader, name string, dryRun bool, ...) (Report, error)
- func (m *Importer) ImportCatalogFile(ctx context.Context, r io.Reader, name string, dryRun bool, ...) (Report, error)
- func (m *Importer) ImportFormat(ctx context.Context, r io.Reader, format Format, dryRun bool, ...) (Report, error)
- type Issue
- type Progress
- type Record
- type Report
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ReadDocument ¶
ReadDocument разбирает корень документа (jsonc/yaml): секция catalog пропускается (импортёр применяет её до записей отдельно), секция sources — тоже (определения источников применяются до записей), записи классов читаются в порядке следования ключей. Проблемы формы накапливаются в issues; записи с проблемами не попадают в Document (применение частичной записи запрещено).
func ReadRecordJSON ¶
ReadRecordJSON читает одну запись наполнения из тела REST-запроса (POST/PUT /api/v1/components — docs/plan/04-module-functionality.md §2): строка-обозначение либо объект «name/system + секции». Разбор — общим читателем формата (дубликаты ключей, форма секций, тексты проблем); класс записи определяется автодетектом по обозначению (для system other создание адресуется PUT с классом в пути). Возвращается первая проблема (REST применяет одну запись, Issues-накопление прогона здесь нет).
Types ¶
type Document ¶
Document — разобранный документ наполнения (jsonc/yaml): записи в порядке файла и число записей, отвергнутых при чтении (проблемы — в Issues; дерево секции catalog импортёр применяет до записей).
type Format ¶
type Format string
Format — формат файла наполнения (реестр форматов — docs/plan/04-module-functionality.md §4): jsonc/json и yaml/yml — документы целиком, ndjson — построчный поток для больших объёмов.
Реестр форматов наполнения.
func FormatByFilename ¶
FormatByFilename определяет формат по расширению имени файла. Имя «-» (стандартный ввод) читается как jsonc — формат экспорта по умолчанию.
func ParseFormat ¶
ParseFormat разбирает имя формата (опция --format, нижний регистр).
type ImportOption ¶ added in v0.0.5
type ImportOption func(*importOptions)
ImportOption — опция прогона импорта (Import/ImportCatalogFile).
func WithProgress ¶ added in v0.0.5
func WithProgress(fn func(Progress)) ImportOption
WithProgress — колбэк прогресса прогона: снимки нарастающих счётчиков по ходу чтения и применения (см. Progress). Вызывается синхронно в горутине прогона: быстрый возврат, долгая обработка останавливает импорт (отмена — контекст прогона).
type Importer ¶
type Importer struct {
// contains filtered or unexported fields
}
Importer — импорт/экспорт файлов наполнения поверх сервисного слоя приложения (docs/plan/04-module-functionality.md §1.1 ImportService).
func (*Importer) Export ¶
Export выгружает записи устройств (все классы либо один) в формате наполнения: jsonc/yaml — документ с секциями классов, ndjson — по строке-обёртке на запись.
func (*Importer) ExportCatalog ¶
ExportCatalog выгружает каталог (снимок определений) в формате наполнения: секция catalog со всеми подразделами.
func (*Importer) Import ¶
func (m *Importer) Import(ctx context.Context, r io.Reader, name string, dryRun bool, opts ...ImportOption) (Report, error)
Import импортирует файл наполнения (формат — по расширению имени). Жёсткая ошибка (возвращается как error, прогона нет) — только синтаксис формата; проблемы формы и значений накапливаются в Report.Issues: корректные записи применяются, ошибочные — нет (запись не применяется вовсе, частичное применение записи запрещено). Опции: WithProgress — колбэк нарастающих счётчиков чтения и применения (NDJSON читается построчно, без загрузки файла целиком).
func (*Importer) ImportCatalogFile ¶
func (m *Importer) ImportCatalogFile(ctx context.Context, r io.Reader, name string, dryRun bool, opts ...ImportOption) (Report, error)
ImportCatalogFile применяет только секцию catalog файла наполнения (catalog import): записи в файле не допускаются — для них есть import. Смешанный файл отвергается до каких-либо записей в БД: признак «есть записи» известен фазе чтения, применение каталога отложено до проверки.
func (*Importer) ImportFormat ¶ added in v0.2.1
func (m *Importer) ImportFormat(ctx context.Context, r io.Reader, format Format, dryRun bool, opts ...ImportOption) (Report, error)
ImportFormat импортирует файл наполнения заданного формата — имя файла не участвует (REST: формат согласован заголовком Content-Type; встраивание: формат выбран явно). Условное имя отчёта — «import.<формат>». Контракт исходов и проблем — как у Import.
type Issue ¶
type Issue struct {
Record string // обозначение записи («» — проблема корневого уровня)
Line int // номер строки NDJSON (0 — не определён)
No int // порядковый номер записи в секции документа (0 — не задан)
Code domain.Code
MsgID domain.MsgID
Args []any
Message string
}
Issue — проблема прогона импорта (Issues-модель — docs/plan/04-module-functionality.md §4): корневые проблемы и проблемы записей накапливаются за один прогон; жёсткой ошибкой (возвращаемой как error) остаётся только синтаксис формата. Сообщение — MsgID каталога + аргументы (этап 8.3); Message — канонический en-рендер, локализованный рендер и сборка позиции — слой вывода CLI. Тексты — контракт CLI.
func ReadCatalogSection ¶
ReadCatalogSection читает дерево секции catalog в каталог. Значение null/отсутствие — пустой вход. Строки NDJSON ({"catalog": {"<подраздел>": […]}}) читаются тем же читателем и сливаются mergeCatalogTrees.
func ReadSourcesSection ¶ added in v0.3.0
func ReadSourcesSection(v value) ([]service.SourceInput, []Issue)
ReadSourcesSection читает корневую секцию sources — массив определений источников. Значение null/отсутствие — пустой вход; строки NDJSON ({"sources": […]}) читаются тем же читателем и сливаются конкатенацией массивов (importNDJSON).
type Progress ¶ added in v0.0.5
type Progress struct {
Read int // записей прочитано из файла (включая отвергнутых чтением)
Applied int // записей доведено до исхода применения (Added/Updated/Skipped/Rejected)
Line int // номер последней прочитанной строки NDJSON (0 — не определён)
}
Progress — снимок прогресса прогона импорта: нарастающие счётчики чтения файла и применения записей. Колбэк WithProgress вызывается по ходу прогона: NDJSON — после каждой прочитанной записи (строки catalog записями не считаются), форматы-документы (jsonc/yaml) читаются целиком — чтение отмечается одним вызовом после разбора; применение записей (все форматы, включая dry-run) — по итоговому исходу каждой записи. Отвергнутые чтением записи входят в Read и не входят в Applied — применяются только прошедшие чтение.
type Record ¶
type Record struct {
Kind domain.Kind
Input service.DeviceInput
Line int // номер строки NDJSON (0 — не определён)
No int // порядковый номер записи в секции документа (0 — не задан)
}
Record — запись наполнения из файла: класс (по ключу секции корня либо строке-обёртке NDJSON) и вход сервисного слоя.
type Report ¶
type Report struct {
Name string
Format Format
DryRun bool
Records int // записей в файле (включая отвергнутые)
Added int
Updated int
Skipped int
Rejected int // записи, не применённые из-за проблем
CatalogApplied bool
SourcesApplied bool // реестр источников изменён корневой секцией sources
Issues []Issue
}
Report — итог прогона импорта: счётчики исходов записей и накопленные проблемы (Issues-модель: полный список за один прогон).