一次 Vue 构建异步化的完整改造

仓库：ice-ai-code-mother 本次改动：commit 9b90e47（15 个文件，+1261 / -119）

一个让用户想摔键盘的场景

在我的 AI 代码生成平台中，用户说一句"帮我做个音乐商城网站"，AI 就流式吐出完整的 Vue 项目代码，实时写进文件，然后构建、预览。

听起来很丝滑对吧？但是构建方式是同步模式：

▼
java
复制代码
// AI 回复完成的回调里，同步执行构建
.onCompleteResponse((ChatResponse response) -> {
    String projectPath = CODE_OUTPUT_ROOT_DIR + "/vue_project_" + appId;
    vueProjectBuilder.buildProject(projectPath);  // ← 就这一行，能卡 8 分钟
    sink.complete();
})

然后用户体验变成了这样：AI 秒回"你的网站已生成完毕！"——然后页面卡死 3~8 分钟，没有任何提示，用户不知道是在构建还是崩了，就想摔键盘。

而且这只是表象，往深了挖是三宗罪：

1. 线程被白嫖：AI 回调线程被 npm install + npm run build 阻塞最长约 8 分钟。十个用户同时生成，十个线程全在等 npm，谁来干活？
2. 数据迟到：AI 回复的对话历史挂在同一个流的完成事件后面，被拖到构建结束才落库。用户这期间一刷新，最后一条 AI 消息没了。
3. 前端锁死：SSE 连接被当成"等构建完成的手段"，前端 isGenerating 全程 true，输入框灰的，按钮点不动。

思路：把"等"变成"推"

问题本质一句话：构建是长耗时任务，却用同步调用的方式挂在请求链路上。

解法也是一句话：构建扔到后台异步跑，用一条独立的 SSE 通道把进度实时推给前端。

为什么是 SSE，不是 WebSocket？

这是最容易被问的问题。我的考量：

• 进度推送是纯单向的（服务端 → 前端），用不上 WebSocket 的双向能力；
• 项目前端本来就在用 EventSource 消费 AI 流式回复，零新依赖、零新协议；
• SSE 自带断线重连语义，配合后端的 replay 机制能优雅处理"页面刷新"这个场景。

简单说：杀鸡用鸡刀就好，牛刀留给真正需要的场景。

整体架构

▼
text
复制代码
【生成通道】不变的部分
用户发消息 ──EventSource──▶ /app/chat/gen/code ──▶ AI 流式输出、工具实时写文件
                                                        │
                                          onCompleteResponse 里 startBuild(appId, path)
                                                        │  ← 只"提交"任务，微秒级返回
                                                        ▼
                                              sink.complete()，生成流正常结束

【进度通道】新增的部分
前端收到 done ──EventSource──▶ /build/progress?appId= ──▶ 鉴权 → subscribe(appId)
                                                                │
                                      构建虚拟线程 → BuildTask → SSE → 前端
                                      事件类型：progress（阶段）/ log（npm 日志）/ done（终态）

关键设计决策：构建线程只管往任务内部的事件流推消息，完全不知道有没有订阅者。前端断线、关页面、刷新——npm 照常跑完，结果在内存里留着，谁来看谁来取。

四个核心实现

1️⃣ BuildTask：一个 replay-latest Sinks 解决两大难题

每个构建任务自带一条 Sinks.many().replay().latest() 事件流。这一个选择同时解决了两个经典难题：

• 页面刷新重连：replay-latest 会先给新订阅者重放最近 1 条事件再接实时流，前端刷新后重新订阅，进度无缝接上；
• 迟到订阅者：终态事件发出后流 complete，Sinks 里留着这条终态——10 分钟内来订阅都能直接拿到结果。

▼
java
复制代码
public class BuildTask {
    private final long appId;
    // 新订阅者先重放最近 1 条事件，再接入实时流
    private final Sinks.Many<BuildProgressMessage> sink = Sinks.many().replay().latest();
    private final AtomicBoolean terminal = new AtomicBoolean(false);
    private volatile Process currentProcess;   // 取消时强杀用

    /** 终态事件：幂等，发出后流 complete */
    public void emitDone(BuildStatusEnum status, String message) {
        synchronized (this) {
            if (terminal.get()) return;
            terminal.set(true);
            doneAt = System.currentTimeMillis();
            sink.tryEmitNext(BuildProgressMessage.done(appId, status, message));
            sink.tryEmitComplete();
        }
    }

    /** 适配为构建监听器；堵住一个隐蔽的竞态 */
    public void onProcessStarted(Process process) {
        synchronized (BuildTask.this) {
            if (terminal.get()) {
                // 取消恰好落在 "npm install 结束 → npm run build 启动" 的间隙
                // 这时刚启动的新进程必须立刻杀掉，否则它就成了漏网之鱼
                process.destroyForcibly();
                return;
            }
            currentProcess = process;
        }
    }
}

那个 onProcessStarted 里的竞态值得单独说：构建有两条命令（install → build），取消请求可能恰好在两条命令的间隙到达。如果只在启动时注册进程引用，间隙里的取消就找不到进程可杀——npm 会继续跑完，跟新一轮生成的文件写入撞车。所以每次进程启动都要重新检查终态标记。

2️⃣ BuildProgressManager：虚拟线程 + 严格的生命周期管理

▼
java
复制代码
@Component
public class BuildProgressManager {
    private static final long TERMINAL_RETENTION_MS = 10 * 60 * 1000L;

    private final Map<Long, BuildTask> tasks = new ConcurrentHashMap<>();
    // 每个构建任务一个虚拟线程——等待 npm 的线程不占真实载体，随便开
    private final ExecutorService executor = Executors.newThreadPerTaskExecutor(
            Thread.ofVirtual().name("vue-build-", 0).factory());

    public void startBuild(Long appId, String projectPath) {
        synchronized (this) {
            evictExpiredTasks();
            BuildTask previous = tasks.get(appId);
            if (previous != null) {
                // 关键：新构建会重写项目文件，旧 npm 进程必须先杀掉
                previous.cancel("检测到新的构建任务，当前构建已取消");
            }
            BuildTask task = new BuildTask(appId);
            tasks.put(appId, task);
            executor.execute(() -> executeBuild(task, projectPath));
        }
    }
}

两个点：

• 虚拟线程是给这种 IO 密集任务量身定做的——线程 90% 的时间在 readLine() 等 npm 吐日志，用平台线程纯属浪费。JDK 21 用上这个，正好。
• 同一 appId 新构建强杀旧构建：AI 对话是迭代式的，用户改需求就触发新一轮生成，旧构建必须立刻终止，不然两个 npm 进程并发读写同一个项目目录，结果不可预测。

3️⃣ VueProjectBuilder：看门狗 + 日志流转发

原来构建完就返回个 boolean，现在要把 npm 的每行输出实时转给前端，还要防它卡死：

▼
java
复制代码
private boolean executeNpmCommand(File projectDir, String commandArgs,
                                  BuildPhaseEnum phase, BuildProgressListener listener,
                                  int timeoutSeconds) {
    Process processToWatch = new ProcessBuilder(command)
            .directory(projectDir)
            .redirectErrorStream(true)   // stderr 合并进 stdout，错误信息也能推给前端
            .start();
    listener.onProcessStarted(processToWatch);

    // 虚拟线程看门狗：超时强杀，保证读取线程不会永久阻塞
    AtomicBoolean timedOut = new AtomicBoolean(false);
    Thread watchdog = Thread.ofVirtual().name("npm-watchdog").start(() -> {
        Thread.sleep(timeoutSeconds * 1000L);
        if (processToWatch.isAlive()) {
            timedOut.set(true);
            processToWatch.destroyForcibly();
        }
    });

    // 逐行读取转发（上限 500 行，防止异常庞大的输出拖垮 SSE）
    try (BufferedReader reader = new BufferedReader(
            new InputStreamReader(processToWatch.getInputStream(), UTF_8))) {
        String line;
        int count = 0;
        while ((line = reader.readLine()) != null) {
            if (count++ < MAX_LOG_LINES) listener.onLog(line);
        }
    }
    processToWatch.waitFor();
    watchdog.interrupt();
    // ...超时/退出码判断，失败时上报阶段信息
}

超时配置：npm install 300 秒、npm run build 180 秒。看门狗到点直接 destroyForcibly()，前端会收到"命令执行超时（N 秒）"的明确报错，而不是永远转圈。

另外保留了单参的 buildProject(String)——部署功能和 LangGraph4j 工作流节点还在用它，改内部实现不动对外签名，老调用方零成本兼容。

4️⃣ SSE 接口：命名事件 + 心跳注释

▼
java
复制代码
@GetMapping(value = "/progress", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> subscribeBuildProgress(@RequestParam Long appId,
                                                            HttpServletRequest request) {
    // 参数校验 → 登录 → 应用归属/管理员鉴权（略）

    Flux<ServerSentEvent<String>> dataFlux = buildProgressManager.subscribe(appId)
            .map(msg -> {
                ServerSentEvent.Builder<String> b = ServerSentEvent.builder(JSONUtil.toJsonStr(msg));
                if (BuildProgressMessage.TYPE_DONE.equals(msg.getType())) {
                    b.event("done");   // 终态用命名事件
                }
                return b.build();
            });
    // 15s 心跳：SSE 注释行，EventSource 自动忽略，纯防代理掐空闲连接
    Flux<ServerSentEvent<String>> heartbeat = Flux.interval(Duration.ofMillis(15_000))
            .map(tick -> ServerSentEvent.<String>builder().comment("keep-alive").build());
    return dataFlux.mergeWith(heartbeat)
            .takeUntil(event -> "done".equals(event.event()));
}

这里有个我必须敲黑板的协议细节：

SSE 命名事件，onmessage 是收不到的！

progress / log 走默认事件，前端用 onmessage 收；done 是命名事件，前端必须 addEventListener('done') 收。我在这里调试半天"为什么终态收不到"——因为 onmessage 只派发无 event 字段的消息。

心跳也是同理：注释行（: keep-alive）是 SSE 协议的一部分，EventSource 自动忽略，它存在的唯一意义是让中间的 Nginx / 容器网络知道"这连接还活着"，别把 15 秒没数据的构建期连接当死连接掐了。

前端

前端体验的改造分三步：

① 生成结束不再傻等，按项目类型分流：

▼
ts
复制代码
const onGenerationFinished = () => {
  if (isVueProject.value) {
    watchBuildProgress()   // Vue 项目：转订阅构建进度流
  } else {
    /* HTML/多文件：走原来的延迟刷新预览 */
  }
}

② 进度订阅——阶段文案实时更新，npm 日志像追剧一样滚动出来：

▼
ts
复制代码
buildEventSource.onmessage = function (event) {
  const payload = JSON.parse(event.data)
  if (payload.type === 'progress') {
    isBuilding.value = true
    buildPhaseText.value = payload.message   // "正在安装依赖（npm install）..."
  } else if (payload.type === 'log' && payload.line) {
    buildLogs.value.push(payload.line)       // 日志控制台滚动
    // 环形窗口：最多保留 200 行，防内存膨胀
  }
}

buildEventSource.addEventListener('done', (event) => {
  closeBuildWatch()
  isBuilding.value = false
  const { status } = JSON.parse((event as MessageEvent).data)
  if (status === 'success') {
    updatePreview(true)   // 带时间戳强制刷新 iframe，绕过缓存
  } else if (status === 'failed') {
    buildError.value = ...  // 失败面板展示错误 + 日志
  }
})

③ 预览刷新的缓存陷阱：构建成功后 iframe 加载的还是旧的 dist？因为浏览器缓存了。解法是在 URL 后拼 ?t=${Date.now()} 破缓存。只有收到 success 才刷新预览——绝不展示半成品。

构建期间，下载/部署按钮禁用（部署会同步重建，和后台构建撞车）；页面刷新后自动重新订阅，构建还在跑就直接接上。

顺手堵掉的两个并发隐患

场景	隐患	解法
用户在构建进行中又发了新消息	新一轮 AI 生成写文件 与 旧 npm 构建读文件 撞车	VUE_PROJECT 生成开始前 cancelBuild(appId)，强杀旧进程
用户在构建进行中点了部署	部署的同步重建 与 后台异步构建 并发跑 npm	部署重建前同样 cancelBuild

原则就一条：同一项目目录，任何时刻最多允许一个 npm 进程在跑。

效果

指标	改造前	改造后
AI 回复完成 → SSE 关闭	卡到构建结束（最长 8 分钟）	毫秒级
对话历史落库时机	构建结束后	生成流结束即落库
构建期间前端状态	全程锁死，无任何反馈	实时阶段进度 + 日志滚动
线程占用	每个构建占 1 个平台线程 8 分钟	虚拟线程，等 IO 不占载体
页面刷新	进度丢失	重连重放，无缝接上

验证：新增 BuildProgressManagerTest 6 个用例全绿（idle / 成功全序列 / 失败 / 异常 / 重复构建取消旧任务 / 终态重放），后端编译通过，前端 vue-tsc 类型检查 + vite build 通过。

踩坑记录

给后来人排雷：

1. StepVerifier.verifyTimeout(Duration) 不是"在时限内完成"——它是断言"超时发生"！带超时的完成验证要写 .expectComplete().verify(Duration)，而且 verify(Duration) 在顶层 StepVerifier 接口上，链尾的 Step 类型没有这个方法。
2. SSE 命名事件：onmessage 收不到带 event: 字段的消息，必须 addEventListener。
3. iframe 缓存：构建产物更新后 iframe 不一定重新加载，时间戳查询参数是最简单可靠的破缓存手段。

最后

完整代码都在仓库里，这次改动的 diff 在这里：

• 📦 仓库：https://github.com/iceblyte/ice-ai-code-mother
• 🔧 本次提交：https://github.com/iceblyte/ice-ai-code-mother/commit/9b90e47cb0a438aff132b76ad6d6fa720766119d

核心文件索引（方便你直奔重点）：

• core/builder/BuildProgressManager.java — 任务调度与生命周期
• core/builder/BuildTask.java — replay Sinks 与取消竞态处理
• core/builder/VueProjectBuilder.java — 进程管理、看门狗、日志转发
• controller/BuildProgressController.java — SSE 端点与协议
• src/pages/app/AppChatPage.vue — 前端进度订阅与 UI

如果这篇文章对你有帮助，欢迎点个 Star ⭐ 有问题欢迎提 Issue 讨论。