ПОЧЕМУ стало ключевым словом, язык поднят до версии 2
- метка обоснования пишется заглавными и вошла в словарь набора: скелет правила теперь целиком из ключевых слов, а не смесь `**ДОЛЖЕН.**` и `**Почему.**`; в переводе на другой язык метка меняется как остальные слова (ПОЧЕМУ / WHY), 235 вхождений заменены - метки правила выделены из шкалы в отдельный перечень: ПОЧЕМУ и МЕХАНИЗИРОВАНО обязательности не задают, а размечают части, и стандартом не даются ни в одном языке — раньше МЕХАНИЗИРОВАНО висело строкой в таблице модальности - версия языка поднята до 2, потому что изменение формы меняет чтение уже написанного текста; строка о версии в двенадцати конвенциях перечисляет теперь и метки, а служебные слова сценария в неё по-прежнему не входят
This commit is contained in:
@@ -7,9 +7,9 @@ extends: arch/db-identifiers.md
|
||||
|
||||
Как базовый слой выглядит в Go-приложении.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
|
||||
ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 2 —
|
||||
тогда и только тогда, когда написаны заглавными.
|
||||
|
||||
Единая точка из `KEYS-3` — пакет `internal/ident`: он
|
||||
порождает идентификаторы (`NewID`, `NewIDAt`) и он же их разбирает
|
||||
@@ -22,7 +22,7 @@ extends: arch/db-identifiers.md
|
||||
**ДОЛЖЕН.** Идентификаторы порождаются и разбираются функциями пакета
|
||||
`internal/ident`; других генераторов и парсеров id в коде нет.
|
||||
|
||||
**Почему.** Реализация `KEYS-3` и `KEYS-4`. Вызов
|
||||
**ПОЧЕМУ.** Реализация `KEYS-3` и `KEYS-4`. Вызов
|
||||
ULID-библиотеки — одна строка, доступная из любого пакета, и на ревью он не
|
||||
выглядит нарушением: значение получается валидное, просто мимо нормализации
|
||||
регистра. Отдельный пакет переводит запрет в проверяемое свойство — импорт
|
||||
@@ -35,7 +35,7 @@ ULID-библиотеки — одна строка, доступная из л
|
||||
**ДОЛЖЕН.** Новая сущность получает значение PK вызовом `ident.NewID()`
|
||||
внутри `Create`-метода слоя store.
|
||||
|
||||
**Почему.** `KEYS-2` требует, чтобы значение было
|
||||
**ПОЧЕМУ.** `KEYS-2` требует, чтобы значение было
|
||||
известно до вставки, но не говорит, кто его присваивает. Store — последний
|
||||
слой, через который проходят все пути создания строки, включая импорт,
|
||||
фоновые задания и тесты. Генерация выше по стеку делает присвоение
|
||||
@@ -48,7 +48,7 @@ ULID-библиотеки — одна строка, доступная из л
|
||||
**ДОЛЖЕН.** Идентификатор батча, задания или корреляционный ключ создаётся
|
||||
вызовом `ident.NewID()` там, где операция начинается.
|
||||
|
||||
**Почему.** Смысл такого идентификатора (`KEYS-7`) —
|
||||
**ПОЧЕМУ.** Смысл такого идентификатора (`KEYS-7`) —
|
||||
сшивать записи лога всей операции. Созданный ниже по стеку или в момент
|
||||
первой записи в базу, он не покрывает начальные шаги — а именно они нужны,
|
||||
когда операция упала до того, как что-либо записала: без общего ключа эти
|
||||
@@ -59,7 +59,7 @@ ULID-библиотеки — одна строка, доступная из л
|
||||
**ДОЛЖЕН.** Идентификаторы, проставляемые существующим строкам в
|
||||
Go-миграции, порождаются с историческим временем строки, а не с текущим.
|
||||
|
||||
**Почему.** Сортировка id тогда сохраняет историческую хронологию, а не
|
||||
**ПОЧЕМУ.** Сортировка id тогда сохраняет историческую хронологию, а не
|
||||
момент прогона миграции. Иначе все затронутые строки получают метку одного
|
||||
момента, склеиваются в нём и встают в порядке обхода — `ORDER BY id`
|
||||
начинает врать ровно на том массиве данных, который старше всего.
|
||||
@@ -71,7 +71,7 @@ Go-миграции, порождаются с историческим врем
|
||||
**ДОЛЖЕН.** `ident.Parse()` вызывается в обработчике HTTP-роута, формы или
|
||||
callback'а бота — раньше, чем идентификатор попадёт в store.
|
||||
|
||||
**Почему.** Реализация `KEYS-5`. Граница выбрана
|
||||
**ПОЧЕМУ.** Реализация `KEYS-5`. Граница выбрана
|
||||
транспортная, потому что только на ней известен источник значения, от
|
||||
которого зависит реакция (GKEY-8): store видит одинаковую строку независимо от
|
||||
того, пришла она из URL или из собственной формы, и ответить по-разному
|
||||
@@ -82,7 +82,7 @@ callback'а бота — раньше, чем идентификатор поп
|
||||
**СЛЕДУЕТ.** Поля идентификаторов в доменных и store-структурах имеют тип
|
||||
`string`.
|
||||
|
||||
**Почему.** Отдельный тип окупается только тогда, когда компилятор ловит им
|
||||
**ПОЧЕМУ.** Отдельный тип окупается только тогда, когда компилятор ловит им
|
||||
ошибку. От перепутывания двух идентификаторов одной семьи (`userID` и
|
||||
`authorID`) он не спасает — оба будут одного типа, и различают их имена
|
||||
параметров. Зато он требует конверсий на каждой границе с sql-драйвером,
|
||||
@@ -93,7 +93,7 @@ json и шаблонами, то есть даёт цену без выгоды.
|
||||
**ДОПУСКАЕТСЯ.** Когда в коде оказываются два вида идентификаторов, которые
|
||||
можно перепутать, для них заводятся различимые типы.
|
||||
|
||||
**Почему.** Явное разрешение нужно, чтобы GKEY-6 не читался как запрет на
|
||||
**ПОЧЕМУ.** Явное разрешение нужно, чтобы GKEY-6 не читался как запрет на
|
||||
типизацию навсегда. Условие названо ровно то, при котором тип начинает
|
||||
работать: пока все идентификаторы — `string`, подстановка одного вида
|
||||
вместо другого компилируется и обнаруживается только на данных.
|
||||
@@ -108,7 +108,7 @@ json и шаблонами, то есть даёт цену без выгоды.
|
||||
| GKEY-8.1 | путь или query URL | 404 без обращения к store |
|
||||
| GKEY-8.2 | собственная форма, callback-данные кнопки | 400 либо понятное сообщение («кнопка устарела») |
|
||||
|
||||
**Почему.** Реализация `KEYS-5.1` и `KEYS-5.2` в терминах
|
||||
**ПОЧЕМУ.** Реализация `KEYS-5.1` и `KEYS-5.2` в терминах
|
||||
HTTP-кодов. В случае GKEY-8.1 снаружи это неотличимо от несуществующей записи —
|
||||
и хорошо: чужая или протухшая ссылка описывается так точно. В случае GKEY-8.2
|
||||
значение сформировало само приложение, и невалидность означает баг
|
||||
@@ -121,7 +121,7 @@ HTTP-кодов. В случае GKEY-8.1 снаружи это неотличи
|
||||
**НЕ ДОЛЖЕН.** Обработчик не конструирует доменный sentinel (например
|
||||
`ErrNotFound`), чтобы тут же сопоставить его со своим ответом.
|
||||
|
||||
**Почему.** Инверсия правила «трансляция у источника» из конвенции
|
||||
**ПОЧЕМУ.** Инверсия правила «трансляция у источника» из конвенции
|
||||
`errors`. Sentinel — сообщение от слоя, который знает факт:
|
||||
строка не найдена, потому что store её искал. Сфабрикованный транспортом,
|
||||
он утверждает непроверенное, и по типу ошибки перестаёт быть видно, был ли
|
||||
|
||||
Reference in New Issue
Block a user