конвенции отделены от обвязки
- сами конвенции переехали в conventions/, описательное — в корень: LANGUAGE.md (язык записи) и GUIDE.md (как ведут конвенции) - conv синхронизирует только conventions/, пути в origin даются относительно неё — раскладка копий в репозиториях не меняется
This commit is contained in:
@@ -0,0 +1,224 @@
|
||||
---
|
||||
extends: arch/config.md
|
||||
---
|
||||
|
||||
# Конфигурация: реализация на Go
|
||||
|
||||
Как `arch/config.md` выглядит в Go-приложении: формат, загрузчик, границы
|
||||
запрета на окружение. Форма записи — `LANGUAGE.md`.
|
||||
|
||||
Секретов Go-специфика не касается: они приходят из деплоя уже в файле, а
|
||||
проверка их непустоты идёт вместе с остальной валидацией — как описано в
|
||||
базовой конвенции.
|
||||
|
||||
## Правила
|
||||
|
||||
### R1. Формат конфигурации — TOML
|
||||
|
||||
**ДОЛЖЕН.** Конфиг — файл TOML.
|
||||
|
||||
**Почему.** Базовая конвенция оставляет формат за стеком, и этот выбор
|
||||
делается один раз на язык, а не в каждом приложении: разные форматы в
|
||||
соседних сервисах означают разные загрузчики, разные шаблоны рендера
|
||||
конфига в деплое и разное поведение при синтаксической ошибке. TOML при
|
||||
этом даёт секции и типизированные скаляры без значимых отступов — конфиг,
|
||||
поправленный руками на сервере, ломается заметно, а не меняет вложенность
|
||||
молча.
|
||||
|
||||
### R2. Разбор и валидация — целиком в `internal/config`
|
||||
|
||||
**ДОЛЖЕН.** Чтение файла, наложение умолчаний и проверки живут в
|
||||
`internal/config`; наружу пакет отдаёт готовую структуру `Config`.
|
||||
|
||||
**Почему.** Пока значение не покинуло пакет, оно может быть невалидным;
|
||||
после — уже нет, и это единственная граница, на которой такое утверждение
|
||||
проверяемо. Валидация, размазанная по потребителям, отвечает на вопрос
|
||||
«проверено ли это поле» только чтением всех вызывающих, часть полей
|
||||
неизбежно окажется непроверенной, и fail-fast (R15) выродится в отказ
|
||||
посреди работы. Экспортированный разбор вдобавок даёт второй способ
|
||||
получить конфиг — мимо умолчаний (R5).
|
||||
|
||||
### R3. Весь конфиг — одна корневая структура
|
||||
|
||||
**ДОЛЖЕН.** Конфиг представлен одним значением типа `Config`, собранным из
|
||||
под-структур по секциям.
|
||||
|
||||
**Почему.** Один корень даёт одну точку, после которой конфиг проверен
|
||||
целиком, и дальше передаётся как обычный аргумент. Несколько независимых
|
||||
структур конфига означают несколько загрузок и вопрос «какая из них уже
|
||||
провалидирована» на каждом использовании; связанные между собой поля
|
||||
(включена интеграция — заданы все её поля) при этом перестают быть
|
||||
проверяемыми в одном месте.
|
||||
|
||||
### R4. Под-структуры названы по секциям файла
|
||||
|
||||
**СЛЕДУЕТ.** Имя под-структуры совпадает с именем секции TOML.
|
||||
|
||||
**Почему.** Имя секции из файла — то, с чего начинают, когда конфиг ведёт
|
||||
себя не так, как ожидали. При совпадении имён поиск по нему сразу приводит
|
||||
в код и обратно; при расхождении связь между полем файла и полем структуры
|
||||
восстанавливается чтением тегов, и проделывать это приходится для каждой
|
||||
секции заново.
|
||||
|
||||
### R5. Умолчания задаёт `Default()`
|
||||
|
||||
**ДОЛЖЕН.** Умолчания собраны в функции `Default()`, разобранный файл
|
||||
накладывается поверх.
|
||||
|
||||
**Почему.** Нулевое значение в Go неотличимо от «поле не задано»: нулевой
|
||||
таймаут и отсутствующий таймаут — один и тот же `0`. Умолчание,
|
||||
подставленное по месту использования (`if x == 0 { x = … }`), поэтому не
|
||||
видно ни целиком, ни из образца, и два потребителя одного поля со временем
|
||||
подставляют разное. `Default()` — единственное место, откуда список
|
||||
умолчаний читается разом и переносится в образец.
|
||||
|
||||
### R6. Имя файла фиксировано, путь переопределяется флагом
|
||||
|
||||
**СЛЕДУЕТ.** По умолчанию читается `config.toml` в рабочей директории,
|
||||
путь переопределяет флаг `--config=path`, образец рядом —
|
||||
`config.example.toml`.
|
||||
|
||||
**Почему.** Фиксированное имя и переопределение из командной строки требует
|
||||
базовая конвенция, но конкретные имена она не задаёт. Одинаковые имена во
|
||||
всех сервисах означают, что unit-файл, `docker run` и инструкция по запуску
|
||||
пишутся, не открывая код приложения. Соседство `config.toml` и
|
||||
`config.example.toml` вдобавок делает расхождение образца с реальным
|
||||
конфигом видимым обычным `diff`, а не вычиткой.
|
||||
|
||||
### R7. Длительности — собственный тип с `UnmarshalText`
|
||||
|
||||
**ДОЛЖЕН.** Поля-длительности объявляются своим типом, отдающим
|
||||
`time.Duration`:
|
||||
|
||||
```go
|
||||
type Duration time.Duration
|
||||
|
||||
func (d *Duration) UnmarshalText(b []byte) error { … }
|
||||
func (d Duration) Std() time.Duration { … }
|
||||
```
|
||||
|
||||
**Почему.** `time.Duration` — это `int64`, и TOML разбирает его в голое
|
||||
число: в конфиге остаётся `poll_interval = 5000`, о котором читатель не
|
||||
знает, секунды это, миллисекунды или наносекунды. Ошибка в тысячу раз
|
||||
проходит и разбор, и проверку диапазона, а проявляется нагрузкой или
|
||||
зависшим ожиданием. Запись `poll_interval = "5s"` несёт единицу измерения
|
||||
в себе и разбирается тем же `time.ParseDuration`, что и остальной код.
|
||||
|
||||
У обёртки есть цена: `UnmarshalText` вызывается на разборе TOML, то есть
|
||||
раньше, чем начинает работать сбор проблем (R12). Ошибка в длительности
|
||||
приходит отдельно и первой, а остальные проблемы конфига в этом запуске не
|
||||
показываются.
|
||||
|
||||
### R8. Приложение не читает окружение
|
||||
|
||||
**НЕ ДОЛЖЕН.** Значения конфигурации не берутся из переменных окружения.
|
||||
|
||||
**Почему.** Второй канал конфигурации — то, против чего написана базовая
|
||||
конвенция, но в Go он ещё и бесследный: `os.Getenv` вызывается из любого
|
||||
пакета, не появляется ни в `Config`, ни в образце и не проходит валидацию.
|
||||
Заведённый так параметр нельзя ни увидеть в конфиге, ни узнать иначе как
|
||||
чтением всего кода — а узнают о нём обычно на сервере, где переменная не
|
||||
выставлена.
|
||||
|
||||
### R9. Проверка запрета покрывает все входы в окружение
|
||||
|
||||
**ДОЛЖЕН.** Механическая проверка R8 (`forbidigo`) ловит не только
|
||||
`os.Getenv`:
|
||||
|
||||
```
|
||||
^os\.(Getenv|LookupEnv|Environ|ExpandEnv)$
|
||||
```
|
||||
|
||||
**Почему.** `LookupEnv`, `Environ` и `ExpandEnv` читают ровно то же самое,
|
||||
поэтому паттерн на одно имя оставляет три обхода. Хуже, что оставляет
|
||||
незаметно: правило числится механизированным, и глазами его больше никто не
|
||||
проверяет.
|
||||
|
||||
### R10. За границей приложения запрет не действует
|
||||
|
||||
**ДОПУСКАЕТСЯ.** Чтение окружения там, где читающий — не конфигурируемое
|
||||
приложение:
|
||||
|
||||
| № | Кто читает | Вердикт |
|
||||
|---|---|---|
|
||||
| R10.1 | тесты, включая интеграционные | допустимо: креды и адреса внешних сервисов взять больше неоткуда |
|
||||
| R10.2 | Go-рантайм и ОС, а не наш код (`GOMEMLIMIT`, `GOMAXPROCS`, `GODEBUG`, `TZ`) | вне запрета: значение читает не приложение |
|
||||
|
||||
**Почему.** R8 — про конфигурацию приложения; расширенный до «никто не
|
||||
трогает окружение», он запрещает то, чем не управляет: `GOMEMLIMIT` читает
|
||||
рантайм, а тесту креды внешнего сервиса взять неоткуда — в репозиторий их
|
||||
не положишь, а отдельный конфиг тестов пришлось бы заводить как ещё один
|
||||
механизм. Явное разрешение нужно и потому, что нерасписанная граница
|
||||
лечится `//nolint` наугад: там, где легальные случаи приходится глушить
|
||||
руками, вместе с ними проходят и нелегальные.
|
||||
|
||||
### R11. Прокси задаётся конфигом, а не `HTTP_PROXY`
|
||||
|
||||
**ДОЛЖЕН.** Исходящий прокси приходит полем конфига и явным `Transport`.
|
||||
|
||||
**Почему.** `HTTP_PROXY`/`HTTPS_PROXY` формально читает не наш код, а
|
||||
дефолтный `http.Transport` — но читает он их от имени приложения и меняет
|
||||
поведение приложения, а не рантайма. Оставленные окружению, они дают ровно
|
||||
тот второй канал, который запрещает R8, и притом самый неудобный: маршрут
|
||||
исходящих запросов отличается от машины к машине без единого следа в
|
||||
конфиге и в образце, а расследование начинается с вопроса «почему на
|
||||
сервере ходит не так, как локально».
|
||||
|
||||
### R12. Проблемы конфига собираются `errors.Join`
|
||||
|
||||
**ДОЛЖЕН.** Проверки не прерываются на первой неудаче, результат — одна
|
||||
ошибка, собранная `errors.Join`.
|
||||
|
||||
**Почему.** Возврат первой ошибки превращает починку конфига в серию
|
||||
перезапусков по одному полю за раз, причём каждый следующий запуск
|
||||
обнаруживает ещё одно. `errors.Join` даёт разом весь список, не требуя
|
||||
своего типа ошибки, и `errors.Is`/`errors.As` продолжают работать по каждой
|
||||
вложенной проблеме.
|
||||
|
||||
### R13. Имя зоны проверяется `time.LoadLocation`
|
||||
|
||||
**ДОЛЖЕН.** IANA-зона из конфига загружается на старте, в общей валидации.
|
||||
|
||||
**Почему.** Проверить имя зоны нечем, кроме загрузки: оно валидно ровно
|
||||
тогда, когда база зон его знает, и никакая проверка формата не отличит
|
||||
`Europe/Moscow` от `Europe/Moskow`. Без загрузки на старте опечатка
|
||||
доживает до первого форматирования времени — то есть до рантайма, мимо
|
||||
fail-fast (R15).
|
||||
|
||||
### R14. `time/tzdata` импортируется в `main`
|
||||
|
||||
**ДОЛЖЕН.** Импорт `_ "time/tzdata"` стоит в `main`, а не в библиотечном
|
||||
пакете.
|
||||
|
||||
**Почему.** Импорт в библиотеке навязывает ~450 КБ zoneinfo каждому
|
||||
импортёру, включая тех, кому зоны не нужны: выбор «встраивать базу или
|
||||
полагаться на системную» принадлежит собираемой программе. Со встроенной
|
||||
базой ошибка `LoadLocation` (R13) означает ровно одно — битое имя зоны; без
|
||||
неё тот же конфиг валиден на машине разработчика и падает в контейнере без
|
||||
zoneinfo, а сообщение указывает не на ту причину.
|
||||
|
||||
### R15. Невалидный конфиг — `ERROR` и выход из `main`
|
||||
|
||||
**ДОЛЖЕН.** `main` пишет `slog` уровня `ERROR` и вызывает `os.Exit(1)` до
|
||||
старта серверов и воркеров.
|
||||
|
||||
**Почему.** Выход именно из `main`: `os.Exit` в библиотечном пакете не
|
||||
оставляет вызывающему возможности ни залогировать причину, ни дописать
|
||||
контекст, и отложенные `defer` при нём не выполняются вовсе. Выход именно
|
||||
до старта воркеров: горутина, поднятая раньше валидации, успевает сходить
|
||||
во внешний сервис и записать в базу от имени процесса, который потом
|
||||
объявит, что не стартовал.
|
||||
|
||||
<!-- local:поля -->
|
||||
<!-- /local -->
|
||||
|
||||
<!-- local:механизировано -->
|
||||
<!-- /local -->
|
||||
|
||||
## Связано
|
||||
|
||||
- `lang/go/time.md` — зона отображения и формат времени.
|
||||
- `lang/go/logging.md` — `slog`, которым падает невалидный конфиг.
|
||||
|
||||
<!-- local:связано -->
|
||||
<!-- /local -->
|
||||
Reference in New Issue
Block a user