next-safe-action으로 타입 안전한 Server Action 만들기 — 미들웨어 인증과 Vitest 테스트까지

// 기존 방식 — 액션마다 이 보일러플레이트가 반복됩니다
export async function updateProfile(data: unknown) {
  const session = await auth();
  if (!session?.user) throw new Error("Unauthorized"); // 매번 직접 체크
 
  const parsed = profileSchema.safeParse(data);
  if (!parsed.success) return { error: parsed.error.flatten() }; // 에러 구조도 제각각
 
  await db.user.update({ where: { id: session.user.id as string }, data: parsed.data });
}

// next-safe-action 방식 — 인증과 검증이 자동으로 처리됩니다
export const updateProfile = authActionClient
  .schema(profileSchema)
  .action(async ({ parsedInput, ctx }) => {
    // ctx.user, parsedInput 모두 타입 단언 없이 완전히 추론됩니다
    await db.user.update({ where: { id: ctx.user.id }, data: parsedInput });
    return { success: true };
  });

// lib/safe-action.ts
import { createSafeActionClient, ActionError } from "next-safe-action";
import { auth } from "@/lib/auth";
 
export const actionClient = createSafeActionClient({
  handleReturnedServerError(err) {
    // ActionError는 메시지를 클라이언트에 그대로 노출하고,
    // 일반 Error는 이 핸들러를 통해 마스킹됩니다
    if (err instanceof ActionError) return err.message;
    return "서버 오류가 발생했습니다.";
  },
}).use(async ({ next }) => {
  console.log("[action] start");
  const result = await next();
  console.log("[action] end");
  return result;
});
 
// actionClient를 확장 — 세션 여부 확인 및 ctx.user 주입
export const authActionClient = actionClient.use(async ({ next }) => {
  const session = await auth();
  if (!session?.user) throw new Error("Unauthorized");
  return next({ ctx: { user: session.user } });
});
 
// authActionClient를 확장 — 관리자 전용
export const adminActionClient = authActionClient.use(async ({ ctx, next }) => {
  if (ctx.user.role !== "admin") throw new ActionError("관리자 권한이 필요합니다.");
  return next({ ctx });
});

// actions/update-profile.ts
"use server";
import { z } from "zod";
import { authActionClient } from "@/lib/safe-action";
import { db } from "@/lib/db";
 
export const updateProfile = authActionClient
  .schema(z.object({ name: z.string().min(1) }))
  .action(async ({ parsedInput, ctx }) => {
    // ctx.user는 별도 타입 선언 없이 완전히 추론됩니다
    await db.user.update({
      where: { id: ctx.user.id },
      data: { name: parsedInput.name },
    });
    return { success: true, name: parsedInput.name };
  });

// actions/delete-user.ts
"use server";
import { z } from "zod";
import { authActionClient } from "@/lib/safe-action";
import { ActionError } from "next-safe-action";
import { db } from "@/lib/db";
 
export const deleteUser = authActionClient
  .use(async ({ ctx, next }) => {
    if (ctx.user.role !== "admin") {
      // ActionError를 사용하면 이 메시지가 클라이언트에 그대로 전달됩니다
      throw new ActionError("관리자 권한이 필요합니다.");
    }
    return next({ ctx });
  })
  .schema(z.object({ userId: z.string().cuid() }))
  .action(async ({ parsedInput }) => {
    await db.user.delete({ where: { id: parsedInput.userId } });
    return { deleted: parsedInput.userId };
  });

// vitest.config.ts
import { defineConfig } from "vitest/config";
import path from "path";
 
export default defineConfig({
  test: {
    environment: "node",
  },
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./"),
    },
  },
});

// actions/delete-user.test.ts
import { vi, describe, it, expect, beforeEach } from "vitest";
import { deleteUser } from "./delete-user";
 
vi.mock("@/lib/auth", () => ({
  auth: vi.fn(),
}));
vi.mock("@/lib/db", () => ({
  db: { user: { delete: vi.fn() } },
}));
 
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
 
describe("deleteUser", () => {
  beforeEach(() => vi.clearAllMocks());
 
  it("관리자는 사용자를 삭제할 수 있다", async () => {
    vi.mocked(auth).mockResolvedValue({
      user: { id: "admin-1", role: "admin" },
    } as any);
    // Auth.js의 Session 타입은 완전히 채워진 객체를 반환하지 않아
    // 테스트 픽스처에서는 as any가 불가피합니다
 
    vi.mocked(db.user.delete).mockResolvedValue({
      id: "user-1",
      name: "홍길동",
      email: "hong@example.com",
    });
 
    const result = await deleteUser({ userId: "cld9oixx0000008l5etfg5f3i" });
 
    expect(result?.data?.deleted).toBe("cld9oixx0000008l5etfg5f3i");
    expect(db.user.delete).toHaveBeenCalledWith(
      expect.objectContaining({ where: { id: "cld9oixx0000008l5etfg5f3i" } })
    );
  });
 
  it("일반 사용자가 호출하면 serverError가 반환된다", async () => {
    vi.mocked(auth).mockResolvedValue({
      user: { id: "user-1", role: "user" },
    } as any);
 
    const result = await deleteUser({ userId: "cld9oixx0000008l5etfg5f3i" });
 
    // ActionError("관리자 권한이 필요합니다.")가 serverError로 래핑됩니다
    expect(result?.serverError).toBeDefined();
    expect(db.user.delete).not.toHaveBeenCalled();
  });
 
  it("비로그인 상태에서는 serverError가 반환된다", async () => {
    vi.mocked(auth).mockResolvedValue(null);
 
    const result = await deleteUser({ userId: "cld9oixx0000008l5etfg5f3i" });
 
    expect(result?.serverError).toBeDefined();
    expect(db.user.delete).not.toHaveBeenCalled();
  });
 
  it("유효하지 않은 userId 형식은 validationErrors를 반환한다", async () => {
    vi.mocked(auth).mockResolvedValue({
      user: { id: "admin-1", role: "admin" },
    } as any);
 
    const result = await deleteUser({ userId: "not-a-cuid" });
 
    expect(result?.validationErrors).toBeDefined();
    expect(db.user.delete).not.toHaveBeenCalled();
  });
});

// lib/middlewares/auth-middleware.ts
export async function authMiddleware({
  auth,
  next,
  ctx,
}: {
  auth: () => Promise<{ user: { id: string; role: string } } | null>;
  next: (args: { ctx: { user: { id: string; role: string } } }) => Promise<unknown>;
  ctx: Record<string, unknown>;
}) {
  const session = await auth();
  if (!session?.user) throw new Error("Unauthorized");
  return next({ ctx: { ...ctx, user: session.user } });
}

// lib/safe-action.ts — authActionClient를 순수 함수로 연결하는 방식
import { authMiddleware } from "@/lib/middlewares/auth-middleware";
import { auth } from "@/lib/auth";
 
export const authActionClient = actionClient.use(({ ctx, next }) =>
  authMiddleware({ auth, ctx, next })
);

// lib/middlewares/auth-middleware.test.ts
import { vi, describe, it, expect } from "vitest";
import { authMiddleware } from "./auth-middleware";
 
describe("authMiddleware", () => {
  it("세션이 없으면 Unauthorized 에러를 던진다", async () => {
    const mockAuth = vi.fn().mockResolvedValue(null);
    const mockNext = vi.fn();
 
    await expect(
      authMiddleware({ auth: mockAuth, next: mockNext, ctx: {} })
    ).rejects.toThrow("Unauthorized");
 
    expect(mockNext).not.toHaveBeenCalled();
  });
 
  it("세션이 있으면 ctx에 user를 주입하고 next를 호출한다", async () => {
    const user = { id: "u1", role: "user" };
    const mockAuth = vi.fn().mockResolvedValue({ user });
    const mockNext = vi.fn().mockResolvedValue({ data: "ok" });
 
    await authMiddleware({ auth: mockAuth, next: mockNext, ctx: {} });
 
    expect(mockNext).toHaveBeenCalledWith({ ctx: { user } });
  });
});

// components/profile-form.tsx
"use client";
import { useAction } from "next-safe-action/hooks";
import { updateProfile } from "@/actions/update-profile";
import { toast } from "sonner";
 
export function ProfileForm() {
  const { execute, status, result } = useAction(updateProfile, {
    onSuccess: () => toast.success("저장되었습니다"),
    onError: ({ error }) =>
      toast.error(error.serverError ?? "알 수 없는 오류가 발생했습니다"),
  });
 
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const formData = new FormData(e.currentTarget);
        execute({ name: formData.get("name") as string });
      }}
    >
      <input name="name" />
      {result.validationErrors?.name && (
        <p className="text-red-500">
          {result.validationErrors.name._errors[0]}
        </p>
      )}
      <button type="submit" disabled={status === "executing"}>
        {status === "executing" ? "저장 중..." : "저장"}
      </button>
    </form>
  );
}