React 22 的 Server Actions 已经从新特性变成构建现代 React 应用的核心能力。它改变了前端与后端交互的方式——不再需要手动编写 API 端点和 fetch 调用,Server Actions 让数据突变变得更加直观。
Server Actions 基础
Server Actions 是标记为 use server 的异步函数,可以在客户端组件中直接调用:
typescript
// actions.ts
'use server'
import { revalidatePath } from 'next/cache'
export async function createUser(formData: FormData) {
const name = formData.get('name') as string
const email = formData.get('email') as string
// 服务端逻辑
const user = await db.user.create({
data: { name, email }
})
// 重新验证缓存
revalidatePath('/users')
return { success: true, user }
}
export async function updateUser(id: string, formData: FormData) {
const name = formData.get('name') as string
await db.user.update({
where: { id },
data: { name }
})
revalidatePath(`/users/${id}`)
return { success: true }
}
客户端调用
typescript
'use client'
import { createUser, updateUser } from './actions'
function UserForm() {
const [state, formAction, isPending] = useActionState(createUser, null)
return (
<form action={formAction}>
<input name="name" required />
<input name="email" type="email" required />
<button type="submit" disabled={isPending}>
{isPending ? 'Creating...' : 'Create User'}
</button>
{state?.success && <p>User created successfully!</p>}
</form>
)
}
复杂表单处理模式
多步骤表单
typescript
// actions.ts
'use server'
interface WizardState {
step: number
data: Partial<FormData>
errors: Record<string, string>
}
export async function wizardAction(
prevState: WizardState,
formData: FormData
): Promise<WizardState> {
const action = formData.get('_action') as string
switch (action) {
case 'next':
const step1Data = {
name: formData.get('name') as string,
email: formData.get('email') as string
}
// 验证第一步数据
const errors1 = validateStep1(step1Data)
if (Object.keys(errors1).length > 0) {
return { step: 1, data: step1Data, errors: errors1 }
}
return { step: 2, data: step1Data, errors: {} }
case 'submit':
const fullData = {
...prevState.data,
address: formData.get('address') as string,
city: formData.get('city') as string
}
// 创建用户
await db.user.create({ data: fullData })
return { step: 3, data: fullData, errors: {} }
default:
return prevState
}
}
// 多步骤表单组件
'use client'
function WizardForm() {
const [state, formAction, isPending] = useActionState(wizardAction, {
step: 1,
data: {},
errors: {}
})
return (
<form action={formAction}>
{state.step === 1 && (
<>
<input name="name" defaultValue={state.data.name} />
{state.errors.name && <span>{state.errors.name}</span>}
<input name="email" defaultValue={state.data.email} />
<input type="hidden" name="_action" value="next" />
<button type="submit">Next</button>
</>
)}
{state.step === 2 && (
<>
<input name="address" defaultValue={state.data.address} />
<input name="city" defaultValue={state.data.city} />
<input type="hidden" name="_action" value="submit" />
<button type="submit" disabled={isPending}>
{isPending ? 'Submitting...' : 'Submit'}
</button>
</>
)}
{state.step === 3 && (
<div>
<h3>Success!</h3>
<p>User created successfully.</p>
</div>
)}
</form>
)
}
动态表单验证
typescript
// actions.ts
'use server'
export async function validateEmail(
prevState: any,
formData: FormData
) {
const email = formData.get('email') as string
// 检查邮箱是否已存在
const existingUser = await db.user.findUnique({
where: { email }
})
if (existingUser) {
return { valid: false, error: 'Email already exists' }
}
// 检查邮箱格式
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
if (!emailRegex.test(email)) {
return { valid: false, error: 'Invalid email format' }
}
return { valid: true, error: null }
}
// 带实时验证的表单
'use client'
function RegistrationForm() {
const [emailState, emailAction, isEmailPending] = useActionState(
validateEmail,
{ valid: null, error: null }
)
return (
<form>
<input
name="email"
type="email"
onBlur={() => {
// 触发邮箱验证
emailAction(new FormData(e.target.form))
}}
/>
{isEmailPending && <span>Checking...</span>}
{emailState.valid === false && (
<span className="error">{emailState.error}</span>
)}
{emailState.valid === true && (
<span className="success">Email available!</span>
)}
</form>
)
}
乐观更新模式
乐观 UI 更新
typescript
'use client'
import { useOptimistic } from 'react'
import { addTodo } from './actions'
function TodoList({ initialTodos }) {
const [todos, setOptimisticTodos] = useOptimistic(
initialTodos,
(state, newTodo) => [...state, { ...newTodo, pending: true }]
)
async function handleSubmit(formData: FormData) {
const text = formData.get('text') as string
// 乐观更新:立即显示新 todo
const optimisticTodo = { id: 'temp', text, pending: true }
setOptimisticTodos(optimisticTodo)
// 服务端操作
await addTodo(formData)
}
return (
<div>
<form action={handleSubmit}>
<input name="text" required />
<button type="submit">Add</button>
</form>
<ul>
{todos.map(todo => (
<li key={todo.id} className={todo.pending ? 'pending' : ''}>
{todo.text}
{todo.pending && <span>Saving...</span>}
</li>
))}
</ul>
</div>
)
}
使用 useTransition 优化
typescript
'use client'
import { useTransition } from 'react'
import { deleteTodo } from './actions'
function TodoItem({ todo, onDelete }) {
const [isPending, startTransition] = useTransition()
function handleDelete() {
startTransition(async () => {
await deleteTodo(todo.id)
})
}
return (
<li className={isPending ? 'deleting' : ''}>
<span>{todo.text}</span>
<button onClick={handleDelete} disabled={isPending}>
{isPending ? 'Deleting...' : 'Delete'}
</button>
</li>
)
}
错误处理策略
全局错误边界
typescript
// error.tsx
'use client'
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div className="error-container">
<h2>Something went wrong!</h2>
<p>{error.message}</p>
<button onClick={reset}>Try again</button>
</div>
)
}
// actions.ts 中的错误处理
'use server'
export async function createOrder(formData: FormData) {
try {
const items = JSON.parse(formData.get('items') as string)
// 验证库存
for (const item of items) {
const product = await db.product.findUnique({
where: { id: item.productId }
})
if (!product || product.stock < item.quantity) {
throw new Error(`Insufficient stock for ${product?.name}`)
}
}
// 创建订单
const order = await db.order.create({
data: {
items,
total: calculateTotal(items)
}
})
return { success: true, orderId: order.id }
} catch (error) {
// 返回结构化错误
return {
success: false,
error: error.message || 'Failed to create order'
}
}
}
表单级别的错误处理
typescript
'use client'
function CheckoutForm() {
const [state, formAction, isPending] = useActionState(createOrder, null)
return (
<form action={formAction}>
{/* 表单字段 */}
{state?.error && (
<div className="form-error">
<p>{state.error}</p>
</div>
)}
{state?.success && (
<div className="form-success">
<p>Order created! ID: {state.orderId}</p>
</div>
)}
<button type="submit" disabled={isPending}>
{isPending ? 'Processing...' : 'Place Order'}
</button>
</form>
)
}
性能优化
批量操作
typescript
// actions.ts
'use server'
export async function batchUpdateUsers(
prevState: any,
formData: FormData
) {
const updates = JSON.parse(formData.get('updates') as string)
// 使用事务批量更新
await db.$transaction(
updates.map(update =>
db.user.update({
where: { id: update.id },
data: update.data
})
)
)
revalidatePath('/users')
return { success: true, updated: updates.length }
}
// 客户端批量操作
'use client'
function BulkUserEditor({ users }) {
const [state, formAction, isPending] = useActionState(batchUpdateUsers, null)
async function handleSubmit(selectedUsers, updates) {
const formData = new FormData()
formData.append('updates', JSON.stringify(
selectedUsers.map(user => ({
id: user.id,
data: updates
}))
))
formAction(formData)
}
return (
<form action={formAction}>
{/* 用户选择和编辑 UI */}
<button type="submit" disabled={isPending}>
{isPending ? 'Updating...' : 'Update Selected Users'}
</button>
</form>
)
}
缓存策略
typescript
// actions.ts
'use server'
import { unstable_cache } from 'next/cache'
// 缓存数据库查询
const getUser = unstable_cache(
async (id: string) => {
return db.user.findUnique({
where: { id },
include: { posts: true }
})
},
['user'],
{ revalidate: 3600 } // 1 小时缓存
)
export async function updateUserProfile(
prevState: any,
formData: FormData
) {
const userId = formData.get('userId') as string
const name = formData.get('name') as string
await db.user.update({
where: { id: userId },
data: { name }
})
// 清除相关缓存
revalidatePath(`/users/${userId}`)
revalidatePath('/users')
return { success: true }
}
最佳实践总结
- 使用
useActionState处理表单状态:自动管理 loading 和 error 状态 - 乐观更新提升用户体验:在等待服务端响应时立即更新 UI
- 结构化错误处理:返回明确的错误信息,而不是抛出异常
- 批量操作优化性能:减少网络请求次数
- 合理使用缓存:避免不必要的数据库查询
小结
React 22 的 Server Actions 彻底改变了前端与后端的交互方式。通过 useActionState、useOptimistic 和 useTransition 等 Hook,可以构建出响应迅速、错误处理完善的现代表单。关键在于理解 Server Actions 的适用场景——它适合数据突变操作,而数据获取仍然应该使用 Server Components 和数据获取模式。
