深入详解SpringBoot中接口异步化实战指南_Java

背景

在一个智慧课堂系统中，有一个"生成讲稿"的接口，内部需要调用 ai 大模型（coze），整个过程耗时可能在数十秒甚至更长。

原始的调用链是这样的：

前端
│
├─ 1. 调 updatecdgenstatus(status=1) → 把状态设为"生成中"
│
├─ 2. 调 generatespeech → 同步等待 ai 生成（可能等几十秒）
│
└─ 3. 调 updatecdgenstatus(status=2) → 把状态设为"已生成"

这个设计存在两个明显问题：

前端长时间阻塞：第 2 步接口响应极慢，用户体验差。
状态不一致：如果用户在第 2 步等待期间刷新了页面，第 3 步永远不会执行，状态永远卡在"生成中"，无法恢复。

解决思路

将两个问题合并解决：

状态管理下沉到后端：generatespeech 内部在成功后自动更新状态为"已生成"，失败时回滚为"暂存"，前端不再负责状态收尾。
接口改为异步：generatespeech 立即返回，ai 生成任务由后台线程池执行，前端轮询状态字段即可感知进度。

改造后的调用链：

前端后端
│ │
├─ updatecdgenstatus(1) ────────►│ 同步，立即返回，状态="生成中"
│◄──────── 200 ok ───────────────┤
│ │
├─ generatespeech ──────────────►│ 立即返回 200 ok
│◄──────── 200 ok ───────────────┤ │
│ │ ▼ 后台线程池异步执行
│ （前端可正常操作/刷新页面） │ 调用 ai 大模型（耗时）
│ │ 成功 → cdgenstatus = 2（已生成）
│ │ 失败 → cdgenstatus = 0（暂存，可重试）
│
前端定时轮询查询接口，检查 cdgenstatus 字段

实现步骤

第一步：创建异步线程池配置类

spring boot 默认的异步线程池配置较为简陋，建议为耗时任务单独配置一个命名线程池，便于监控和隔离。

package org.jeecg.modules.business.config;

import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
import org.springframework.scheduling.annotation.enableasync;
import org.springframework.scheduling.concurrent.threadpooltaskexecutor;

import java.util.concurrent.executor;
import java.util.concurrent.threadpoolexecutor;

/**
 * @author lxy
 */
@configuration
@enableasync  // 开启 spring 异步支持
public class asyncconfig {

    /**
     * 生成讲稿专用异步线程池。
     * ai 调用属于 io 密集型，核心线程数不需要很大。
     * 使用 callerrunspolicy 作为拒绝策略，保证任务不丢失。
     */
    @bean("speechexecutor")
    public executor speechexecutor() {
        threadpooltaskexecutor executor = new threadpooltaskexecutor();
        executor.setcorepoolsize(2);       // 核心线程数
        executor.setmaxpoolsize(5);        // 最大线程数
        executor.setqueuecapacity(20);     // 队列容量
        executor.setthreadnameprefix("speech-async-");
        executor.setkeepaliveseconds(60);
        // 队列满且线程达到上限时，由调用方线程执行，避免任务丢失
        executor.setrejectedexecutionhandler(new threadpoolexecutor.callerrunspolicy());
        executor.initialize();
        return executor;
    }
}

为什么不用 @springbootapplication 上加 @enableasync？

将 @enableasync 放在独立的 @configuration 类中，职责更清晰，也方便后续扩展其他线程池。

第二步：在 service 实现方法上加 @async

/**
 * 异步生成讲稿。方法立即返回，由后台线程池（speechexecutor）执行耗时的 ai 调用。
 * 生成成功后自动将 cdgenstatus 更新为"讲稿已生成"（2），
 * 生成失败则回滚为"暂存"（0），无需前端二次调用更新状态接口。
 *
 * @param speechdto 生成讲稿所需参数，包含 coursedetailid、classid 等
 */
@async("speechexecutor")  // 指定使用 speechexecutor 线程池
@override
public void generatespeech(speechdto speechdto) {
    try {
        // --- 耗时操作：调用 ai 大模型 ---
        string genword = cozeutil.pptcreate(cozedto);

        // 其他业务逻辑...

        // 生成成功 → 后端直接更新状态为"已生成"
        this.updatecdgenstatus("2", speechdto.getcoursedetailid(), speechdto.getclassid());

    } catch (exception e) {
        // 生成失败 → 回滚状态为"暂存"，前端可重试
        this.updatecdgenstatus("0", speechdto.getcoursedetailid(), speechdto.getclassid());
        throw new runtimeexception(e);
    }
}

第三步：controller 无需任何改动

@postmapping(value = "/generatespeech")
public result<?> generatespeech(@requestbody speechdto speechdto) {
    bizcoursedetailservice.generatespeech(speechdto);  // 立即返回
    return result.ok();
}

由于 generatespeech 已标注 @async，spring 会在调用时直接提交任务到线程池并返回，controller 完全感知不到异步细节。

关键注意事项

@async 的自调用陷阱

@async 基于 spring aop 代理实现，同一个类内部的方法互相调用无法触发异步。

// ❌ 错误：在同一个 service 内部调用，@async 不生效
public void somemethod() {
    this.generatespeech(dto);  // 直接调用，不走代理，不会异步
}

// ✅ 正确：从另一个 spring bean（如 controller）注入后调用
@autowired
private ibizcoursedetailservice bizcoursedetailservice;

public void somemethod() {
    bizcoursedetailservice.generatespeech(dto);  // 走代理，异步生效
}

异步方法的返回值

@async 方法的返回值只能是 void 或 future<t> / completablefuture<t>。

本场景使用 void 即可，状态通过数据库字段通知前端。

异步方法中的事务

@async 方法运行在新线程中，@transactional 的事务上下文不会从调用方传播过来。如果异步方法内需要事务，需要在异步方法本身上加 @transactional。

securitycontext（shiro/spring security）不传播

异步线程中拿不到调用方的登录用户信息，如需使用，需在调用前手动传入，或通过参数传递。

前端配合改造

去掉 generatespeech 成功回调里调用 updatecdgenstatus 的逻辑，改为轮询查询接口：

// 调用生成讲稿接口后，定时轮询状态
async function generatespeech(params) {
  await api.generatespeech(params);  // 立即返回

  // 轮询，每 3 秒检查一次
  const timer = setinterval(async () => {
    const res = await api.querycoursedetail({ id: params.coursedetailid, classid: params.classid });
    const status = res.result.cdgenstatus;
    if (status === '2') {
      clearinterval(timer);
      // 生成成功，刷新页面
    } else if (status === '0') {
      clearinterval(timer);
      // 生成失败，提示用户重试
    }
  }, 3000);
}

总结

改造点	方式
开启 spring 异步	`@configuration` 类上加 `@enableasync`
配置专用线程池	`@bean` 注册 `threadpooltaskexecutor`
方法异步化	service 实现方法上加 `@async("poolname")`
状态管理内聚	try 块末尾更新成功状态，catch 中回滚失败状态
前端感知进度	去掉二次状态更新调用，改为轮询查询接口