Вы больше не можете создать сервер авторизации с помощью @EnableAuthorizationServer, потому что Spring Security OAuth задеприкейтили, а проект Spring Authorization Serverвсё ещё экспериментальный? Выход есть! Напишем авторизацию своими руками... Что?.. Нет?.. Не хочется? И вообще получаются какие-то костыли и велосипеды? Ну ладно, тогда давайте возьмём уже что-то готовое. Например, Keycloak.

Что, зачем и почему?

Как-то сидя на карантине захотелось мне написать pet-проект, да не простой, а с использованием микросервисной архитектуры (ну или около того). На начальном этапе одного сервиса для фронта и одного для бэка, в принципе, будет достаточно. Если вдруг в будущем понадобятся ещё сервисы, то будем добавлять их по мере необходимости. Для бэка будем использовать Spring Boot. Для фронта - Vue.js, а точнее Vuetify, чтобы не писать свои компоненты, а использовать уже готовые.

Начнём с авторизации. В качестве протокола авторизации будем использовать OAuth2, т.к. стильно, модно, молодёжно, да и использовать токены для получения доступа к сервисам, одно удовольствие, особенно в микросервисной архитектуре.

Для авторизации пусть будет отдельный сервис. И раз уж мы решили использовать Spring Boot, то сможет ли он нам чем-то помочь в создании этого сервиса? Например, каким-нибудь готовым решением, таким как Authorization Server? Правильно, не сможет. Проект Spring Security OAuth в котором находился Authorization Server задеприкейтили, а сам проект Authorization Server стал эксперементальным и на данный момент находится в активной разработке. Что делать? Как быть? Можно написать свой сервис авторизации. Если подсматривать в исходники задеприкейченого Authorization Server, то, вероятно, задача будет не такой уж и страшной. Правда, при этом возможны ситуации когда реализацию каких-то интересных фич будет негде подсмотреть и решать вопросы о том "быть или не быть", "правильно ли так делать или чё-то фигня какая-то" придётся исходя из собственного опыта, что может привести к получению на выходе большого количества неприглядных костылей.

Что делать, если городить собственные велосипеды не хочется или хочется, но на данный момент это кажется весьма долгим процессом, а результат нужен уже вчера? Есть ли какие-то готовые решения, способные решить данную проблему? Да, есть. Давайте одно из таких решений и рассмотрим.

Keycloak

Keycloak представляет из себя сервис, который предназначен для идентификации и контроля доступа. Что он умеет:

• SSO (Single-Sign On) - это когда вы логинитесь в одном едином месте входа, получаете идентификатор (например, токен), с которым можете получить доступ к различным вашим сервисам

• Login Flows - различные процессы по регистрации, сбросу пароля, проверки почты и тому подобное, а так же соответствующие страницы для этих процессов

• Темы - можно кастомизировать страницы для Login Flows

• Social Login - можно логиниться через различные социальные сети

• и много чего ещё

И всё это он умеет практически из коробки, достаточно просто настроить требуемое поведение из админки (Admin Console), которая у Keycloak тоже имеется. А если вам всего этого вдруг окажется мало, то Keycloak является open sourceпродуктом, который распространяется по лицензии Apache License 2.0. Так что можно взять исходники Keycloak и дописать требуемый функционал, если он вам, конечно, настолько сильно нужен.

А ещё у Keycloak имеются достаточно удобные интеграции со Spring Boot и Vue.js, что значительно упрощает разработку связанную с взаимодействием с ним.

Getting Started with Keycloak

Запускать локально сторонние сервисы, требуемые для разработки своих собственных, лично я предпочитаю с помощью Docker Compose, т.к. наглядно и достаточно удобно в yml-файле описывать как и с какими параметрами требуется осуществлять запуск. А посему, Keycloak локально будем запускать с помощью Docker Compose.

В качестве докер-образа возьмём jboss/keycloak. Чтобы иметь возможность обращаться к Keycloak прокинем из контейнера порт 8080. Так же, чтобы иметь возможность заходить в админку Keycloak, требуется установить логин и пароль от админской учётки. Сделать это можно установив переменные окружения KEYCLOAK_USER для логина и KEYCLOAK_PASSWORD для пароля. Итоговый файл приведен ниже.

# For developmentversion: "3.8"services:  keycloak:    image: jboss/keycloak:12.0.2    environment:      KEYCLOAK_USER: admin      KEYCLOAK_PASSWORD: admin    ports:      - 8080:8080

Создание своих realm и client

Для того чтобы иметь возможность из своего клиентского приложения обращаться к Keycloak, например, для аутентификации или авторизации, нужно в Keycloak создать клиента (client), который будет соответствовать этому приложению. Клиента в Keycloak можно создать в определённом realm. Realm - это независимая область в которую входят пользователи, клиенты, группы, роли и много чего ещё.

По умолчанию уже создан один realm и называется он master. В нём будет находится админская учётка логин и пароль от которой мы задали при запуске Keycloak с помощью Docker Compose. Данный realm предназначен для администрирования Keycloak и он не должен использоваться для ваших собственных приложений. Для своих приложений нужно создать свой realm.

Для начала нам нужно залогиниться в админке Keycloak, запустить который можно с помощью файла Docker Compose, описанного ранее. Для этого можно перейти по адресу http://localhost:8080/auth/ и выбрать Administration Console.

После этого мы попадаем на страницу авторизации админки Keycloak. Здесь можно ввести логин и пароль от админской учётки для входа в Keycloak.

После входа откроется страница настроек realm master.

Давайте создадим свой realm. Для этого необходимо навести курсор на область с названием realm, чтобы появилась кнопка Add realm.

На странице создания realm достаточно заполнить только поле Name.

После нажатия на кнопку Createмы попадём на страницу редактирования этого realm. Но пока дополнительно в нашем realm ничего менять не будем.

Теперь перейдём в раздел Clients. Как можно заметить, по умолчанию уже создано несколько технических клиентов, предназначенных для возможности администрирования через Keycloak, например, для того чтобы пользователи могли менять свои данные или чтобы можно было настраивать realm'ы с помощью REST API и много для чего ещё. Подробнее про этих клиентов можно почитать тут.

Давайте создадим своего клиента. Для этого в разделе Clientsнеобходимо нажать на кнопку Create.

На странице создания клиента необходимо заполнить поля:

• Client ID - идентификатор клиента, будет использоваться в различных запросах к Keycloak для идентификации приложения.

• Root URL - адрес клиентского приложения.

После нажатия на кнопку Saveмы попадём на страницу редактирования этого клиента. Настройки клиента менять не будем, оставим их такими, какими они были выставлены по умолчанию.

Интеграция со Spring Boot

В первую очередь давайте создадим проект на Spring Boot. Сделать это можно, например, с помощью Spring Initializr. В качестве системы автоматической сборки проекта будем использовать Gradle. В качестве языка пусть будет Java 15. Никаких дополнительных зависимостей в соответствующем блоке Dependencies добавлять не требуется.

Для того чтобы в Spring Boot проекте появилась поддержка Keycloak, необходимо добавить в него Spring Boot Adapter и добавить в конфиг приложения конфигурацию для Keycloak.

Для того чтобы добавить Spring Boot Adapter, необходимо в проект подключить зависимость org.keycloak:keycloak-spring-boot-starter и сам adapter org.keycloak.bom:keycloak-adapter-bom. Сделать это можно изменив файл build.gradle следующим образом:

...dependencyManagement {imports {mavenBom 'org.keycloak.bom:keycloak-adapter-bom:12.0.3'}}dependencies {implementation 'org.springframework.boot:spring-boot-starter-web'implementation 'org.keycloak:keycloak-spring-boot-starter'testImplementation 'org.springframework.boot:spring-boot-starter-test'}...

...dependencies {implementation('org.springframework.boot:spring-boot-starter-web') {exclude module: 'spring-boot-starter-tomcat'}implementation ('org.keycloak:keycloak-spring-boot-starter') {exclude module: 'spring-boot-starter-tomcat'}implementation 'org.springframework.boot:spring-boot-starter-undertow'testImplementation 'org.springframework.boot:spring-boot-starter-test'}...

Теперь перейдём к конфигурации приложения. Вместо properties файла конфигурации давайте будем использовать более удобный (на мой взгляд, конечно же) yml. А так же, чтобы подчеркнуть, что данный конфиг предназначен для разработки, профиль dev. Т.е. полное название файла конфигурации будет application-dev.yml.

server:  port: 8082keycloak:  auth-server-url: http://localhost:8080/auth  realm: "list-keep"  resource: "list-keep"  bearer-only: true  security-constraints:    - authRoles:        - uma_authorization      securityCollections:        - patterns:            - /api/*

Давайте подробнее разберём данный конфиг:

• server

  • port - порт на котором будет запущенно приложение

• keycloak

  • auth-server-url - адрес на котором запущен Keycloak

  • realm - название нашего realm в Keycloak

  • resource - Client ID нашего клиента

  • bearer-only - если выставлено true, то приложение может только проверять токены, и в приложении нельзя будет залогиниться, например, с помощью логина и пароля из браузера

  • security-constraints - для описания ролевой политики

    • authRoles - список ролей Keycloak

    • securityCollections

      • patterns - URL-паттерны для методов REST API, которые требуется закрыть соответствующими ролями

    В данном конкретном случае мы закрываем ролью uma_authorization все методы, в начале которых присутствует путь /api/. Звёздочка в конце паттерна означает любое количество любых символов. Роль uma_authorization добавляется автоматически ко всем созданным пользователям, т.е. по сути данная ролевая политика означает что все методы /api/* доступны только авторизованным пользователям.

В общем-то, это все настройки которые нужно выполнить в Spring Boot приложении для интеграции с Keycloak. Давайте теперь добавим какой-нибудь тестовый контроллер.

@RestController@RequestMapping("/api/user")public class UserController {    @GetMapping("/current")    public User getCurrentUser(            KeycloakPrincipal<KeycloakSecurityContext> principal    ) {        return new User(principal.getKeycloakSecurityContext()                .getToken().getPreferredUsername()        );    }}

public class User {    private String name;    public User(String name) {        this.name = name;    }    public String getName() {        return name;    }    public void setName(String name) {        this.name = name;    }}

В данном контроллере есть лишь один метод /api/user/current, который возвращает информацию по текущему юзеру, а именно Preferred Username из токена. По умолчанию в Preferred Username находится username пользователя Keycloak.

Исходники проекта можно посмотреть тут.

Интеграция с Vue.js

Начнём с создания проекта. Создать проект можно, например, с помощью Vue CLI.

vue create list-keep-front

После ввода данной команды необходимо выбрать версию Vue. Т.к. в проекте будет использоваться библиотека Vuetify, которая на данный момент не поддерживает Vue 3, нужно выбрать Vue 2.

После этого нужно перейти в проект и добавить Vuetify.

vue add vuetify

После добавления Vuetify вместе с самой библиотекой в проект будут добавлены каталоги components и assets. В components будет компонент HelloWorld, с примером страницы на Vuetify, а в assets ресурсы, использующиеся в компоненте HelloWorld. Эти каталоги нам не пригодятся, поэтому можно их удалить.

Для удобства разработки сконфигурируем devServer следующим образом: запускать приложение будем на порту 8081, все запросы, которые начинаются с /api/ будем проксировать на адрес, на котором запущенно приложение на Spring Boot.

module.exports = {  devServer: {    port: 8081,    proxy: {      '^/api/': {        target: 'http://localhost:8082'      }    }  }}

Перейдём к добавлению в проект поддержки Keycloak. Для начала обратимся к официальной документации. Там нам рассказывают о том, что в проект нужно добавить Keycloak JS Adapter. Сделать это можно с помощью библиотеки keycloak-js. Добавим её в проект.

yarn add keycloak-js

Далее нам предлагают добавить в src/main.js код, который добавит в наш проект поддержку Keycloak.

// Параметры для подключения к Keycloaklet initOptions = {  url: 'http://127.0.0.1:8080/auth', // Адрес Keycloak  realm: 'keycloak-demo', // Имя нашего realm в Keycloak  clientId: 'app-vue', // Идентификатор клиента в Keycloak    // Перенаправлять неавторизованных пользователей на страницу входа  onLoad: 'login-required'}// Создать Keycloak JS Adapterlet keycloak = Keycloak(initOptions);// Инициализировать Keycloak JS Adapterkeycloak.init({ onLoad: initOptions.onLoad }).then((auth) => {  if (!auth) {    // Если пользователь не авторизован - перезагрузить страницу    window.location.reload();  } else {    Vue.$log.info("Authenticated");        // Если авторизован - инициализировать приложение Vue    new Vue({      el: '#app',      render: h => h(App, { props: { keycloak: keycloak } })    })  }  // Пытаемся обновить токен каждые 6 секунд  setInterval(() => {    // Обновляем токен, если срок его действия истекает в течении 70 секунд    keycloak.updateToken(70).then((refreshed) => {      if (refreshed) {        Vue.$log.info('Token refreshed' + refreshed);      } else {        Vue.$log.warn('Token not refreshed, valid for '          + Math.round(keycloak.tokenParsed.exp          + keycloak.timeSkew - new Date().getTime() / 1000) + ' seconds');      }    }).catch(() => {      Vue.$log.error('Failed to refresh token');    });  }, 6000)}).catch(() => {  Vue.$log.error("Authenticated Failed");});

С инициализацией Keycloak JS Adapter, вроде бы, всё понятно. А вот использование setInterval для обновления токенов мне показалось не очень практичным и красивым решением. Как минимум, кажется, что при бездействии пользователя на странице токены всё равно продолжат обновляться, хоть это и не требуется. На мой взгляд, обновление токенов лучше сделать так, как предлагает, например, автор данной статьи. Т.е. обновлять токены когда пользователь выполняет какое-либо действие в приложении. Автор указанной статьи выделяет три таких действия:

• Взаимодействие с API (бэкендом)

• Навигация (переход по страницам)

• Переход на вкладку с нашим приложением, например, из другой вкладки

Приступим к реализации. Для того чтобы можно было обновлять токен из различных частей приложения, нам понадобится глобальный экземпляр Keycloak JS Adapter. Для этого во Vue.js существует функционал плагинов. Создадим свой плагин для Keycloak JS Adapter в файле /plugins/keycloak.js.

import Vue from 'vue'import Keycloak from 'keycloak-js'const initOptions = {    url: process.env.VUE_APP_KEYCLOAK_URL,    realm: 'list-keep',    clientId: 'list-keep'}const keycloak = Keycloak(initOptions)const KeycloakPlugin = {    install: Vue => {        Vue.$keycloak = keycloak    }}Vue.use(KeycloakPlugin)export default KeycloakPlugin

Значение адреса Keycloak, указанное в initOptions.url, может отличаться в зависимости от того где запущенно приложение (локально, на тесте, на проде), поэтому, чтобы иметь возможность указывать значения в зависимости от среды, будем использовать переменные окружения. Для локального запуска можно создать файл .env.local в корне проекта со следующим содержимым.

VUE_APP_KEYCLOAK_URL = http://localhost:8080/auth

Теперь нам достаточно импортировать файл с созданным нами плагином в main.js, и мы сможем из любого места приложения обратиться к нашему Keycloak JS Adapter с помощью Vue.$keycloak. Давайте это и сделаем, а так же создадим экземпляр Vue нашего приложения. Для этого изменим файл main.js следующим образом.

import Vue from 'vue'import App from './App.vue'import vuetify from './plugins/vuetify'import router from '@/router'import i18n from '@/plugins/i18n'import '@/plugins/keycloak'import { updateToken } from '@/plugins/keycloak-util'Vue.config.productionTip = falseVue.$keycloak.init({ onLoad: 'login-required' }).then((auth) => {  if (!auth) {    window.location.reload();  } else {    new Vue({      vuetify,      router,      i18n,      render: h => h(App)    }).$mount('#app')    window.onfocus = () => {      updateToken()    }  }})

Помимо инициализации Keycloak JS Adapter, здесь добавлен вызов функции updateToken() на событие window.onfocus, которое будет возникать при переходе пользователя на вкладку с нашим приложением. Наша функция updateToken() вызывает функцию updateToken() из Keycloak JS Adapter и, соответственно, обновляет токен, если срок жизни токена в секундах на данный момент меньше, чем значение TOKEN_MIN_VALIDITY_SECONDS, после чего возвращает актуальный токен.

import Vue from 'vue'const TOKEN_MIN_VALIDITY_SECONDS = 70export async function updateToken () {    await Vue.$keycloak.updateToken(TOKEN_MIN_VALIDITY_SECONDS)    return Vue.$keycloak.token}

Теперь добавим обновление токена на оставшиеся действия пользователя, а именно на взаимодействие с API и на навигацию. С API мы будем взаимодействовать с помощью axios. Помимо обновления токена нам в каждом запросе необходимо добавлять http-хидер Authorization: Bearer с нашим токеном для авторизации в нашем Spring Boot сервисе. Так же давайте будем перенаправлять на какую-нибудь страницу с ошибками, например, /error, если API будет возвращать нам ошибки. Для того чтобы выполнять какие-либо действие на любые запросы/ответы в axios существуют интерцепторы, добавить которые можно в App.vue.

<template>  <v-app>    <v-main>      <router-view></router-view>    </v-main>  </v-app></template><script>import Vue from 'vue'import axios from 'axios'import { updateToken } from '@/plugins/keycloak-util'const AUTHORIZATION_HEADER = 'Authorization'export default Vue.extend({  name: 'App',  created: function () {    axios.interceptors.request.use(async config => {      // Обновляем токен      const token = await updateToken()      // Добавляем токен в каждый запрос      config.headers.common[AUTHORIZATION_HEADER] = `Bearer ${token}`      return config    })        axios.interceptors.response.use( (response) => {      return response    }, error => {      return new Promise((resolve, reject) => {        // Если от API получена ошибка - отправляем на страницу /error        this.$router.push('/error')        reject(error)      })    })  },  // Обновляем токен при навигации  watch: {    $route() {      updateToken()    }  }})</script>

Помимо интерцепторов мы здесь добавили наблюдателя (watch), который будет отслеживать переход пользователя по страницам приложения и обновлять при этом токен.

Интеграция с Keycloak закончена. Давайте теперь добавим тестовую страницу /pages/Home.vue, на которой будем вызывать с помощью axios тестовый метод /api/user/current, который мы ранее добавили в Spring Boot приложение, и выводить имя полученного пользователя.

<template>  <div>    <p>{{ user.name }}</p>  </div></template><script>import axios from 'axios'export default {  name: 'Home',  data() {    return {      user: {}    }  },  mounted() {    axios.get('/api/user/current')        .then(response => {          this.user = response.data        })  }}</script>

Для того чтобы можно было попасть на данную страницу в нашем приложении необходимо добавить её в router.js. Данная страница будет доступна по пути /.

import Vue from 'vue'import VueRouter from 'vue-router'import Home from '@/pages/Home'import Error from '@/pages/Error'import NotFound from '@/pages/NotFound'Vue.use(VueRouter)let router = new VueRouter({    mode: 'history',    routes: [        {            path: '/',            component: Home        },        {            path: '/error',            component: Error        },        {            path: '*',            component: NotFound        }    ]})export default router

По умолчанию роутер работает в так называемом режиме хэша и при навигации страницы в адресной строке отображаются с символом #. Для более естественного отображения можно включить режим history.

<template>  <v-container      class="text-center"      fill-height      style="height: calc(100vh - 58px);"  >    <v-row align="center">      <v-col>        <h1 class="display-2 primary--text">          {{ $t('oops.error.has.occurred') }}        </h1>        <p>{{ $t('please.try.again.later') }}</p>        <v-btn            href="http://personeltest.ru/aways/habr.com/"            color="primary"            outlined        >          {{ $t('go.to.main.page') }}        </v-btn>      </v-col>    </v-row>  </v-container></template><script>export default {  name: 'Error'}</script>

import Vue from 'vue'import VueI18n from 'vue-i18n'Vue.use(VueI18n)function loadLocaleMessages () {    const locales = require.context('@/locales', true,                                    /[A-Za-z0-9-_,\s]+\.json$/i)    const messages = {}    locales.keys().forEach(key => {        const matched = key.match(/([A-Za-z0-9-_]+)\./i)        if (matched && matched.length > 1) {            const locale = matched[1]            messages[locale] = locales(key)        }    })    return messages}export default new VueI18n({    locale: 'ru',    fallbackLocale: 'ru',    messages: loadLocaleMessages()})

import Vue from 'vue'import Vuetify from 'vuetify/lib/framework'import 'vuetify/dist/vuetify.min.css'import '@fortawesome/fontawesome-free/css/all.css'Vue.use(Vuetify);const opts = {    icons: {        iconfont: 'fa'    }}export default new Vuetify(opts)

Исходники проекта можно посмотреть тут.

Login Flows

Теперь давайте перейдём непосредственно к настройке процессов авторизации и регистрации, а так же соответствующих страниц. Т.к. возможностей по конфигурации Login Flows в Keycloak очень много, то давайте рассмотрим лишь некоторые из них, которые, на мой взгляд, являются наиболее важными. Предлагаю следующий список.

• Авторизация и регистрация пользователей

• Локализация страниц

• Подтверждение email

• Вход через социальные сети

Локализация страниц в Keycloak

Запустим наши Spring Boot и Vue.js приложения. При переходе в клиентское Vue.js приложение нас перенаправит на страницу логина Keycloak.

В первую очередь давайте добавим поддержку русского языка. Для этого в админке Keycloak, на вкладке Theams, в настройки realm включаем флаг Internationalization Enabled . В Supported Locales убираем все локали кроме ru, пусть наше приложение на Vue.js поддерживает только один язык. В Default Locale выставляем ru.

Нажимаем Save и возвращаемся в наше клиентское приложение.

Как видим, русский язык у нас появился, правда, не все текстовки были локализованы. Это можно исправить, добавив собственные варианты перевода. Сделать это можно на вкладке Localization, в настройках realm.

Здесь имеется возможность добавить текстовки вручную по одной, либо загрузить их из json файла. Давайте сделаем это вручную. Для начала требуется добавить локаль. Вводим ru и нажимаем Create. После чего попадаем на страницу Add localization text. На этой странице нам необходимо заполнить поля Key и Value. Если с value всё ясно, это будет просто значение нашей текстовки, то вот где взять Key не совсем понятно. В документации допустимые ключи нигде не описаны (либо я просто плохо искал), поэтому остаётся лишь найти их в исходниках Keycloak. Находим в ресурсах нужную нам базовую тему base и страницу login, а затем файл с текстовками в локали en - messages_en.properties. В этом файле по значению определяем нужный нам ключ текстовки, добавляем его в Key на странице Add localization text, а так же добавляем нужное нам Value и нажимаем Save.

После этого на вкладке Localization в настройках realm, при выборе локали ru, появляется таблица, в которой можно посмотреть, отредактировать или удалить нашу добавленную текстовку.

Вернёмся в наше клиентское приложение. Теперь все текстовки на странице логина локализованы.

Регистрация пользователей

Поддержку регистрации пользователей можно добавить, включив флаг User registration на вкладке Login в настройках realm.

После этого на странице логина появится кнопка Регистрация.

Нажимаем на кнопку Регистрация и попадаем на соответствующую страницу.

Давайте немного подкрутим эту страницу. Для начала добавим отсутствующий перевод текстовки, аналогично тому, как мы делали это ранее для страницы логина. Так же давайте уберём поле Имя пользователя. На самом деле совсем его убрать нельзя, т.к. это поля обязательно для заполнения у пользователя Keycloak, но можно сделать так, чтобы в качестве имени пользователя использовался email, при этом поле Имя пользователя исчезнет с формы регистрации. Сделать это можно, включив флаг Email as username на вкладке Login в настройках realm. После этого возвращаемся на страницу регистрации и видим что поле исчезло.

Кроме этого на странице логина поле, которое ранее называлось Имя пользователя или E-mail, теперь называется просто E-mail. Правда, пользователи, которые, например, были созданы до выставления этого флага, и у которых email отличается от имени пользователя, могут продолжать в качестве логина использовать имя пользователя и всё будет корректно работать.

Подтверждение email

Давайте включим подтверждение email у пользователей, чтобы после регистрации они не могли зайти в наше приложение, пока не подтвердят свой email. Сделать это можно, включив флаг Verify email на вкладке Login в настройках realm. И нет, после этого волшебным образом всё не заработает, нужно ещё где-то добавить конфигурацию SMTP-сервера, с которого мы будем осуществлять рассылку. Сделать это можно на вкладке Email, в настройках realm. Ниже приведён пример настроек SMTP-сервера Gmail.

Нажимаем Test connection и получаем ошибку.

Ошибка возникает из-за того, что при нажатии на Test connection должно отправиться письмо на адрес пользователя, под которым мы сейчас залогинены в Keycloak, но этот адрес не задан. Соответственно, если вы заранее задали этот email, ошибки не будет.

Давайте зададим email нашему пользователю Keycloak. Для этого перейдём в realm master на страницу Users и нажмём View all users, чтобы отобразить всех пользователей.

Перейдём на страницу редактирования нашего пользователя и зададим ему email.

Возвращаемся на страницу конфигурации SMTP-сервера, снова пробуем Test connection и видим что всё рабо... Нет, мы снова видим ошибку. Правда, уже другую.

Если все параметры подключения к SMTP-серверу заданы корректно, и вы тоже используете SMTP-сервер Gmail, то, возможно, вам поможет разрешение доступа к вашему аккаунту "ненадежных приложений" в настройках безопасности вашего аккаунта, с которого вы пытаетесь отправлять письма. Если не поможет, то да прибудет с вами Google. Если вы используете SMTP-сервер не от Gmail, то, возможно, у вас не будет подобной ошибки, а если будет, может быть, в настройках вашей почты тоже можно задать подобную конфигурацию для "ненадежных приложений".

Снова жмём Test connection и, наконец-то, получаем Success.

Содержимое письма, которое будет ждать нас на почте, представлено ниже.

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

После нажатия на кнопку Регистрация. Мы попадём на страницу с предупреждением о том, что нужно подтвердить email. На эту страницу мы будем попадать каждый раз при логине в нашем приложении, до тех пор пока не подтвердим email.

На почту нам придёт письмо с ссылкой, по которой можно подтвердить email.

После перехода по ссылке мы попадём на нашу тестовую страницу /pages/Home.vue, на которой просто выводится имя пользователя. Т.к. в настройках нашего realm мы указали Email as username, то на данной странице мы увидим email нашего пользователя.

Social Login

Теперь добавим вход через социальные сети. В качестве примера давайте рассмотрим вход с помощью Google. Для того чтобы добавить данный функционал нужно в нашем realm создать соответствующий Identity Provider. Для этого нужно перейти на страницу Identity Providers и в списке Add provider... выбрать Google.

После этого мы попадём на страницу создания Identity Provider.

Здесь нам требуется задать два обязательных параметра - Client ID и Client Secret. Взять их можно из Google Cloud Platform.

В первую очередь нам нужно создать в Google Cloud Platform проект.

Жмём CREATE PROJECT и попадаем на страницу создания проекта.

Задаём имя, жмём CREATE, ждём некоторое время, пока не будет создан наш проект, и после этого попадаем на DASHBOARD проекта.

Выбираем в меню APIs & Services -> Credentials. И попадаем на страницу на которой мы можем создавать различные ключи для нашего приложения.

Жмём Create credentials -> OAuth client ID и попадаем на очередную страницу.

Видим, что нам так просто не хотят давать возможность создавать ключи, а сначала просят создать некий OAuth consent screen. Что ж, хорошо, жмём CONFIGURE CONSENT SCREEN и снова новая страница.

Здесь давайте выберем External. Ну как выберем, выбора, на самом деле, у нас нет, т.к. Internal доступно только пользователямGoogle Workspace и эта штука платная и нужна, в общем-то, только организациям. Нажимаем Create и попадаем на страницу OAuth consent screen. Здесь заполняем название приложения и почты и жмём SAVE AND CONTINUE.

На следующей странице можно задать так называемые области действия OAuth 2.0 для API Google. Ничего задавать не будем, жмём SAVE AND CONTINUE.

На этой странице можно добавить тестовых пользователей. Только тестовые пользователи могут получить доступ к вашему приложением пока оно находится в статусе Testing. Но при этом логиниться в вашем приложении можно не добавляя здесь пользователей. По крайней мере это так работает на момент написания статьи. Поэтому давайте не будем добавлять здесь никаких пользователей. В любом случае, если у вас не получится авторизоваться, вы сможете добавить тестовых пользователей позднее.

На следующей странице можно проверить все данные, которые мы заполняли и в случае чего перейти к конкретному блоку с помощью кнопки EDIT.

Жмём BACK TO DASHBOARD, чтобы всё это уже закончить, и попадаем на страницу, на которой мы можем редактировать все те данные, которые мы вводили на предыдущих страницах.

Жмём Credentials, затем снова Create credentials -> OAuth client ID и попадаем на страницу создания OAuth client ID. И снова нужно что-то вводить. Google, ну сколько можно?! Ниже приведены поля, которые необходимо заполнить на этой странице.

• Application type - выбираем Web application

• Name - пишем имя нашего приложения

• Authorized redirect URIs - сюда пишем значение из поля Redirect URI со страницы создания Identity Provider, чтобы Google редиректил пользователей на корректный адрес Keycloak после авторизации

Жмём CREATE и, наконец-то, получаем требуемые нам Client ID и Client Secret, которые нам нужно указать на странице создания Identity Provider в Keycloak.

Заполняем поля Client ID и Client Secret и жмём Save, чтобы создать Identity Provider. Теперь вернёмся на страницу логина нашего клиентского приложения. На этой странице появится нелокализованная текстовка, добавить её можно аналогично тому, как это было сделано ранее. Ниже на скрине ниже эта проблема уже устранена.

Итак, это всё что требовалось сделать, теперь мы можем входить в наше приложение с помощью Google.

Импорт и экспорт в Keycloak

В Keycloak есть возможность импортировать и экспортировать конфигурации ваших realm'ов. Это можно использовать, например, для переноса конфигураций между различными инстансами Keycloak. Или, что более вероятно, для того чтобы можно было запускать Keycloak локально с уже готовой конфигурацией и использовать его для разработки. Это может быть полезно в тех ситуациях, когда нет возможности запустить Keycloak глобально на каком-нибудь сервере либо когда до этого инстанса Keycloak по какой-либо причине нет доступа.

Для того чтобы экспортировать конфигурацию из Keycloak, нужно перейти на страницу Export, выбрать данные, которые нужно экспортировать и нажать Export.

После этого выгрузится файл realm-export.json с конфигурацией того realm в котором мы сейчас находимся. При этом различные пароли и секреты в этом файле будут в виде **********, поэтому, прежде чем куда-то импортировать этот файл, нужно заменить все такие значения на корректные. Либо сделать это после импорта через адиминку.

Импортировать данные можно на странице Import. Либо в yml-файле Docker Compose, если вы его используете. Для этого нужно указать в переменной окружения KEYCLOAK_IMPORT путь до ранее экспортированного файла и примонтировать этот файл в контейнер с помощью volumes. Итоговый файл приведен ниже.

# For developmentversion: "3.8"services:  keycloak:    image: jboss/keycloak:12.0.2    environment:      KEYCLOAK_USER: admin      KEYCLOAK_PASSWORD: admin      KEYCLOAK_IMPORT: "/tmp/realm-export.json"    volumes:      - "./keycloak/realm-export.json:/tmp/realm-export.json"    ports:      - 8080:8080

#!/bin/bashDIRECT_GRANT_RESPONSE=$(curl -i --request POST http://localhost:8080/auth/realms/master/protocol/openid-connect/token --header "Accept: application/json" --header "Content-Type: application/x-www-form-urlencoded" --data "grant_type=password&username=admin&password=admin&client_id=admin-cli");export DIRECT_GRANT_RESPONSEACCESS_TOKEN=$(echo $DIRECT_GRANT_RESPONSE | grep "access_token" | sed 's/.*\"access_token\":\"\([^\"]*\)\".*/\1/g');export ACCESS_TOKENcurl -i --request POST http://localhost:8080/auth/admin/realms/list-keep/localization/ru -F "file=@ru.json" --header "Content-Type: multipart/form-data" --header "Authorization: Bearer $ACCESS_TOKEN";

Заключение

Что ж. Вот и всё. Это конец. Надеюсь, мне удалось показать насколько просто и быстро можно интегрировать Keycloak с вашими приложениями. А так же насколько просто можно прикручивать различный функционал, связанный с аутентификацией и авторизацией пользователей, благодаря тому что большая часть этого функционала доступна из коробки. По крайней мере, насколько это может быть проще, чем если бы всё это приходилось писать самому.
Надеюсь, вы нашли в этой статье что-то полезное и интересное.
И ещё... Берегите там себя.

Будущих студентов курса Разработчик на Spring Framework и всех желающих приглашаем на открытый онлайн-урок по теме Введение в облака, создание кластера в Mongo DB Atlas018. Участники вместе с преподавателем-экспертом поговорят о видах облаков и настроят бесплатный Mongo DB кластер для своих проектов.

А сейчас делимся с вами традиционным переводом статьи.

В этой статье мы поговорим о том, как установить и настроить службу обнаружения (service discovery) для Java-микросервисов.

Что такое Eureka Server?

Eureka Server это service discovery (обнаружение сервисов) для ваших микросервисов. Клиентские приложения могут самостоятельно регистрироваться в нем, а другие микросервисы могут обращаться к Eureka Server для поиска необходимых им микросервисов.

Eureka Server также известен как Discovery Server и содержит такую информацию как IP-адрес и порт микросервиса.

Для создания приложения с Eureka Server необходимо в pom.xml добавить указанную ниже зависимость.

<dependency>  <groupId>org.springframework.cloud</groupId>  <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId></dependency>

Запускаем Eureka Server

Перейдите на https://start.spring.io и создайте шаблон проекта. Укажите метаданные, такие как Group, Artifact, и добавьте указанные ниже зависимости / модули. Нажмите "Generate Project" и загрузите проект в zip-файле. Далее разархивируйте его и импортируйте в IDE как Maven-проект.

• Eureka Server

• Web

• Actuator

Проверьте, что pom.xml выглядит следующим образом:

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://personeltest.ru/away/maven.apache.org/POM/4.0.0" xmlns:xsi="http://personeltest.ru/away/www.w3.org/2001/XMLSchema-instance"        xsi:schemaLocation="http://personeltest.ru/away/maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">   <modelVersion>4.0.0</modelVersion>   <parent>       <groupId>org.springframework.boot</groupId>       <artifactId>spring-boot-starter-parent</artifactId>       <version>2.0.7.RELEASE</version>       <relativePath/> <!-- lookup parent from repository -->   </parent>   <groupId>com.example.eureka.server</groupId>   <artifactId>eureka-server</artifactId>   <version>0.0.1-SNAPSHOT</version>   <name>eureka-server</name>   <description>Demo project for Spring Boot</description>   <properties>       <java.version>1.8</java.version>       <spring-cloud.version>Finchley.SR2</spring-cloud.version>   </properties>   <dependencies>       <dependency>           <groupId>org.springframework.boot</groupId>           <artifactId>spring-boot-starter-actuator</artifactId>       </dependency>       <dependency>           <groupId>org.springframework.boot</groupId>           <artifactId>spring-boot-starter-web</artifactId>       </dependency>       <dependency>           <groupId>org.springframework.cloud</groupId>           <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>       </dependency>       <dependency>           <groupId>org.springframework.boot</groupId>           <artifactId>spring-boot-starter-test</artifactId>           <scope>test</scope>       </dependency>   </dependencies>   <dependencyManagement>       <dependencies>           <dependency>               <groupId>org.springframework.cloud</groupId>               <artifactId>spring-cloud-dependencies</artifactId>               <version>${spring-cloud.version}</version>               <type>pom</type>               <scope>import</scope>           </dependency>       </dependencies>   </dependencyManagement>   <build>       <plugins>           <plugin>               <groupId>org.springframework.boot</groupId>               <artifactId>spring-boot-maven-plugin</artifactId>           </plugin>       </plugins>   </build></project>

Теперь откройте файл EurekaServerApplication.java и добавьте для класса аннотацию @EnableEurekaServer, как показано ниже.

package com.example.eureka.server.eurekaserver;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;@SpringBootApplication@EnableEurekaServerpublic class EurekaServerApplication {  public static void main(String[] args) {     SpringApplication.run(EurekaServerApplication.class, args);  }}

Добавьте в application.properties, расположенный в src/main/resources, следующие параметры.

spring.application.name=eureka-serverserver.port=8761eureka.client.register-with-eureka=falseeureka.client.fetch-registry=false

• spring.application.name уникальное имя для вашего приложения.

• server.port порт, на котором будет запущено ваше приложение, мы будем использовать порт по умолчанию (8761).

• eureka.client.register-with-eureka определяет, регистрируется ли сервис как клиент на Eureka Server.

• eureka.client.fetch-registry получать или нет информацию о зарегистрированных клиентах.

Запустите сервер Eureka как Java-приложение и перейдите по адресу http://localhost:8761/

Вы увидите, что Eureka Server запущен и работает, но в нем еще нет зарегистрированных приложений.

Регистрация клиентского приложения в Eureka Server

Перейдите на https://start.spring.io и создайте шаблон проекта. Укажите метаданные, такие как Group, Artifact, и добавьте указанные ниже зависимости / модули. Нажмите "Generate Project" и загрузите проект в zip-файле. Далее разархивируйте его и импортируйте в IDE как Maven-проект.

• DevTools

• Actuator

• Discovery Client

Проверьте, что ваш pom.xml выглядит следующим образом:

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://personeltest.ru/away/maven.apache.org/POM/4.0.0" xmlns:xsi="http://personeltest.ru/away/www.w3.org/2001/XMLSchema-instance"      xsi:schemaLocation="http://personeltest.ru/away/maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  <modelVersion>4.0.0</modelVersion>  <parent>     <groupId>org.springframework.boot</groupId>     <artifactId>spring-boot-starter-parent</artifactId>     <version>2.0.7.RELEASE</version>     <relativePath/> <!-- lookup parent from repository -->  </parent>  <groupId>com.example.eureka.client</groupId>  <artifactId>EurekaClientApplication</artifactId>  <version>0.0.1-SNAPSHOT</version>  <name>EurekaClientApplication</name>  <description>Demo project for Spring Boot</description>   <properties>     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>     <java.version>1.8</java.version>     <spring-cloud.version>Finchley.SR2</spring-cloud.version>  </properties>   <dependencies>     <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-web</artifactId>     </dependency>     <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-actuator</artifactId>     </dependency>     <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-devtools</artifactId>        <scope>runtime</scope>     </dependency>     <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-test</artifactId>        <scope>test</scope>     </dependency>     <dependency>        <groupId>org.springframework.cloud</groupId>        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>     </dependency>  </dependencies>   <dependencyManagement>     <dependencies>        <dependency>           <groupId>org.springframework.cloud</groupId>           <artifactId>spring-cloud-dependencies</artifactId>           <version>${spring-cloud.version}</version>           <type>pom</type>           <scope>import</scope>        </dependency>     </dependencies>  </dependencyManagement>  <build>     <plugins>        <plugin>           <groupId>org.springframework.boot</groupId>           <artifactId>spring-boot-maven-plugin</artifactId>        </plugin>     </plugins>  </build></project>

Откройте файл EurekaClientApplication.java и добавьте для класса аннотацию @EnableDiscoveryClient, как показано ниже.

package com.example.eureka.client.application;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.cloud.client.discovery.EnableDiscoveryClient;@SpringBootApplication@EnableDiscoveryClientpublic class EurekaClientApplication {  public static void main(String[] args) {     SpringApplication.run(EurekaClientApplication.class, args);  }}

Добавление REST-контроллера

Создайте класс HelloWorldController в пакете com.example.eureka.client.application и добавьте GET-метод в этом классе.

package com.example.eureka.client.application;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.RestController;@RestControllerpublic class HelloWorldController {   @GetMapping("/hello-worlds/{name}")   public String getHelloWorld(@PathVariable String name) {       return "Hello World " + name;   }}

В application.properties, расположенный в src/main/resources, добавьте следующие параметры.

spring.application.name=eureka-client-serviceserver.port=8081eureka.client.service-url.defaultZone=http://localhost:8761/eureka/

Параметр eureka.client.service-url.defaultZone определяет адрес Eureka Server, чтобы клиентское приложение могло там зарегистрироваться.

Запуск клиентского приложения

Перед запуском приложения необходимо убедиться, что Eureka Server запущен и работает. Запустите нашего клиента как Java-приложение и перейдите в Eureka Server по адресу http://localhost:8761/. На этот раз вы должны увидеть, что наше клиентское приложение зарегистрировалось на Eureka Server.

Теперь вы знаете как использовать Eureka Server для своих микросервисов. В следующей статье посмотрим на распределенную трассировку (Distributed Tracing) для Spring Boot-микросервисов.

Узнать подробнее о курсе Разработчик на Spring Framework.

Записаться на открытый онлайн-урок по теме Введение в облака, создание кластера в Mongo DB Atlas018.

В преддверии старта курса Разработчик на Spring Framework подготовили традиционный перевод полезного материала.

Также абсолютно бесплатно предлагаем посмотреть запись демо-урока на тему Введение в облака, создание кластера в Mongo DB Atlas.

WebClient это неблокирующий, реактивный клиент для выполнения HTTP-запросов.

Время RestTemplate подошло к концу

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

NOTE: As of 5.0 this class is in maintenance mode, with only minor requests for changes and bugs to be accepted going forward. Please, consider using the org.springframework.web.reactive.client.WebClient which has a more modern API and supports sync, async, and streaming scenarios.

ПРИМЕЧАНИЕ: Начиная с версии 5.0, этот класс законсервирован и в дальнейшем будут приниматься только минорные запросы на изменения и на исправления багов. Пожалуйста, подумайте об использовании org.springframework.web.reactive.client.WebClient, который имеет более современный API и поддерживает синхронную, асинхронную и потоковую передачи.

Конечно, мы понимаем, что RestTemplate не исчезнет мгновенно, однако новой функциональности в нем уже не будет. По этой причине в Интернете можно видеть десятки вопросов о том, что такое WebClient и как его использовать. В этой статье вы найдете советы по использованию новой библиотеки.

Отличия между WebClient и RestTemplate

Если в двух словах, то основное различие между этими технологиями заключается в том, что RestTemplate работает синхронно (блокируя), а WebClient работает асинхронно (не блокируя).

RestTemplate это синхронный клиент для выполнения HTTP-запросов, он предоставляет простой API с шаблонным методом поверх базовых HTTP-библиотек, таких как HttpURLConnection (JDK), HttpComponents (Apache) и другими.

Spring WebClient это асинхронный, реактивный клиент для выполнения HTTP-запросов, часть Spring WebFlux.

Вам, вероятно, интересно, как можно заменить синхронного клиента на асинхронный. У WebClient есть решение этой задачи. Мы рассмотрим несколько примеров использования WebClient.

А сейчас настало время попрощаться с RestTemplate , сказать ему спасибо и продолжить изучение WebClient.

Начало работы с WebClient

Предварительные условия

• Spring Boot 2

• JDK 11

Подготовка проекта

Давайте создадим базовый проект с зависимостями, используя Spring Initializr.

Теперь взглянем на зависимости нашего проекта. Самая важная для нас зависимость spring-boot-starter-webflux.

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webflux</artifactId> </dependency>

Spring WebFlux является частью Spring 5 и обеспечивает поддержку реактивного программирования для веб-приложений.

Пришло время настроить WebClient.

Настройка WebClient

Есть несколько способов настройки WebClient. Первый и самый простой создать его с настройками по умолчанию.

WebClient client = WebClient.create();

Можно также указать базовый URL:

WebClient client = WebClient.create("http://base-url.com");

Третий и самый продвинутый вариант создать WebClient с помощью билдера. Мы будем использовать конфигурацию, которая включает базовый URL и таймауты.

@Configurationpublic class WebClientConfiguration {    private static final String BASE_URL = "https://jsonplaceholder.typicode.com";    public static final int TIMEOUT = 1000;    @Bean    public WebClient webClientWithTimeout() {        final var tcpClient = TcpClient                .create()                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, TIMEOUT)                .doOnConnected(connection -> {                    connection.addHandlerLast(new ReadTimeoutHandler(TIMEOUT, TimeUnit.MILLISECONDS));                    connection.addHandlerLast(new WriteTimeoutHandler(TIMEOUT, TimeUnit.MILLISECONDS));                });        return WebClient.builder()                .baseUrl(BASE_URL)                .clientConnector(new ReactorClientHttpConnector(HttpClient.from(tcpClient)))                .build();    }}

Параметры, поддерживаемые WebClient.Builder можно посмотреть здесь.

Подготовка запроса с помощью Spring WebClient

WebClient поддерживает методы: get(), post(), put(), patch(), delete(), options() и head().

Также можно указать следующие параметры:

• Переменные пути (path variables) и параметры запроса с помощью метода uri().

• Заголовки запроса с помощью метода headers().

• Куки с помощью метода cookies().

После указания параметров можно выполнить запрос с помощью retrieve() или exchange(). Далее мы преобразуем результат в Mono с помощью bodyToMono() или во Flux с помощью bodyToFlux().

Асинхронный запрос

Давайте создадим сервис, который использует бин WebClient и создает асинхронный запрос.

@Service@AllArgsConstructorpublic class UserService {    private final WebClient webClient;    public Mono<User> getUserByIdAsync(final String id) {        return webClient                .get()                .uri(String.join("", "/users/", id))                .retrieve()                .bodyToMono(User.class);    }}

Как вы видите, мы не сразу получаем модель User. Вместо User мы получаем Mono-обертку, с которой выполняем различные действия. Давайте подпишемся неблокирующим способом, используя subscribe().

userService  .getUserByIdAsync("1")  .subscribe(user -> log.info("Get user async: {}", user));

Выполнение продолжается сразу без блокировки на методе subscribe(), даже если для получения значения будет требоваться некоторое время.

Синхронный запрос

Если вам нужен старый добрый синхронный вызов, то это легко сделать с помощью метода block().

public User getUserByIdSync(final String id) {    return webClient            .get()            .uri(String.join("", "/users/", id))            .retrieve()            .bodyToMono(User.class)            .block();}

Здесь поток блокируется, пока запрос не выполнится. В этом случае мы получаем запрашиваемую модель сразу же после завершения выполнения метода.

Повторные попытки

Мы все знаем, что сетевой вызов не всегда может быть успешным. Но мы можем перестраховаться и в некоторых случаях выполнить его повторно. Для этого используется метод retryWhen(), который принимает в качестве аргумента класс response.util.retry.Retry.

public User getUserWithRetry(final String id) {    return webClient            .get()            .uri(String.join("", "/users/", id))            .retrieve()            .bodyToMono(User.class)            .retryWhen(Retry.fixedDelay(3, Duration.ofMillis(100)))            .block();}

С помощью билдера можно настроить параметры и различные стратегии повтора (например, экспоненциальную). Если вам нужно повторить успешную попытку, то используйте repeatWhen() или repeatWhenEmpty() вместо retryWhen().

Обработка ошибок

В случае ошибки, когда повторная попытка не помогает, мы все еще можем контролировать ситуацию с помощью резервного варианта. Доступны следующие методы:

• doOnError() срабатывает, когда Mono завершается с ошибкой.

• onErrorResume() при возникновении ошибки подписывается на резервного издателя, используя функцию для выбора действия в зависимости от ошибки.

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

public User getUserWithFallback(final String id) {    return webClient            .get()            .uri(String.join("", "/broken-url/", id))            .retrieve()            .bodyToMono(User.class)            .doOnError(error -> log.error("An error has occurred {}", error.getMessage()))            .onErrorResume(error -> Mono.just(new User()))            .block();}

В некоторых ситуациях может быть полезно отреагировать на конкретный код ошибки. Для этого можно использовать метод onStatus().

public User getUserWithErrorHandling(final String id) {  return webClient          .get()          .uri(String.join("", "/broken-url/", id))          .retrieve()              .onStatus(HttpStatus::is4xxClientError,                      error -> Mono.error(new RuntimeException("API not found")))              .onStatus(HttpStatus::is5xxServerError,                      error -> Mono.error(new RuntimeException("Server is not responding")))          .bodyToMono(User.class)          .block();}

Клиентские фильтры

Для перехвата и изменения запроса можно настроить фильтры через билдер WebClient .

WebClient.builder()  .baseUrl(BASE_URL)  .filter((request, next) -> next          .exchange(ClientRequest.from(request)                  .header("foo", "bar")                  .build()))  .clientConnector(new ReactorClientHttpConnector(HttpClient.from(tcpClient)))  .build();

Ниже приведен пример фильтра для базовой аутентификации с помощью статического фабричного метода.

WebClient.builder()  .baseUrl(BASE_URL)  .filter(basicAuthentication("user", "password")) // org.springframework.web.reactive.function.client.basicAuthentication()  .clientConnector(new ReactorClientHttpConnector(HttpClient.from(tcpClient)))  .build();

Заключение

В этой статье мы узнали, как настроить WebClient и выполнять синхронные и асинхронные HTTP-запросы. Все фрагменты кода, упомянутые в статье, можно найти в GitHub-репозитории. Документацию по Spring WebClient вы можете найти здесь.

Подводя итог, мы видим, что WebClient прост в использовании и включает в себя все необходимые функции, необходимые в современном программировании.

Удачи с новым Spring WebClient!

Узнать подробнее о курсе Разработчик на Spring Framework.

Посмотреть запись демо-урока на тему Введение в облака, создание кластера в Mongo DB Atlas.

Перевод статьи подготовлен в рамках набора учащихся на курс Разработчик на Spring Framework.

Приглашаем также всех желающих на открытый демо-урок Конфигурация Spring-приложений. На занятии рассмотрим, как можно конфигурировать Spring Boot приложения с помощью свойств:
- properties vs. YAML
- @Value + SpEL
- @ConfigurationProperties
- Externalized конфигурация.
Присоединяйтесь!

Разрабатывая корпоративные веб-приложения, каждый из нас рано или поздно сталкивается с необходимостью обеспечить их безопасность и защитить их ресурсы от несанкционированного доступа. Нужно определить роли для управления доступом, которые будут назначаться пользователям или группам и наделять их полномочиями выполнять те или иные операции в приложении.

Okta это облачный сервис, который позволяет управлять удостоверениями и доступом. Согласно документации Okta, это сервис корпоративного уровня, который создан для управления удостоверениями в облачной среде, но при этом совместим и со многими локальными приложениями. С его помощью ИТ-специалисты могут управлять доступом сотрудников к любому приложению или устройству. Сервис развернут на надежной и защищенной облачной платформе, которая обладает широкими возможностями аудита и тесно интегрируется с локальными приложениями, службами каталогов и системами управления удостоверениями. Подробную информацию о том, как Okta интегрируется с приложениями, можно получить по этой ссылке.

Для авторизации пользователей в Okta используется протокол OAuth2. Подробнее о протоколе OAuth2 и стандарте Open ID Connect (OIDC) можно почитать в блоге Okta.

В этой статье мы рассмотрим демонстрационное приложение Контакты и настройку разрешений на просмотр, создание, редактирование и удаление контактов. Это вторая часть цикла статей о приложении Контакты, посвященная его защите с помощью Okta. О базовом приложении подробно написано в первой статье цикла: Разработка веб-приложения на Spring Boot + Angular.

Полный код, фрагменты которого мы рассматриваем в этой статье, доступен на GitHub.

В итоге наше приложение будет иметь следующую архитектуру:

О том, как контейнеризировать это приложение и развернуть его в кластере Kubernetes, можно узнать по ссылкам:

Kubernetes: развертывание приложения на Angular + Java/ Spring Boot в Google Kubernetes Engine (GKE)

Kubernetes: развертывание приложения на Angular + Spring Boot в облаке Microsoft Azure

Конфигурация на портале разработчика Okta

Для начала нам нужно настроить учетную запись Okta и добавить приложение в Okta. Здесь можно создать учетную запись разработчика бесплатно.

После создания учетной записи мы можем добавить наше приложение в консоль администрирования Okta. Для этого выберем вкладку Applications (Приложения) и щелкнем Add Application (Добавить приложение).

Выберем в качестве платформы Single Page App (Одностраничное приложение) и настроим его так, как показано на скриншоте ниже. Здесь мы отметим только опцию Authorization code (Код авторизации), поскольку нам не нужно, чтобы токен возвращался непосредственно в URL-адресе (о связанных с этим рисках безопасности написано в этой статье в блоге Okta).

В нашем случае требуется два перенаправления входа: во-первых, когда пользователь входит в приложение через пользовательский интерфейс, куда сервер авторизации Okta должен перенаправлять пользователя с указанием кода авторизации, а во-вторых когда пользователь напрямую вызывает открытые API серверной части. Также выберем здесь PKCE.

OAuth предлагает различные потоки авторизации (authorization code flows) выбор конкретного потока зависит от сценария использования приложения. О том, какой поток OAuth выбрать, можно прочитать в этой статье на Medium или в документации Okta. Пользовательский интерфейс нашего демонстрационного приложения представляет собой одностраничное приложение на Angular, поэтому выберем неявный поток (implicit flow) с дополнительной проверкой для обмена кодом (Proof Key Code Exchange, PKCE).

Авторизация запросов через сервер авторизации

Для авторизации всех входящих запросов к приложению нам понадобится сервер авторизации. В нашем примере используется сервер авторизации, который Okta предоставляет по умолчанию. Если вы захотите написать собственный сервер для авторизации запросов, это тоже возможно; тогда нужно будет указать в Okta ссылку на его конечную точку.

Чтобы увидеть сервер авторизации на портале Okta, нужно выбрать пункт меню, показанный ниже на скриншоте.

Добавление заявлений о группах (groups claims) в приложение Контакты

Для демонстрации создадим группу Admin. Администратор будет обладать правами на создание/редактирование/удаление.

О том, как создать группу и идентифицировать ее с помощью токена доступа, можно узнать в блоге Okta. В официальном блоге Okta описана автономная конфигурация приложения на Spring Boot в качестве веб-проекта Okta. В нашем случае менять тип проекта не нужно. Мы просто создадим группы и включим заявления о группах в токен доступа, выдаваемый сервером авторизации.

На скриншотах ниже показано, как мы создали группу, связали ее с нашим приложением и включили заявление о группах в токен доступа.

Настроив проект через консоль администрирования Okta описанным выше способом, можно приступать к его интеграции с приложением Контакты для защиты доступа к приложению.

Настройка Okta в клиентской части приложения

Для защиты клиентской части приложения Контакты воспользуемся SDK-библиотекой Okta для Angular. Мы будем авторизовывать пользователя, перенаправляя его на конечную точку авторизации, настроенную для нашей организации в Okta. Библиотеку можно установить с помощью npm:

npm install @okta/okta-angular --save

Чтобы реализовать этот промежуточный слой, после установки нужно будет указать значения из клиента OIDC, полученные на предыдущем этапе. Также понадобится URL-адрес организации в Okta его можно узнать на домашней странице консоли разработчика Okta.

В файле app.module.ts создадим объект конфигурации и в нем установим true для параметра PKCE.

const oktaConfig = {issuer: 'https://{yourOktaDomain}/oauth2/default',redirectUri: window.location.origin + '/implicit/callback',clientId: 'your clientId',pkce: true};

Этот объект нужно добавить в раздел providers. Также импортируем OktaAuthModule:

import { OktaAuthModule, OktaCallbackComponent } from '@okta/okta-angular';import {OKTA_CONFIG} from '@okta/okta-angular';....imports:[...OktaAuthModule...]providers: [...{ provide: OKTA_CONFIG, useValue: oktaConfig }...]

В модуле обработки маршрутов приложения зададим защиту маршрута, воспользовавшись Route Guard из Angular. Вот фрагмент кода из app-routing-module.ts:

import { OktaCallbackComponent } from '@okta/okta-angular';...const routes: Routes = [{ path: 'contact-list',canActivate: [ OktaAuthGuard ],component: ContactListComponent },{ path: 'contact',canActivate: [ OktaAuthGuard, AdminGuard ],component: EditContactComponent },{path: 'implicit/callback',component: OktaCallbackComponent},{ path: '',redirectTo: 'contact-list',pathMatch: 'full'},];

Здесь мы защищаем просмотр контактов с помощью AuthGuard, а создание, обновление, удаление контактов с помощью AdminGuard и OktaAuthGuard.

Метод canActivate в OktaAuthGuard используется для проверки того, прошел ли пользователь процедуру аутентификации. Если нет, он перенаправляется на страницу входа Okta; если да, мы позволяем ему просматривать страницу, на которую ведет маршрут.

async canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot) {this.authenticated = await this.okta.isAuthenticated();if (this.authenticated) { return true; }// Redirect to login flow.this.oktaAuth.loginRedirect();return false;}

Аналогичным образом метод canActivate в AdminGuard проверяет, принадлежат ли вошедшие в систему пользователи к группе Admin; если нет, запрос на доступ к маршруту отклоняется и выводится предупреждение.

async canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot) {this.user = await this.okta.getUser();const result = this.user.groups.find((group) => group === 'Admin');if (result) {return true;} else {alert('User is not authorized to perform this operation');return false; }}

Ниже показана последовательность операций, которые выполняются, когда пользователь пытается обратиться к маршруту /contact-list для просмотра списка контактов.

Ниже представлена последовательность операций, демонстрирующая принцип работы PKCE. В случае одностраничного приложения, если токен возвращается непосредственно как часть URL-адреса перенаправления, любое расширение браузера может получить доступ к токену еще до того, как его увидит приложение. Это представляет потенциальную угрозу безопасности. Для снижения этого риска в PKCE вычисляется хэш SHA256 от случайной строки верификатора кода (code verifier), и этот хэш включается в запрос кода доступа как контрольное значение (code challenge). Когда поступает запрос на обмен токена доступа на код доступа, сервер авторизации может снова вычислить хэш SHA256 от верификатора кода и сопоставить результат с сохраненным контрольным значением.

Библиотека для Angular производит все эти операции за кадром: вычисляет хэш от верификатора кода с помощью алгоритма SHA256 и обменивает токен на код доступа, сопоставляя верификатор кода с контрольным значением.

Настройка Okta в серверной части приложения

Для того чтобы приложение Spring Boot поддерживало Okta, нужно установить следующие зависимости:

<dependency><groupId>com.okta.spring</groupId><artifactId>okta-spring-boot-starter</artifactId><version>1.2.1</version><exclusions><exclusion><groupId>org.springframework.security.oauth</groupId><artifactId>spring-security-oauth2</artifactId></exclusion></exclusions></dependency><dependency><groupId>org.springframework.security.oauth</groupId><artifactId>spring-security-oauth2</artifactId><version>2.4.0.RELEASE</version></dependency>

Spring Security OAuth2 и Okta Spring Boot Starter следует добавить в classpath, тогда Spring настроит поддержку Okta во время запуска.

Укажем следующие значения конфигурации для настройки и подключения Spring к приложению Okta:

okta.oauth2.client-id=<clientId>okta.oauth2.issuer=https://{yourOktaDomain}/oauth2/defaultokta.oauth2.groups-claim=groups

В классе SpringSecurity нужно указать, что приложение Spring Boot является сервером ресурсов:

@EnableWebSecurity@EnableGlobalMethodSecurity(prePostEnabled = true)@Profile("dev")@Slf4jpublic class SecurityDevConfiguration extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception{http.cors().and().csrf().disable();http.cors().configurationSource(request -> new CorsConfiguration(corsConfiguratione()));// http.authorizeRequests().antMatchers(HttpMethod.OPTIONS, "/**").permitAll()// .and().http.antMatcher("/**").authorizeRequests().antMatchers(HttpMethod.OPTIONS, "/**").permitAll().antMatchers("/").permitAll().anyRequest().authenticated();http.oauth2ResourceServer();}

При такой конфигурации конечные точки нашего приложения защищены. Если попробовать обратиться к конечной точке /contacts по адресу http://localhost:8080/api/contacts, будет возвращена ошибка 401, поскольку запрос не пройдет через фильтр аутентификации.

Для того чтобы предоставить права на создание, обновление и удаление контактов только администратору, нужно включить защиту методов в классе SpringSecurityConfig при помощи следующей аннотации:

@EnableGlobalMethodSecurity(prePostEnabled = true)

На конечных точках, которые мы хотим защитить, можно выполнять проверку ролей с помощью PreAuthorize следующим образом:

@PreAuthorize("hasAuthority('Admin')")public Contact saveContact(@RequestBody Contact contact,@AuthenticationPrincipal Principal userInfo) {

Для получения сведений о вошедшем в систему пользователе можно использовать объект Principal (@AuthenticationPrincipal).

Защита доступа к API из клиентской части приложения с помощью токена доступа

Теперь Okta защищает и клиентскую, и серверную часть нашего приложения. Когда клиентская часть направляет запрос к API, она должна передавать токен доступа в заголовке авторизации. В Angular для этого можно использовать перехватчик HttpInterceptor. В классе перехватчика авторизации можно задать токен доступа для любого HTTP-запроса следующим образом:

private async handleAccess(request: HttpRequest<any>, next: HttpHandler): Promise<HttpEvent<any>> {const accessToken = await this.oktaAuth.getAccessToken();if ( accessToken) {request = request.clone({setHeaders: {Authorization: 'Bearer ' + accessToken}});}return next.handle(request).toPromise();}}

Прямой доступ к API приложения через внешний сервер API

Если все настроено правильно, пользовательский интерфейс нашего приложения сможет получать доступ к API серверной части. В корпоративных приложениях часто присутствует несколько микросервисов, к которым обращается пользовательский интерфейс приложения, а также ряд микросервисов, доступ к которым открыт непосредственно для других приложений или пользователей. Так как наше приложение настроено как одностраничное, в настоящее время оно поддерживает доступ только из JavaScript-кода. Чтобы открыть доступ к микросервисам как к API для других потребителей API, нужно создать в Okta серверное приложение с типом веб-приложение, а затем создать микросервисы как одностраничные приложения и разрешить единый вход для доступа к ним (технически мы имеем дело с двумя разными приложениями в Okta).

Я разработал небольшое решение, позволяющее обойти эту проблему. Мы по-прежнему будем использовать неявный поток с PKCE, но на этот раз не станем перенаправлять пользователя на страницу входа (при направлении запроса к API войти в Okta в ручном режиме невозможно, поскольку в этом случае пользователем будет пользователь API). Вместо этого будем следовать следующему алгоритму.

Я создал сервер API, тоесть микросервис-обертку, предоставляющий список API, к которым мы хотим открыть доступ как к серверным API.

Эта обертка выдает токены доступа с указанием конечной точки входа, а затем вызывает нужный API, используя токен доступа.

Она выступает в роли прокси-сервера для основного серверного API нашего приложения и открывает доступ к необходимым сервисам. В ней используется библиотека Spring Cloud OpenFeign, предназначенная для написания декларативных REST-клиентов. Такая обертка представляет собой очень простой способ создания клиентов для веб-сервисов. Она позволяет сократить количество кода при написании потребителей веб-сервисов на базе REST, а также поддерживает перехватчики, позволяющие реализовать любые промежуточные операции, которые должны выполняться до направления запроса к API. В нашем случае мы будем использовать перехватчик для задания токена доступа и распространения прав доступа пользователей. Дополнительные сведения о Feign доступны по этой ссылке.

При правильной настройке все конечные точки нашего приложения, а также компоненты клиентской части приложения будут надежно защищены. Доступ к нему будет открыт только для авторизованных пользователей. О том, как контейнеризировать это приложение и развернуть его в кластере Kubernetes, можно прочитать по ссылкам:

Kubernetes: развертывание приложения на Angular + Java/ Spring Boot в Google Kubernetes Engine (GKE)

Kubernetes: развертывание приложения на Angular + Spring Boot в облаке Microsoft Azure

Узнать подробнее о курсе Разработчик на Spring Framework

Смотреть вебинар Конфигурация Spring-приложений

В этой статье мы рассмотрим, как использовать Spring Boot 2.x и Redis для выполнения асинхронных задач, а полный код продемонстрирует шаги, описанные в этом посте.

Spring/Spring Boot

Spring самый популярный фреймворк для разработки Java приложений.Таким образом, Spring имеет одно из крупнейших сообществ с открытым исходным кодом.Кроме того, Spring предоставляет обширную и актуальную документацию, которая охватывает внутреннюю работу фреймворка и примеры проектов в своем блоге, а наStackOverflowболее 100 тысяч вопросови ответов.

Вначале Spring поддерживал только конфигурацию на основе XML, и из-за этого был подвержен множеству критических замечаний.Позже Spring представила конфигурацию на основе аннотаций, которая изменила все.Spring 3.0 была первой версией, которая поддерживала конфигурацию на основе аннотаций.В 2014 годубыла выпущенаSpring Boot1.0, полностью изменившая наш взгляд на экосистему фреймворка Spring.Более подробное описание истории Spring можно найтиздесь.

Redis

Redis одна из самых популярных NoSQL баз данных в памяти.Redis поддерживает разные типы структур данных. Redis поддерживает различные типы структур данных, например Set, Hash table, List, простую пару ключ-значение это лишь некоторые из них.Задержка вызова Redis составляет менее миллисекунд, поддержка набора реплик и т. д. Задержка операции Redis составляет менее миллисекунд, что делает ее еще более привлекательной для сообщества разработчиков.

Почему асинхронное выполнение задачи

Типичный вызов API состоит из пяти этапов:

1. Выполние одного или нескольких запросов к базе данных (RDBMS / NoSQL)

2. Одна или несколько операций системы кэширования (In-Memory, Distributed и т. д.)

3. Некоторые вычисления (это может быть обработка данных при выполнении некоторых математических операций)

4. Вызов других служб (внутренних / внешних)

5. Планирование выполнения одной или нескольких задач на более позднее время или немедленно, но вфоновом режиме

Задачу можно запланировать на более позднее время по многим причинам.Например, счет-фактура должен быть создан через 7 дней после создания или отгрузки заказа.Точно так же уведомления по электронной почте не нужно отправлять немедленно, поэтому мы можем отложить их.

Имея в виду эти реальные примеры, иногда нам нужно выполнять задачи асинхронно, чтобы сократить время ответа API.Например, если мы удалим более 1K записей за один раз, и если мы удалим все эти записи в одном вызове API, то время ответа API наверняка увеличится.Чтобы сократить время ответа API, мы можем запустить задачу в фоновом режиме, которая удалит эти записи.

Отложенная очередь

Каждый раз, когда мы планируем запуск задачи в определенное время или через определенный интервал, мы используем задания cron, которые запланированы на определенное время или интервал.Мы можем запускать задачи по расписанию, используя различные инструменты, такие как crontab в стиле UNIX,Chronos, если мы используем фреймворки Spring, тогда речь идетоб аннотацииScheduled.

Большинство заданий cron просматривают записи о том, когда должно быть предпринято определенное действие, например, поиск всех поставок по истечении семи дней, по которым не были созданы счета.Большинство таких механизмов планирования страдаютпроблемами масштабирования, когда мы сканируем базы данных, чтобы найти соответствующие строки/записи.Во многих случаях это приводит кполному сканированию таблицы,которое работает очень медленно.Представьте себе случай, когда одна и та же база данных используется приложением реального времени и этой системой пакетной обработки.Поскольку она не является масштабируемый, нам понадобится какая-то масштабируемая система, которая может выполнять задачи в заданное время или интервал без каких-либо проблем с производительностью.Есть много способов масштабирования таким образом, например, запускать задачи в пакетном режиме или управлять задачами для определенного подмножества пользователей/регионов.Другой способ запустить конкретную задачу в определенное время без зависимости от других задач, например безсерверной функции.Отложенная очередьможет использоваться в тех случаях, как только таймер достигнет запланированного времени работа будет вызвана. Имеется множествосистем/программного обеспечения для организации очередей, но очень немногие из них, например SQS, предоставляют функцию, которая обеспечивает задержку на 15 минут, а не произвольную задержку, такую как 7 часов или 7 дней и т. д.

Rqueue

Rqueue это брокер сообщений, созданный для платформыSpring,который хранит данные в Redis и предоставляет механизм для выполнения задачи с любой указанной задержкой.Rqueue поддерживается Redis, поскольку Redis имеет некоторые преимущества перед широко используемыми системами очередей, такими как Kafka, SQS.В большинстве серверных приложений веб-приложений Redis используется для хранения данных кеша или для других целей.В настоящее время8,4% веб-приложений используют базу данных Redis.

Как правило, для очереди мы используем либо Kafka/SQS, либо некоторые другие системы, эти системы приносят дополнительные накладные расходы в разных измерениях, например, финансовые затраты, которые можно уменьшить до нуля с помощью Rqueue и Redis.

Помимо затрат, если мы используем Kafka, нам необходимо выполнить настройку инфраструктуры, обслуживание, то есть больше операций, так как большинство приложений уже используют Redis, поэтому у нас не будет накладных расходов на операции, на самом деле можно использовать тот же сервер/кластер Redis с Rqueue.Rqueue поддерживает произвольную задержку

Доставка сообщений

Rqueue гарантирует доставку сообщения хотя бы раз, так как длинные данные не теряются в базе данных.Подробнее об этом читайте настранице Введение в Rqueue.

Инструменты, которые нам понадобятся:

1. Любая IDE

2. Gradle

3. Java

4. Redis

Мы собираемся использоватьSpring Boot для простоты.Мы создадим проект Gradle с помощью инициализатора Spring Boot по адресуhttps://start.spring.io/.

Из зависимостей нам понадобятся:

1. Spring Data Redis

2. Spring Web

3. Lombok и некоторые другие

Структура каталогов/папок показана ниже:

Мы собираемся использоватьбиблиотекуRqueueдля выполнения любых задач с произвольной задержкой.Rqueue это основанный на Spring исполнитель асинхронных задач, который может выполнять задачи с любой задержкой, он построен на библиотеке обмена сообщениями Spring и поддерживается Redis.

Мы добавим зависимость spring boot starter дляRqueue com.github.sonus21:rqueue-spring-boot-starter:2.0.0-RELEASE с помощью кода:

dependencies {    implementation 'org.springframework.boot:spring-boot-starter-data-redis'  implementation 'org.springframework.boot:spring-boot-starter-web'  implementation 'com.github.sonus21:rqueue-spring-boot-starter:2.0.0-RELEASE'  compileOnly 'org.projectlombok:lombok'     annotationProcessor 'org.projectlombok:lombok'  providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'  testImplementation('org.springframework.boot:spring-boot-starter-test') {    exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'    }}

Нам нужно включить функции Redis Spring Boot.В целях тестирования мы также включим WEB MVC.

Обновите файл application как:

@SpringBootApplication@EnableRedisRepositories@EnableWebMvcpublic class AsynchronousTaskExecutorApplication {   public static void main(String[] args) {     SpringApplication.run(AsynchronousTaskExecutorApplication.class, args);  }}

Добавлять задачи с помощью Rqueue очень просто.Нам нужно аннотировать метод с помощьюRqueueListener.ВRqueuListenerаннотации есть несколько полей, которые можно настроить в зависимости от варианта использования.УстановитеdeadLetterQueueдля отправки задач в другую очередь.В противном случае задача будет отброшена в случае неудачи.Мы также можем установить, сколько раз задача должна быть повторена, используяполе.numRetries

Создайте файл Java с именемMessageListenerи добавьте несколько методов для выполнения задач:

@Component@Slf4jpublic class MessageListener {  @RqueueListener(value = "${email.queue.name}") (1)  public void sendEmail(Email email) {    log.info("Email {}", email);  }  @RqueueListener(value = "${invoice.queue.name}") (2)  public void generateInvoice(Invoice invoice) {    log.info("Invoice {}", invoice);  }}

Нам понадобится классы Email и Invoiceдля хранения данных электронной почты и счетов-фактур соответственно.Для простоты у классов будет только небольшое количество полей.

Invoice.java:

import lombok.Data;@Data@AllArgsConstructor@NoArgsConstructorpublic class Invoice {  private String id;  private String type;}

Email.java:

import lombok.Data;@Data@AllArgsConstructor@NoArgsConstructorpublic class Email {  private String email;  private String subject;  private String content;}

Отправка задач в очередь

Задачу можно отправить в очередь с помощьюRqueueMessageSenderbean-компонента. У которого есть несколько методов для постановки задачи в очередь в зависимости от сценария использования, используйте один из доступных методов.Для простых задач используйте enqueue, для отложенных задач используйте enqueueIn.

Нам нужно автоматически подключитьRqueueMessageSenderили использовать внедрение на основе конструктора для внедрения этих bean-компонентов.

Воткак создать контроллер для тестирования.

Мы планируем создать счет-фактуру, который нужно будет выполнить через 30 секунд.Для этого мы отправим задачу с задержкой 30000 (миллисекунд) в очереди счетов.Кроме того, мы постараемся отправить электронное письмо, которое может выполняться в фоновом режиме.Для этого мы добавим два метода GET,sendEmailи generateInvoice, мы также можем использовать POST.

@RestController@RequiredArgsConstructor(onConstructor = @__(@Autowired))@Slf4jpublic class Controller {  private @NonNull RqueueMessageSender rqueueMessageSender;  @Value("${email.queue.name}")  private String emailQueueName;  @Value("${invoice.queue.name}")  private String invoiceQueueName;  @Value("${invoice.queue.delay}")  private Long invoiceDelay;  @GetMapping("email")  public String sendEmail(      @RequestParam String email, @RequestParam String subject, @RequestParam String content) {    log.info("Sending email");    rqueueMessageSender.enqueu(emailQueueName, new Email(email, subject, content));    return "Please check your inbox!";  }  @GetMapping("invoice")  public String generateInvoice(@RequestParam String id, @RequestParam String type) {    log.info("Generate invoice");    rqueueMessageSender.enqueueIn(invoiceQueueName, new Invoice(id, type), invoiceDelay);    return "Invoice would be generated in " + invoiceDelay + " milliseconds";  }}

Добавим в файл application.properties следующие строки:

email.queue.name=email-queueinvoice.queue.name=invoice-queue# 30 seconds delay for invoiceinvoice.queue.delay=300000

Теперь мы можем запустить приложение.После успешного запуска приложения вы можете просмотреть результат по этойссылке.

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

Ниже приведено расписание выставления счетов через 30 секунд:

http://localhost:8080/invoice?id=INV-1234&type=PROFORMA

Заключение

Теперь мы можем планировать задачи с помощью Rqueue без большого объёма вспомогательного кода!Были приведены основные соображения по настройке и использованию библиотеки Rqueue.Следует иметь в виду одну важную вещь: независимо от того, является ли задача отложенной задачей или нет, по умолчанию предполагается, что задачи необходимо выполнить как можно скорее.

Полный код этого поста можно найти в репозиториинаGitHub.

Дополнительноечтение

Spring Boot: Creating Asynchronous Methods Using @Async Annotation

Spring and Threads: Async

Distributed Tasks Execution and Scheduling in Java, Powered by Redis

В этом руководстве мы рассмотрим, как реализовать мультиарендность в Spring Boot приложении с использованием MongoDB и Redis.

Используются:

• Spring Boot 2.4

• Maven 3.6. +

• JAVA 8+

• Монго 4.4

• Redis 5

Что такое мультиарендность?

Мультиарендность (англ. multitenancy множественная аренда) это программная архитектура, в которой один экземпляр программного приложения обслуживает нескольких клиентов.Все должно быть общим, за исключением данных разных клиентов, которые должны быть должным образом разделены.Несмотря на то, что они совместно используют ресурсы, арендаторы не знают друг друга, и их данные хранятся совершенно отдельно.Каждый покупатель называется арендатором.

Предложение программное обеспечение как услуга (SaaS) является примером мультиарендной архитектуры.Более подробно.

Модели с несколькими арендаторами

Можно выделить три основных архитектурных шаблона для мультиарендной архитектуры (Multitenancy), которые различаются степенью физического разделения данных клиента.

1. База данных для каждого арендатора: каждый арендатор имеет свою собственную базу данных и изолирован от других арендаторов.

2. Общая база данных, общая схема:все арендаторы совместно используют базу данных и таблицы.В каждой таблице есть столбец с идентификатором клиента, который показывает владельца строки.

3. Общая база данных, отдельная схема: все арендаторы совместно используют базу данных, но имеют свои собственные схемы и таблицы базы данных.

Начнем

В этом руководстве мы реализуем мультиарендность на основе базы данных для каждого клиента.

Мы начнем с создания простого проекта Spring Boot наstart.spring.ioсо следующими зависимостями:

<dependencies>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-data-mongodb</artifactId>    </dependency>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-web</artifactId>    </dependency>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-data-redis</artifactId>    </dependency>    <dependency>        <groupId>redis.clients</groupId>        <artifactId>jedis</artifactId>    </dependency>    <dependency>        <groupId>org.projectlombok</groupId>        <artifactId>lombok</artifactId>        <optional>true</optional>    </dependency></dependencies>

Определение текущего идентификатора клиента

Идентификатор клиента необходимо определить для каждого клиентского запроса.Для этого мы включим поле идентификатора клиента в заголовок HTTP-запроса.

Давайте добавим перехватчик, который получает идентификатор клиента из http заголовкаX-Tenant.

@Slf4j@Componentpublic class TenantInterceptor implements WebRequestInterceptor {    private static final String TENANT_HEADER = "X-Tenant";    @Override    public void preHandle(WebRequest request) {        String tenantId = request.getHeader(TENANT_HEADER);        if (tenantId != null && !tenantId.isEmpty()) {            TenantContext.setTenantId(tenantId);            log.info("Tenant header get: {}", tenantId);        } else {            log.error("Tenant header not found.");            throw new TenantAliasNotFoundException("Tenant header not found.");        }    }    @Override    public void postHandle(WebRequest webRequest, ModelMap modelMap) {        TenantContext.clear();    }    @Override    public void afterCompletion(WebRequest webRequest, Exception e) {    }}

TenantContextэто хранилище, содержащее переменную ThreadLocal.ThreadLocal можно рассматривать как область доступа (scope of access), такую как область запроса (request scope) или область сеанса (session scope).

Сохраняя tenantId в ThreadLocal, мы можем быть уверены, что каждый поток имеет свою собственную копию этой переменной и что текущий поток не имеет доступа к другому tenantId:

@Slf4jpublic class TenantContext {    private static final ThreadLocal<String> CONTEXT = new ThreadLocal<>();    public static void setTenantId(String tenantId) {        log.debug("Setting tenantId to " + tenantId);        CONTEXT.set(tenantId);    }    public static String getTenantId() {        return CONTEXT.get();    }    public static void clear() {        CONTEXT.remove();    }}

Настройка источников данных клиента (Tenant Datasources)

В нашей архитектуре у нас есть экземпляр Redis, представляющий базу метаданных (master database), в которой централизована вся информация о базе данных клиента.Таким образом, из каждого предоставленного идентификатора клиента информация о подключении к базе данных извлекается из базы метаданных .

RedisDatasourceService.java это класс, отвечающий за управление всеми взаимодействиями с базой метаданных .

@Servicepublic class RedisDatasourceService {    private final RedisTemplate redisTemplate;    private final ApplicationProperties applicationProperties;    private final DataSourceProperties dataSourceProperties;public RedisDatasourceService(RedisTemplate redisTemplate, ApplicationProperties applicationProperties, DataSourceProperties dataSourceProperties) {        this.redisTemplate = redisTemplate;        this.applicationProperties = applicationProperties;        this.dataSourceProperties = dataSourceProperties;    }        /**     * Save tenant datasource infos     *     * @param tenantDatasource data of datasource     * @return status if true save successfully , false error     */        public boolean save(TenantDatasource tenantDatasource) {        try {            Map ruleHash = new ObjectMapper().convertValue(tenantDatasource, Map.class);            redisTemplate.opsForHash().put(applicationProperties.getServiceKey(), String.format("%s_%s", applicationProperties.getTenantKey(), tenantDatasource.getAlias()), ruleHash);            return true;        } catch (Exception e) {            return false;        }    }        /**     * Get all of keys     *     * @return list of datasource     */         public List findAll() {        return redisTemplate.opsForHash().values(applicationProperties.getServiceKey());    }        /**     * Get datasource     *     * @return map key and datasource infos     */         public Map<String, TenantDatasource> loadServiceDatasources() {        List<Map<String, Object>> datasourceConfigList = findAll();        // Save datasource credentials first time        // In production mode, this part can be skip        if (datasourceConfigList.isEmpty()) {            List<DataSourceProperties.Tenant> tenants = dataSourceProperties.getDatasources();            tenants.forEach(d -> {                TenantDatasource tenant = TenantDatasource.builder()                        .alias(d.getAlias())                        .database(d.getDatabase())                        .host(d.getHost())                        .port(d.getPort())                        .username(d.getUsername())                        .password(d.getPassword())                        .build();                save(tenant);            });        }        return getDataSourceHashMap();    }        /**     * Get all tenant alias     *     * @return list of alias     */         public List<String> getTenantsAlias() {        // get list all datasource for this microservice        List<Map<String, Object>> datasourceConfigList = findAll();        return datasourceConfigList.stream().map(data -> (String) data.get("alias")).collect(Collectors.toList());    }        /**     * Fill the data sources list.     *     * @return Map<String, TenantDatasource>     */         private Map<String, TenantDatasource> getDataSourceHashMap() {        Map<String, TenantDatasource> datasourceMap = new HashMap<>();        // get list all datasource for this microservice        List<Map<String, Object>> datasourceConfigList = findAll();        datasourceConfigList.forEach(data -> datasourceMap.put(String.format("%s_%s", applicationProperties.getTenantKey(), (String) data.get("alias")), new TenantDatasource((String) data.get("alias"), (String) data.get("host"), (int) data.get("port"), (String) data.get("database"), (String) data.get("username"), (String) data.get("password"))));        return datasourceMap;    }}

В этом руководстве мы заполнили информацию о клиенте из yml-файла (tenants.yml).В производственном режиме можно создать конечные точки для сохранения информации о клиенте в базе метаданных.

Чтобы иметь возможность динамически переключаться на подключение к базе данных mongo, мы создаемкласс MultiTenantMongoDBFactory, расширяющий класс SimpleMongoClientDatabaseFactory из org.springframework.data.mongodb.core.Он вернетэкземплярMongoDatabase, связанный с текущим арендатором.

@Configurationpublic class MultiTenantMongoDBFactory extends SimpleMongoClientDatabaseFactory {@Autowired    MongoDataSources mongoDataSources;public MultiTenantMongoDBFactory(@Qualifier("getMongoClient") MongoClient mongoClient, String databaseName) {        super(mongoClient, databaseName);    }    @Override    protected MongoDatabase doGetMongoDatabase(String dbName) {        return mongoDataSources.mongoDatabaseCurrentTenantResolver();    }}

Нам нужно инициализироватьконструктор MongoDBFactoryMultiTenantс параметрами по умолчанию (MongoClientиdatabaseName).

Это реализует прозрачный механизм для получения текущего клиента.

@Component@Slf4jpublic class MongoDataSources {    /**     * Key: String tenant alias     * Value: TenantDatasource     */    private Map<String, TenantDatasource> tenantClients;    private final ApplicationProperties applicationProperties;    private final RedisDatasourceService redisDatasourceService;    public MongoDataSources(ApplicationProperties applicationProperties, RedisDatasourceService redisDatasourceService) {        this.applicationProperties = applicationProperties;        this.redisDatasourceService = redisDatasourceService;    }    /**     * Initialize all mongo datasource     */    @PostConstruct    @Lazy    public void initTenant() {        tenantClients = new HashMap<>();        tenantClients = redisDatasourceService.loadServiceDatasources();    }    /**     * Default Database name for spring initialization. It is used to be injected into the constructor of MultiTenantMongoDBFactory.     *     * @return String of default database.     */    @Bean    public String databaseName() {        return applicationProperties.getDatasourceDefault().getDatabase();    }    /**     * Default Mongo Connection for spring initialization.     * It is used to be injected into the constructor of MultiTenantMongoDBFactory.     */    @Bean    public MongoClient getMongoClient() {        MongoCredential credential = MongoCredential.createCredential(applicationProperties.getDatasourceDefault().getUsername(), applicationProperties.getDatasourceDefault().getDatabase(), applicationProperties.getDatasourceDefault().getPassword().toCharArray());        return MongoClients.create(MongoClientSettings.builder()                .applyToClusterSettings(builder ->                        builder.hosts(Collections.singletonList(new ServerAddress(applicationProperties.getDatasourceDefault().getHost(), Integer.parseInt(applicationProperties.getDatasourceDefault().getPort())))))                .credential(credential)                .build());    }    /**     * This will get called for each DB operations     *     * @return MongoDatabase     */    public MongoDatabase mongoDatabaseCurrentTenantResolver() {        try {            final String tenantId = TenantContext.getTenantId();            // Compose tenant alias. (tenantAlias = key + tenantId)            String tenantAlias = String.format("%s_%s", applicationProperties.getTenantKey(), tenantId);            return tenantClients.get(tenantAlias).getClient().                    getDatabase(tenantClients.get(tenantAlias).getDatabase());        } catch (NullPointerException exception) {            throw new TenantAliasNotFoundException("Tenant Datasource alias not found.");        }    }73}

Тест

Давайте создадим CRUD пример с документом Employee.

@Builder@Data@AllArgsConstructor@NoArgsConstructor@Accessors(chain = true)@Document(collection = "employee")public class Employee  {    @Id    private String id;    private String firstName;    private String lastName;    private String email;}

Также нам нужно создать классы EmployeeRepository, EmployeeServiceиEmployeeController.Для тестирования при запуске приложения мы загружаем фиктивные данные в каждую базу данных клиента.

@Overridepublic void run(String... args) throws Exception {    List<String> aliasList = redisDatasourceService.getTenantsAlias();    if (!aliasList.isEmpty()) {        //perform actions for each tenant        aliasList.forEach(alias -> {            TenantContext.setTenantId(alias);            employeeRepository.deleteAll();            Employee employee = Employee.builder()                    .firstName(alias)                    .lastName(alias)                    .email(String.format("%s%s", alias, "@localhost.com" ))                    .build();            employeeRepository.save(employee);            TenantContext.clear();        });    }}

Теперь мы можем запустить наше приложение и протестировать его.

Итак, мы все сделали. Надеюсь, это руководство поможет вам понять, что такое мультиарендность и как она может быть реализована в Spring Boot проекте с использованием MongoDB и Redis.

Полный исходный код примера можно найти наGitHub.

Одна из основных функций Spring - функция публикации событий.Мы можем использовать события для разделения частей нашего приложения и реализации шаблона публикации-подписки.Одна часть нашего приложения может публиковать событие, на которое реагируют несколько слушателей (даже асинхронно).В рамкахSpring Framework 5.3.3(Spring Boot 2.4.2) теперь мы можем записывать и проверять все опубликованные события (ApplicationEvent) при тестировании приложений Spring Boot с использованием@RecrodApplicationEvents.

Настройка для записи ApplicationEvent с помощью Spring Boot

Чтобы использовать эту функцию, нам нужен толькоSpring Boot Starter Test,который является частью каждого проекта Spring Boot, который вы загружаете наstart.spring.io.

<dependency>  <groupId>org.springframework.boot</groupId>  <artifactId>spring-boot-starter-test</artifactId>  <scope>test</scope></dependency>

Обязательно используйте версию Spring Boot >= 2.4.2, так как нам нужна версия Spring Framework >= 5.3.3.

Для наших тестов есть одно дополнительное требование: нам нужно работать со SpringTestContextпоскольку публикация событий является основной функциональностью платформыApplicationContext.

Следовательно, она не работает для модульного теста, где неиспользуется поддержка инфраструктуры Spring TestContext.Есть несколькоаннотаций тестовых срезов Spring Boot,которые удобно загружают контекст для нашего теста.

Введение в публикацию событий Spring

В качестве примера мы протестируем класс Java, который выдает UserCreationEvent,когда мы успешно создаем нового пользователя.Событие включает метаданные о пользователе, актуальные для последующих задач:

public class UserCreationEvent extends ApplicationEvent {   private final String username;  private final Long id;   public UserCreationEvent(Object source, String username, Long id) {    super(source);    this.username = username;    this.id = id;  }   // getters}

Начиная со Spring Framework 4.2, нам не нужно расширять абстрактныйкласс ApplicationEventи мы можем использовать любой POJO в качестве нашего класса событий.В следующий статье привеленоотличное введение в события приложенийс помощью Spring Boot.

НашUserServiceсоздает и хранит наших новых пользователей.Мы можем создать как одного пользователя, так и группу пользователей:

@Servicepublic class UserService {   private final ApplicationEventPublisher eventPublisher;   public UserService(ApplicationEventPublisher eventPublisher) {    this.eventPublisher = eventPublisher;  }   public Long createUser(String username) {    // logic to create a user and store it in a database    Long primaryKey = ThreadLocalRandom.current().nextLong(1, 1000);     this.eventPublisher.publishEvent(new UserCreationEvent(this, username, primaryKey));     return primaryKey;  }   public List<Long> createUser(List<String> usernames) {    List<Long> resultIds = new ArrayList<>();     for (String username : usernames) {      resultIds.add(createUser(username));    }     return resultIds;  }}

Как только пользователь станет частью нашей системы, мы уведомим другие компоненты нашего приложения, опубликовав файлUserCreationEvent.

Например, наше приложение выполняет две дополнительные операции всякий раз, когда мы запускаем такоеUserCreationEvent:

@Componentpublic class ReportingListener {   @EventListener(UserCreationEvent.class)  public void reportUserCreation(UserCreationEvent event) {    // e.g. increment a counter to report the total amount of new users    System.out.println("Increment counter as new user was created: " + event);  }   @EventListener(UserCreationEvent.class)  public void syncUserToExternalSystem(UserCreationEvent event) {    // e.g. send a message to a messaging queue to inform other systems    System.out.println("informing other systems about new user: " + event);  }}

Запись и проверка событий приложения с помощью Spring Boot

Давайте напишем наш первый тест, который проверяет,UserServiceгенерирует событие всякий раз, когда мы создаем нового пользователя.Мы инструктируем Spring фиксировать наши события с помощью@RecordApplicationEventsаннотации поверх нашего тестового класса:

@SpringBootTest@RecordApplicationEventsclass UserServiceFullContextTest {   @Autowired  private ApplicationEvents applicationEvents;   @Autowired  private UserService userService;   @Test  void userCreationShouldPublishEvent() {     this.userService.createUser("duke");     assertEquals(1, applicationEvents      .stream(UserCreationEvent.class)      .filter(event -> event.getUsername().equals("duke"))      .count());     // There are multiple events recorded    // PrepareInstanceEvent    // BeforeTestMethodEvent    // BeforeTestExecutionEvent    // UserCreationEvent    applicationEvents.stream().forEach(System.out::println);  }}

После того, какмы выполняем публичный метод нашего класса испытываемый (createUserизUserServiceв этом примере), мы можем запросить все захваченные события из биновApplicationEvents,которые мы внедряем в наш тест.

Открытый.stream()методкласса ApplicationEventsпозволяет просмотреть все события, записанные для теста.Есть перегруженная версия .stream(),вкоторой мы запрашиваем поток только определенных событий.

Несмотря на то, что мы генерируем только одно событие из нашего приложения, Spring захватывает четыре события для теста выше.Остальные три события относятся к Spring, как иPrepareInstanceEventв среде TestContext.

Поскольку мы используем JUnit Jupiter иSpringExtension(зарегистрированный для нас при использовании@SpringBootTest), мы также можем внедритьbean-компонент ApplicationEventsв метод жизненного цикла JUnit или непосредственно в тест:

@Testvoid batchUserCreationShouldPublishEvents(@Autowired ApplicationEvents events) {  List<Long> result = this.userService.createUser(List.of("duke", "mike", "alice"));   assertEquals(3, result.size());  assertEquals(3, events.stream(UserCreationEvent.class).count());}

ЭкземплярApplicationEventsсоздается до и удаляется после каждого теста как часть текущего потока.Следовательно, вы даже можете использовать внедрение поля и@TestInstance(TestInstance.Lifecycle.PER_CLASS)делить тестовый экземпляр между несколькими тестами (PER_METHODпо умолчанию).

Обратите внимание, что запуск всего контекста Spring@SpringBootTestдля такого тестаможет быть излишним.Мы также могли бы написать тест, который заполняет минимальный SpringTestContextтолько нашимbean-компонентом UserService, чтобы убедиться, чтоUserCreationEvent опубликован:

@RecordApplicationEvents@ExtendWith(SpringExtension.class)@ContextConfiguration(classes = UserService.class)class UserServicePerClassTest {   @Autowired  private ApplicationEvents applicationEvents;   @Autowired  private UserService userService;   @Test  void userCreationShouldPublishEvent() {     this.userService.createUser("duke");     assertEquals(1, applicationEvents      .stream(UserCreationEvent.class)      .filter(event -> event.getUsername().equals("duke"))      .count());     applicationEvents.stream().forEach(System.out::println);  }}

Или используйте альтернативный подход к тестированию.

Альтернативы тестированию весенних событий

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

@ExtendWith(MockitoExtension.class)class UserServiceUnitTest {   @Mock  private ApplicationEventPublisher applicationEventPublisher;   @Captor  private ArgumentCaptor<UserCreationEvent> eventArgumentCaptor;   @InjectMocks  private UserService userService;   @Test  void userCreationShouldPublishEvent() {     Long result = this.userService.createUser("duke");     Mockito.verify(applicationEventPublisher).publishEvent(eventArgumentCaptor.capture());     assertEquals("duke", eventArgumentCaptor.getValue().getUsername());  }   @Test  void batchUserCreationShouldPublishEvents() {    List<Long> result = this.userService.createUser(List.of("duke", "mike", "alice"));     Mockito      .verify(applicationEventPublisher, Mockito.times(3))      .publishEvent(any(UserCreationEvent.class));  }}

Обратите внимание, что здесь мы не используем никакой поддержки Spring Test иполагаемсяисключительно наMockitoи JUnit Jupiter.

Другой подход заключается в том, чтобы не проверять события публикации явно, а проверять весь сценарий использования с помощью интеграционного теста:

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)class ApplicationIT {   @Autowired  private TestRestTemplate testRestTemplate;   @Test  void shouldCreateUserAndPerformReporting() {     ResponseEntity<Void> result = this.testRestTemplate      .postForEntity("/api/users", "duke", Void.class);     assertEquals(201, result.getStatusCodeValue());    assertTrue(result.getHeaders().containsKey("Location"),      "Response doesn't contain Location header");     // additional assertion to verify the counter was incremented    // additional assertion that a new message is part of the queue  }}

В этом случае нам нужно будет проверить результат работы наших слушателей событий и, например, проверить, что мы помещаем сообщение в очередь или увеличиваем счетчик.

Резюме тестирования событий Spring с помощью Spring Boot

Все различные подходы сводятся к тестированию поведения и состояния.Благодаря новойфункции @RecordApplicationEvents вSpring Test у насможетвозникнуть соблазн провести больше поведенческих тестов и проверить внутреннюю часть нашей реализации.В общем, мы должны сосредоточиться на тестировании состояния (также известном как результат), поскольку оно поддерживает беспроблемный рефакторинг.

Представьте себе следующее: мы используем,ApplicationEventчтобы разделять части нашего приложения и гарантировать, что это событие запускается во время теста.Через две недели мы решаем убрать / переработать эту развязку (по каким-то причинам).Наш вариант использования может по-прежнему работать, как ожидалось, но наш тест теперь не проходит, потому что мы делаем предположения о технической реализации, проверяя, сколько событий мы опубликовали.

Помните об этом и не перегружайте свои тесты деталями реализации (если вы хотите провести рефакторинг в будущем :).Тем не менее, есть определенные тестовые сценарии, когда функция@RecordApplicationEvents очень помогает.

Исходный код со всеми альтернативными вариантами для тестирования Spring Event с помощью Spring Bootдоступен на GitHub.

Зачем об этом писать?

Это моя первая статья, в ней я попытаюсь описать полученный мною практический опыт работы со Spring Repository под капотом фреймворка. Готовых статей про эту тему я в интернете не нашёл ни на русском, ни на английском, были только несколько репозиториев исходников на github, ну и исходники самого Spring. Поэтому и решил, почему бы не написать, вдруг тема написания своих типов репозиториев для Spring для кого-то ещё актуальна.

Программирование для Infinispan я не буду рассматривать подробно, детали реализации всегда можно посмотреть в исходниках, указанных в конце статьи. Основной упор сделан именно на сопряжение механизма Spring Boot Repository и нового типа репозитория.

С чего всё начиналось

В ходе работы на одном из проектов у одного из архитектора возникла идея, что можно написать свои типы репозиториев по аналогии, как это сделано в разных модулях Spring (например, JPARepository, KeyValueRepository, CassandraRepository и т.п.). В качестве пробной реализации решили выбрать работу с данными через Infinispan.

Естественно, что архитекторы - люди занятые, поэтому реализовывать идею поручили Java разработчику, т.е. мне.

Когда я начал прорабатывать тему в интернете, то Google упорно выдавал почти одни статьи про то, как замечательно использовать JPARepository во всех видах на тривиальных примерах. По KeyValueRepository информации было ещё меньше. На StackOverFlow печальные никем не отвеченные вопросы по подобной теме. Делать нечего, пришлось лезть в исходники Spring.

Infinispan

Если говорить кратко про Infinispan, то это всего лишь распределённое хранилище данных в виде ключ-значение, и всё это постоянно висит закэшированное в памяти. Перегружаем Infinispan, данные все обнуляются.

Было решено, что наиболее подходящий кандидат для исследования - KeyValueRepository, как самый близкий к данной области, уже реализованный в Spring. Вся разница только в том, что вместо Infinispan (на его месте мог быть и Hazelcast, например), как хранилища данных, в KeyValueRepository обычный ConcurrentHashMap.

Реализация

Чтобы в Spring проекте подключить возможность пользоваться репозиторием для хранилища ключ-значение пользуются аннотацией EnableMapRepositories.

@SpringBootApplication@EnableMapRepositories("my.person.package.for.entities")public class Application {    public static void main(String[] args) {        SpringApplication.run(Application.class, args);    }}

Можем практически полностью скопировать содержимое кода данной аннотации и создать свою EnableInfinispanRepositories.

Чтобы каждый раз это не писать, скажу, что слово map мы всегда заменяем на infinispan, в аналогичных реализациях, скрытых спойлерами.

@Target(ElementType.TYPE)@Retention(RetentionPolicy.RUNTIME)@Documented@Inherited@Import(InfinispanRepositoriesRegistrar.class)public @interface EnableInfinispanRepositories {    String[] value() default {};    String[] basePackages() default {};    Class<?>[] basePackageClasses() default {};    ComponentScan.Filter[] excludeFilters() default {};    ComponentScan.Filter[] includeFilters() default {};    String repositoryImplementationPostfix() default "Impl";    String namedQueriesLocation() default "";    QueryLookupStrategy.Key queryLookupStrategy() default QueryLookupStrategy.Key.CREATE_IF_NOT_FOUND;    Class<?> repositoryFactoryBeanClass() default KeyValueRepositoryFactoryBean.class;    Class<?> repositoryBaseClass() default DefaultRepositoryBaseClass.class;    String keyValueTemplateRef() default "infinispanKeyValueTemplate";    boolean considerNestedRepositories() default false;}

Если посмотреть что происходит в коде аннотации EnableMapRepositories, то увидим, что там импортируется класс, который и делает всю магию по активации данного типа репозитория.

@Import(MapRepositoriesRegistrar.class)public @interface EnableMapRepositories {}

Ниже код MapRepositoriesRegistar.

public class MapRepositoriesRegistrar extends RepositoryBeanDefinitionRegistrarSupport {@Overrideprotected Class<? extends Annotation> getAnnotation() {return EnableMapRepositories.class;}@Overrideprotected RepositoryConfigurationExtension getExtension() {return new MapRepositoryConfigurationExtension();}}

В коде перегружаются два метода. В одном связывается Registar со своей активирующей аннотацией, чтобы потом из неё получить заполненные атрибуты конфигурации. В другом находится реализация хранилища данных, специфичных для данного типа репозитория.

@NoArgsConstructorpublic class InfinispanRepositoriesRegistrar extends RepositoryBeanDefinitionRegistrarSupport {    @Override    protected Class<? extends Annotation> getAnnotation() {        return EnableInfinispanRepositories.class;    }    @Override    protected RepositoryConfigurationExtension getExtension() {        return new InfinispanRepositoryConfigurationExtension();    }}

Теперь посмотрим, как же выглядит сама реализация хранилища.

public class MapRepositoryConfigurationExtension extends KeyValueRepositoryConfigurationExtension {@Overridepublic String getModuleName() {return "Map";}@Overrideprotected String getModulePrefix() {return "map";}@Overrideprotected String getDefaultKeyValueTemplateRef() {return "mapKeyValueTemplate";}@Overrideprotected AbstractBeanDefinition getDefaultKeyValueTemplateBeanDefinition(RepositoryConfigurationSource configurationSource) {BeanDefinitionBuilder adapterBuilder = BeanDefinitionBuilder.rootBeanDefinition(MapKeyValueAdapter.class);adapterBuilder.addConstructorArgValue(getMapTypeToUse(configurationSource));BeanDefinitionBuilder builder = BeanDefinitionBuilder.rootBeanDefinition(KeyValueTemplate.class);    ...  }  ...}

В MapKeyValueAdapter будет реализована самая специфическая часть, характерная именно для локального хранения кэша в HashMap. А вот KeyValueTemplate оборачивает методы адаптера довольно общим кодом.

Поэтому чтобы выполнить задачу и заменить хранение данных с локального кэша на распределённое хранилище Infinispan, нужно сделать аналогичный ConfigurationExtension, но заменить на специфичный адаптер, где и будет реализована вся логика чтения/записи/поиска данных, характерная для Infinispan.

@NoArgsConstructorpublic class InfinispanRepositoryConfigurationExtension extends KeyValueRepositoryConfigurationExtension {    @Override    public String getModuleName() {        return "Infinispan";    }    @Override    protected String getModulePrefix() {        return "infinispan";    }    @Override    protected String getDefaultKeyValueTemplateRef() {        return "infinispanKeyValueTemplate";    }    @Override    protected Collection<Class<?>> getIdentifyingTypes() {        return Collections.singleton(InfinispanRepository.class);    }    @Override    protected AbstractBeanDefinition getDefaultKeyValueTemplateBeanDefinition(RepositoryConfigurationSource configurationSource) {        RootBeanDefinition infinispanKeyValueAdapterDefinition = new RootBeanDefinition(InfinispanKeyValueAdapter.class);        RootBeanDefinition keyValueTemplateDefinition = new RootBeanDefinition(KeyValueTemplate.class);        ConstructorArgumentValues constructorArgumentValuesForKeyValueTemplate = new ConstructorArgumentValues();        constructorArgumentValuesForKeyValueTemplate.addGenericArgumentValue(infinispanKeyValueAdapterDefinition);        keyValueTemplateDefinition.setConstructorArgumentValues(constructorArgumentValuesForKeyValueTemplate);        return keyValueTemplateDefinition;    }}

Нужно обязательно в нашем ConfigurationExtension ещё перегрузить метод getIdentifyingTypes(), чтобы в нём сослаться на наш новый тип репозитория (см. реализацию выше).

@NoRepositoryBeanpublic interface InfinispanRepository <T, ID> extends PagingAndSortingRepository<T, ID> {}

Чтобы окончательно всё заработало, нужно сконфигурировать KeyValueTemplate, подсунув ему наш адаптер.

@Configurationpublic class InfinispanConfiguration extends CachingConfigurerSupport {    @Autowired    private ApplicationContext applicationContext;    @Bean    public InfinispanKeyValueAdapter getInfinispanAdapter() {        return new InfinispanKeyValueAdapter(                applicationContext.getBean(CacheManager.class)        );    }    @Bean("infinispanKeyValueTemplate")    public KeyValueTemplate getInfinispanKeyValueTemplate() {        return new KeyValueTemplate(getInfinispanAdapter());    }}

На этом всё.

Можно, конечно, копать глубже и не пользоваться готовыми Spring-овыми реализациями для репозиториев, а наследоваться исключительно от их абстрактных классов и интерфейсов, но объём работ будет намного больше, чем в этой статье.

Резюме

Написав всего 6 своих классов, мы получили новый тип репозитория, который может работать с Infinispan в качестве хранилища данных. И работает этот новый тип репозитория очень похоже на стандартные Spring репозитории.

Полный комплект исходников можно найти на моём github.

Исходники Spring Data KeyValue можно увидеть также на github.

Если у вас есть конструктивные замечания к данной реализации, то пишите в комментариях, либо можете сделать pull request в исходном проекте.

Мониторинг очень важен для современных приложений, современные приложения по своей природе сильно распределены и имеют разные зависимости, такие как база данных, службы, кеширование и многое другое.Поэтому все более важны отслеживание и мониторинг этих служб, чтобы приложение придерживалось условий SLA(ServiceLevelAgreement).SLA это соглашение между клиентом и поставщиком услуг, в нем учитываются надежность, скорость отклика и другие показатели уровня обслуживания.

Мы всегда стараемся не нарушать никаких SLA, нарушение любой части SLA может иметь множество последствий.Если услуга не соответствует условиям, определенным в SLA, она можкт нанести ущерб репутации бренда и привести к потери дохода.Хуже всего то, что компания может потерять клиента в пользу конкурента из-за своей неспособности удовлетворить требования клиента к уровню обслуживания.

Какие показатели нужно отслеживать?

• Доступность услуги:время, в течение которого услуга доступна для использования.Это может быть измерено с точки зрения времени отклика, например, процентиль X, сокращенно обозначаемый как pX, например, p95, p99, p99.999.Не для всех сервисов требуется p99,999, системы с гарантированной высокой доступностью, такие как электронная коммерция, поиск, оплата и т. д., должны иметь более высокое SLA.

• Уровень дефектов:несмотря на все усилия по разработке системы, ни одна система не является идеальной на 100%.Мы должны подсчитывать процент ошибок в основных потоках.В эту категорию могут быть включены производственные сбои, такие как ошибка сервера, ошибка запроса базы данных, ошибка соединения, сетевые ошибки и пропущенные сроки.

• Безопасность:в наши сверх регулируемые времена нарушения безопасности приложений и сети могут быть дорогостоящими.В эту категорию можно включить измерение контролируемых мер безопасности, таких как доступ к системе, несанкционированный доступ к базе данных, массовая загрузка записей базы данных или перемещение больших объемов данных.

• Бизнес-результаты: ИТ-клиенты все чаще хотят включать метрики бизнес-процессов в свои SLA, чтобы можно было принимать более правильные бизнес-решения.В этой категории могут быть собраны различные данные, такие как количество пользователей, посетивших страницу, активность входа, эффективность купона и т. д.

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

Настройка мониторинга

Типичная система настройки мониторинга будет состоять из трех компонентов

1. Хранилища метрик (какправило,база данных временных рядов), такое как InfluxDB, TimescaleDB, Prometheusи т. д.

2. Панель инструментов (панель будет использоваться для визуализации данных, хранящихся в хранилище метрик).

3. Приложения, которые будут продолжать отправлять метрики в хранилище метрик или хранилище метрик, периодически извлекают данные из локального состояния приложения.

У нас могут быть и другие компоненты, например, оповещение, где каналами оповещения могут быть электронная почта, Slack или любые другие.Компонент оповещения будет отправлять оповещения владельцам приложений или подписчикам событий.Мы собираемся использоватьGrafanaкак панель управления и систему оповещений,Prometheusкак систему хранения метрик.

Нам понадобятся:

1. Любая IDE

2. Платформа Java

3. Gradle

Создайте проект с помощью инициализатора Spring Boot, добавьте столько зависимостей, сколько нам нужно.Мы собираемся использовать библиотеку Micrometer, это инструментальный фасад, который обеспечивает привязки для многих хранилищ метрик, таких как Prometheus, Datadog и New Relic, и это лишь некоторые из них.

Из коробки Micrometer обеспечивает

1. HTTP-запрос

2. JVM

3. База данных

4. Метрики, относящиеся к системе кэширования и т. д.

Некоторые метрики включены по умолчанию, тогда как другие можно включить, отключить или настроить.Мы будем использовать файл application.properties для включения, отключения и настройки метрик. Нам также нужно использовать Spring boot actuator, так как он откроет доступ к конечной точкеPrometheus.

Добавьте эти зависимости в файл build.gradle:

1. io.micrometer: micrometer-registry-prometheus

2. org.springframework.boot: spring-boot-starter-actuator

dependencies {  implementation 'org.springframework.boot:spring-boot-starter-data-jpa'  implementation 'org.springframework.boot:spring-boot-starter-web'  compileOnly 'org.projectlombok:lombok'  annotationProcessor 'org.projectlombok:lombok'  providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'  implementation 'io.micrometer:micrometer-registry-prometheus'  implementation 'org.springframework.boot:spring-boot-starter-actuator'  // https://mvnrepository.com/artifact/com.h2database/h2  compile group: 'com.h2database', name: 'h2', version: '1.4.200'  testImplementation('org.springframework.boot:spring-boot-starter-test') {  exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'  }}

Мы можем включить экспорт Prometheus, добавив следующую строку в файл свойств.

management.metrics.export.prometheus.enabled = true

После добавления этой строки Micrometer начнет накапливать данные о приложении, и эти данные можно будет просмотреть, перейдя на конечную точку actuator/Prometheus.Эта конечная точка будет использоваться в скрипте Prometheus для получения данных с наших серверов приложений.

Несмотря на то, что мы добавили эту строку в свойствах, мы не можем просматривать конечную точку Prometheus, поскольку она отключена по умолчанию, мы можем открыть ее, используя конечную точку управления, включивPrometheusв список.

management.endpoints.web.exposure.include=prometheus

ПРИМЕЧАНИЕ. Не включайте все конечные точки actuator, так как это может открыть лазейку в системе безопасности.Мы должны выбирать их выборочно, особенно в производственной системе, даже если мы хотим, не раскрывать конечную точку для всего мира, так как она может раскрыть большой объем данных о приложении, использовать какой-то прокси или какое-то правило, чтобы скрыть данные от внешнего мира.

Различные частиHTTP-запросовнастраиваются, например SLA, настройка признака должна быть вычислена или нет гистограмма процентилей делается спомощьюсвойствmetrics.distribution.

В примере application.properties могут быть такие строки

# Включить экспорт prometheusmanagement.metrics.export.prometheus.enabled = true# Включить конечную точку Prometheusmanagement.endpoints.web.exposure.include = Прометей# включить гистограмму на основе процентилей для http запросовmanagement.metrics.distribution.percentiles-histogram.http.server.requests = true# сегментов гистограммы http SLAmanagement.metrics.distribution.sla.http.server.requests = 100 мс, 150 мс, 250 мс, 500 мс, 1 с# включить метрики JVMmanagement.metrics.enable.jvm = true

Теперь, если мы запустим приложение и перейдем на страницу http://locahost:8080/actator/prometheus, будет отображаться чертовски много данных.

Приведенные выше данные отображают детали HTTP-запроса, exception=None означает, что исключение не произошло, если оно есть, мы можем использовать это для фильтрации количества запросов, которые не удалось выполнить из-за этого исключения,method=GETимя метода HTTP.status=200HTTP статус равен 200,uri=/actator/prometheusотображает путь URL,le=xyzотображает время обработки,N.0отображает количествовызововэтой конечной точки.

Эти данные представляют собой гистограмму, которую можно построить в Grafana, например, чтобы построить график p95 за 5 минут, мы можем использовать следующий запрос.

histogram_quantile(0.95,sum(rate(http_server_requests_seconds_bucke[5m])) by (le))

В Grafana можно построить и другие графики показателей, например круговую диаграмму и т. д.

Пользовательские показатели

Часто нам нужны специальные метрики, некоторые из сценариев использования это количество вошедших в систему пользователей, сведения о запасах доступных, в настоящее время, количество заказов в очереди и т. д. Некоторые из бизнес сценариев использования могут быть решены с использованием пользовательских метрик, микрометра. поддерживает различные типы показателей, такие как таймер, датчик, счетчик, сводки распределения, таймеры для длительных задач и т. д. В основном мы сосредоточимся на датчике и счетчике. Датчик дает нам мгновенные данные, такие как длина очереди, тогда как счетчик похож на монотонно увеличивающееся число, начинающееся с единицы.

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

1. Добавить товары

2. Получить товары

Для этого мы создадим один счетчик и одну метрику вметодеinit, при каждомвызове getItems мы увеличиваем счетчик, а также измеряем размер запаса, тогда как при вызове addItems мы только обновляем метрику.

@Componentpublic class StockManager {  @Autowired private MeterRegistry meterRegistry;  private List<String> orders = new Vector<>();  private Counter counter;  private Gauge gauge;@PostConstruct  public void init() {    counter =        Counter.builder("order_created")            .description("number of orders created")            .register(meterRegistry);    gauge =        Gauge.builder("stock.size", this, StockManager::getNumberOfItems)            .description("Number of items in stocks")            .register(meterRegistry);  }public int getNumberOfItems() {    return orders.size();  }public void addItems(List<String> items) {    orders.addAll(items);    // measure gauge    gauge.measure();  }public List<String> getItem(int count) {    List<String> items = new ArrayList<>(count);    while (count < 0) {      try {        items.add(orders.remove(0));      } catch (ArrayIndexOutOfBoundsException e) {        break;      }      count -= 1;    }    // increase counter    counter.increment();    //  measure gauge    gauge.measure();    return items;  }}

В демонстрационных целях мы добавим две конечные точки для добавления товаров и получения товаров.

@RestController@RequestMapping(path = "stocks")@RequiredArgsConstructor(onConstructor = @__(@Autowired))public class StockController {  @NonNull private StockManager stockManager;  @GetMapping  @ResponseBody  public List<String> getItems(@RequestParam int size) {    return stockManager.getItem(size);  }  @PostMapping  @ResponseBody  public int addItems(@RequestParam List<String> items) {    stockManager.addItems(items);    return stockManager.getNumberOfItems();  }}  @PostMapping  @ResponseBody  public int addItems(@RequestParam List<String> items) {    stockManager.addItems(items);    return stockManager.getNumberOfItems();  }}

Давайте сначала добавим десять товаров, используя два вызова API:

1. Curl -X POST http://localhost:8080/stocks?Items = 1,2,3,4

2. Curl -X POST http://localhost:8080/stocks?Items = 5,6,7,8,9,10

Теперь, если мы перейдем к конечным точкам Prometheus, то увидим следующие данные, которые показывают, что в настоящее время у нас есть 10 товаров на складе.

# HELP stock_size Количество товаров на складе# TYPE stock_size gaugestock_size 10.0

Теперь мы собираемся разместить заказ на 3 товара:

http://localhost:8080/stocks?size=3

Теперь, если мы посмотрим конечную точку Prometheus, мы получим следующие данные, которые показывают, что размер запаса был изменен до семи.

# HELP stock_size Количество товаров на складе# TYPE stock_size gaugestock_size 7.0

Кроме того, мы видим, что на счетчике добавлено значение 1, это означает, что размещен один ордер.

# HELP order_created_total количество созданных заказов# TYPE order_created_total counterorder_created_total 1.0ordercreated_total 1.0

Профилирование

В программной инженерии профилирование (профилирование программы, профилирование программного обеспечения) - это форма динамического анализа программы, который измеряет, например, объем (память) или временную сложность программы, использование определенных инструкций или частоту и продолжительность вызовов функций.

Чаще всего профилирующая информация помогает оптимизировать программу. Профилирование достигается путем сбора характеристик работы программы, таких как время выполнения отдельных фрагментов (обычно подпрограмм), число верно предсказанных условных переходов, число кэш-промахов и т. д. Инструмент, используемый для анализа работы, называют профилировщиком или профайлером (profiler). Профилировщики могут использовать ряд различных методов, таких как методы, основанные на событиях, статистические, инструментальные методы и методы моделирования. Википедия

Профилирование очень полезно при диагностике системных проблем, например, сколько времени занимает HTTP-вызов, если он занимает N секунд, а затем, где все это время было потрачено, каково распределение N секунд между различными запросами к базе данных, вызовами последующих служб и т. д. Мы можем использовать гистограмму для построения графика распределения на панели инструментов, также мы можем использовать счетчик для измерения количества запросов к БД и т. д. Для профилирования нам необходимо внедрить код во многие функции, которые будут выполняться как часть выполнения метода.

Важно то, что внедряемая часть кода профилирования одинакова для профилировщиков аналогичных типов, что означает, что нам нужно скопировать и вставить аналогичный код в тысячи мест, если нам нужно что-то изменить, нам нужно обновить то же самое. Код профилировщика в каждом файле и, вероятно, в каждой функции, требующей профилирования, повысит сложность и может стать создать полный беспорядок, впрочем мы можем избежать этого беспорядка, используяаспектно-ориентированное программирование (АОП).

Короче говоря, АОП работает пошаблону проектирования прокси, хотя его можно реализовать и с помощью модификации байтового кода.

Всякий раз, когда вызывается метод, мы ожидаем, что вызываемый метод будет вызываться напрямую без каких-либо промежуточных шагов, но когда AOP помещается на место, тогда вызов метода перехватывается прокси-методом, а прокси-метод вызывает целевой метод, прокси-метод возвращает результат для вызывающего абонента, как показано на рисунке ниже.

Система зависит от других систем, поэтому мы можем быть заинтересованы в профилировании различных компонентов по-разному, например, вызовов базы данных, HTTP-запросов, последующих вызовов служб или некоторых конкретных методов, которые являются критическими или хотели бы увидеть, что происходит в некоторых конкретных методах.Мы можем использовать ту же библиотеку Micrometer для профилирования, но это может быть не совсем то, что нам нужно, поэтому мы изменим код.

Micrometer поставляется саннотациейTimed, эту аннотацию можно разместить в любомpublic методе, таккак название предполагает, что она может измерять время выполнения, это будет измерять время выполнения соответствующего метода.Вместо того, чтобы напрямую использовать эту аннотацию, мы расширим эту аннотацию для поддержки других функций, таких как ведение журнала, повторная попытка и т. Д.

Аннотация Timed бесполезна без бина TimedAspect, поскольку мы переопределяем аннотациюTimed, поэтому мы также определим класс TimedAspect в соответствии с потребностями, такими как ведение журнала, массовое профилирование (профилируйте все методы в пакете без добавления каких-либо аннотаций к любому методу или классу), повторить попытку и т. д. В этой истории мы рассмотрим три сценария использования:

1. Массовое профилирование.

2. Логирование.

3. Специфический для профиля метод.

Созадим файл java MonitoringTimed.java, в который мы добавим новое поле с именемloggingEnabled,это поле будет использоваться для проверки, включено ли ведение журнала или нет, если оно включено, а затем регистрировать аргументы метода и возвращаемые значения.

@Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE, ElementType.METHOD})@Retention(RetentionPolicy.RUNTIME)public @interface MonitoringTimed {  /** All fields are same as in {@link io.micrometer.core.annotation.Timed} */  String value() default "";  String[] extraTags() default {};  boolean longTask() default false;  double[] percentiles() default {};  boolean histogram() default false;  String description() default "";  // NEW fields starts here  boolean loggingEnabled() default false;}

Эта аннотация бесполезна без класса аспекта Timed, поэтомубудет определенновый классMonitoringTimedAspectсо всеми необходимыми деталями, этот класс будет иметь метод для профилирования любого метода на основе объединенного объекта обработки иобъектаMonitoringTimed,а другой - для профилирования метода на основе в аннотации MonitoringTimed.

@Around("execution (@com.gitbub.sonus21.monitoring.aop.MonitoringTimed * *.*(..))")public Object timedMethod(ProceedingJoinPoint pjp) throws Throwable {  Method method = ((MethodSignature) pjp.getSignature()).getMethod();  MonitoringTimed timed = method.getAnnotation(MonitoringTimed.class);  if (timed == null) {    method = pjp.getTarget().getClass().getMethod(method.getName(), method.getParameterTypes());    timed = method.getAnnotation(MonitoringTimed.class);  }  final String metricName = generateMetricName(pjp, timed);  return timeThisMethod(pjp, timed, metricName);}public Object timeThisMethod(ProceedingJoinPoint pjp, MonitoringTimed timed) throws Throwable {  final String metricName = generateMetricName(pjp, timed);  return timeThisMethod(pjp, timed, metricName);}

МетодTimedMethodсаннотациейAroundиспользуется для фильтрации всех вызовов методов, аннотированных с помощьюMonitoringTimed.

Для массового профилирования мы определим класс профилировщика, который будет работать с фильтрацией на уровне пакета. Например, для профилирования HTTP-запроса мы можем добавить ControllerProfiler, который будет обрабатывать профилирование всех общедоступных методов, доступных в пакете контроллера.

@Aspect@Componentpublic class ControllerProfiler {  private static Map<String, Object> timedAnnotationData = new HashMap<>();  static {    // use percentile data of p90, p95, p99.99    double[] percentiles = {0.90, 0.95, 0.9999};    // set histogram to true    timedAnnotationData.put("histogram", true);    // set percentile    timedAnnotationData.put("percentiles", percentiles);  }  @Autowired private MonitoringTimedAspect timedAspect;  private static final MonitoringTimed timed = Javanna.createAnnotation(MonitoringTimed.class, timedAnnotationData);  private static final Logger logger = LoggerFactory.getLogger(ControllerProfiler.class);  @Pointcut("execution(* com.gitbub.sonus21.monitoring.controller..*.*(..))")  public void controller() {}  @Around("controller()")  public Object profile(ProceedingJoinPoint pjp) throws Throwable {    // here add other logic like error happen then log parameters etc    return timedAspect.timeThisMethod(pjp, timed);  }}

Интересной строкой в приведенном выше коде является @Pointcut(execution(com.gitbub.sonus21.monitoring.controller...*(..))), которая определяет pointcut, выражение pointcut может быть определено с использованием логических операторов вродеnot (!), or (||), and (&&). После того, как метод квалифицирован согласно выражению pointcut, он может вызвать соответствующий метод, определенный с помощью аннотации [at]Around.Поскольку мы определилиметодprofile,который будет вызываться, мы также можем определить другие методы, используя аннотации [at]After, [at]Before и т. д.

После добавления нескольких элементов с помощью метода POST мы можем увидеть следующие данные в конечной точке Prometheus.

method_timed_seconds {class = "com.gitbub.sonus21.monitoring.controller.StockController", exception = "none", method = "addItems", quantile = "0.9",} 0.0method_timed_seconds_bucket {class = "com.gitbub.sonus21.monitoring.controller.StockController", exception = "none", method = "addItems", le = "0.001",} 3.0method_timed_seconds_bucket {class = "com.gitbub.sonus21.monitoring.controller.StockController", exception = "none", method = "addItems", le = "0.002446676",} 3.0

Мы можем напрямую использоватьаннотациюMonitoringTimedтакже для любого метода для измерения времени выполнения, например, давайтеизмерим,сколько времениStockManagerметод addItemsтратит на добавление элементов.

@MonitoringTimedpublic void addItems(List<String> items) {  orders.addAll(items);  // measure gauge  gauge.measure();}

Как только мы запустим приложение и добавим несколько элементов, мы увидим следующее в конечной точке Prometheus.

method_timed_seconds_count{class="com.gitbub.sonus21.monitoring.service.StockManager",exception="none",method="addItems",} 4.0method_timed_seconds_sum{class="com.gitbub.sonus21.monitoring.service.StockManager",exception="none",method="addItems",} 0.005457965method_timed_seconds_max{class="com.gitbub.sonus21.monitoring.service.StockManager",exception="none",method="addItems",} 0.00615316

MonitoringTimed можно дополнительно настроить, например, можно добавить количество повторных попыток для поддержки повторных попыток в случае сбоя, записать аргументы функции в случае сбоя, чтобы позже можно было проанализировать причину сбоя.

Полный код доступен наGitHub.

Дополнительное чтение

Magic With the Spring Boot Actuator

Spring Boot Actuator in Spring Boot 2.0

Spring Boot Admin Client Configuration Using Basic HTTP Authentication

До Spring Boot разработки вам нужно сделать несколько вещей, чтобы настроитьSpring Data JPA.Вам не только нужно было аннотировать свои классы сущностей с помощью аннотаций преобразования, добавить Spring Data JPA зависимость и настроить соединение с базой данных.Вам также нужно включить репозитории и управление транзакциями и настроить EntityManagerFactory.Это - повторяющаяся и раздражающая задача.

Spring Boot изменяет этот подход, предоставляя готовые к использованию интеграции, которые включают необходимые зависимости и огромный набор конфигураций по умолчанию.Но это не значит, что вы не можете отменить их, если вам нужно.

В этой статье объясняется конфигурация Spring Boot по умолчанию для Spring Data JPA, какие параметры конфигурации вы можете использовать для ее изменения, а также конфигурацию, которую вы, возможно, захотите добавить.

Обязательные зависимости

Прежде чем вы сможете приступить к настройке Spring Data JPA, вам необходимо добавить его в свое приложение.В приложении Spring Boot это обычно означает, что вам нужно добавить правильный стартер в зависимости вашего проекта.Самый простой способ сделать это для нового проекта - использоватьSpring Initializrдля настройки процесса сборки и добавления всех необходимых зависимостей.Для всех проектов Spring Boot вам необходимо добавитьмодульspring-boot-starter-data-jpa.

<dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-data-jpa</artifactId></dependency>

Вам также необходимо добавить зависимость JDBC драйвера для конкретной базы данных.В следующих примерах выполняется подключение к базе данных PostgreSQL и, следовательно, потребуется зависимость от JDBC драйвера PostgreSQL.

<dependency>    <groupId>org.postgresql</groupId>    <artifactId>postgresql</artifactId>    <version>${postgresql.version}</version></dependency>

Конфигурация по умолчанию

Как упоминалось ранее, интеграция Spring Boot со Spring Data JPA обеспечивает обширную конфигурацию по умолчанию и добавляет большинство необходимых зависимостей в ваш проект.Она включает в себя:

• зависимость отпуласоединенийHikariCPи базовой конфигурации по умолчанию.Вы можете установить все параметры конфигурации HikariCP вфайлеapplication.properties, добавив префиксspring.datasource.hikariк имени параметра.

• создание базы данных в памяти H2, HSQL или Derby, если ваш путь к классам содержит соответствующий драйвер JDBC.

• зависимость от Hibernate в качестве вашей реализации JPA и требуемую конфигурацию для создания экземпляраEntityManagerFactory.

• зависимость и необходимая конфигурация для управления вашими транзакциями с помощью встроенного менеджера транзакций Atomikos.

• необходимая конфигурация для использования репозиториев Spring Data JPA.

Примечание: поскольку Spring Data JPA использует Hibernate в качестве реализации JPA по-умолчанию, вы можете использоватьвсе, что вы знаете о Hibernate, со Spring Data JPA.

Как видите, это в основном все, что вам ранее приходилось настраивать в своем классе конфигурации.Вот почему большинство проектов предпочитают использовать Spring Boot классическому Spring.

Если вы используете базу данных в памяти, вам не нужно предоставлять какую-либо настраиваемую конфигурацию.Конфигурации Spring Boot по умолчанию обычно достаточно для всех малых и средних приложений.

Большинство корпоративных приложений используют автономную базу данных, например,сервер базы данныхPostgreSQLили Oracle.В этом случае вам нужно только предоставить URL-адрес, имя пользователя и пароль для подключения к этой базе данных.Вы можете сделать это, установив следующие 3 свойства конфигурации вфайлеapplication.properties.

spring.datasource.url=jdbc:postgresql://localhost:5432/testspring.datasource.username=postgresspring.datasource.password=postgres

Настройка конфигурации по умолчанию

Просто потому, что Spring Data JPA автоматически интегрирует несколько других проектов Spring и настраивает их для вас, вы не обязаны их использовать.Вы можете легко изменить поведение и интеграцию по умолчанию, указав различные зависимости и добавив несколько параметров в свою конфигурацию.

Использование другого пула подключений

По умолчанию Spring Boot добавляет зависимость к HikariCP и настраивает ее.Вы можете использовать другой пул соединений, исключив HikariCP из зависимостей вашего проекта.

<dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-data-jpa</artifactId>    <exclusions>        <exclusion>            <groupId>com.zaxxer</groupId>            <artifactId>HikariCP</artifactId>        </exclusion>    </exclusions></dependency>

Затем Spring Boot пытается найти следующие реализации пула соединений в описанном порядке в пути к классам и использует первую из найденных:

• Пул соединений Tomcat,

• Commons DBCP2,

• Oracle UCP.

Если вы не хотите полагаться на сканирование пути к классам вашего приложения, вы также можете явно указать пул соединений, настроив свойство spring.datasource.type.

spring.datasource.type=org.apache.tomcat.jdbc.pool.DataSource

После того, каквы изменили пул соединений, вы можете установить все свои стандартные параметры конфигурации вapplication.propertiesфайл путем добавления префикса spring.datasource.tomcat, spring.datasource.dbcp2 или spring.datasource.oracleucp с именем параметра.

Использование Bitronix Transaction Manager

В прошлом Bitronix был популярным менеджером транзакций в приложениях Spring.Поддержка Spring Boot для него устарела и будет удалена в будущем.

Если вы все еще хотите его использовать, вы можете добавить в свое приложение зависимость отspring-boot-starter-jta-bitronix.Затем Spring Boot будет включать все необходимые зависимости и настраивать Bitronix для управления вашими транзакциями.

Деактивация репозиториев Spring Data JPA

Я рекомендую использовать репозитории Spring Data JPA.Они значительно упрощают реализацию вашей персистентности, предоставляя набор стандартных методов для сохранения, чтения и удаления сущностей.Они также предоставляют такие функции, какпроизводныеинастраиваемые запросы.

Если вы решите не использовать эти функции, вы можете деактивировать все репозитории JPA в своей конфигурации.

spring.data.jpa.repositories.enabled=false

Дополнительный параметр конфигурации, который вы должны знать

Вы можете использовать огромный набор параметров конфигурации, чтобы адаптировать поведение Spring Boot и используемых вами библиотек.Вы можете найти полный список всех поддерживаемых параметров вофициальной документации Spring.В следующих разделах объясняются несколько параметров, которые вам необходимо знать.

Настройка ведения журнала

Как объясняется в Руководстве по ведению журнала Hibernate рекомендовано использовать 2 разные конфигурации ведения журнала для среды разработки и рабочей среды.Это, конечно, меняется не при настройке Spring Data JPA.Используя Spring Boot, вы можете настроить уровни журнала для всех категорий Hibernate вфайлеapplication.properties, добавив префиксlogging.levelк имени категории журнала.

Конфигурация среды разработки

Во время разработки вы хотите получить как можно больше информации о взаимодействиях с базой данных.Это позволяет вам понять, как ваше приложение взаимодействует с базой данных, и найти проблемы с производительностью перед их развертыванием в рабочей среде.

Чтобы получить всю необходимую информацию, рекомендуется использовать следующую конфигурацию.

logging.level.org.hibernate=INFOlogging.level.org.hibernate.SQL=DEBUGlogging.level.org.hibernate.cache=DEBUGlogging.level.org.hibernate.stat=DEBUG

Она активирует статистический компонент Hibernate.Он предоставляет вам сводную информацию о количестве и времени, затраченном Hibernate на выполнение наиболее важных операций во время каждого сеанса.Он также добавляет все выполненные операторы SQL в файл журнала и показывает, как Hibernate использовал кеш 2-го уровня.

Spring Boot также поддерживает параметр spring.jpa.show-sql, чтобы включить ведение журнала операторов SQL.Но вам лучше избегать этого, по2тому что он игнорирует вашу структуру ведения журнала и записывает операторы SQL непосредственно в стандартный вывод.

Конфигурация рабочей среды

В рабочей среде вы должны установить уровень журнала Hibernate на ERROR, чтобы сократить накладные расходы как можно меньше.

logging.level.org.hibernate=ERROR

Настройка свойств JPA и Hibernate

Когда вы используете JPA и Hibernate без Spring Data JPA, вы обычно настраиваете его с помощьюфайлаpersistence.xml.Вэлементе свойствэтого XML-файла вы можете указать параметры конфигурации, зависящие от поставщика.

Вы можете установить все эти параметры вфайлеapplication.properties, добавив префиксspring.jpa.propertiesк имени свойства конфигурации.

spring.jpa.properties.hibernate.generate_statistics=true

Настройка создания базы данных

По умолчанию Spring Boot автоматически создает для вас базы данных в памяти.Эта функция отключена для всех остальных баз данных.Вы можете активировать ее, установив для свойстваspring.jpa.hibernate.ddl-auto значения: none,validate,updateилиcreate-drop.

Рекомендуетсявместо этогоиспользоватьSpring Boot's Flyway или интеграцию с Liquibase.Они более мощные и дают вам полный контроль над определением структур ваших таблиц.

Вывод

Spring Boot стартер для Spring Data JPA добавляет в ваше приложение наиболее распространенные зависимости и разумную конфигурацию по умолчанию.Единственное, что вам нужно добавить, это информацию о подключении к вашей базе данных.

Но это не значит, что вам обязательно нужно использовать эти значения по умолчанию.Как вы узнали из этой статьи, вы можете легко заменить все зависимости по умолчанию и настроить конфигурацию по умолчанию по своим требованиям.

Spring Boot Actuator помогает нам отслеживать и управлять нашими приложениями в производственной среде.Он предоставляет конечные точки, которые публикуются показатели работоспособности и другая информация о запущенном приложении.Мы также можем использовать его для изменения уровня ведения журнала приложения, создания дампа потока и т. д. - короче говоря, возможностей, которые упрощают работу в производственной среде.

Хотя Actuator в основном используется в производственной среде, он также может помочь нам во время разработки и сопровождения.Мы можем использовать его для изучения и анализа нового приложения Spring Boot.

В этой статье мы увидим, как использовать некоторые из его конечных точек для изучения нового приложения, с которым мы не знакомы.Мы будем работать в командной строке и использоватьcurl иjq, с изящным и мощным JSON процессором командной строки.

Пример кода

Эта статья сопровождается примером рабочего кодана GitHub.

Зачем использовать Actuator для анализа и изучения приложения?

Представим, что мы впервые работаем над новой кодовой базой на основе Spring Boot.Мы, вероятно, изучим структуру папок, посмотрим на имена папок, проверим имена пакетов и имена классов, чтобы попытаться построить модель приложения в нашем уме.Мы могли бы сгенерировать некоторые UML диаграммы, чтобы помочь определить зависимости между модулями, пакетами, классами и т. д.

Хотя это важные шаги, они дают нам только статичное представление о приложении.Мы не можем получить полную картину, не понимая, что происходит во время выполнения.Например, что представляют собой все создаваемые Spring Beans?Какие конечные точки API доступны?Каковы все фильтры, через которые проходит запрос?

Построение этой мысленной модели формы выполнения приложения очень полезно.Она позволит глубже погрузиться в чтение и более эффективно понять важные части кода.

Общий обзор Spring Boot Actuator

Начнем с краткого обзора по Spring Boot Actuator.

На верхнем уровне, когда мы работаем с Actuator, мы делаем следующие шаги:

1. Добавляем Actuator как зависимость к нашему проекту

2. Включаем и открываем конечные точки

3. Защищаем и настраиваем конечные точки

Давайте кратко рассмотрим каждый из этих шагов.

Шаг 1. Добавьте Actuator зависимость

Добавление Actuator в наш проект похоже на добавление любой другой зависимости.Вот фрагмент для Mavenpom.xml:

<dependencies>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-actuator</artifactId>    </dependency></dependencies>

Если бы мы использовали Gradle, мы бы добавили вфайл build.gradle следующийфрагмент:

dependencies {    implementation 'org.springframework.boot:spring-boot-starter-actuator'}

Простое добавление указанной выше зависимости в приложение Spring Boot предоставляет некоторые готовые конечные точки, такие как/actuator/health, которые могут использоваться, например, для поверхностной проверки работоспособности с помощью балансировщика нагрузки.

$ curl http://localhost:8080/actuator/health{"status":"UP"}

Мы можем перейти на конечную точку/actuator, чтобы просмотреть другие конечные точки, доступные по умолчанию.Конечная точка /actuator открывает обзорную страницу со всеми доступными конечными точками:

$ curl http://localhost:8080/actuator{"_links":{"self":{"href":"http://localhost:8080/actuator","templated":false},"health":{"href":"http://localhost:8080/actuator/health","templated":false},"health-path":{"href":"http://localhost:8080/actuator/health/{*path}","templated":true},"info":{"href":"http://localhost:8080/actuator/info","templated":false}}}

Шаг 2. Включите и откройте конечные точки

Конечные точки идентифицируются идентификаторами,такими как health, info, metrics и так далее.Включение и открытие конечной точки делает ее доступной для использования попути /actuator URL-адреса приложения, напримерhttp://your-service.com/actuator/health,http://your-service.com/actuator/metrics и т. д.

Большинство конечных точек, за исключениемshutdown, включены по умолчанию.Мы можем отключить конечную точку, установив для свойства management.endpoint.<id>.enabled значениеfalseвapplication.propertiesфайле.Например, вот как мы отключимmetrics конечную точку:

management.endpoint.metrics.enabled=false

Доступ к отключенной конечной точке возвращает ошибку HTTP 404:

$ curl http://localhost:8080/actuator/metrics{"timestamp":"2021-04-24T12:55:40.688+00:00","status":404,"error":"Not Found","message":"","path":"/actuator/metrics"}

Мы можем предоставить доступ к конечным точкам через HTTP и / или JMX.Хотя обычно используется HTTP, для некоторых приложений может быть предпочтительнее JMX.

Мы можем раскрыть конечные точки, установивmanagement.endpoints.[web|jmx].exposure.include для списка идентификаторов конечных точек, которые мы хотим раскрыть.Вот как мы можем открытьmetrics конечную точку, например:

management.endpoints.web.exposure.include=metrics

Чтобы конечная точка была доступна, она должна быть включена и доступна.

Шаг 3. Защитите и настройте конечные точки

Поскольку многие из конечных точек содержат конфиденциальную информацию, важно защитить их.Конечные точки должны быть доступны только авторизованным пользователям, которые управляют нашим приложением и работают с ним в производственной среде, а не обычным пользователям нашего приложения.Представьте себе катастрофические последствия обычного пользователя приложения,имеющий доступ к конечным точкам heapdump или shutdown!

В этой статье мы не будем подробно рассматривать вопросы защиты конечных точек, поскольку мы в основном заинтересованы в использовании Spring Actuator для изучения приложения в нашей локальной среде разработки.Вы можете найти подробности в документацииздесь.

Краткое введение вjq

jq представляет собой JSON-процессор командной строки.Он работает как фильтр, принимая входные данные и производя выходные данные.Доступно множество встроенных фильтров, операторов и функций.Мы можем комбинировать фильтры, направлять выходной сигнал одного фильтра в другой и т. д.

Предположим, у нас в файле есть следующий JSONsample.json:

{  "students": [    {      "name": "John",      "age": 10,      "grade": 3,      "subjects": ["math", "english"]          },    {      "name": "Jack",      "age": 10,      "grade": 3,      "subjects": ["math", "social science", "painting"]    },    {      "name": "James",      "age": 11,      "grade": 5,      "subjects": ["math", "environmental science", "english"]    },    .... other student objects omitted ...  ]}

Это объект, содержащий массив объектов student с некоторыми деталями для каждого ученика.

Давайте рассмотрим несколько примеров обработки и преобразования этого JSON с помощьюjq.

$ cat sample.json | jq '.students[] | .name'"John""Jack""James"

Рассмотримjq команду, чтобы понять, что происходит:

Теперь давайте составим список студентов, изучающих такие предметы, как экология, обществоведение и т. д.:

$ cat sample.json | jq '.students[] | select(.subjects[] | contains("science"))'{  "name": "Jack",  "age": 10,  "grade": 3,  "subjects": [    "math",    "social science",    "painting"  ]}{  "name": "James",  "age": 11,  "grade": 5,  "subjects": [    "math",    "environmental science",    "english"  ]}

Рассмотримкоманду еще раз:

С одним небольшим изменением мы можем снова собрать эти элементы в массив:

$ cat sample.json | jq '[.students[] | select(.subjects[] | contains("science"))]'[  {    "name": "Jack",    "age": 10,    "grade": 3,    "subjects": [      "math",      "social science",      "painting"    ]  },  {    "name": "James",    "age": 11,    "grade": 5,    "subjects": [      "math",      "environmental science",      "english"    ]  }]

Все, что нам нужно было сделать, это заключить все выражение в квадратные скобки.

Мы можем использоватьjq как для фильтрации, так и для изменения формы JSON:

$ cat sample.json | jq '[.students[] | {"studentName": .name, "favoriteSubject": .subjects[0]}]'[  {    "studentName": "John",    "favoriteSubject": "math"  },  {    "studentName": "Jack",    "favoriteSubject": "math"  },  {    "studentName": "James",    "favoriteSubject": "math"  }]

Мы, выполнив итерацию по массивуstudents, создали новый объект,содержащий свойствоstudentName иfavoriteSubject со значениями устанавленными из атрибутаname и первогоsubject из исходногообъекта student .В результате мы собрали все новые объекты в массив.

Мы можем многое сделать с помощью нескольких командjq.Поскольку большинство API-интерфейсов, с которыми мы обычно работаем, используют JSON, это отличный инструмент в нашем арсенале инструментов.

Ознакомьтесь сучебникомируководствомиз официальной документации.jqplay- отличный ресурс дляэкспериментови построения нашихjq выражений.

Изучение приложения Spring Boot

В оставшейся части этой статьи мы будем использовать Actuator для изучения работающего приложения Spring Boot.Само приложение представляет собой очень упрощенный пример приложения для обработки заказов электронной коммерции.В нем есть только скелетный код, необходимый для иллюстрации идей.

Хотя доступно множество конечных точек Actuator, мы сосредоточимся только на тех, которые помогают нам понять структуру приложения во время выполнения.

се конечные точки, которые мы увидим, включены по умолчанию. Давйте откроем их:

management.endpoints.web.exposure.include=mappings,beans,startup,env,scheduledtasks,caches,metrics

Использование конечной точки отображения

Проверка доступных API-интерфейсов обычно является хорошим местом для начала знакомства с сервисом. Конечная точка отображения предоставляет все маршруты и обработчики, а также дополнительные сведения.

Давайте перейдем на конечную точку с помощью команды curl и направим ответ в jq, чтобы красиво его распечатать:

$ curl http://localhost:8080/actuator/mappings | jq

Вот ответ:

{  "contexts": {    "application": {      "mappings": {        "dispatcherServlets": {          "dispatcherServlet": [            {              "handler": "Actuator web endpoint 'metrics'",              "predicate": "{GET [/actuator/metrics], produces [application/vnd.spring-boot.actuator.v3+json || application/vnd.spring-boot.actuator.v2+json || application/json]}",              "details": {                "handlerMethod": {                  "className": "org.springframework.boot.actuate.endpoint.web.servlet.AbstractWebMvcEndpointHandlerMapping.OperationHandler",                  "name": "handle",                  "descriptor": "(Ljavax/servlet/http/HttpServletRequest;Ljava/util/Map;)Ljava/lang/Object;"                },                "requestMappingConditions": {                  ... properties omitted ...                  ],                  "params": [],                  "patterns": [                    "/actuator/metrics"                  ],                  "produces": [                    ... properties omitted ...                  ]                }              }            },          ... 20+ more handlers omitted ...          ]        },        "servletFilters": [          {            "servletNameMappings": [],            "urlPatternMappings": [              "/*"            ],            "name": "webMvcMetricsFilter",            "className": "org.springframework.boot.actuate.metrics.web.servlet.WebMvcMetricsFilter"          },          ... other filters omitted ...        ],        "servlets": [          {            "mappings": [              "/"            ],            "name": "dispatcherServlet",            "className": "org.springframework.web.servlet.DispatcherServlet"          }        ]      },      "parentId": null    }  }}

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

jq для дальнейшей фильтрации этой информации. Поскольку мы знаем имена пакетов из нашей службы, jq будет выбирать только те обработчики, которые содержат имя нашего пакета io.reflectoring.springboot.actuator:

Давайте воспользуемся jq для дальнейшей фильтрации этой информации. Поскольку мы знаем имена пакетов из нашей службы, jqselectбудет выбирать только те обработчики, которые содержат имя нашего пакета io.reflectoring.springboot.actuator:

$ curl http://localhost:8080/actuator/mappings | jq '.contexts.application.mappings.dispatcherServlets.dispatcherServlet[] | select(.handler | contains("io.reflectoring.springboot.actuator"))'{  "handler": "io.reflectoring.springboot.actuator.controllers.PaymentController#processPayments(String, PaymentRequest)",  "predicate": "{POST [/{orderId}/payment]}",  "details": {    "handlerMethod": {      "className": "io.reflectoring.springboot.actuator.controllers.PaymentController",      "name": "processPayments",      "descriptor": "(Ljava/lang/String;Lio/reflectoring/springboot/actuator/model/PaymentRequest;)Lio/reflectoring/springboot/actuator/model/PaymentResponse;"    },    "requestMappingConditions": {      "consumes": [],      "headers": [],      "methods": [        "POST"      ],      "params": [],      "patterns": [        "/{orderId}/payment"      ],      "produces": []    }  }}{  "handler": "io.reflectoring.springboot.actuator.controllers.OrderController#getOrders(String)",  "predicate": "{GET [/{customerId}/orders]}",  "details": {    "handlerMethod": {      "className": "io.reflectoring.springboot.actuator.controllers.OrderController",      "name": "getOrders",      "descriptor": "(Ljava/lang/String;)Ljava/util/List;"    },    "requestMappingConditions": {      "consumes": [],      "headers": [],      "methods": [        "GET"      ],      "params": [],      "patterns": [        "/{customerId}/orders"      ],      "produces": []    }  }}{  "handler": "io.reflectoring.springboot.actuator.controllers.OrderController#placeOrder(String, Order)",  "predicate": "{POST [/{customerId}/orders]}",  "details": {    "handlerMethod": {      "className": "io.reflectoring.springboot.actuator.controllers.OrderController",      "name": "placeOrder",      "descriptor": "(Ljava/lang/String;Lio/reflectoring/springboot/actuator/model/Order;)Lio/reflectoring/springboot/actuator/model/OrderCreatedResponse;"    },    "requestMappingConditions": {      "consumes": [],      "headers": [],      "methods": [        "POST"      ],      "params": [],      "patterns": [        "/{customerId}/orders"      ],      "produces": []    }  }}

Мы можем видеть доступные API-интерфейсы и подробную информацию об HTTP методе, пути запроса и т. д. В сложном реальном приложении это дало бы консолидированное представление обо всех API-интерфейсах и их деталях, независимо от того, как пакеты были организованы в несколько -модуль кодовая база.Это полезный метод для начала изучения приложения, особенно при работе с многомодульной устаревшей кодовой базой, где даже документация Swagger может быть недоступна.

Точно так же мы можем проверить, через какие фильтры проходят наши запросы, прежде чем они достигнут контроллеров:

$ curl http://localhost:8080/actuator/mappings | jq '.contexts.application.mappings.servletFilters'[  {    "servletNameMappings": [],    "urlPatternMappings": [      "/*"    ],    "name": "webMvcMetricsFilter",    "className": "org.springframework.boot.actuate.metrics.web.servlet.WebMvcMetricsFilter"  },  ... other filters omitted ...]

Использование конечной точкиbeans

Теперь давайте посмотрим на список созданных bean-компонентов:

$ curl http://localhost:8080/actuator/beans | jq{  "contexts": {    "application": {      "beans": {        "endpointCachingOperationInvokerAdvisor": {          "aliases": [],          "scope": "singleton",          "type": "org.springframework.boot.actuate.endpoint.invoker.cache.CachingOperationInvokerAdvisor",          "resource": "class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/EndpointAutoConfiguration.class]",          "dependencies": [            "org.springframework.boot.actuate.autoconfigure.endpoint.EndpointAutoConfiguration",            "environment"          ]        },               .... other beans omitted ...    }  }}

Это дает общее представление обо всех компонентах вApplicationContext. Промотр его дает нам некоторое представление о структуре приложения во время выполнения - какие внутренние bean-компоненты Spring, каковы bean-компоненты приложения, каковы их области действия, каковы зависимости каждого bean-компонента и т. д.

Опять же, мы можем использоватьjq для фильтрации ответов и сосредоточиться на тех частях ответа, которые нам интересны:

$ curl http://localhost:8080/actuator/beans | jq '.contexts.application.beans | with_entries(select(.value.type | contains("io.reflectoring.springboot.actuator")))'{  "orderController": {    "aliases": [],    "scope": "singleton",    "type": "io.reflectoring.springboot.actuator.controllers.OrderController",    "resource": "file [/code-examples/spring-boot/spring-boot-actuator/target/classes/io/reflectoring/springboot/actuator/controllers/OrderController.class]",    "dependencies": [      "orderService",      "simpleMeterRegistry"    ]  },  "orderService": {    "aliases": [],    "scope": "singleton",    "type": "io.reflectoring.springboot.actuator.services.OrderService",    "resource": "file [/code-examples/spring-boot/spring-boot-actuator/target/classes/io/reflectoring/springboot/actuator/services/OrderService.class]",    "dependencies": [      "orderRepository"    ]  },  ... other beans omitted ...  "cleanUpAbandonedBaskets": {    "aliases": [],    "scope": "singleton",    "type": "io.reflectoring.springboot.actuator.services.tasks.CleanUpAbandonedBaskets",    "resource": "file [/code-examples/spring-boot/spring-boot-actuator/target/classes/io/reflectoring/springboot/actuator/services/tasks/CleanUpAbandonedBaskets.class]",    "dependencies": []  }}

Это дает представление обо всех компонентах приложения и их зависимостях с высоты птичьего полета.

Чем это полезно?Мы можем получить дополнительную информацию из этого типа представления: например,если мы видим некоторую зависимость, повторяющуюся в нескольких bean-компонентах, вероятно, в нем инкапсулированы важные функции, которые влияют на несколько потоков.Мы могли бы отметить этот класс как важный, который мы хотели бы понять, когда углубимся в код.Или, возможно, этот bean-компонент является God object,который требует некоторого рефакторинга, когда мы поймем кодовую базу.

Использование конечной точкиstartup

В отличие от других конечных точек, которые мы видели, для настройки конечной точкиstartup требуются некоторые дополнительные действия.Мы должны обеспечить реализациюApplicationStartup для нашего приложения:

SpringApplication app = new SpringApplication(DemoApplication.class);app.setApplicationStartup(new BufferingApplicationStartup(2048));app.run(args);

Здесь мы установили для нашего приложенияApplicationStartup значение a,BufferingApplicationStartup которое является структурой в памяти, которая фиксирует события в сложном процессе запуска Spring.Внутренний буфер будет иметь указанную нами емкость - 2048.

Теперь перейдем конечной точкеstartup.В отличие от других конечных точек startup поддерживаетPOST метод:

$ curl -XPOST 'http://localhost:8080/actuator/startup' | jq{  "springBootVersion": "2.4.4",  "timeline": {    "startTime": "2021-04-24T12:58:06.947320Z",    "events": [      {        "startupStep": {          "name": "spring.boot.application.starting",          "id": 1,          "parentId": 0,          "tags": [            {              "key": "mainApplicationClass",              "value": "io.reflectoring.springboot.actuator.DemoApplication"            }          ]        },        "startTime": "2021-04-24T12:58:06.956665337Z",        "endTime": "2021-04-24T12:58:06.998894390Z",        "duration": "PT0.042229053S"      },      {        "startupStep": {          "name": "spring.boot.application.environment-prepared",          "id": 2,          "parentId": 0,          "tags": []        },        "startTime": "2021-04-24T12:58:07.114646769Z",        "endTime": "2021-04-24T12:58:07.324207009Z",        "duration": "PT0.20956024S"      },         .... other steps omitted ....      {        "startupStep": {          "name": "spring.boot.application.started",          "id": 277,          "parentId": 0,          "tags": []        },        "startTime": "2021-04-24T12:58:11.169267550Z",        "endTime": "2021-04-24T12:58:11.212604248Z",        "duration": "PT0.043336698S"      },      {        "startupStep": {          "name": "spring.boot.application.running",          "id": 278,          "parentId": 0,          "tags": []        },        "startTime": "2021-04-24T12:58:11.213585420Z",        "endTime": "2021-04-24T12:58:11.214002336Z",        "duration": "PT0.000416916S"      }    ]  }}

Ответ представляет собой массив с подробной информацией о событиях: name, startTime, endTimeиduration.

Как эта информация может помочь нам в исследовании приложения?Если мы знаем, какие шаги требуют больше времени при запуске, мы можем проверить эту область кодовой базы, чтобы понять, почему.Например, может случиться так, что, прогрев кэша выполняет предварительную выборку данных из базы данных или предварительное вычисление некоторых данных.

Поскольку приведенный выше ответ содержит много деталей, давайте сузим его, отфильтровав поspring.beans.instantiate шагу, а также отсортируем события по продолжительности в порядке убывания:

$ curl -XPOST 'http://localhost:8080/actuator/startup' | jq '.timeline.events | sort_by(.duration) | reverse[] | select(.startupStep.name | contains("instantiate"))'$ 

Что здесь произошло?Почему мы не получили ответа?Вызовконечной точки startup также очищает внутренний буфер.Повторим попытку после перезапуска приложения:

$ curl -XPOST 'http://localhost:8080/actuator/startup' | jq '[.timeline.events | sort_by(.duration) | reverse[] | select(.startupStep.name | contains("instantiate")) | {beanName: .startupStep.tags[0].value, duration: .duration}]' [  {    "beanName": "orderController",    "duration": "PT1.010878035S"  },  {    "beanName": "orderService",    "duration": "PT1.005529559S"  },  {    "beanName": "requestMappingHandlerAdapter",    "duration": "PT0.11549366S"  },  {    "beanName": "tomcatServletWebServerFactory",    "duration": "PT0.108340094S"  },  ... other beans omitted ...]

Таким образом, на созданиеbean-компонентовorderController иуходит больше секундыorderService!Это интересно - теперь у нас есть конкретная область приложения, на которой мы можем сосредоточиться, чтобы понять больше.

Командаjq здесь была немного сложнее по сравнению с предыдущими.Давайте разберемся, чтобы понять, что происходит:

jq '[.timeline.events \  | sort_by(.duration) \  | reverse[] \  | select(.startupStep.name \  | contains("instantiate")) \  | {beanName: .startupStep.tags[0].value, duration: .duration}]'

Скобки над всем выражением указывают на то, что мы хотим собрать все созданные объекты JSON в массив.

Использование конечной точкиenv

Конечная точка env дает обобщенное представление всех свойств конфигурации приложения.Сюда входят конфигурации изapplication.properties файла, системные свойства JVM, переменные среды и т. д.

Мы можем использовать конечную точкуenv, чтобы увидеть, есть ли в приложении конфигурации, установленные с помощью переменных окружения, какие файлы jar находятся в его пути к классам и т. д.:

$ curl http://localhost:8080/actuator/env | jq{  "activeProfiles": [],  "propertySources": [    {      "name": "server.ports",      "properties": {        "local.server.port": {          "value": 8080        }      }    },    {      "name": "servletContextInitParams",      "properties": {}    },    {      "name": "systemProperties",      "properties": {        "gopherProxySet": {          "value": "false"        },        "java.class.path": {          "value": "/target/test-classes:/target/classes:/Users/reflectoring/.m2/repository/org/springframework/boot/spring-boot-starter-actuator/2.4.4/spring-boot-starter-actuator-2.4.4.jar:/Users/reflectoring/.m2/repository/org/springframework/boot/spring-boot-starter/2.4.4/spring-boot-starter-2.4.4.jar: ... other jars omitted ... "        },       ... other properties omitted ...      }    },    {      "name": "systemEnvironment",      "properties": {        "USER": {          "value": "reflectoring",          "origin": "System Environment Property \"USER\""        },        "HOME": {          "value": "/Users/reflectoring",          "origin": "System Environment Property \"HOME\""        }        ... other environment variables omitted ...      }    },    {      "name": "Config resource 'class path resource [application.properties]' via location 'optional:classpath:/'",      "properties": {        "management.endpoint.logfile.enabled": {          "value": "true",          "origin": "class path resource [application.properties] - 2:37"        },        "management.endpoints.web.exposure.include": {          "value": "metrics,beans,mappings,startup,env, info,loggers",          "origin": "class path resource [application.properties] - 5:43"        }      }    }  ]}

Использование конечной точкиscheduledtasks

Эта конечная точка позволяет нам проверять, выполняет ли приложение какую-либо задачу периодически, используя@Scheduled аннотациюSpring:

$ curl http://localhost:8080/actuator/scheduledtasks | jq{  "cron": [    {      "runnable": {        "target": "io.reflectoring.springboot.actuator.services.tasks.ReportGenerator.generateReports"      },      "expression": "0 0 12 * * *"    }  ],  "fixedDelay": [    {      "runnable": {        "target": "io.reflectoring.springboot.actuator.services.tasks.CleanUpAbandonedBaskets.process"      },      "initialDelay": 0,      "interval": 900000    }  ],  "fixedRate": [],  "custom": []}

Из ответа мы видим, что приложение генерирует некоторые отчеты каждый день в 12 часов дня и что существует фоновый процесс, который выполняет некоторую очистку каждые 15 минут.Затем мы могли бы прочитать код этих конкретных классов, если бы мы хотели знать, что это за отчеты, какие шаги необходимо предпринять для очистки брошенной корзины и т. д.

Использование конечной точкиcaches

Эта конечная точка перечисляет все кэши приложений:

$ curl http://localhost:8080/actuator/caches | jq{  "cacheManagers": {    "cacheManager": {      "caches": {        "states": {          "target": "java.util.concurrent.ConcurrentHashMap"        },        "shippingPrice": {          "target": "java.util.concurrent.ConcurrentHashMap"        }      }    }  }}

Мы можем сказать,что приложение кэширует некоторые данные: states и shippingPrice. Это дает нам еще одну область приложения, которую нужно изучить и узнать больше: как создаются кеши, когда удаляются записи кеша и т. д.

Использование конечной точкиhealth

Конечная точка health показывает информацию оздоровье приложения:

$ curl http://localhost:8080/actuator/health{"status":"UP"}

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

Многие приложения также реализуютглубокие проверки работоспособности, которые могут помочь нам быстро узнать, каковы внешние зависимости приложения, к каким базам данных и брокерам сообщений оно подключается и т. д.

Прочтитеэтустатьюна Reflectoring,чтобы узнать больше о реализации проверок работоспособности с помощью Actuator.

Использование конечной точкиmetrics

Эта конечная точка перечисляет все метрики, сгенерированные приложением:

$ curl http://localhost:8080/actuator/metrics | jq{  "names": [    "http.server.requests",    "jvm.buffer.count",    "jvm.buffer.memory.used",    "jvm.buffer.total.capacity",    "jvm.threads.states",    "logback.events",    "orders.placed.counter",    "process.cpu.usage",    ... other metrics omitted ...  ]}

Затем мы можем получить данные отдельных показателей:

$ curl http://localhost:8080/actuator/metrics/jvm.memory.used | jq{  "name": "jvm.memory.used",  "description": "The amount of used memory",  "baseUnit": "bytes",  "measurements": [    {      "statistic": "VALUE",      "value": 148044128    }  ],  "availableTags": [    {      "tag": "area",      "values": [        "heap",        "nonheap"      ]    },    {      "tag": "id",      "values": [        "CodeHeap 'profiled nmethods'",        "G1 Old Gen",                ... other tags omitted ...      ]    }  ]}

Особенно полезна проверка доступных пользовательских метрик API.Это может дать нам некоторое представление о том, что важно в этом приложении с точки зрения бизнеса.Например, из списка показателей мы можем видеть, что есть индикатор, orders.placed.counter который, вероятно, сообщает нам, сколько заказов было размещено за определенный период времени.

Заключение

В этой статье мы узнали, как использовать Spring Actuator в нашей локальной среде разработки для изучения нового приложения.Мы рассмотрели несколько конечных точек исполнительных механизмов, которые могут помочь нам определить важные области кодовой базы, которые могут потребовать более глубокого изучения.Попутно мы также узнали, как обрабатывать JSON в командной строке, используя легкий и чрезвычайно мощный инструментjq.

Вы можете поиграть с полным приложением, иллюстрирующим эти идеи, используя кодна GitHub.