Applying Axon Framework and Spring StateMachine in iQIYI Contract Platform: Architecture, Practices, and Lessons

In 2004 Eric Evans introduced Domain‑Driven Design (DDD), which has become a cornerstone for building complex business systems. With the rise of micro‑services, Event Sourcing (ES) and Command‑Query Responsibility Segregation (CQRS) have also gained popularity, but they bring challenges such as massive event volumes and the need for state reconstruction.

To address these issues, Allard Buijze released the Axon Framework in 2009, which integrates DDD, ES, and CQRS into a single solution. iQIYI’s “iQIYI‑号” team adopted Axon during their micro‑service migration and applied it to several services.

Technical selection : After evaluating frameworks such as Cola, Axon, Activiti, and Spring StateMachine, the team chose a combination of Axon and Spring StateMachine because Axon offers built‑in event replay and comprehensive documentation, while StateMachine provides lightweight workflow flexibility.

Axon framework overview : Axon follows DDD, CQRS, and Event‑Driven Architecture principles, enabling robust, adaptable applications. Its typical architecture includes a command side, an event store, and query projections.

Spring StateMachine overview : This library brings hierarchical state‑machine capabilities to the Spring ecosystem, supporting states, transitions, actions, guards, and distributed deployment via Zookeeper.

Project introduction : The iQIYI‑号 contract platform manages a complex signing workflow with more than 20 states, heavy third‑party integration, and strict data‑consistency requirements. The initial version used Activiti, which proved cumbersome for workflow evolution. The upgraded version (2.0) adopts Axon + Spring StateMachine, resulting in a lighter‑weight workflow engine.

Architecture layers :

User‑interface layer – MQ, UI, and API endpoints for user requests, approvals, and third‑party notifications.

Application layer – validates inputs and translates them into Axon Commands.

Domain layer – receives domain events, converts them to StateMachine events, and drives state transitions.

Infrastructure layer – provides storage, third‑party services, etc.

Advantages :

Development: promotes object‑oriented thinking, separates command handling from query handling, and improves developer productivity.

Operations: event sourcing enables full traceability and snapshotting mitigates event‑load issues; CQRS supports high‑throughput scenarios.

Maintenance: clear code layers and event‑driven extensibility simplify future enhancements.

Challenges :

Distributed transaction consistency – implementing sagas and compensation logic is complex.

Limited batch processing capabilities.

Integration with Spring Cloud and lack of comprehensive Chinese documentation.

Axon’s rich domain model can be overkill for simple use cases.

Future plans : Starting from version 4.0, Axon evolves into a platform comprising Axon Framework and Axon Server. The project currently uses Axon 3.0.4 (single‑node). Future work includes deeper exploration of Axon Server, Spring Cloud integration, distributed commands/events, and advanced saga patterns.