Документирование. Тестирование. Кэширование

Современных подход к разработке программного обеспечения: автоматизировать все что можно. Почитайте про опыт Yandex: Использование Swagger/OpenAPI Specification (по крайней мере до деталей реализации). Для больших проектов это значительная экономия времени-ресурсов + устранение ошибок рассинхронизации API, клиента, тестов и документации. Есть несколько подходов автоматического генерирования документации, например Spring REST Docs — генерирование документации на основе тестов. Подключать его сложнее и, на мой взгляд, он менее распространен, чем генерация документации на основе Spring контроллеров через OpenAPI/Swagger.

Есть 2 способа подключения OpenAPI 3.0 в Spring Boot проект: через Springdoc-openapi и Springfox (см. также migrating from springfox swagger2 to springdoc openapi). Я выбрал первый:

• Для авторизации и поддержки Spring Data REST, кроме springdoc-openapi-ui добавил зависимости springdoc-openapi-security и springdoc-openapi-data-rest.
• Добавил конфигурацию OpenApi в классе OpenApiConfig (OpenAPI/Swagger Basic Auth authorization)
• Для отображения имени контроллера добавил аннотацию @Tag в AccountController контроллер и UserRepository, на основе которого Spring Data REST генерирует User Controller (Swagger-2.X аннтоции)

После патча запуститесь и можно тестировать REST API нашего приложения (не забудте предварительно атворизоваться через Authorize справа вверху). С помощью плагинов Maven также можно генерировать документацию на этапе сборки и автогенерировать код для API.

Apply patch 6_01_oas3_swagger

• http://localhost:8080/swagger-ui.html
• http://localhost:8080/v3/api-docs

• Обновил версию Spring Boot на 2.4.4 (откатите, если у вас новее)
• Добавил ломбуковский @UtilityClass в утильные классы для приватных конструкторов и удалил лишний @AllArgsConstructor
• Добавил в Exception Handler логирование (по умолчанию стандартные ошибки возвращаются без сообщения, чтобы не раскрывать детали реализации)
• Поменял ddl-auto. У нас inmemory база и drop приводит к эксепшенам в логах тестов
• Починил consumes = MediaType.APPLICATION_JSON_VALUE в AccountController

Вариантов тестирования Spring Boot приложения большое множество. Можно поднимать не весь контекст приложения, а только его часть, например только слой репозитория, см Тестовые срезы Spring Boot. Можно, наоборот, поднимать только выбранный контроллер, а остальное мокать. Наконец, можно поднимать весь контекст и тестировать через MockMvc, WebTestClient или RestTemplate. Кроме того, популярно тестирование с помощью REST-Assured (Testing Spring Boot with REST-Assured). Если теперь это умножить на варианты проверки результатов, даже через стандартные библиотеки, которые подтягивает spring-boot-starter-test, мы получим огромное количество информации по запросу тестирование Spring Boot.

На стажировке TopJava мы тестируем как сервисы, так и контроллеры (более 130 тестов). В тестовом приложении на работу (мое личное мнение) не стоит стараться покрыть тестами 100% функционала. Достаточно показать ваш подход к тестированию и сделать тесты самых важных сценариев (юзкейсов). Для тестирования контроллеров в TopJava мы использовали MockMvc, который приходилось самостоятельно настраивать. Spring Boot аннотации @AutoConfigureMockMvc и @SpringBootTest делают это за нас, остается только заинжектить его в тесты, см. базовый класс для всех тестов контроллеров AbstractControllerTest. Добавим зависимость spring-security-test и имитацию аутентификации через @WithUserDetails (см. mock authentication in Spring) и мы уже можем писать тесты к нашим контроллерам.

Теперь подключим поддержку JSON: нужно тестировать запросы с телом (create/update) и проверять содержимое ответов. Вручную писать JSON строки неинтересно, сделаем класс для сериализации-десериализации: JsonUtil. Я разместил его в классах приложения — достаточно часто приходится работать с JSON не только в тестах, но и самом приложении и сделал класс утилитным (обратите внимание, что я не создаю ObjectMapper, а беру из WebSecurityConfig Spring-овый, со всеми настройками). В класс UserTestUtil с тестовыми данными добавим методы для получения созданного и обновленного объекта User и используем их в тестах create/update.

И последнее — проверка тела ответов и объектов в базе после create/update. Создаем в UserTestUtil эталонные объекты для сравнения (те же, что мы вставляем в базу через data.sql). Мы не можем сравнивать entity-объекты, переопределяя equals по всем полям (очень частая ошибка): how should equals and hashcode be implemented when using JPA and Hibernate. В реальных проектах обычно объекты сравниваются по PK (обычно сравнение происходит уже после сохранения в базе, см. реализацию AbstractPersistable от Spring Data JPA). А для сравнения по всем полям (исключая закодированный password) удобно использовать библиотеку AssertJ, которая транзитивно подтягивается с spring-boot-starter-test: Field by field recursive comparison. Напомню, что по идеологии HATEOAS id в ответах не отдается, поэтому для тестирования UserControllerTest сделал еще один метод проверки UserTestUtil#assertNoIdEquals. Работа с _links вместо id и проверка в UserControllerTest#getAll содержимого ответа становится не совсем тривиальной задачей. Если решитесь работать с HATEOAS, предлагаю решить ее вам самим.

• GET http://localhost:8080/api/account (authorize with: user@gmail.com/password)
• GET http://localhost:8080/api/account // cached

• PUT http://localhost:8080/api/account
  Content-Type: application/json
  Authorization: Basic user@gmail.com password
  {
   "id": 1,
   "email": "user@gmail.com",
   "firstName": "User_First_Update",
   "lastName": "User_Last_Update",
   "roles": [
   "USER"
   ]
  }
  ####
  

• GET http://localhost:8080/api/account // cached
• GET http://localhost:8080/api/account // cached

Apply patch 6_06_add_cache

Apply patch 6_07_update_cache