Next-Safe-Action 中 executeAsync 方法的 Promise 行为解析

问题现象

在使用 next-safe-action 库时，开发者发现了一个有趣的行为：当通过 executeAsync 方法调用服务器动作时，即使服务器动作内部抛出了错误，返回的 Promise 仍然会以 fulfilled 状态完成，而不是预期的 rejected 状态。

技术背景

next-safe-action 是一个为 Next.js 应用提供类型安全服务器动作的库。它通过封装 Next.js 的服务器动作，提供了更好的类型安全和错误处理机制。其中 executeAsync 方法是常用的异步执行服务器动作的接口。

行为分析

在常规的 Promise 使用中，当异步操作抛出错误时，Promise 应该进入 rejected 状态。然而 next-safe-action 的设计选择了不同的路径：

1. 设计意图：库作者明确指出这不是 bug，而是有意为之的设计决策
2. 错误处理机制：所有错误（包括服务器错误和验证错误）都会被捕获并作为结果对象的一部分返回
3. 结果对象结构：返回的结果对象包含三个可能字段：
   • data：成功时的返回数据
   • validationErrors：验证错误信息
   • serverError：服务器错误信息

解决方案

开发者有三种方式来处理这种特殊行为：

1. 全局配置：通过 createSafeActionClient 的 handleServerError 选项全局配置错误处理行为
2. 动作级别配置：在定义动作时使用 throwServerError 或 throwValidationErrors 选项
3. 手动处理：如示例代码所示，可以手动检查结果对象并决定是否抛出错误

最佳实践建议

1. 明确错误处理策略：根据应用需求决定是使用默认的返回错误对象方式，还是配置为抛出错误
2. 类型安全：无论采用哪种方式，都应充分利用 TypeScript 的类型系统确保类型安全
3. 一致性：在整个项目中保持统一的错误处理风格，避免混用不同方式

技术思考

这种设计体现了"错误也是数据"的理念，将错误视为正常业务流程的一部分而非异常情况。这种模式在某些场景下可能更有利于：

• 简化错误处理逻辑
• 保持数据流的可预测性
• 便于在 UI 中统一处理各种状态

但同时也会带来与传统 Promise 行为不一致的认知成本，开发者需要根据项目实际情况权衡选择。