next-safe-action
概述
next-safe-action 为 Next.js Server Actions 添加了类型安全、输入验证和中间件支持。无需手动解析 FormData 和处理错误,只需定义一个 Zod 模式,即可获得经过验证、类型明确的输入,并自动处理错误。
操作指南
第 1 步:安装与设置
npm install next-safe-action zod
// lib/safe-action.ts — 包含认证中间件的 Action 客户端
import { createSafeActionClient } from 'next-safe-action'
import { auth } from '@/auth'
// 公开操作(无需认证)
export const publicAction = createSafeActionClient()
// 已认证操作
export const authAction = createSafeActionClient({
async middleware() {
const session = await auth()
if (!session?.user) throw new Error('Not authenticated')
return { user: session.user }
},
})
第 2 步:定义操作
// actions/projects.ts — 类型安全的 Server Actions
'use server'
import { authAction } from '@/lib/safe-action'
import { z } from 'zod'
import { prisma } from '@/lib/db'
import { revalidatePath } from 'next/cache'
const createProjectSchema = z.object({
name: z.string().min(1).max(100),
description: z.string().max(500).optional(),
})
export const createProject = authAction
.schema(createProjectSchema)
.action(async ({ parsedInput, ctx }) => {
const project = await prisma.project.create({
data: {
...parsedInput,
ownerId: ctx.user.id,
},
})
revalidatePath('/dashboard')
return { project }
})
const updateProjectSchema = z.object({
id: z.string().uuid(),
name: z.string().min(1).max(100).optional(),
description: z.string().max(500).optional(),
status: z.enum(['active', 'archived']).optional(),
})
export const updateProject = authAction
.schema(updateProjectSchema)
.action(async ({ parsedInput, ctx }) => {
const { id, ...data } = parsedInput
// 验证所有权
const project = await prisma.project.findFirst({
where: { id, ownerId: ctx.user.id },
})
if (!project) throw new Error('Project not found')
const updated = await prisma.project.update({
where: { id },
data,
})
revalidatePath(`/projects/${id}`)
return { project: updated }
})
第 3 步:在组件中使用
// components/CreateProjectForm.tsx — 使用安全操作的表单
'use client'
import { useAction } from 'next-safe-action/hooks'
import { createProject } from '@/actions/projects'
export function CreateProjectForm() {
const { execute, result, isExecuting } = useAction(createProject)
return (
<form action={execute}>
<input name="name" placeholder="项目名称" required />
<textarea name="description" placeholder="描述(可选)" />
{result.validationErrors && (
<div className="errors">
{Object.entries(result.validationErrors).map(([field, errors]) => (
<p key={field}>{field}: {errors?.join(', ')}</p>
))}
</div>
)}
{result.serverError && (
<p className="error">{result.serverError}</p>
)}
<button disabled={isExecuting}>
{isExecuting ? '正在创建...' : '创建项目'}
</button>
</form>
)
}
使用指南
- 始终使用 Zod 模式进行输入验证 —— 绝不信任客户端提交的数据。
- 使用中间件进行认证 —— 在每个操作链执行前运行。
useAction钩子提供了isExecuting、result和自动错误处理功能。- 结合
useOptimisticAction实现即时 UI 反馈。 - 在数据变更后重新验证路径/标签,以保持 UI 与数据库同步。