Design and Implementation of a General‑Purpose Asynchronous Processing SDK for Spring Backend

Good system design must follow the open‑closed principle; as business evolves, core code changes, increasing error probability, while most new features extend existing functionality, requiring both performance and quality, often using asynchronous thread pools that add uncertainty. To address this, a generic asynchronous processing SDK is designed for easy implementation.

The purpose of the SDK is to ensure that methods execute reliably without affecting the main flow and to provide fallback mechanisms that achieve eventual consistency.

Advantages include a non‑intrusive design, independent database, scheduler, message queue, and manual execution UI with unified authentication; it uses Spring transaction event mechanisms so that even if the async strategy fails, business logic is unaffected. If a method runs within a transaction, the event is processed after commit or rollback, and fallback execution ensures processing even when the transaction succeeds but async parsing fails.

Principle: after the container finishes bean initialization, it scans all methods for the @AsyncExec annotation and caches them. At runtime, an AOP aspect publishes an event, and a @TransactionalEventListener(fallbackExecution=true, phase=TransactionPhase.AFTER_COMPLETION) handles the asynchronous execution.

Components: Kafka message queue, XXL‑Job scheduler, MySQL database, Spring AOP, Vue UI.

Asynchronous strategy configuration example:

async.enabled=true
spring.application.name=xxx
async.datasource.driver-class-name=com.mysql.jdbc.Driver
async.datasource.url=jdbc:mysql://127.0.0.1:3306/fc_async?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true
async.datasource.username=user
async.datasource.password=xxxx
async.datasource.filters=config
async.datasource.connectionProperties=config.decrypt=true;config.decrypt.key=yyy
async.executor.thread.corePoolSize=10
async.executor.thread.maxPoolSize=50
async.executor.thread.queueCapacity=10000
async.executor.thread.keepAliveSeconds=600
async.exec.deleted=true
async.topic=${spring.application.name}_async_queue
async.exec.count=5
async.retry.limit=100
async.comp.limit=100
async.login=false

Usage steps: enable the async switch, annotate methods that need asynchronous execution with @AsyncExec(type=AsyncExecEnum.SAVE_ASYNC, remark="data dictionary") , and provide a manual handling address such as http://localhost:8004/async/index.html .

Important notes: configure the application name, queue name prefix, retry count, execution deletion policy, and optional login interception.

GitHub repository: https://github.com/xiongyanokok/fc-async