Next-Safe-Action 项目即将支持自定义服务错误类型

在服务端与客户端交互的过程中，错误处理一直是开发者需要重点关注的环节。Next-Safe-Action 作为一个专注于提升 Next.js 应用安全性的库，其最新版本(v7)将带来一项重要改进：允许开发者自定义服务端错误的返回类型。

当前限制与改进方向

目前 Next-Safe-Action 在处理服务端错误时，强制要求错误信息必须是字符串类型。这在简单场景下尚可接受，但对于需要返回结构化错误信息的复杂应用就显得力不从心。例如：

• 需要同时返回错误码和详细描述
• 需要携带额外的错误上下文信息
• 需要区分不同类型的错误响应

新版解决方案

v7版本将引入泛型支持，允许开发者通过配置自定义错误类型。核心改进点包括：

1. 类型安全：通过TypeScript泛型确保整个错误处理流程的类型一致性
2. 灵活处理：可以根据不同错误类型返回不同结构的数据
3. 向后兼容：默认仍支持字符串类型，确保平滑升级

典型使用场景

假设我们需要处理以下两种错误情况：

// API返回的典型错误结构
interface ApiError {
  code: number;
  message: string;
  additional?: Record<string, unknown>;
}

// 特殊业务错误
interface BusinessError {
  instance: string;
  response: unknown;
}

新版实现方式：

const action = createSafeActionClient<ApiError | BusinessError>({
  handleReturnedServerError(e) {
    if (e instanceof FetchError) {
      return {
        code: e.response?._data?.code,
        message: e.response?._data?.message,
        additional: e.response?._data?.additional,
      };
    }

    if (e instanceof CustomError) {
      return {
        instance: e.response?._data?.instance,
        response: e.response?._data?.response,
      }
    }

    return DEFAULT_ERROR;
  }
});

技术实现要点

1. 类型推断：客户端会自动推断出正确的错误类型
2. 错误处理：开发者可以针对不同错误来源进行差异化处理
3. 默认值：提供合理的默认错误结构，避免类型不一致

升级建议

对于现有项目：

1. 小规模项目可以直接升级，继续使用字符串错误
2. 复杂项目可以逐步迁移到结构化错误
3. 建议在类型定义中明确区分预期错误和意外错误

这项改进将使Next-Safe-Action在错误处理方面更加灵活和强大，特别适合企业级应用和需要精细错误管理的场景。开发者现在可以构建类型更安全、信息更丰富的错误处理流程，提升应用的可维护性和用户体验。