scratch

Универсальный шаблон Go-сервиса: echo v5 + bun (PostgreSQL) + templ + shadcn-templ

• htmx 4/Alpine.js + golang.yandex/di + OTel/Prometheus. Самодостаточен для среднего сервиса; проверен миграцией oktable и MarkPad (см. ниже).

Структура

api/                  OpenAPI-спецификация + embed (источник кодогенерации)
cmd/
  server/             точка входа HTTP-сервиса (DI-контейнер golang.yandex/di)
  migrate/            миграции bun: init | up | down | status | new
internal/
  config/             конфигурация: env + .env (caarlos0/env + godotenv)
  database/           подключение к PostgreSQL (bun + pgdriver, TZ-сессии МСК)
  server/             echo: middleware, маршруты, статика, /metrics, openapi.yaml
  handler/            HTTP-обработчики + сгенерированный ServerInterface
  view/               templ-шаблоны (layout + страницы + фрагменты),
                      shadcn-templ компоненты (view/components/) и хелперы (view/utils/)
  model/              модели данных (bun)
  repo/               универсальный generic-репозиторий + примеры расширения
  migrations/         SQL-миграции (go:embed) + коллекция bun
  observability/      OTel-трейсинг (OTLP) + Prometheus RED-метрики
pkg/
  api/                сгенерированный API-клиент (oapi-codegen)
web/
  static/             статика: css (tailwind-сборка), js (htmx, alpine) — go:embed

Инструменты

Всё через go tool — без глобальных установок: templ, oapi-codegen, shadcn-templ, golangci-lint. Tailwind — standalone-бинарник в bin/ (make tools).

Команды

make tools            # скачать tailwindcss standalone (один раз)
make generate         # templ + oapi-codegen (сервер и клиент)
make css              # tailwind: app.css -> main.css
make run              # go run ./cmd/server
make build            # бинари в bin/
make test             # go test ./...
make lint             # golangci-lint
make migrate-up       # применить миграции (или AUTO_MIGRATE=true на старте)
make migrate-new name=add_users   # новая SQL-миграция
docker compose -f compose.dev.yml up -d   # dev-окружение (pg+minio+jaeger)

Окружение

Переменная	По умолчанию	Описание
HTTP_ADDR	:8080	адрес HTTP-сервера
DATABASE_DSN	postgres на localhost:5433	DSN PostgreSQL
LOG_LEVEL	info	debug / info / warn / error
LOG_FORMAT	text	text / json
AUTO_MIGRATE	true	применить миграции на старте
OTEL_SERVICE_NAME	scratch	имя сервиса в трейсах
OTEL_EXPORTER_OTLP_ENDPOINT	пусто	OTLP/HTTP эндпоинт; пусто — трейсы не экспортируются

Observability

• /metrics — Prometheus (RED: http_requests_total, http_request_duration_seconds по route/method/status)
• трейсы: HTTP-запросы оборачиваются otelhttp, экспорт OTLP/HTTP (в dev — Jaeger из compose.dev.yml: UI на :16686)

Docker

• Dockerfile: сборка в golang:alpine, рантайм — gitrepo.ru/neonxp/base (пользователь app:1001, /srv, таймзона Europe/Moscow, в DSN-сессии PostgreSQL тоже TimeZone=Europe/Moscow — иначе UTC в timestamptz)
• compose.dev.yml — dev-инфраструктура без приложения (pg :5433, minio, jaeger)
• compose.yml — прод: app + db, JSON-логи

Тесты

• handler: httptest поверх сгенерированных маршрутов
• view: рендер-тесты templ (layout, фрагменты, shadcn-компоненты)
• repo: компайл-чеки генериков

Миграция существующих сервисов

Первые кандидаты — oktable и MarkPad (тот же стек: echo v5, bun, templ). Общие библиотеки для переиспользования: auth (OAuth+JWT-сессии), objstore (S3/minio), ssehub (SSE), testenv (testcontainers).