Next.js 长耗时音频任务的异步架构
文章以 AI 音乐生成为例,将长耗时推理拆成任务创建、立即返回任务编号、Webhook 回调及客户端状态同步。重点讨论无服务器超时、积分原子扣减,以及重试或失败时的重复计费问题。
AI 深度解读
AI 音乐生成不能直接照搬聊天接口:一首带人声的完整歌曲,可能要等 30 秒到超过 2 分钟。作者为 Alyven Music 搭建的 Next.js + TypeScript 流水线,把提交任务、扣积分、接收结果和页面更新拆开,让前端先拿到任务编号,再等待音频完成。
这套方案值得看,尤其是它把积分退款和任务补偿也放进了讨论。但架构方向成立,不代表示例代码已经解决并发安全。读懂它,需要同时看见可复用的设计和仍需补齐的边界。
为什么应该先返回 jobId
作者的平台包含 Music Generator、Song Extender 和 AI Instrumental Generator。这些功能共同的问题是:上游推理耗时长,放在 Vercel 或 AWS Lambda 的同步 serverless API 路由里等待,容易撞上执行时限。原文没有交代具体部署配置,因此不能把超时理解成所有环境下的固定结论。
作者把一次生成拆成四步:
- 校验余额,在数据库里扣积分并创建
PENDING任务。 - 调用上游 AI API,附带 webhook 回调地址。
- 向前端返回
jobId,HTTP 状态码为202。 - 上游完成后回调,前端查询任务状态,直到
COMPLETED或FAILED。
长任务需要持久化的任务身份,页面不必一直占着提交请求。
作者给出的返回目标是小于 200ms,但代码在返回前仍然 await fetch(...),等待上游接单。它缩短的是等待完整音频生成的时间,并没有消除上游接口响应慢的影响。原文也没有提供延迟统计,< 200ms 更适合作为作者报告的表现,不能直接当作这套架构的保证。
请求入口是 /api/generate,提交字段包括 userId、prompt 和 instrumental。上游地址、密钥分别来自 AUDIO_API_ENDPOINT、AUDIO_API_KEY,回调地址用 NEXT_PUBLIC_APP_URL 拼成 /api/webhooks/audio?jobId=...。
扣积分和退款,为什么一个事务还不够
作者设置每次生成消耗 12 积分,用 GENERATION_COST = 12 表示。在 db.$transaction 中读取用户、检查余额、执行 decrement,然后创建任务。任务保存 cost,后续失败时按该值退款。
这能把扣款和建任务作为一组数据库操作提交,但示例还有两处容易被高估。
第一,先读取余额再更新,不自动等于并发下不会超扣。能否安全取决于事务隔离级别、锁或条件更新,原文没有说明。用户双击也可能创建两个合法任务,阻止同一次提交被重复处理,还需要请求幂等键。
第二,上游调用发生在事务提交之后。失败时增加积分、把任务标记为 FAILED,属于补偿操作,并非撤销原事务。而且 fetch 遇到 HTTP 4xx 或 5xx 通常不会直接抛异常;示例没有检查 res.ok,可能漏掉上游明确拒绝请求的情况。网络超时则更麻烦:本地没收到响应,上游却可能已经接单。
作者用下面的 webhook 处理结果,意图避免重复回调造成重复退款:
// app/api/webhooks/audio/route.ts
import { NextResponse } from "next/server";
import { db } from "@/lib/db";
export async function POST(req: Request) {
const { searchParams } = new URL(req.url);
const jobId = searchParams.get("jobId");
const payload = await req.json();
if (!jobId) return NextResponse.json({ error: "Missing jobId" }, { status: 400 });
const job = await db.audioJob.findUnique({ where: { id: jobId } });
// 幂等保护:忽略已经处理的任务
if (!job || job.status !== "PENDING") {
return NextResponse.json({ received: true });
}
if (payload.status === "succeeded") {
await db.audioJob.update({
where: { id: jobId },
data: { status: "COMPLETED", audioUrl: payload.audio_url, duration: payload.duration },
});
} else {
await db.$transaction([
db.audioJob.update({ where: { id: jobId }, data: { status: "FAILED" } }),
db.user.update({ where: { id: job.userId }, data: { credits: { increment: job.cost } } }),
]);
}
return NextResponse.json({ received: true });
}
要盯住 job.status !== "PENDING" 这一行:检查与更新分开执行,两个并发回调仍可能同时读到 PENDING,随后各退一次积分。更稳妥的实现需要原子地争取状态转换权,只有成功改变状态的请求才能退款。
另外,这段代码把所有非 succeeded 状态都当作失败,依赖上游只发送终态的约定;回调签名验证也没有展示。它说明了处理思路,还不足以证明完整的幂等与安全性。
三秒轮询够用,但必须有人处理失联任务
作者认为,对耗时 45–90 秒的生成任务,WebSockets 通常没有必要。他们用 useAudioJob(jobId: string | null) 每 3000 毫秒请求 /api/jobs/${jobId},收到 COMPLETED 或 FAILED 后清除定时器。
这个取舍容易理解:如果页面只关心任务是否完成,轮询能减少连接管理的复杂度。Hook 在卸载或切换任务时清理定时器,还通过 active 标记忽略旧响应。不过,它没有展示查询接口的鉴权,也没有处理请求耗时超过轮询间隔导致的重叠请求,查询失败时只记录日志。
轮询负责让页面知道结果,补偿机制负责让任务最终有结果。
作者提出三项生产经验。其一,上游临时音频 URL 往往在 24–48 小时后过期,应转存到 Cloudflare R2 或 AWS S3,保存自己的 CDN 地址。其二,cron 扫描超过 10 分钟仍为 PENDING 的任务,查询供应商状态 API,再完成任务或退款。其三,展示 Queued → Composing → Mastering 等阶段,减少等待中的刷新。
最后一项需要真实状态来源。原文没有说明这些阶段如何获得,不能据此认定上游一定提供精确进度。
我的判断
我认可作者先拆生命周期、再处理积分与补偿的顺序。对只有提交和终态通知的产品,HTTP 202、webhook 加轮询,是容易理解和维护的起点。
但「事务保证扣款安全」「状态检查保证幂等」都需要补上条件。用户身份应从可信会话获取,不能直接信任请求体里的 userId;回调需要验证来源;任务状态与积分流水需要一起约束并发。
轮询比 WebSockets 更省事,是有场景前提的经验判断。作者没有提供负载、成本或对照数据。结尾提到的 Inngest、Trigger.dev 也没有实际比较,不能据此判断是否该引入后台队列。需要可靠投递、重试和恢复时,再评估这些工具解决了哪些具体缺口。
能拿来做什么
- 在 Next.js 或 Node 中接入长耗时音频生成时,先建立持久化任务记录,让提交接口返回
jobId,页面根据任务状态恢复展示。 - 做积分计费时,把条件扣款、提交幂等键和退款流水一起设计,并验证重复提交、并发失败回调、上游接单后本地超时这几类情况。
- 前端可以从三秒轮询起步,同时补上终态停止、错误重试和请求重叠控制;进度展示应对应可验证的任务阶段。
- 上线前安排超时任务巡检和音频转存,明确无人回调、资源过期时由谁收尾,避免任务永久停留在等待状态。