next-safe-action 错误处理机制深度解析：从服务器错误到验证错误

next-safe-action 错误处理机制深度解析从服务器错误到验证错误【免费下载链接】next-safe-actionType safe and validated Server Actions in your Next.js project.项目地址: https://gitcode.com/gh_mirrors/ne/next-safe-actionnext-safe-action 作为 Next.js 项目中实现类型安全和验证的 Server Actions 解决方案其强大的错误处理机制是核心优势之一。本文将深入解析 next-safe-action 的错误处理体系帮助你理解三种不同的错误类型及其处理方式构建更健壮的应用程序。为什么 next-safe-action 的错误处理如此重要在传统的 Next.js Server Actions 中错误处理往往混乱且难以维护。next-safe-action 通过统一的错误分类和清晰的处理流程为开发者提供了完整的解决方案。无论是表单验证失败、服务器异常还是页面导航next-safe-action 都能优雅地处理。错误分类三大错误类型详解next-safe-action 将错误分为三类每种类型都有不同的产生方式和处理策略1. 验证错误 (Validation Errors)验证错误发生在客户端发送的数据不符合输入模式时。这类错误返回在结果对象中而非抛出始终对用户安全可见。const result await createUser({ name: , email: bad }); result.validationErrors; // → { name: { _errors: [Too short] }, email: { _errors: [Invalid email] } }验证错误有两种产生方式自动产生当 Standard Schema 验证失败时手动产生在服务器代码中调用returnValidationErrors()函数next-safe-action 错误分类体系验证错误、服务器错误和框架错误的完整架构2. 服务器错误 (Server Errors)服务器错误是意外的故障如数据库超时、API 失败或服务器代码中的 bug。next-safe-action 默认会捕获抛出的错误传递给handleServerError在客户端选项中定义将处理程序的返回值作为result.serverError返回const actionClient createSafeActionClient({ handleServerError(e) { console.error(Action error:, e.message); return e.message; // 客户端接收到的错误信息 }, });安全提示默认的handleServerError返回通用的 Something went wrong 消息。如果返回e.message请确保错误不包含敏感信息堆栈跟踪、数据库查询等。3. 框架导航/错误 (Framework Navigation/Errors)框架导航/错误是由 Next.js 函数如redirect()、notFound()、forbidden()和unauthorized()触发的导航事件。这些不是真正的错误而是 Next.js 用于触发导航的控制流机制。export const loginAction actionClient .inputSchema(loginSchema) .action(async ({ parsedInput }) { const user await authenticate(parsedInput); redirect(/dashboard); // 触发导航而非正常返回 });错误处理配置返回还是抛出next-safe-action 提供了灵活的配置选项让你决定如何处理错误抛出服务器错误 (throwServerError)设置throwServerError: true让服务器错误重新抛出而不是返回在result.serverError中export const myAction actionClient .inputSchema(schema) .action( async ({ parsedInput }) { // ... }, { throwServerError: true, // 服务器错误会抛出 } );抛出验证错误 (throwValidationErrors)可以在客户端级别或操作级别设置throwValidationErrors// 客户端级别应用于从此客户端创建的所有操作 const actionClient createSafeActionClient({ throwValidationErrors: true, }); // 操作级别覆盖此特定操作的客户端设置 export const myAction actionClient .inputSchema(schema) .action( async ({ parsedInput }) { // ... }, { throwValidationErrors: true, } );框架导航处理onNavigation 回调当操作中调用导航函数时useAction钩子会检测导航并将状态设置为hasNavigated触发onNavigation回调const { execute, hasNavigated } useAction(loginAction, { onNavigation: ({ navigationKind }) { if (navigationKind redirect) { // 用户被重定向 } else if (navigationKind notFound) { // 资源未找到 } }, });throwOnNavigation: true设置throwOnNavigation: true将导航错误传播到最近的错误边界。在 Next.js 中这会显示相应的错误页面// 导航错误传播到 Next.js 错误边界 const { execute } useAction(loginAction, { throwOnNavigation: true, });实战示例错误处理最佳实践示例 1表单验证与错误展示在 apps/playground/src/app/validation-errors/_components/validation-errors-client.tsx 中你可以看到如何处理不同类型的验证错误// 扁平化错误格式 const flattenedErrors result.validationErrors?.fieldErrors; // 嵌套错误格式 const nestedErrors result.validationErrors?.nested; // 自定义错误格式 const customErrors result.validationErrors?.custom;示例 2服务器错误处理查看 apps/playground/src/app/middleware/_actions/error-handling-action.ts 了解如何自定义服务器错误处理const errorHandlingClient createSafeActionClient({ handleServerError: (e) { // 自定义错误处理逻辑 return Custom error: ${e.message}; }, });示例 3导航错误处理在 apps/docs/content/docs/advanced/framework-errors.mdx 中详细说明了如何处理不同的导航类型函数navigationKindHTTP 状态码描述redirect(url)redirect303/307/308导航到另一个页面notFound()notFound404显示未找到页面forbidden()forbidden403显示禁止访问页面unauthorized()unauthorized401显示未授权页面错误处理总结表错误类型如何产生出现在哪里对用户安全验证错误模式解析失败或returnValidationErrors()result.validationErrors是服务器错误服务器代码/中间件中抛出的错误result.serverError取决于handleServerError框架错误redirect()、notFound()等发生导航N/A由 Next.js 处理核心源码路径要深入了解 next-safe-action 的错误处理实现可以查看以下核心文件错误分类定义packages/next-safe-action/src/validation-errors.ts客户端配置packages/next-safe-action/src/safe-action-client.ts钩子实现packages/next-safe-action/src/hooks.ts中间件支持packages/next-safe-action/src/middleware.ts最佳实践建议始终使用类型安全的错误处理利用 TypeScript 确保错误类型的安全性自定义错误消息根据业务需求定制用户友好的错误信息日志记录在handleServerError中添加适当的日志记录错误边界结合 React 错误边界处理未捕获的异常渐进式增强为不同类型的错误提供不同的用户体验结语next-safe-action 的错误处理机制为 Next.js Server Actions 提供了完整的解决方案。通过清晰的错误分类、灵活的处理策略和类型安全的 API开发者可以构建更加健壮和用户友好的应用程序。无论是简单的表单验证还是复杂的服务器端逻辑next-safe-action 都能帮助你优雅地处理各种错误场景。掌握这些错误处理技巧你将能够构建出更加稳定、可维护的 Next.js 应用程序为用户提供更好的体验。【免费下载链接】next-safe-actionType safe and validated Server Actions in your Next.js project.项目地址: https://gitcode.com/gh_mirrors/ne/next-safe-action创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考