safe-action-advanced

next-safe-action 高级功能

概述

功能	使用场景
绑定参数	通过 .bind() 向操作传递额外参数（例如资源 ID）
元数据	为操作附加类型化元数据，以便在中间件中使用
框架错误	在操作中处理 redirect、notFound、forbidden、unauthorized
类型工具	从操作函数和中间件推断类型

服务端级操作回调

.action() 的第二个参数接受在服务端运行的回调（不是客户端钩子）：

export const createPost = authActionClient
  .inputSchema(schema)
  .action(
    async ({ parsedInput, ctx }) => {
      const post = await db.post.create(parsedInput);
      return post;
    },
    {
      onSuccess: async ({ data, parsedInput, ctx, metadata, clientInput }) => {
        // Runs on the server after successful execution
        await invalidateCache("posts");
      },
      onError: async ({ error, metadata, ctx, clientInput, bindArgsClientInputs }) => {
        // error: { serverError?, validationErrors? }
        await logError(error);
      },
      onSettled: async ({ result }) => {
        // Always runs
        await recordMetrics(result);
      },
      onNavigation: async ({ navigationKind }) => {
        // Runs when a framework error (redirect, notFound, etc.) occurs
        console.log("Navigation:", navigationKind);
      },
    }
  );

这些回调与钩子回调（useAction({ onSuccess })）不同——服务端回调在 Node.js 运行时中运行，钩子回调则在浏览器中运行。

throwServerError

重新抛出服务端错误，而不是将其作为 result.serverError 返回：

export const myAction = actionClient
  .inputSchema(schema)
  .action(serverCodeFn, {
    throwServerError: true,
    // The handled server error (return of handleServerError) is thrown
  });

不要将它与 returnServerError() 混淆：throwServerError 会抛出经过处理的错误（即经过 handleServerError 处理后的错误），而不是返回该错误；returnServerError(payload) 则会在 result.serverError 中返回一个类型化的预期错误，并完全绕过 handleServerError（请参阅 safe-action-client 技能中的错误处理文档）。