Маршруты чтения
Что читать под конкретную задачу и в каком порядке. Каждый маршрут собран так, чтобы после него задачу можно было выполнить целиком, не догадываясь о пропущенном.
7 минутЧто читать под конкретную задачу и в каком порядке. Каждый маршрут собран так, чтобы после него задачу можно было выполнить целиком, не догадываясь о пропущенном.
Общее для всех маршрутов: PRINCIPLES — почему всё устроено именно так. Одна страница, читается первой и объясняет решения в остальных документах.
Собрать бэкенд
| № | Документ | Что даёт |
|---|---|---|
| 1 | PRINCIPLES | принципы: контракт на границе, ничто не приколочено |
| 2 | BMAP | корни репозитория, место бэка в продукте |
| 3 | BMBP | слои, API-иерархия, конверт, данные, идемпотентность, транзакции |
| 4 | AUTH | кто обращается и что ему можно: удостоверения, правила доступа |
| 5 | Стиль кода бэка | именование, типизация, исключения, асинхронность, журнал |
| 6 | База данных | схема на сервис, миграции, подключение и таймауты |
| 7 | Тестирование | что покрывать на каждом слое |
| 8 | Git и репозитории | что попадает в историю, как ведём версии |
Если бэков несколько и перед ними нужен единый вход — дальше BMGP. Если сервисы общаются событиями — Обмен сообщениями.
Собрать фронт
| № | Документ | Что даёт |
|---|---|---|
| 1 | PRINCIPLES | принципы |
| 2 | BMAP | место фронта в продукте, связь с бэком |
| 3 | BMFP | слои, состояние, контракт, маршруты, стили, оптимизация загрузки |
| 4 | Правила дизайна + Адаптивность | как это должно выглядеть и вести себя на разных экранах |
| 5 | Стиль кода фронта | именование, вложенность стилей, приёмы разметки |
| 6 | Тестирование | что покрывать на каждом слое |
| 7 | Git и репозитории | версии и история |
Если во фронте есть вход и закрытые разделы — AUTH: что хранится в браузере, когда продлевается сессия, почему право проверяется на сервере, а не кнопкой.
Форма ответов бэка описана в BMBP — читается, если контракт ещё не задан.
Собрать шлюз
| № | Документ | Что даёт |
|---|---|---|
| 1 | BMGP | структура, маршруты, upstream, сквозные правила |
| 2 | BMBP, раздел про API-иерархию | какие ручки бэков существуют и чем отличаются |
| 3 | Сетевой контур | где шлюз стоит в цепочке и что публикует |
Развернуть систему на сервере
Порядок обязателен: каждый следующий документ опирается на состояние, оставленное предыдущим.
| № | Документ | Что даёт |
|---|---|---|
| 1 | Настройка сервера | пользователь, вход по ключу, межсетевой экран, часы, журналы |
| 2 | Docker | движок, правила публикации портов, ротация логов |
| 3 | Частная сеть | обращение между машинами по частным адресам |
| 4 | Сетевой контур | как соединены слои, что наружу не смотрит |
| 5 | База данных | хранилище, пользователи, схема на сервис, миграции |
| 6 | Секреты | откуда части системы берут пароли и ключи |
| 7 | Запуск приложения | compose продукта, проверки готовности, ограничения |
| 8 | HTTPS для домена | домен, сертификат, автопродление |
| 9 | Резервное копирование | копии и проверка восстановлением — до первого выката |
| 10 | Релиз и выкат | сборка, выкат без простоя, откат |
| 11 | Наблюдение + Журналы | метрики, пороги, оповещения, сбор записей |
Если сервисы общаются событиями, между шагами 7 и 8 добавляется Обмен сообщениями: брокер поднимается до потребителей, иначе темы рождаются с настройками по умолчанию.
Копии настраиваются до первого выката с миграциями: выкат, меняющий схему, без свежей копии не имеет пути назад.
Выпустить новую версию
| № | Документ | Что даёт |
|---|---|---|
| 1 | Git и репозитории | чистое зафиксированное состояние, метка версии |
| 2 | Тестирование | прогон как условие выпуска |
| 3 | Релиз и выкат | сборка артефакта, выкат, откат, миграции |
| 4 | Наблюдение | что смотреть сразу после выката |
Выделить переиспользуемую единицу
| № | Документ | Что даёт |
|---|---|---|
| 1 | REUSE | когда выделять, топология, подключение с закреплённой версией |
| 2 | BMFP, раздел про модули | как устроен фронт-модуль и его публичный контракт |
| 3 | Git и репозитории | версии: что означает каждая часть номера |
| 4 | Тестирование | тесты принадлежат единице, а не потребителю |
Разобраться, почему не работает
| Симптом | Куда смотреть |
|---|---|
| сайт не открывается, ошибка сертификата | HTTPS для домена, раздел отказов |
502 или 504 | Сетевой контур, проверка по слоям |
| сервис доступен снаружи в обход шлюза | Docker, публикация портов |
| после выката всё сломалось | Релиз и выкат, откат |
| данные потеряны | Резервное копирование, восстановление |
| непонятно, где искать причину | Наблюдение, разбор отказа |
| нужны записи за прошлый час | Журналы, запросы к хранилищу |
| действие выполнилось дважды | BMBP, идемпотентность |
| сообщения обрабатываются не по порядку | Обмен сообщениями, ключ и порядок |
| вход перестал работать, разлогинивает | AUTH, таблица отказов |
| машины не видят друг друга по частным адресам | Частная сеть, таблица отказов |
| часть не поднимается или не выходит в готовность | Запуск приложения, где искать причину |
| ошибка подключения к базе, исчерпан пул | База данных, таблица отказов |
| секрет попал в репозиторий | Секреты, раздел про утечку |
| заперся снаружи, потерян доступ к серверу | Настройка сервера, откат |
Внести изменение в существующий код
| № | Документ | Что даёт |
|---|---|---|
| 1 | Работа в кодовой базе | с чем сверяться, как вносить правку, что делать при расхождении с архитектурой |
| 2 | Спецификация нужного слоя: BMFP, BMBP или BMGP | границы, за которые нельзя выходить ради краткости |
| 3 | Стиль соответствующей стороны: фронт или бэк | чтобы правка читалась как соседний код |
| 4 | Тестирование | что прогнать перед сдачей |
| 5 | Git и репозитории | одно изменение — один коммит |
Написать документ в библиотеку
| № | Документ | Что даёт |
|---|---|---|
| 1 | Документ библиотеки | критерий готовности, обязательные части |
| 2 | Правила письма | язык: точность, нейтральность, чего избегать |
Перед публикацией — ./tools/check-leaks.sh.
Откройте исходник документа по ссылке «Предложить правку» — там же видно, что и когда в нём менялось.