Технічний базовий рівень курсу

1. Потрібно фіксувати базовий рівень із першого дня 🪂

Якщо не зафіксувати технічну рамку від самого початку, проєкт починає жити в режимі «кожен приклад сам по собі». Один фрагмент коду написаний під одну версію Spring Boot, інший — під іншу. Один студент запускає Gradle, інший — Maven, третій тримає конфігурацію в .properties, а автор прикладу показує YAML. Формально всі щось роблять на Java і Spring. На практиці курс перетворюється на шум.

Baseline розвʼязує дуже просте завдання: робить усі приклади частиною однієї системи. Це означає, що в нас є один інструмент збирання, один вебстек, один формат конфігурації, один підхід до JSON, одна базова тестова стратегія та зрозумілі межі того, що вважається «нормальним шляхом» проєкту.

Це корисно не лише мені як автору курсу, а й вам. Коли стек стабільний, ви приділяєте увагу суті теми. Коли стек плаває, ви постійно вгадуєте: у мене ще не вляглася концепція чи приклад просто написаний на іншій технологічній лінії?

Ще одна цінність baseline полягає в тому, що він привчає до професійної дисципліни. У реальній розробці хороший проєкт майже завжди тримається на домовленостях: чим збираємо, як конфігуруємо, де лежать запити, які залежності вважаються офіційними, які теми не виносимо в публічний контракт. Цей курс починає тренувати таку дисципліну з першого дня, а не «колись потім».

2. Наш мінімальний робочий набір і чому його обрано

У цьому курсі фіксується цілком конкретна технічна рамка:

На старті корисно побачити це не як «таблицю версій», а як карту навчальної дисципліни. Ми не змішуємо Maven і Gradle. Не стрибаємо між application.yml та .properties як рівноправними шляхами. Не підтягуємо WebFlux у курс, який свідомо побудований навколо Spring MVC. Не вдаємо, що validation або Problem Details — це «опційні теми, якщо залишиться час».

Мінімальний build.gradle.kts проєкту матиме приблизно такий вигляд:

plugins {
    java
    // Підключаємо плагін Spring Boot для Gradle і фіксуємо версію платформи (baseline)
    id("org.springframework.boot") version "4.0.3"
}

java {
    toolchain {
        // Жорстко фіксуємо версію Java через toolchain, щоб не залежати від локальної JVM розробника
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    // Стандартний репозиторій, звідки Gradle отримуватиме залежності
    mavenCentral()
}

dependencies {
    // Сервлетний вебстек: Spring MVC (а не WebFlux)
    implementation("org.springframework.boot:spring-boot-starter-webmvc")

    // Валідація вхідних даних як частина контракту API
    implementation("org.springframework.boot:spring-boot-starter-validation")

    // Swagger UI + генерація OpenAPI для документації, орієнтованої на споживача
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.1")

    // Базовий набір тестів для Spring Boot (JUnit, MockMvc тощо)
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

У нас немає мети «підключити все, що буває в проді» 🙃. І це правильно. Стек саме такий, який потрібен курсу з проєктування REST API. Ні ширший, ні вужчий.

3. Один спосіб конфігурації та один стиль запуску

Хороший навчальний проєкт виграє не лише завдяки правильним залежностям, а й завдяки правильним домовленостям. Одна з найкорисніших домовленостей тут — конфігурація живе в application.yml, і це основний шлях проєкту.

Мінімальний фрагмент може виглядати так:

spring:
  mvc:
    problemdetails:
      # Увімкнемо Problem Details як базову модель помилок, щоб error contract був стандартним
      enabled: true

app:
  attachments:
    # Шлях до сховища вкладень задаємо через конфіг, а не хардкодимо в коді
    storage-dir: ./storage/attachments

Ця невелика конфігурація вже робить кілька важливих речей. По-перше, вона фіксує, що Problem Details у проєкті — не факультативна гілка, а нормальна базова модель помилок. По-друге, вона показує правильну дисципліну: налаштування проєкту живуть у конфігу, а не захардкоджені в коді. Вкладення зберігатимуться за шляхом, який задається ззовні, а не ховаються десь у private static final String.

Так само важливий і стиль запуску 🚀. Проєкт збираємо через Gradle. Запити до API живуть у .http-файлах або в колекції Postman, а не «десь у автора в локальних нотатках». Конфігурація єдина, структура проєкту передбачувана. Усе це разом створює відчуття не «навчального хаосу», а нормального репозиторію, який можна відкрити й одразу зрозуміти.

4. Стартовий каркас Task Tracker API як опора

До кінця першого рівня в проєкті має бути не «набір ідей», а зрозумілий стартовий каркас. Приблизно такий:

# Корінь репозиторію проєкту
task-tracker-api/
├── build.gradle.kts
├── settings.gradle.kts
├── gradlew
├── gradlew.bat
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/tasktracker/TaskTrackerApplication.java
│   │   └── resources/
│   │       └── application.yml
├── requests/
│   └── tasks.http
└── README.md

Ця структура здається дуже простою, але в ній уже є все важливе 📦. Є єдине збирання. Є зрозумілий базовий пакет. Є ресурсна конфігурація. Є місце, де живуть ручні HTTP-сценарії. Є один спосіб запускати й перевіряти застосунок.

Наприклад, навіть чорновий .http-файл уже корисний як частина репозиторію:

### Чернетковий запит для списку завдань
# Тестовий запит: отримати список завдань (ручна перевірка API без Postman)
GET http://localhost:8080/api/v1/tasks
# Кажемо серверу, що очікуємо JSON у відповіді
Accept: application/json

Чому це хороший знак? Тому що проєкт стає відтворюваним не лише для JVM, а й для людини 👋. Відкривши репозиторій, ви бачите не тільки код, а й те, як передбачається викликати й перевіряти цей API. Для текстового курсу із самостійним проходженням це дуже цінно: матеріал сам підказує форму роботи.

5. 8 модулів поетапно збирають API production-рівня — шар за шаром

Зверніть увагу: наш курс перестає бути «списком тем» і стає архітектурою зростання одного API.

Це дуже сильна ідея. Вона показує, що наступні 29 днів — не розтягування однієї думки, а послідовне складання API production-рівня. Один і той самий API спочатку вчиться правильно спілкуватися по HTTP, потім отримує нормальний шар контролерів, потім зовнішній JSON-контракт, потім валідацію, потім помилки, потім роботу зі списками, потім файли, потім документацію та тести.

Саме тому курс спроєктовано як міст, а не як огляд. Ви не просто знайомитеся з безліччю тем. Ви шар за шаром доводите один зовнішній API до зрілого стану. Це і є та системність, яку зазвичай дуже цінують у реальній роботі, але рідко вдається відчути в хаотичних туторіалах.

6. Який шлях наш курс відкриває далі

Тепер можна побачити місце курсу в траєкторії backend-розробника. До нього потрібен базовий рівень Spring Boot: вміти підіймати застосунок, розуміти структуру проєкту, не лякатися @RestController і Gradle. Після нього значно краще лягають наступні дисципліни.

Коли зовнішній контракт API вже стабілізований, Spring Data JPA перестає бути спробою побудувати все «від бази вгору» 🗄️. Він стає тим, чим і має бути: курсом про рівень збереження даних, транзакції, модель сутностей, запити та дисципліну роботи з даними.

Коли ресурси, операції та модель помилок уже зібрані, Spring Security перестає бути абстрактною надбудовою 🔐. Він лягає на зрозумілу систему: є ресурси, є операції, є зовнішній контракт, а до них додаються ідентичність, правила доступу та логіка авторизації.

Коли API вже має чіткі сценарії успіху й помилки, JSON-моделі та зрозумілу поведінку валідації, Spring Test теж починає звучати інакше 🧪. Тестується не «щось контролерне», а реальна поведінка контракту.

Саме тому місце цього курсу в лінійці дуже логічне: Spring Boot → Spring REST & MVC → Data / Security / Testing.

Це не організаційна формальність. Це порядок, у якому різні шари backend-професії починають складатися без зайвого хаосу.

7. Типові помилки старту та підсумок дня

Помилка №1: сприймати baseline як нудну бюрократію.
Насправді baseline — це захист від хаосу. Він звільняє увагу для змісту теми, а не відбирає її.

Помилка №2: вважати, що курс «занадто рано переходить до організації».
Якщо організаційна частина справді суха й існує окремо від змісту, це поганий старт. Але тут baseline, проєкт і модульна карта безпосередньо пов'язані з тим, як буде будуватися один API production-рівня.

Помилка №3: недооцінювати модульну архітектуру курсу.
Дуже легко бачити лише назви модулів і не помітити головного: кожен наступний модуль посилює цей самий API, а не відкриває новий випадковий світ.

Помилка №4: думати, що після першого дня ще не почалося справжнє навчання.
Навпаки. Уже сьогодні ви отримали новий професійний кут зору: на API треба дивитися очима клієнта, а на курс — як на складання зовнішнього контракту шар за шаром.