Next-Safe-Action 中导航函数状态处理的演进与最佳实践

背景分析

在 Next.js 应用开发中，服务端动作(Server Actions)与客户端交互的状态管理一直是个重要课题。next-safe-action 作为专门优化这一流程的库，近期在处理导航函数状态时遇到了一个值得探讨的行为模式：当在服务端动作中调用 next/navigation 的导航函数（如 notFound()、redirect() 等）时，会意外触发 onSuccess 回调而非预期的 onError 回调。

问题本质

这个现象源于 Next.js 导航函数的底层实现机制。实际上，这些导航函数都是通过抛出特殊异常来实现页面跳转或状态改变的：

1. redirect() 抛出 REDIRECT 异常
2. notFound() 抛出 NOT_FOUND 异常
3. forbidden() 抛出自定义异常

在 next-safe-action 的原始设计中，这些异常被归类为"成功状态"，因为从技术实现角度看，它们确实完成了预期的导航功能。但这种设计在用户体验层面存在矛盾点：

• 开发者直觉上会将 404(notFound) 或 403(forbidden) 视为错误状态
• 只有 redirect 更符合"成功跳转"的语义

解决方案演进

经过社区讨论，next-safe-action 在 v8 版本中引入了更精细的状态处理机制：

1. 新增 onNavigation 专用回调
   专门处理所有导航函数触发的情况，与传统的 onSuccess/onError 解耦

2. 引入 hasNavigated 状态标志
   在钩子中明确标记是否发生了导航跳转

3. 分类处理导航函数

   • redirect() 保持触发 onSuccess（保持向后兼容）
   • notFound()/forbidden() 改为触发 onError（更符合直觉）

最佳实践建议

基于新的架构，推荐以下实现模式：

const { execute, hasNavigated } = useAction(myAction, {
  onSuccess: (data) => {
    // 处理纯数据成功的场景
  },
  onError: (error) => {
    // 处理业务错误及404/403等
  },
  onNavigation: (navType) => {
    // 专门处理导航事件
    console.log(`导航触发: ${navType}`) 
  }
})

技术决策背后的思考

这种改进体现了几个重要的设计原则：

1. 关注点分离
   将导航状态从业务状态中分离，使状态机更加清晰

2. 渐进式增强
   通过新增 API 而非直接修改现有行为，保证向后兼容

3. 开发者体验优先
   让 API 行为更符合开发者心理模型

升级指南

对于从 v7 迁移到 v8 的用户：

1. 检查所有使用导航函数的 action
2. 将导航相关逻辑迁移到 onNavigation 回调
3. 对于 notFound/forbidden 的情况，更新错误处理逻辑
4. 利用 hasNavigated 状态优化 UI 响应

这种改进使得 next-safe-action 在复杂场景下的状态管理更加精准和可预测，为开发者提供了更完善的工具链来处理 Next.js 应用的各类交互场景。