Книга: первая версия плана

May 25, 2025

План книги

Введение

Эргономичный подход

В этой главе читатель познакомится с Эргономичным подходом:

  1. какие проблемы он призван решить (четыре проекции большого кома грязи на примере реальных проектов - класс сущности на 100+ полей, граф модели данных, граф зависимостей компонентов (Spring-бинов) системы, граф вызовов методов реализации одной операции)
  2. чего мне не хватило в существующих подходах:
    1. Чиста Архитектура - нет чёткого руководства и методик, как избегать кома грязи внутри слоёв.
    2. DDD - требует, чтобы вся команда (включая заказчика/эксперта предметной области) знала и следовала DDD и участвовала в построении и использовании Ubiquitous language, а так же чтобы в проектировании реализации принимали активное участие эксперты ПО - в моей практике добиться этого не вышло ни разу.
  3. основными принципами ЭП:
    1. 100% покрытие поведения системы тестами
    2. декомпозиция модели на ацикличный граф небольших агрегатов
    3. декомпозиция состояния системы на лес компонентов
    4. предпочтение неизменяемым данным и методам без побочных эффектов в реализации.
  4. основной отличительной чертой - моделью системы на базе эффектов и её составными частями:
    1. Сигналы - события внешнего мира, на которые реагирует система
    2. Ресурсы - элементы состояния системы
    3. Эффекты - операции модификации и записи состояния отдельных ресурсов
    4. Операции - сложные операции включающие работу с несколькими ресурсами

"Хочу зюзюку"

В этой главе читатель познакомится с проектом, который будем разрабатывать на протяжении книги:

  1. Предметной областью (йогатерапия)
  2. Бизнес-процессом йогатерапевта
  3. Задачами и проблемами, которые заказчик хочет решить с помощью разрабатываемой системы

Сетап "ходячего скелета" проекта

В этой главе мы подготовим проект и инфраструктуру и читатель узнает как инициировать разработку проекта и создать "ходячий скелет" будущей системы:

  1. Инициализация проекта Spring Boot-приложения;
  2. Верхнеуровневая структура кода приложения;
  3. Базовые блоки реализации:
    1. Контроллеры;
    2. Репозитории
  4. Паттерн тестирования "Оптимизация testcontainer-а PostgreSQL";
  5. Настройка GitHub Actions для верификации проекта перед мёржем Pull Request;
  6. Настройка GitHub Actions для сборки Docker-образа приложения;
  7. Покупка VDS и доменного имени (?);
  8. Подготовка Docker Compose-файла для развёртывания системы;
  9. Подготовка скрипта деплоя последней версии приложения на сервер.

Здесь же будет обоснован выбор стека - Kotlin, Spring Boot, Spring Data JDBC, PostgreSQL. Частично на базе принципов ЭП, частично на базе "здравого смысла" (Spring Boot и PostgreSQL - проверенные временем и самые распространённые решения с наибольшими базами знаний и специалистов).

Тут же будет ремарка о нестандартном и нерекомендуемом в реальной разработке способе реализации UI - MultiPage Application + Alpine.js для логики внутри страницы, который обусловлен следующими вещами:

  1. Книга посвящена бакэнд разработке;
  2. Я не умею делать SPA-приложения и изучение этого сильно замедлит написание книги;
  3. Львиную долю демонстрационного кода хочется сделать типичным для современных бакендов, и в части АПИ это должно быть HTTP/JSON (aka RESTful) API.

Фича - список клиентов

В этой главе мы реализуем первую фичу системы - список клиентов и читатель узнает о следующих элементах Эргономичного подхода:

  1. Entity-Relation модель и диаграмма;
  2. Модель элементов решения (из Basecamp-овского Shape Up);
  3. Test-Driven Development
  4. Верхнеуровневая структура кода тестов (? или сначала весь код свалить в один пакет, а потом его растащить под предлогом, что получилась свалка);
  5. Эпохальная модель времени (? может стоить утащить подальше, чтобы не перегружать главу)
  6. Элементы модели эффектов:
    1. Сигнал типа "Поступил HTTP-запрос";
    2. Ресурсы типа "Репозиторий";
  7. Базовые блоки реализации:
    1. Сущности
    2. DTO команд и запросов;
    3. DTO представлений;
  8. Реализация кастомного базового класс Spring Data JDBC-репозиториев;
  9. Кастомный DSL для динамического построения запросов на базе Spring Data JDBC Criteria API;
  10. Паттерн тестирования "Параллельная разработка операций создания и чтения сущности"
  11. Гайдлан именования тестов: "Тестируемый компонент" + "[при условии] должен делать то-то" - "Метод запроса списка клиентов" + "при отсутствии данных в БД должен возвращать пустой список";
  12. Гайдлан структурирования тела тестов - Arrange/Act/Assert - Сетап/Действие/Проверка;
  13. Паттерн тестирования "Генерация случайных тестовых объектов";
  14. Паттерн тестирования "Генерация списков тестовых объектов";
  15. Паттерн тестирования "Клиенты АПИ";
  16. Паттерн тестирования "getForResponse методы клиентов АПИ"
  17. Паттерн тестирования "Тестовые АПИ";
  18. Паттерн тестирования "Базовый класс тестов";
  19. Модель ошибок и их обработки

Фича - регистрация и логин терапевтов

В этой главе мы реализуем аутентификацию и авторизацию запросов, а так же операции регистрации и логина терапевта. По ходу дела читатель узнает о:

  1. Блоках реализации
    1. Ресурс внешнего сервиса (отправки почты);
    2. Ресурс конфигурируемого алгоритма;
    3. Вспомогательный ресурс;
    4. Ресурс изменяемой структуры данных;
    5. Сложная операция;
    6. Доменная операция;
  2. Паттерне тестирования "Базовая разделяемая фикстура";
  3. Паттерне тестирования "Noop-энкодер паролей в тестах";
  4. Паттерне тестирования "Фейковая реализация ресурса";
  5. Паттерне тестирования "Нарушение инкапсуляции"
  6. Паттерне тестирование "Использование GreenMail в тестах логики отправки Email-ов".

Фича - журнал клиента

В этой главе мы реализуем журналы клиентов и справочник терапевтических задач и по ходу дела узнаем о:

  1. Отношениях 1 ко многим и идентифицирующих и неидентифицирующих отношениях;
  2. Понятии логического и технического агрегата;
  3. Связях между техническими агрегатами (через идентификатор) и внутри технических агрегатов (через прямую ссылку);
  4. Модели и диаграмме эффектов;
  5. Методике транзакционного анализа на базе диаграммы эффектов;
  6. Понятии субдомена модели предметной области;
  7. Паттернах работы с БД "createIfAbsent" и "Upsert";

Фича - файлы клиента

В этой главе мы реализуем хранение файлов клиентов (контрольных фотографий, сканов приёмов врачей и результатов различной диагностики и т.п.) и по ходу дела узнаем о:

  1. Базовом блоке "Составной ресурс"

Фича - справочник упражнений

В этой главе мы реализуем справочник упражнений и по ходу дела узнаем о:

  1. Классах ресурсов - в системе появится два экземпляра ресурса "Хранилище файлов" для файлов клиентов и изображений шагов упражнений;
  2. Базовом блоке объект-значение;
  3. Связи 1 к немногим;
  4. Примененении Mockito для тестирования кода обработки ошибок инфраструктуры
  5. Паттерне тестирования ""

Фича - программы занятий

В этой главе мы реализуем составление программ из упражнений и генерацию docx-документов с программами и по ходу дела узнаем о:

  1. Связях с атрибутами (упражнение У входит в программу П 3-им по порядку);
  2. Применении возможностей PostgreSQL для работы с JSON для выборки сложных представлений;
  3. Модели сбалансированной формы системы;
  4. Паттерне реализации
  5. Паттерне тестирования "Тестирование генерации docx/xlsx-файлов слепым сравнением структуры";

Фича - расписание приёмов

В этой главе реализуем фичу приёмов с их отображением в виде календаря и по ходу дела:

  1. Рассмотрим пример реализации сложной логики (построение view-модели календаря) в виде чистых функций;

Фича - интеграция с ics-календарями

В этой главе реализуем интеграцию с ics-календарями и возможность создания приёмов на базе событий из них и по ходу дела узнаем о:

  1. Абстрактных ресурсах - интерфейс календаря, реализуемый ресурсами приёмов и ics-календарей;
  2. Сигналах типа "Наступил момент выполнения cron-задачи";
  3. Применение WireMock для тестирования интеграции с внешними сервисами по HTTP;

Фича - интеграция с Google Calendars

В этой главе реализуем интеграцию с Google Calendars и возможность создания приёмов на базе событий из них и по ходу дела узнаем о:

  1. Применении Mockito для тестирования интеграций с внешними сервисами через SDK;

Фича - интеграция с Яндекс.Формами

В этой главе реализуем получение WebHook-а от Яндекс.Форм с данными новых клиентов и создание новых карточек клиентов и по ходу дела узнаем о:

  1. Идентифицирующих связях один к одному

Фича - пуш-уведомления

В этой главе мы добавим в систему WebPush-уведомления и реализуем на их основе напоминания для терапевта о планировании предстоящих приёмов и добавлении записей в журнал о прошедших приёмах, оповещении об автоматическом создании новых карточек клиентов и по ходу дела узнаем о:

  1. Ресурсах типа "Очередь сообщений";
  2. Сигналах типа "Поступило новое сообщение в очередь";
  3. Сигналах типа "Произошло доменное событие"

Заключение

Приложение - Руководство пользователя Эргономичного подхода

Опциональное приложение со статьями с Эрговики о ключевых концепциях ЭП.