Создание нового микросервиса

Микросервисы в Citeck — самостоятельные приложения на базе Spring Boot, которые регистрируются в системе через Service Discovery и взаимодействуют с остальными компонентами платформы через Records API, Commands API и шину событий (RabbitMQ).

Создать собственный микросервис стоит, когда требуется:

  • реализовать изолированную бизнес-логику с отдельным жизненным циклом развёртывания;

  • подключить стороннюю библиотеку или внешнюю систему, не затрагивая основные сервисы;

  • масштабировать отдельный компонент независимо от остальной платформы.

Статья описывает два способа создания микросервиса: вручную через IDE и с помощью плагина для IntelliJ IDEA.

Примечание

Для создания микросервиса используется Spring Boot

Пример минимального проекта: Citeck/ecos-webapp-sample. Версии зависимостей примера следует согласовать с используемым выпуском платформы.

Создание микросервиса в интегрированной среде разработки

Настройка pom.xml

Для создания нового микросервиса Citeck нужно создать новый maven spring-boot проект и в pom.xml добавить в качестве родителя один из следующих pom файлов:

Артефакт

Описание

ru.citeck.ecos.webapp:ecos-webapp-spring-base-parent

Базовый родитель для spring-boot микросервисов, где требуется ручная настройка плагинов для сборки.
Этот проект является родительским для всех остальных в этой таблице.

ru.citeck.ecos.webapp:ecos-webapp-spring-hibernate-parent

Родитель для spring-boot микросервисов, в которых предполагается использование hibernate.
Настройка плагинов для сборки не требуется.

ru.citeck.ecos.webapp:ecos-webapp-spring-simple-parent

Родитель для spring-boot микросервисов без состояния или микросервисов, которые работают с БД через jdbc или ecos-data.

Версию родительского POM выбирайте в соответствии с используемым выпуском платформы и требованиями его библиотек. Например, на 10.11.2026 в ветках develop сервисов ecos-model и ecos-integrations используются версии hibernate-parent 3.39.0 и 3.38.5 соответственно, а в ecos-uiserv и ecos-notifications — 3.37.1. Это примеры используемых версий, а не указание последнего релиза для всех parent POM.

JDK и Maven должны соответствовать требованиям выбранного parent POM. В CI перечисленных ecos-model, ecos-integrations и ecos-notifications используется JDK 25. Требования предыдущих выпусков могут отличаться.

Родительские POM управляют версиями зависимостей Spring Boot и библиотек Citeck. Состав тестовых зависимостей и настройки сборки зависят от выбранного parent и его версии. Для загрузки зависимостей нужен доступ к настроенным Maven-репозиториям.

Пример структуры POM с simple-parent приведён ниже. В нём используется фиксированная версия 3.22.9; перед созданием проекта замените её совместимой версией simple-parent для вашего окружения. Наличие нужного выпуска проверяйте для выбранного артефакта: версии simple-parent и hibernate-parent нужно согласовать с их зависимостями.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>ru.citeck.ecos.webapp.sample</groupId>
    <artifactId>minimal-sample</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <parent>
        <groupId>ru.citeck.ecos.webapp</groupId>
        <artifactId>ecos-webapp-spring-simple-parent</artifactId>
        <version>3.22.9</version>
    </parent>

    <repositories>
        <repository>
            <id>citeck-public</id>
            <url>https://nexus.citeck.ru/repository/maven-public</url>
        </repository>
    </repositories>

</project>

Главный класс приложения

Следующим шагом нужно создать главный класс для запуска spring-boot приложения по следующему пути:

src/main/java/ru/citeck/ecos/webapp/sample/minimal/MinimalWebAppSample.java
  • ru/citeck/ecos/webapp/sample/minimal — java пакет для нашего приложения, который может быть произвольным;

  • MinimalWebAppSample.java — файл с основным классом для запуска приложения. Может быть произвольным. Есть поддержка как Kotlin так и Java файлов.

Содержимое основного класса:

package ru.citeck.ecos.webapp.sample.minimal;

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import ru.citeck.ecos.webapp.lib.spring.EcosSpringApplication;

@SpringBootApplication
@EnableDiscoveryClient
public class MinimalWebAppSample {

    public static final String NAME = "minimal-webapp";

    public static void main(String[] args) {
        new EcosSpringApplication(MinimalWebAppSample.class).run(args);
    }
}

где

  • public static final String NAME = "minimal-webapp"; — имя приложения (app name). Выберите отдельное имя для нового сервиса; экземпляры одного сервиса используют одинаковое имя. Оно применяется в нескольких механизмах платформы:

    • При использовании распределённого кэша Hazelcast одноимённые экземпляры сервиса объединяются согласно настройкам кэша;

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

    • Records API работает на базе этого имени. Имя приложения используется при поиске и указывается в sourceId до символа “/» (напр. emodel/person). Ссылки на сущности формируются с учетом имени приложения (напр. emodel/person@someuser);

    • Service discovery механизм работает на основе имени приложения.

  • EcosSpringApplication — наше расширение штатного SpringApplication. Для корректной работы микросервиса нужно использовать EcosSpringApplication.

Файл настроек

Создать файл с настройками по пути (опционально):

src/main/resources/config/application.yml

Содержимое файла:

---
server:
  port: 8686 # указываем порт, на котором будет развернут микросервис

В этом файле можно разместить настройки приложения. Пример задаёт только HTTP-порт. Для подключения к платформе настройте используемые сервисом Service Discovery, транспорт сообщений и источники данных согласно конфигурации окружения. Набор обязательных подключений зависит от функций сервиса и выбранного parent POM.

Логирование

Добавить файл для настройки логирования:

src/main/resources/logback-spring.xml

со следующим содержимым:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration>
<configuration>
    <include resource="ecos/logback-base.xml" />
</configuration>

Запуск

Перед запуском проверьте выбранный JDK, доступ к зависимостям и необходимым внешним сервисам. Для запуска микросервиса локально с parent, подключающим spring-boot-maven-plugin, используйте команду из корня проекта:

mvn spring-boot:run

Или стандартные механизмы IDE для запуска spring-boot приложений.

Тестирование

Создать файл с настройками логирования для тестов (опционально):

src/test/resources/logback-test.xml

с содержимым:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration>
<configuration>
    <include resource="ecos/logback-base.xml" />
</configuration>

Создать файл с настройками для автотестов (опционально):

src/test/resources/config/application-test.yml

В этом файле можно разместить настройки тестового профиля. Ресурсы из src/test/resources доступны тестам и не включаются в основной артефакт приложения. Файл application-test.yml загружается при активном профиле test; в примере ниже он включён явно через @ActiveProfiles("test").

Создать файл для тестирования микросервиса:

src/test/java/ru/citeck/ecos/webapp/sample/minimal/MinimalWebAppSampleTest.java

где

  • ru/citeck/ecos/webapp/sample/minimal — java пакет с тестами. Может быть любым, но крайне желательно размещать тесты в том же пакете или подпакетах, что и основной класс из раздела «Главный класс приложения»;

  • MinimalWebAppSampleTest.java — имя файла с тестами. Может быть любым.

Пример smoke-теста загрузки Spring-контекста и регистрации главного класса приложения:

package ru.citeck.ecos.webapp.sample.minimal;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.ApplicationContext;
import org.springframework.test.context.ActiveProfiles;
import ru.citeck.ecos.webapp.lib.spring.test.extension.EcosSpringExtension;

import static org.assertj.core.api.AssertionsForClassTypes.assertThat;

@ExtendWith(EcosSpringExtension.class)
@SpringBootTest(classes = { MinimalWebAppSample.class })
@ActiveProfiles("test")
public class MinimalWebAppSampleTest {

    @Autowired
    private ApplicationContext context;

    @Test
    public void contextLoads() {
        assertThat(context.getBean(MinimalWebAppSample.class)).isNotNull();
    }
}

где

  • EcosSpringExtension — расширение Citeck для интеграции с тестовым Spring-контекстом и тестовой инфраструктурой. Тип БД, mocks и необходимость контейнерного окружения зависят от версии библиотек и настроек. Например, тестовая инфраструктура WebApp поддерживает PostgreSQL в контейнере; наличие расширения само по себе не гарантирует использование in-memory БД;

  • MinimalWebAppSample.class — класс из раздела «Главный класс приложения».

Такой тест проверяет загрузку контекста. Проверки бизнес-логики и взаимодействия через Records API добавляйте отдельно для компонентов вашего сервиса.

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

mvn clean test

Сборка

Для сборки Docker-образа нужен доступный Docker daemon, JDK выбранного выпуска и доступ к зависимостям и базовому образу. Следующая команда рассчитана на parent с подключёнными jib-maven-plugin и ecos-webapp-maven-plugin. При использовании base-parent эти плагины и их выполнения в жизненном цикле Maven нужно настроить отдельно.

Из корня проекта выполните:

mvn clean package jib:dockerBuild -Djib.docker.image.tag=1.0.0-snapshot

Примечание

В стандартной конфигурации образа entrypoint использует следующие файлы:

  • /entrypoint.sh;

  • /app/jib-classpath-file;

  • /app/jib-main-class-file.

Подготовку скрипта запуска выполняет цель prepare-image плагина ecos-webapp-maven-plugin; Jib добавляет подготовленные файлы в образ и формирует файлы classpath и главного класса. В подключающем эти настройки parent они выполняются при стандартной сборке. Если конфигурация плагинов изменена, проверьте выполнение подготовки образа и соответствие путей его entrypoint.

В конфигурации parent, использующей ${project.artifactId}:${jib.docker.image.tag}, приведённая команда создаёт образ с тегом 1.0.0-snapshot в локальном Docker daemon.

Проверка версии в интерфейсе

В списке модулей системы UI использует поле label как ID и название модуля. Версия и дата сборки загружаются из info.version и info.buildDate источника build-info. Поле info.repo используется отдельно для сведений о репозиториях и коммитах; оно не является прямым источником столбца ID.

../../_images/system_modules.png

Метаданные сборки создаёт цель build-info плагина ecos-webapp-maven-plugin. При стандартной конфигурации ресурсы находятся по путям:

  • в проекте — target/classes/ecos/build-info.json;

  • в образе Jib со стандартной раскладкой приложения — /app/resources/ecos/build-info.json.

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

Создание микросервиса с использованием плагина для IntelliJ IDEA

Быстрее и удобнее создавать микросервис с использованием плагина для IntelliJ IDEA см. как.