Server Actions
优先级:P1(高)
[!WARNING] 如果项目使用
pages/目录而非 App Router,请完全忽略此技能。
无需创建 API 端点即可处理表单提交和变异操作。
实施指南
-
指令:始终以
'use server'开始文件或函数。使用formData.get('title')访问类型化表单字段。导出异步函数用于变异。 -
表单处理:使用
<form>的action属性通过action={createPost}触发操作。使用useFormStatus()处理pending状态 —— 在按钮上使用disabled={pending}。使用useActionState(React 19/Next.js 15)处理<form action={action}>的表单状态。 -
数据刷新:在成功变异后使用
revalidatePath('/')或revalidateTag('tag-name')触发 UI 更新。 -
交互性:对于非表单触发器,使用
useTransition钩子调用操作,以处理加载 UI 并防止页面阻塞。 -
乐观更新:使用
useOptimistic在服务器确认变异之前立即显示预期的 UI 状态。 -
安全性:对
FormData中的所有输入进行消毒。在每个操作中执行身份验证检查(await auth())。按大小和 MIME 类型限制文件上传。 -
表单:
<form action={createPost}>(即使没有 JS,渐进增强也能工作)。 -
事件处理程序:
onClick={() => createPost(data)}。 -
挂起状态:使用
useFormStatus钩子(必须在表单内渲染的组件中使用)。
P1:操作标准
1. 安全与验证
在处理之前,始终使用 z.object({ 模式和 safeParse 验证输入。在操作中检查授权。参见安全操作示例。
2. 挂起状态
使用 useActionState(React 19/Next.js 15+)处理状态,使用 useFormStatus 处理按钮加载状态。
约束
- 闭包:避免在组件内定义操作,以防止隐藏的闭包加密开销和序列化错误。
- 重定向:使用
redirect()进行成功导航;它会抛出一个错误,Next.js 捕获该错误以处理重定向。
反模式
- 不要有未验证的 Server Action 输入:始终在使用 Zod 处理之前进行验证。
- 不要跳过权限检查:在每个操作中验证会话/用户,而不仅仅是在中间件中。
- 不要在组件内定义操作:在
actions.ts中定义,以避免闭包错误。 - 不要在 try/catch 中使用
redirect():redirect()会抛出异常;捕获它会抑制重定向。