Server-Action on HanGR的碎碎念

Next.js Server Actions 最佳实践

Tue, 13 Aug 2024 00:00:00 +0000

为什么用 Server Actions 而不是 API Route

对比项	Server Actions	API Route
类型安全	全栈类型推断	需要手动定义
调用方式	直接调用函数	fetch + JSON
错误处理	统一封装	每个 route 单独处理
认证	在 action 内部处理	在 route 内部处理
代码量	少	多

Server Actions 的最大优势是类型安全：前端调用时，TypeScript 直接知道返回值的类型，不需要手动定义接口。

next-safe-action 封装

直接用 Next.js 原生 Server Actions 缺少统一的错误处理和输入校验。next-safe-action 提供了一个更好的封装：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// src/lib/safe-action.ts
import { createSafeActionClient } from "next-safe-action";

export const actionClient = createSafeActionClient({
 handleServerError(error) {
 if (error instanceof ActionError) {
 return {
 code: error.code,
 message: error.message,
 details: error.details,
 };
 }
 console.error("Unexpected error:", error);
 return {
 code: "INTERNAL_SERVER_ERROR",
 message: "An unexpected error occurred",
 };
 },
});

输入校验

所有 Server Actions 都用 Zod 做输入校验：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/schemas/image-gen.schema.ts
import { z } from "zod";

export const generateImageSchema = z.object({
 prompt: z
 .string()
 .min(3, "Prompt must be at least 3 characters")
 .max(1000, "Prompt must be at most 1000 characters"),
});

export type GenerateImageSchema = z.infer<typeof generateImageSchema>;

1
2
3
4
5
6
7
8


// src/sites/image-gen/site.actions.ts
export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // parsedInput 已经过 Zod 校验，类型安全
 const { prompt } = parsedInput;
 // ...
 });

错误处理

统一的错误类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// src/lib/action-error.ts
export class ActionError extends Error {
 constructor(
 public code: string,
 message: string,
 public details?: unknown
 ) {
 super(message);
 }
}

在 action 中抛出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 const session = await requireVerifiedEmail();
 if (!session) {
 throw new ActionError("NOT_AUTHORIZED", "You must be signed in");
 }

 const hasCredits = await checkCredits(session.user.id, 10);
 if (!hasCredits) {
 throw new ActionError("PAYMENT_REQUIRED", "Insufficient credits", {
 billingPath: "/dashboard/billing",
 });
 }
 // ...
 });

客户端调用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


"use client";

import { useAction } from "next-safe-action/hooks";
import { generateImageAction } from "./site.actions";

export function ImageGenClient() {
 const { execute, status } = useAction(generateImageAction, {
 onSuccess: ({ data }) => {
 toast.success("Generation started!");
 },
 onError: ({ error }) => {
 const serverError = error.serverError;

 if (serverError?.code === "PAYMENT_REQUIRED") {
 toast.error(serverError.message);
 const billingPath = serverError.details?.billingPath;
 if (billingPath) router.push(billingPath);
 return;
 }

 toast.error(serverError?.message ?? "Something went wrong");
 },
 });

 return (
 <Button
 onClick={() => execute({ prompt })}
 disabled={status === "executing"}
 >
 {status === "executing" ? "Generating..." : "Generate"}
 </Button>
 );
}

AI 任务轮询模式

AI 生成任务需要轮询状态，这是一个常见的异步模式：

提交任务

1
2
3
4
5
6


export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // 扣积分 + 请求大模型 + 存 DB
 return { taskId };
 });

轮询状态

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


export const checkImageStatusAction = actionClient
 .inputSchema(z.object({ taskId: z.string() }))
 .action(async ({ parsedInput }) => {
 const task = await db.query.generatedImageTable.findFirst({
 where: eq(generatedImageTable.id, parsedInput.taskId),
 });

 if (task.status === "completed") {
 return { status: "completed", r2Key: task.r2Key };
 }

 if (task.status === "processing") {
 // 查看最新状态
 const prediction = await CheckPrediction(task.predictionId);
 if (prediction.status === "completed") {
 // 存 R2 + 更新 DB
 return { status: "completed", r2Key };
 }
 }

 return { status: task.status };
 });

前端轮询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const { execute: pollStatus } = useAction(checkImageStatusAction, {
 onSuccess: ({ data }) => {
 if (data?.status === "completed") {
 setResult(data);
 clearInterval(intervalRef.current);
 }
 },
});

useEffect(() => {
 if (!taskId) return;
 const interval = setInterval(() => {
 pollStatus({ taskId });
 }, 3000);
 return () => clearInterval(interval);
}, [taskId]);

总结

Server Actions 的最佳实践：

用 next-safe-action 统一封装，避免重复的错误处理代码
所有输入用 Zod 校验，Schema 前后端共享
用 ActionError 统一错误类型，前端可以根据 code 做不同处理
异步任务用"提交 + 轮询"模式，不要在 action 里等待结果

参考资源

Cloudflare Workers 异步任务处理与 CPU 限制

Wed, 26 Jun 2024 00:00:00 +0000

问题背景

RuiToolAI 的图片生成流程是：

1
2


用户提交 prompt → 调用大模型 → 返回预测 ID
 → 轮询获取结果 → 下载图片 → 存到 R2 → 返回给用户

图片生成需要 10-30 秒，这就需要一个异步任务处理机制。

最初的方案：waitUntil + 后台轮询

最开始，我想用 Cloudflare Workers 的 waitUntil API 在后台轮询：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 提交任务
const predictionId = await SubmitImage({ model, prompt });

// 保存任务到 DB
await db.insert(generatedImageTable).values({
 id: taskId,
 userId,
 status: IMAGE_GEN_STATUS.PROCESSING,
 predictionId,
});

// 启动后台轮询
waitUntil(
 runBackgroundPoll({ taskId, userId, predictionId })
);

// 立即返回给前端
return { taskId };

后台轮询函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


async function runBackgroundPoll({ taskId, predictionId }) {
 for (let attempt = 1; attempt <= 60; attempt++) {
 await new Promise(r => setTimeout(r, 3000));

 const prediction = await CheckPrediction(predictionId);

 if (prediction.status === "completed") {
 // 下载 + 存 R2 + 更新 DB
 return;
 }
 }
}

为什么失败了

部署上线后，发现任务永远停留在 processing 状态。

根本原因：Cloudflare Workers 的 setTimeout 不会真正 sleep。

Workers 的运行时是 V8 引擎，不是 Node.js。在 Workers 中：

1

await new Promise(r => setTimeout(r, 3000));

这行代码不会等待 3 秒。它几乎立即继续执行，导致 60 次轮询瞬间跑完，Workers 进程结束，但是大模型还没完成。

此外，waitUntil 在 Workers 中也有 CPU 时间限制：

计划	CPU 限制
免费	10ms
付费	30s（wall clock）
`waitUntil`	30s（wall clock）

即使 setTimeout 能正常 sleep，30 秒的 wall clock 限制也不够轮询完 60 次 × 3 秒 = 3 分钟。

最终方案：前端轮询 Server Action

核心思路： 不在后台轮询，而是让前端每次请求时去问一下状态。

1. 提交任务（同步返回）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // 扣积分
 await ensureBillingAccess({ userId, creditsRequired: 10 });

 // 提交到大模型
 const predictionId = await SubmitImage({ model, prompt });

 // 存 DB（状态 = processing）
 await db.insert(generatedImageTable).values({
 id: taskId,
 userId,
 status: IMAGE_GEN_STATUS.PROCESSING,
 predictionId,
 });

 // 立即返回，不等待结果
 return { taskId };
 });

2. 前端轮询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 每 3 秒调用一次
useEffect(() => {
 if (!pollingTaskId) return;

 const interval = setInterval(() => {
 executePoll({ taskId: pollingTaskId });
 }, 3000);

 return () => clearInterval(interval);
}, [pollingTaskId]);

3. 状态查询 Action（关键）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


export const checkImageStatusAction = actionClient
 .inputSchema(checkImageStatusSchema)
 .action(async ({ parsedInput }) => {
 const task = await db.query.generatedImageTable.findFirst({
 where: eq(generatedImageTable.id, parsedInput.taskId),
 });

 // 已经完成或失败 → 直接返回
 if (task.status === IMAGE_GEN_STATUS.COMPLETED) {
 return { status: "completed", r2Key: task.r2Key };
 }
 if (task.status === IMAGE_GEN_STATUS.FAILED) {
 return { status: "failed" };
 }

 // 还是在 processing → 查看状态
 const prediction = await CheckPrediction(task.predictionId);

 if (prediction.status === "completed") {
 // 下载图片 + 存 R2 + 更新 DB
 const imageRes = await fetch(prediction.url);
 const buffer = await imageRes.arrayBuffer();
 await env.USER_UPLOADS_BUCKET.put(r2Key, buffer);

 await db.update(generatedImageTable)
 .set({ status: "completed", r2Key })
 .where(eq(generatedImageTable.id, task.id));

 return { status: "completed", r2Key };
 }

 if (prediction.status === "failed") {
 // 退款 + 更新 DB
 await db.update(generatedImageTable)
 .set({ status: "failed" })
 .where(eq(generatedImageTable.id, task.id));

 await addUserCredits(userId, task.creditsCharged);
 return { status: "failed" };
 }

 // 还在处理中
 return { status: "processing" };
 });

用户关闭浏览器后的恢复机制

用户关闭浏览器，再打开时，怎么恢复任务状态？

页面加载时查 DB 里有没有 processing 的任务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// page.tsx (Server Component)
const processingTask = await db.query.generatedImageTable.findFirst({
 where: and(
 eq(generatedImageTable.userId, userId),
 eq(generatedImageTable.status, IMAGE_GEN_STATUS.PROCESSING),
 ),
 orderBy: (table, { desc }) => [desc(table.createdAt)],
});

// 传给客户端组件
return <ImageGenClient processingTaskId={processingTask?.id} />;

1
2
3
4
5
6


// site.client.tsx
useEffect(() => {
 if (processingTaskId) {
 setPollingTaskId(processingTaskId);
 }
}, []);

历史页面也自动轮询：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 找到所有 processing 状态的任务
const processingIds = items
 .filter(item => item.status === IMAGE_GEN_STATUS.PROCESSING)
 .map(item => item.id);

// 每 4 秒轮询一次
useEffect(() => {
 if (processingIds.length === 0) return;
 const interval = setInterval(() => {
 for (const id of processingIds) {
 pollStatus({ taskId: id });
 }
 }, 4000);
 return () => clearInterval(interval);
}, [processingIds.length]);

总结

方案演进：

版本	方案	问题
v1	waitUntil + setTimeout	setTimeout 不 sleep
v2	前端轮询 + checkImageStatusAction	每个请求独立，无时间限制

关键设计原则：

每次轮询是一个独立的 Worker 请求，不受 CPU 时间限制
用户关闭浏览器后，DB 保留任务状态，回来后可恢复
历史页面自动轮询所有 processing 任务，不需要手动刷新