Files

Michael Chus 66c38f5a60 Add app binary contract

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-01 17:45:53 +03:00

4.0 KiB

Raw Blame History

Contract: Application Binary

Version: 1.0

Purpose

Правила сборки, упаковки ресурсов и первого запуска Go-приложений.

Бинарник

Бинарник самодостаточен — все ресурсы встроены через //go:embed:

HTML-шаблоны
Статика (JS, CSS, иконки)
Шаблон конфиг-файла (config.template.yaml)
Миграции БД

Никаких внешних папок рядом с бинарником не требуется для запуска.

Конфиг-файл

Создаётся автоматически при первом запуске, если не существует.

Расположение

Режим приложения	Путь
Однопользовательское	`~/.config/<appname>/config.yaml`
Серверное / многопользовательское	`/etc/<appname>/config.yaml` или рядом с бинарником

Приложение само определяет путь и создаёт директорию если её нет.

Содержимое

Конфиг хранит:

Настройки приложения (порт, язык, таймауты, feature flags)
Параметры подключения к централизованной СУБД (host, port, user, password, dbname)

Конфиг не хранит:

Данные пользователя
Кеш или состояние
Что-либо что относится к SQLite (см. ниже)

Шаблон

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

# <appname> configuration
# Generated on first run. Edit as needed.

server:
  port: 8080

database:
  host: localhost
  port: 5432
  user: ""
  password: ""
  dbname: ""

# ... остальные настройки

SQLite (однопользовательский режим)

Если приложение использует локальную SQLite:

Файл хранится рядом с конфигом: ~/.config/<appname>/<appname>.db
Путь к файлу не выносится в конфиг — приложение вычисляет его из пути конфига
SQLite не хранит параметры подключения к централизованной СУБД — только локальные данные приложения

Первый запуск — алгоритм

Старт приложения
│
├── Конфиг существует? → Нет → создать директорию → скопировать шаблон → сообщить пользователю путь
│                                                                        → завершить с кодом 0
│                                                                          (пользователь заполняет конфиг)
└── Конфиг существует? → Да → валидировать → запустить приложение

При первом создании конфига приложение не запускается — выводит сообщение:

Config created: ~/.config/<appname>/config.yaml
Edit the file and restart the application.

Сборка

Финальный бинарник собирается без CGO если это возможно (для SQLite — с CGO):

CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/<appname> ./cmd/<appname>

С SQLite:

CGO_ENABLED=1 go build -ldflags="-s -w" -o bin/<appname> ./cmd/<appname>

Бинарник не зависит от рабочей директории запуска.

4.0 KiB Raw Blame History Unescape Escape