Design and Implementation of a Generic Asynchronous Processing SDK for Java Backend Systems

Good system design must obey the open‑closed principle; as business iterates, core code changes frequently, increasing error probability. Most new features extend existing functionality, requiring both performance and quality, so asynchronous thread pools are often used despite adding uncertainty.

To address this, a generic asynchronous processing SDK was designed to enable easy implementation of various async tasks.

The SDK aims to ensure that asynchronous handling does not block the main flow while guaranteeing eventual consistency through fallback mechanisms that prevent data loss.

Key advantages include a non‑intrusive design, independent database, scheduler, message queue, and a unified manual execution UI with single sign‑on; it leverages Spring transaction events so that even if async strategy parsing fails, business logic remains unaffected. If a method runs within a transaction, the async event is processed after commit or rollback, and fallback mechanisms handle failures unless the database, queue, or method itself is faulty.

The core principle is that after container initialization, all beans are scanned and methods annotated with @AsyncExec are cached. At runtime, an AOP aspect publishes an event, and a transaction event listener processes the async execution strategy.

@TransactionalEventListener(fallbackExecution = true, phase = TransactionPhase.AFTER_COMPLETION)

fallbackExecution=true

– process the event even when no transaction is active. TransactionPhase.AFTER_COMPLETION – handle the event after transaction commit or rollback.

Components used by the SDK are:

Kafka message queue

XXL‑Job scheduler

MySQL database

Spring AOP

Vue front‑end

Design patterns applied include Strategy, Template Method, and Dynamic Proxy.

Database schema for async requests and logs is provided below.

CREATE TABLE `async_req` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `application_name` varchar(100) NOT NULL DEFAULT '' COMMENT '应用名称',
  `sign` varchar(50) NOT NULL DEFAULT '' COMMENT '方法签名',
  `class_name` varchar(200) NOT NULL DEFAULT '' COMMENT '全路径类名称',
  `method_name` varchar(100) NOT NULL DEFAULT '' COMMENT '方法名称',
  `async_type` varchar(50) NOT NULL DEFAULT '' COMMENT '异步策略类型',
  `exec_status` tinyint NOT NULL DEFAULT '0' COMMENT '执行状态 0：初始化 1：执行失败 2：执行成功',
  `exec_count` int NOT NULL DEFAULT '0' COMMENT '执行次数',
  `param_json` longtext COMMENT '请求参数',
  `remark` varchar(200) NOT NULL DEFAULT '' COMMENT '业务描述',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`) USING BTREE,
  KEY `idx_applocation_name` (`application_name`) USING BTREE,
  KEY `idx_exec_status` (`exec_status`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='异步处理请求';

CREATE TABLE `async_log` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `async_id` bigint NOT NULL DEFAULT '0' COMMENT '异步请求ID',
  `error_data` longtext COMMENT '执行错误信息',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`) USING BTREE,
  KEY `idx_async_id` (`async_id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='异步处理日志';

Async strategy, security levels, execution states, and detailed flowcharts are illustrated with images (omitted here).

Configuration via Apollo includes a switch to enable the SDK, data source settings, thread‑pool parameters, retry policies, and topic naming.

# Switch (default off)
async.enabled=true

# Application name
spring.application.name=xxx

# Data source (Druid)
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/fc_async?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true
spring.datasource.username=user
spring.datasource.password=xxxx
... (other properties omitted for brevity) ...

# Thread pool settings
async.executor.thread.corePoolSize=10
async.executor.thread.maxPoolSize=50
async.executor.thread.queueCapacity=10000
async.executor.thread.keepAliveSeconds=600

# Retry and compensation settings
async.exec.count=5
async.retry.limit=100
async.comp.limit=100

# Topic prefix (default to application name)
async.topic=${spring.application.name}

Usage steps:

Enable the async switch: scm.async.enabled=true Add

@AsyncExec(type = AsyncExecEnum.SAVE_ASYNC, remark = "Data Dictionary")

to any Spring‑proxied method that should run asynchronously.

Access the manual handling UI at http://localhost:8004/async/index.html.

Important notes include ensuring the correct application name, using a consistent queue name (default ${async.topic:${spring.application.name}}_async_queue), implementing idempotency in business logic, and that a single queue is shared across the application. The SDK also provides scheduled retry (every 2 minutes) and compensation (hourly) tasks.

Effect screenshots demonstrate the UI and processing flow (images omitted).

The source code is hosted at https://github.com/xiongyanokok/fc-async.git .

Finally, the article includes a community invitation for backend developers, recruiters, and technology enthusiasts, but this part is promotional and not part of the technical content.