Заводим Spring StateMachine03.08.2019 22:49

Вступление


В проектах я встречался с тремя примерами, так или иначе связанными с теорией конечных автоматов

  • Пример 1. Занимательный говнокод код. Занимает уйму времени, на то чтоб понять что происходит. Характерной особенностью воплощения обозначенной теории в коде является довольно лютая свалка, которая местами дико напоминает процедурный код. О том что этот вариант кода лучше не трогать на проекте знает каждый технолог, методолог и продуктолог. Заходят в этот код что-то поправить в случае крайней нужды (когда совсем сломалось), о доработке каких либо фичей речи не идет. Ибо сломать страшно. Второй яркой особенностью, обосабливающий данный тип является наличие могучих таких switch, на весь экран. На этот счет даже есть шутеечка:
    Оптимальный размер

    На каком то из JPoint, один из спикеров, возможно Николай Алименков рассказывал о том, сколько кейсов в switch норма, сказал что топ-ответ «пока влазит в экран». Соответственно если влазить перестало и ваш switch уже как бы не норм, берете и уменьшаете размер шрифта

  • Пример 2. Pattern State. Основная идея (для тех кто не любит переходить по ссылкам) заключается в том, что некую бизнес-задачу, мы разбиваем на набор конечных состояний и описываем их кодом.
    Основной недостаток Pattern State заключается в том, что состояния знают друг про друга, знают что есть братья и вызывают друг друга. Такой код довольно сложно сделать универсальным. Например при реализации платежной системы с несколькими типами платежей вы рискуете настолько закопаться в Generic-s, что декларация ваших методов может стать примерно такой: 
    private <
      T extends BaseContextPayment,
      Q extends BaseDomainPaymentRequest,
      S,
      B extends AbstractPaymentDetailBuilder,
      F extends AbstractPaymentBuilder
      > PaymentContext build(final Q request, final Class factoryClass){
//"несложная" реализация
}

    Резюмируя по State: реализация может вылиться в довольно непростой код.
  • Пример 3 StateMachine Основная идея Pattern-а в том что состояния ничего не знают друг о друге, управление переходами осуществляет контекст, уже лучше, меньше связанности — проще код.


Прочувствовав всю «мощь» первого типа и всю сложность второго мы решили использовать Pattern StateMachine, для нового бизнес-кейса.
Чтобы не изобретать свой велосипед, за основу было решено взять Statemachine Spring-а (это-ж Spring).
После прочтения доки я пошел на Ютуб и Хабр (чтоб понять как с этим работают люди, как это чувствует себя на проде, какие грабли и т.д.) Выяснилось что информации немного, на Ютубе — пара-тройка видео, все довольно поверхностные. На Хабре по данной теме я нашел всего одну статью, так же как и видео, довольно поверхностную.
В одной статье не получится описать все тонкости работы Spring statemachine, пройтись по всей доке и описать все кейсы, но я постараюсь рассказать самое важное и востребованное, ну и про грабельки, конкретно мне, при знакомстве с farmework-ом информация, изложенная ниже, была бы очень полезна.

Основная часть


Создадим Spring Boot приложение добавим стартер Web (получаем как можно быстрее работающее web-приложение).Приложение будет абстракцией на процесс покупки. Продукт при покупке будет проходить стадии new, reserved, reserved decline и purchase complete.
Небольшая импровизация, в реальном проекте статусов было бы больше, ну да ладно, у нас тоже вполне реальный проект.
В pom.xml вновьиспеченного web-приложения добавим зависимость на машину и на тесты для нее (Web Starter уже должен быть, если собирали через start.spring.io): 


    org.springframework.statemachine
    spring-statemachine-core
    2.1.3.RELEASE


    org.springframework.statemachine
    spring-statemachine-test
    2.1.3.RELEASE
    test


Создадим структуру:
u8nwoqaezenqp1pouozil4qjwno.png
Пока не надо особо вдаваться в подробности этой структуры, все буду пояснять последовательно, а на исходники в конце статьи будет ссылка.

Итак, поехали.
У нас есть чистый проект с нужными зависимостями, для начала создадим enum, с states и events, довольно простая абстракция, сами по себе эти компоненты не несут никакой логики.

public enum PurchaseEvent {
   RESERVE, BUY, RESERVE_DECLINE
}
public enum PurchaseState {
    NEW, RESERVED, CANCEL_RESERVED, PURCHASE_COMPLETE
}


Хотя формально, можно добавить в эти enum поля, и захардкодить в них что-нибудь, свойственное например, конкретному state, что довольно логично (мы так и поступили решая свой кейс, довольно удобно).
Конфигурить машину будем через java-конфиг, создадим конфиг-файл и за-extends-им класс EnumStateMachineConfigurerAdapter. Так как наши state и event есть enum, то и интерфейс соответствующий, но это не обязательно, может быть использован совершенно любой тип объекта в качестве generic-ов (не рассматриваем другие примеры в статье, так как EnumStateMachineConfigurerAdapter на мой взгляд более чем достаточно).

Следующий важный момент одна ли машина будет жить в контексте приложения: в единственном экземпляре @EnableStateMachine, или каждый раз будет создаваться новая @EnableStateMachineFactory. Если это многопользовательское веб-приложение, с кучей пользователей, то едва ли первый вариант вам подойдет, поэтому мы будем использовать второй, как более популярный. StateMachine так же может быть создана через builder как обычный bean (см.документацию), что бывает удобно в отдельных случаях (например вам нужно чтобы машина обязательно была явно объявлена как bean), и если это отдельный бин, то мы можем указать ему свой scope, например session или request. В нашем проекте, над бином statemachine был реализован wrapper (особенности нашей бизнес-логики), wrapper был singleton, а сама машина prototype

Грабли

Как реализовать prototype в singlton-е?
По сути все что требуется сделать это получать каждый раз при обращении к объекту новый bean из applicationContext. Inject-ать applicationContext в бизнес-логику грех, поэтому bean statemachine должен либо реализовывать интерфейс с хотя бы одним методом, либо абстрактный метод, который при создании в java — конфиге должен будет быть реализован, а для реализации мы запросим у applicationContext новый bean. Иметь в config классе ссылку на applicationContext нормальная практика, и через абстрактный метод мы будет вызвать из контекста .getBean ();


У класса EnumStateMachineConfigurerAdapter есть несколько методов, переопределяя которые мы настраиваем машинку.
Для начала зарегистрируем статусы: 

    @Override
    public void configure(final StateMachineStateConfigurer states) throws Exception {
        states
                .withStates()
                .initial(NEW)
                .end(PURCHASE_COMPLETE)
                .states(EnumSet.allOf(PurchaseState.class));

    }


initial (NEW) — это статус в котором будет находиться машина после создания bean-а, end (PURCHASE_COMPLETE) — статус зайдя в который машина выполнит statemachine.stop (), для недетерминированной машины (коих большинство) неактуально, но что-то указать надо. .states (EnumSet.allOf (PurchaseState.class) список всех статусов, можно пихать скопом.

Сконфигурим глобальный настройки машины

    @Override
    public void configure(final StateMachineConfigurationConfigurer config) throws Exception {
        config
                .withConfiguration()
                .autoStartup(true)
                .listener(new PurchaseStateMachineApplicationListener());
    }


Здесь autoStartup определяет будет ли запущена машина сразу после создания по-умолчанию, иными словами — перейдет ли она автоматически в статус NEW (по умолчанию false). Тут же мы регистрируем listener для контекста машины (о нем чуть позже), в этом же конфиге можно задать отдельный TaskExecutor, что удобно тогда, когда на каком-то их переходов выполняется долгий Action, а приложение должно идти дальше.
Ну и сами переходы: 

    @Override
    public void configure(final StateMachineTransitionConfigurer transitions) throws Exception {
        transitions
                .withExternal()
                .source(NEW)
                .target(RESERVED)
                .event(RESERVE)
                .action(reservedAction(), errorAction())

                .and()
                .withExternal()
                .source(RESERVED)
                .target(CANCEL_RESERVED)
                .event(RESERVE_DECLINE)
                .action(cancelAction(), errorAction())

                .and()
                .withExternal()
                .source(RESERVED)
                .target(PURCHASE_COMPLETE)
                .event(BUY)
                .guard(hideGuard())
                .action(buyAction(), errorAction());
    }


Вся логика переходов или transitions задается тут, на переходы можно навешивать Guard, компонент который всегда возвращает boolean, что именно вы будете проверять на переходе из одного статуса в другой на ваше усмотрение, в Guard-е может быть совершенна любая логика, это совершенно обычный компонент, но вернуть он должен boolean. В рамках нашего проекта, например, HideGuard может проверять некую настройку, которую мог выставить пользователь (не показывать данный товар)и в соответствии с ней не пропускать машину в state защищенный Guard-ом. Отмечу что Guard на один переход в конфиге может быть добавлен только один, вот такая конструкция не сработает: 

   .withExternal()
                .source(RESERVED)
                .target(PURCHASE_COMPLETE)
                .event(BUY)
                .guard(hideGuard())
                .guard(veryHideGuard())


Точнее сработает, но только первый guard (hideGuard ())
А вот Action можно добавлять несколько (сейчас речь об Action, которые мы прописываем в конфигурации transitions), лично я пробовал добавлять три Action на один переход.

                .withExternal()
                .source(NEW)
                .target(RESERVED)
                .event(RESERVE)
                .action(reservedAction(), errorAction())


вторым аргументом идет ErrorAction, управление попадет к нему в случае если ReservedAction бросит исключение (throw е).

Грабли

Имейте в виду, что если в вашем Action, вы все-таки обработаете ошибку, через try/catch, то в ErrorAction вы уже не зайдете, если надо и обработать и зайти-таки в ErrorAction то следет бросить из catch RuntimeException (), например (вы же сами сказали что очень надо).


Помимо «навешивания» Action в transitions можно также «навешивать» их в методе configure для state, примерно в таком виде: 

    @Override
    public void configure(final StateMachineStateConfigurer states) throws Exception {
        states
                .withStates()
                .initial(NEW)
                .end(PURCHASE_COMPLETE)
                .stateEntry()
                .stateExit()
                .state()
                .states(EnumSet.allOf(PurchaseState.class));

    }


Все в зависимости от того как именно вы хотите запускать action

Грабли
Учтите, что если вы укажете action при конфигурировании state (), например так
        states
                .withStates()
                .initial(NEW)
                .end(PURCHASE_COMPLETE)
                .state(randomAction())

он будет выполняться асинхронно, предполагается что если вы например говорите .stateEntry (), то Action должен быть выполнен непосредственно при входе, но если вы говорите .state () значит Action должен быть выполнен в целевом state, но не так важно когда именно.
В нашем проекте мы сконфигурировали все Action на transition конфиге, благо навешивать их можно по нескольку на один переход.


Окончательная версия конфига будет выглядеть так: 

@Configuration
@EnableStateMachineFactory
public class StateMachineConfig extends EnumStateMachineConfigurerAdapter {

    @Override
    public void configure(final StateMachineConfigurationConfigurer config) throws Exception {
        config
                .withConfiguration()
                .autoStartup(true)
                .listener(new PurchaseStateMachineApplicationListener());
    }

    @Override
    public void configure(final StateMachineStateConfigurer states) throws Exception {
        states
                .withStates()
                .initial(NEW)
                .end(PURCHASE_COMPLETE)
                .stateEntry()
                .stateExit()
                .state()
                .states(EnumSet.allOf(PurchaseState.class));

    }

    @Override
    public void configure(final StateMachineTransitionConfigurer transitions) throws Exception {
        transitions
                .withExternal()
                .source(NEW)
                .target(RESERVED)
                .event(RESERVE)
                .action(reservedAction(), errorAction())

                .and()
                .withExternal()
                .source(RESERVED)
                .target(CANCEL_RESERVED)
                .event(RESERVE_DECLINE)
                .action(cancelAction(), errorAction())

                .and()
                .withExternal()
                .source(RESERVED)
                .target(PURCHASE_COMPLETE)
                .event(BUY)
                .guard(hideGuard())
                .action(buyAction(), errorAction());
    }

    @Bean
    public Action reservedAction() {
        return new ReservedAction();
    }

    @Bean
    public Action cancelAction() {
        return new CancelAction();
    }

    @Bean
    public Action buyAction() {
        return new BuyAction();
    }

    @Bean
    public Action errorAction() {
        return new ErrorAction();
    }

    @Bean
    public Guard hideGuard() {
        return new HideGuard();
    }

    @Bean
    public StateMachinePersister persister() {
        return new DefaultStateMachinePersister<>(new PurchaseStateMachinePersister());
    }


Сделаем контроллер: 

@RestController
@SuppressWarnings("unused")
public class PurchaseController {

    private final PurchaseService purchaseService;

    public PurchaseController(PurchaseService purchaseService) {
        this.purchaseService = purchaseService;
    }

    @RequestMapping(path = "/reserve")
    public boolean reserve(final String userId, final String productId) {
        return purchaseService.reserved(userId, productId);
    }

    @RequestMapping(path = "/cancel")
    public boolean cancelReserve(final String userId) {
        return purchaseService.cancelReserve(userId);
    }

    @RequestMapping(path = "/buy")
    public boolean buyReserve(final String userId) {
        return purchaseService.buy(userId);
    }

}



интерфейс сервиса

public interface PurchaseService {
    /**
     * Резервирование товара перед покупкой, зарезервированный товар может находиться в корзине сколько угодно долго
     *
     * @param userId    id пользователя, так как приложение простое, для того чтоб различать пользователей id будем
     *                  принимать прямо в http-запросе
     * @param productId id продукта, который начинает процедуру покупки
     * @return успешная/не успешная операция, в нашем примере операция может стать не успешной если при попытке восстановить
     * машину их импровизированного репозитория произойдет ошибка.
     */
    boolean reserved(String userId, String productId);

    /**
     * Отмена резервирования товара/удаление из пользовательской корзины
     *
     * @param userId id пользователя, так как приложение простое, для того чтоб различать пользователей id будем
     *               принимать прямо в http-запросе
     * @return успешная/не успешная операция, в нашем примере операция может стать не успешной если при попытке восстановить
     * машину их импровизированного репозитория произойдет ошибка.
     */
    boolean cancelReserve(String userId);

    /**
     * Покупка ранее зарезервированного товара
     *
     * @param userId id пользователя, так как приложение простое, для того чтоб различать пользователей id будем
     *               принимать прямо в http-запросе
     * @return успешная/не успешная операция, в нашем примере операция может стать не успешной если при попытке восстановить
     * машину их импровизированного репозитория произойдет ошибка.
     */
    boolean buy(String userId);
}


Грабли

А вы знаете, почему работая со Spring важно создавать bean через интерфейс? Столкнулись с этой проблемой (ну да-да и Женя Борисов рассказывал в потрошителе), когда однажды в контроллере попытались за-implement-ить самодельный не пустой интерфейс. Spring создает прокси на компоненты, и если компонент не реализует ни один интерфейс, то он сделает это через CGLIB, но как только вы реализуете какой-то интерфейс — Spring попытается создать прокси через dynamic-прокси, в результате вы получите непонятный тип объекта и NoSuchBeanDefinitionException.


Следующий важный момент, это то как вы будете восстанавливать состояние своей машины, ведь на каждое обращение будет создан новый bean, который ничего про ваши предыдущие статусы машины и ее контекст не знает.
Для этих целей в spring statemachine есть механизм Persistens: 

public class PurchaseStateMachinePersister implements StateMachinePersist {

    private final HashMap> contexts = new HashMap<>();

    @Override
    public void write(final StateMachineContext context, String contextObj) {
        contexts.put(contextObj, context);
    }

    @Override
    public StateMachineContext read(final String contextObj) {
        return contexts.get(contextObj);
    }
}


Для нашей наивной реализации мы используем в качестве хранилища состояний обычную Map, в ненаивной реализации это будет какая-то БД, обратите внимание на третий generic типа String, это ключ по которому будет сохраняться состояние вашей машины, со всеми статусами, переменными в контексте, id и тд. В своей примере я использовал id пользователя для ключа сохранения, что может быть указан совершенно любой ключ (session_id пользователя, уникальный логин и т.д.).

Грабли
В нашем проекте механизм сохранения и восстановления состояний из коробки нам не подошел, так как статусы машины мы хранили в БД и их мог менять job, который ничего не знал о машине.
Пришлось завязываться на статус полученный из БД, делать некий InitAction который при старте машины получал статус из БД, и выставлял его принудительно, и только потом бросал event, пример кода который выполняет вышесказанное: 
stateMachine
                .getStateMachineAccessor()
                .doWithAllRegions(access -> {
                    access.resetStateMachine(new DefaultStateMachineContext<>({ResetState}, null, null, null, null));
                });
stateMachine.start();
stateMachine.sendEvent({NewEventFromResetState});


Реализацию сервиса рассмотрим в каждом методе: 

    @Override
    public boolean reserved(final String userId, final String productId) {
        final StateMachine stateMachine = stateMachineFactory.getStateMachine();
        stateMachine.getExtendedState().getVariables().put("PRODUCT_ID", productId);
        stateMachine.sendEvent(RESERVE);
        try {
            persister.persist(stateMachine, userId);
        } catch (final Exception e) {
            e.printStackTrace();
            return false;
        }
        return true;
    }


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

Оставшиеся два метода похожи: 

    @Override
    public boolean cancelReserve(final String userId) {
        final StateMachine stateMachine = stateMachineFactory.getStateMachine();
        try {
            persister.restore(stateMachine, userId);
            stateMachine.sendEvent(RESERVE_DECLINE);
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
        return true;
    }

    @Override
    public boolean buy(final String userId) {
        final StateMachine stateMachine = stateMachineFactory.getStateMachine();
        try {
            persister.restore(stateMachine, userId);
            stateMachine.sendEvent(BUY);
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
        return true;
    }


Здесь мы сначала восстанавливаем состояние машины для userId конкретного пользователя, а затем бросаем event, который соответствует методу api.
Заметьте, что productId в методе уже не фигурирует, мы добавили его в контекст машины и достанем после восстановления машины из ее бэкапа.
В реализации Action мы получим id продукта из контекста машины и выведем в лог сообщение, соответствующее переходу, для примера приведу код ReservedAction: 

public class ReservedAction implements Action {
    @Override
    public void execute(StateContext context) {
        final String productId = context.getExtendedState().get("PRODUCT_ID", String.class);
        System.out.println("Товар с номером " + productId + " зарезервирован.");
    }
}


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

public class PurchaseStateMachineApplicationListener implements StateMachineListener {
    @Override
    public void stateChanged(State from, State to) {
        if (from.getId() != null) {
            System.out.println("Переход из статуса " + from.getId() + " в статус " + to.getId());
        }
    }

    @Override
    public void stateEntered(State state) {

    }

    @Override
    public void stateExited(State state) {

    }

    @Override
    public void eventNotAccepted(Message event) {
        System.out.println("Евент не принят " + event);
    }

    @Override
    public void transition(Transition transition) {

    }

    @Override
    public void transitionStarted(Transition transition) {

    }

    @Override
    public void transitionEnded(Transition transition) {

    }

    @Override
    public void stateMachineStarted(StateMachine stateMachine) {
        System.out.println("Machine started");
    }

    @Override
    public void stateMachineStopped(StateMachine stateMachine) {

    }

    @Override
    public void stateMachineError(StateMachine stateMachine, Exception exception) {
    }

    @Override
    public void extendedStateChanged(Object key, Object value) {

    }

    @Override
    public void stateContext(StateContext stateContext) {

    }
}


Единственная проблема в том, что это интерфейс, а значит нужно все эти методы реализовать, но так как они вряд ли понадобятся вам все, часть из них будет висеть пустыми, на что coverage скажет что методы не покрыты тестами.
Тут в lisener-е мы можем навесить совершенно любые метрики, на совершенно разные события машины (Например не проходят платежи, машина часто уходит в какой-то статус PAYMENT_FAIL, слушаем переходы, и если машина зашла в ошибочный статус — пишем, в одтельный лог, или базу или зовем милицию, как угодно).

Грабли

В lisener-e есть event stateMachineError, но он с нюансом, когда у вас случается исключение и вы обрабатываете его в catch, машина не считает что была ошибка, в catch нужно говорить явно
stateMachine.setStateMachineError (exception) и передавать ошибку.


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

  • 1. Резервирование и последующий отказ от покупки. Отправим приложению запрос на URI »/reserve», с параметрами userId=007, productId=10001, а следом за ним запрос »/cancel» c параметром userId=007 вывод консоли будет следующим:
    Machine started
    Товар с номером 10001 зарезервирован.
    Переход из статуса NEW в статус RESERVED
    Machine started
    Резервирование товара 10001 отменено
    Переход из статуса RESERVED в статус CANCEL_RESERVED
  • 2. Резервирование и успешная покупка:
    Machine started
    Товар с номером 10001 зарезервирован.
    Переход из статуса NEW в статус RESERVED
    Machine started
    Товар с номером 10001 успешно куплен
    Переход из статуса RESERVED в статус PURCHASE_COMPLETE


Заключение


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

   @Test
    public void testWhenReservedCancel() throws Exception {
        StateMachine machine = factory.getStateMachine();
        StateMachineTestPlan plan =
                StateMachineTestPlanBuilder.builder()
                        .defaultAwaitTime(2)
                        .stateMachine(machine)
                        .step()
                        .expectStates(NEW)
                        .expectStateChanged(0)
                        .and()
                        .step()
                        .sendEvent(RESERVE)
                        .expectState(RESERVED)
                        .expectStateChanged(1)
                        .and()
                        .step()
                        .sendEvent(RESERVE_DECLINE)
                        .expectState(CANCEL_RESERVED)
                        .expectStateChanged(1)
                        .and()
                        .build();
        plan.test();
    }

    @Test
    public void testWhenPurchaseComplete() throws Exception {
        StateMachine machine = factory.getStateMachine();
        StateMachineTestPlan plan =
                StateMachineTestPlanBuilder.builder()
                        .defaultAwaitTime(2)
                        .stateMachine(machine)
                        .step()
                        .expectStates(NEW)
                        .expectStateChanged(0)
                        .and()
                        .step()
                        .sendEvent(RESERVE)
                        .expectState(RESERVED)
                        .expectStateChanged(1)
                        .and()
                        .step()
                        .sendEvent(BUY)
                        .expectState(PURCHASE_COMPLETE)
                        .expectStateChanged(1)
                        .and()
                        .build();
        plan.test();
    }


Грабли

Если вам вдруг захочется протестировать вашу машину без поднятия контекста, обычными unit-тестами, то можно создать машину через builder (частично рассматривалоcь выше), создать экземпляр класса с конфигом и получить оттуда action и guard, будет работать и без контекста, можно написать небольшой тестовый фреймворк на mock-ах, в нем плюсом можно будет проверить какие Action вызывались, какие нет, сколько раз и тд, на разные кейсы.


P.S


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

Примечание


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

Ссылки


Дока
Исходники

© Habrahabr.ru