validated-handler

Next.js 已验证处理器模式

适用于 Next.js App Router 的类型安全 API 路由处理器，支持自动 Zod 验证。

何时使用此技能

在以下情况下使用此技能：

• 构建 Next.js API 路由（App Router）
• 需要使用 Zod 自动验证输入
• 需要在各个 API 路由中统一处理错误
• 希望消除样板验证代码
• 使用 TypeScript 构建类型安全的 API

问题

如果没有已验证处理器，每个 API 路由都会重复编写验证代码：

// ❌ REPETITIVE - Every route looks like this
export async function GET(request: NextRequest) {
  try {
    // 1. Parse query params
    const { searchParams } = new URL(request.url);
    const rawPage = searchParams.get('page');
    const rawLimit = searchParams.get('limit');

    // 2. Validate each param manually
    if (!rawPage || isNaN(Number(rawPage))) {
      return NextResponse.json(
        { error: 'Invalid page parameter' },
        { status: 400 }
      );
    }

    if (!rawLimit || isNaN(Number(rawLimit))) {
      return NextResponse.json(
        { error: 'Invalid limit parameter' },
        { status: 400 }
      );
    }

    const page = Number(rawPage);
    const limit = Number(rawLimit);

    // 3. Validate ranges
    if (page < 1) {
      return NextResponse.json(
        { error: 'Page must be >= 1' },
        { status: 400 }
      );
    }

    if (limit < 1 || limit > 100) {
      return NextResponse.json(
        { error: 'Limit must be between 1 and 100' },
        { status: 400 }
      );
    }

    // 4. Finally, business logic
    const data = await fetchData(page, limit);
    return NextResponse.json(data);

  } catch (error) {
    console.error(error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

问题：

• 每个路由有 30 多行样板代码
• 手动验证容易出错
• 错误消息不一致
• 没有类型安全
• 难以维护 100 多个路由

解决方案：validatedHandler

创建一个可复用的处理器，将 Zod 验证与 Next.js API 路由结合起来：

// src/lib/api/handler.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

type ValidationSource = 'query' | 'body';

export function validatedHandler<T extends z.ZodType>(
  config: {
    input: { schema: T; source: ValidationSource };
  },
  handler: (ctx: { input: z.infer<T>; request: NextRequest }) => Promise<Response>,
) {
  return async (request: NextRequest): Promise<Response> => {
    try {
      // 1. Parse input based on source
      const rawInput = config.input.source === 'query'
        ? Object.fromEntries(new URL(request.url).searchParams)
        : await request.json();

      // 2. Validate with Zod schema
      const result = config.input.schema.safeParse(rawInput);

      if (!result.success) {
        return NextResponse.json({
          error: "Validation failed",
          details: result.error.issues.map(err => ({
            path: err.path.join("."),
            message: err.message,
          })),
        }, { status: 400 });
      }

      // 3. Call handler with typed data
      return await handler({ input: result.data, request });

    } catch (error) {
      console.error('API Error:', error);
      return NextResponse.json(
        { error: "Internal server error" },
        { status: 500 }
      );
    }
  };
}

使用示例

使用 validatedHandler 后，路由代码简洁且类型安全：

// src/app/api/schools/route.ts
import { validatedHandler } from '@/lib/api/handler';
import { paginationInputSchema } from '@/lib/api/pagination';
import { z } from 'zod';
import { db } from '@/lib/db';
import { schools } from '@/lib/db/schema';
import { ilike } from 'drizzle-orm';

// Define schema
const getSchoolsSchema = paginationInputSchema.extend({
  keyword: z.string().optional(),
  districtId: z.string().uuid().optional(),
});

// Use validatedHandler - clean and type-safe!
export const GET = validatedHandler({
  input: { source: 'query', schema: getSchoolsSchema }
}, async ({ input }) => {
  // input is fully typed: { page: number, limit: number, keyword?: string, districtId?: string }

  const schoolList = await db.query.schools.findMany({
    where: input.keyword
      ? ilike(schools.name, `%${input.keyword}%`)
      : undefined,
    limit: input.limit,
    offset: (input.page - 1) * input.limit,
  });

  return NextResponse.json(schoolList);
});

优点：

• ✅ 仅需 15 行，而非 50 多行
• ✅ 使用 Zod 自动验证
• ✅ 完整的 TypeScript 类型推断
• ✅ 统一的错误响应
• ✅ 无需手动解析
• ✅ 在一个地方维护验证逻辑

核心实现

完整的处理器实现

// src/lib/api/handler.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

type ValidationSource = 'query' | 'body';

interface HandlerConfig<T extends z.ZodType> {
  input: {
    schema: T;
    source: ValidationSource;
  };
}

interface HandlerContext<T extends z.ZodType> {
  input: z.infer<T>;
  request: NextRequest;
}

export function validatedHandler<T extends z.ZodType>(
  config: HandlerConfig<T>,
  handler: (ctx: HandlerContext<T>) => Promise<Response>,
) {
  return async (request: NextRequest): Promise<Response> => {
    try {
      // Parse input based on source
      let rawInput: unknown;

      if (config.input.source === 'query') {
        const { searchParams } = new URL(request.url);
        rawInput = Object.fromEntries(searchParams);
      } else if (config.input.source === 'body') {
        rawInput = await request.json();
      }

      // Validate with Zod
      const result = config.input.schema.safeParse(rawInput);

      if (!result.success) {
        return NextResponse.json({
          error: "Validation failed",
          details: result.error.issues.map(err => ({
            path: err.path.join("."),
            message: err.message,
          })),
        }, { status: 400 });
      }

      // Call handler with typed data
      return await handler({
        input: result.data,
        request,
      });

    } catch (error) {
      // Log error for debugging
      console.error('API Error:', error);

      // Return generic error to client
      return NextResponse.json(
        { error: "Internal server error" },
        { status: 500 }
      );
    }
  };
}

分页架构（可复用）

// src/lib/api/pagination.ts
import { z } from 'zod';

export const paginationInputSchema = z.object({
  page: z.coerce.number().min(1).default(1),
  limit: z.coerce.number().min(1).max(100).default(10),
});

export type PaginationInput = z.infer<typeof paginationInputSchema>;

export type PaginatedResponse<T> = {
  data: T[];
  page: number;
  limit: number;
  total: number;
  totalPages: number;
  nextPage: number | null;
  previousPage: number | null;
};

export function createPaginatedResponse<T>(
  data: T[],
  total: number,
  page: number,
  limit: number
): PaginatedResponse<T> {
  const totalPages = Math.ceil(total / limit);
  return {
    data,
    page,
    limit,
    total,
    totalPages,
    nextPage: page < totalPages ? page + 1 : null,
    previousPage: page > 1 ? page - 1 : null,
  };
}

常见模式

带查询参数的 GET 路由

// src/app/api/providers/route.ts
import { validatedHandler } from '@/lib/api/handler';
import { paginationInputSchema } from '@/lib/api/pagination';
import { z } from 'zod';

const getProvidersSchema = paginationInputSchema.extend({
  status: z.enum(['active', 'inactive']).optional(),
  specialty: z.string().optional(),
});

export const GET = validatedHandler({
  input: { source: 'query', schema: getProvidersSchema }
}, async ({ input }) => {
  const providers = await db.query.providers.findMany({
    where: buildWhereClause(input),
    limit: input.limit,
    offset: (input.page - 1) * input.limit,
  });

  return NextResponse.json(providers);
});

带请求体验证的 POST 路由

// src/app/api/providers/route.ts
import { validatedHandler } from '@/lib/api/handler';
import { z } from 'zod';

const createProviderSchema = z.object({
  name: z.string().min(1).max(255),
  email: z.string().email(),
  specialty: z.string().min(1),
  licenseNumber: z.string().optional(),
});

export const POST = validatedHandler({
  input: { source: 'body', schema: createProviderSchema }
}, async ({ input }) => {
  const newProvider = await db.insert(providers)
    .values(input)
    .returning();

  return NextResponse.json(newProvider[0], { status: 201 });
});

带路径参数的路由

// src/app/api/providers/[id]/route.ts
import { validatedHandler } from '@/lib/api/handler';
import { z } from 'zod';

const updateProviderSchema = z.object({
  name: z.string().min(1).max(255).optional(),
  email: z.string().email().optional(),
  specialty: z.string().min(1).optional(),
});

export const PATCH = validatedHandler({
  input: { source: 'body', schema: updateProviderSchema }
}, async ({ input, request }) => {
  // Extract path param manually
  const url = new URL(request.url);
  const id = url.pathname.split('/').pop();

  if (!id) {
    return NextResponse.json({ error: 'Invalid ID' }, { status: 400 });
  }

  const updated = await db.update(providers)
    .set(input)
    .where(eq(providers.id, id))
    .returning();

  return NextResponse.json(updated[0]);
});

带身份验证的路由

// src/app/api/providers/route.ts
import { validatedHandler } from '@/lib/api/handler';
import { auth } from '@/lib/auth';
import { z } from 'zod';

const getProvidersSchema = paginationInputSchema.extend({
  status: z.enum(['active', 'inactive']).optional(),
});

export const GET = validatedHandler({
  input: { source: 'query', schema: getProvidersSchema }
}, async ({ input, request }) => {
  // Authentication check
  const session = await auth(request);
  if (!session) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  // Authorization check
  if (!session.user.roles.includes('admin')) {
    return NextResponse.json(
      { error: 'Forbidden' },
      { status: 403 }
    );
  }

  // Business logic
  const providers = await db.query.providers.findMany({
    where: buildWhereClause(input),
    limit: input.limit,
    offset: (input.page - 1) * input.limit,
  });

  return NextResponse.json(providers);
});

高级模式

多个验证来源

// Validate both query and body
const searchSchema = z.object({
  query: z.string(),
});

const filtersSchema = z.object({
  category: z.string().optional(),
  priceMin: z.number().optional(),
  priceMax: z.number().optional(),
});

export const POST = async (request: NextRequest) => {
  // Validate query params
  const queryResult = searchSchema.safeParse(
    Object.fromEntries(new URL(request.url).searchParams)
  );

  if (!queryResult.success) {
    return NextResponse.json({ error: 'Invalid query' }, { status: 400 });
  }

  // Validate body
  const body = await request.json();
  const bodyResult = filtersSchema.safeParse(body);

  if (!bodyResult.success) {
    return NextResponse.json({ error: 'Invalid filters' }, { status: 400 });
  }

  // Use both
  const results = await search(queryResult.data.query, bodyResult.data);
  return NextResponse.json(results);
};

自定义错误响应

// src/lib/api/handler.ts (enhanced)
export function validatedHandler<T extends z.ZodType>(
  config: {
    input: { schema: T; source: ValidationSource };
    errorTransform?: (error: z.ZodError) => { error: string; details?: unknown };
  },
  handler: (ctx: { input: z.infer<T>; request: NextRequest }) => Promise<Response>,
) {
  return async (request: NextRequest): Promise<Response> => {
    try {
      const rawInput = config.input.source === 'query'
        ? Object.fromEntries(new URL(request.url).searchParams)
        : await request.json();

      const result = config.input.schema.safeParse(rawInput);

      if (!result.success) {
        const errorResponse = config.errorTransform
          ? config.errorTransform(result.error)
          : {
              error: "Validation failed",
              details: result.error.issues.map(err => ({
                path: err.path.join("."),
                message: err.message,
              })),
            };

        return NextResponse.json(errorResponse, { status: 400 });
      }

      return await handler({ input: result.data, request });
    } catch (error) {
      console.error('API Error:', error);
      return NextResponse.json(
        { error: "Internal server error" },
        { status: 500 }
      );
    }
  };
}

测试

处理器单元测试

// src/lib/api/handler.test.ts
import { validatedHandler } from './handler';
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

describe('validatedHandler', () => {
  it('should validate query params successfully', async () => {
    const schema = z.object({
      page: z.coerce.number(),
    });

    const handler = validatedHandler({
      input: { source: 'query', schema }
    }, async ({ input }) => {
      return NextResponse.json({ page: input.page });
    });

    const request = new NextRequest('http://localhost?page=2');
    const response = await handler(request);
    const data = await response.json();

    expect(data).toEqual({ page: 2 });
  });

  it('should return 400 for invalid input', async () => {
    const schema = z.object({
      page: z.coerce.number().min(1),
    });

    const handler = validatedHandler({
      input: { source: 'query', schema }
    }, async ({ input }) => {
      return NextResponse.json({ page: input.page });
    });

    const request = new NextRequest('http://localhost?page=0');
    const response = await handler(request);

    expect(response.status).toBe(400);
    const data = await response.json();
    expect(data.error).toBe('Validation failed');
  });
});

API 路由集成测试

// src/app/api/schools/route.test.ts
import { GET } from './route';
import { NextRequest } from 'next/server';

describe('GET /api/schools', () => {
  it('should return paginated schools', async () => {
    const request = new NextRequest('http://localhost/api/schools?page=1&limit=10');
    const response = await GET(request);
    const data = await response.json();

    expect(response.status).toBe(200);
    expect(data).toHaveProperty('data');
    expect(data).toHaveProperty('page', 1);
    expect(data).toHaveProperty('limit', 10);
  });

  it('should validate pagination parameters', async () => {
    const request = new NextRequest('http://localhost/api/schools?page=-1');
    const response = await GET(request);

    expect(response.status).toBe(400);
  });
});

优点总结

减少代码量

• 之前：每个路由包含验证代码时需要 50 多行
• 之后：每个路由需要 10 到 15 行
• 节省：代码量减少 70%

类型安全

• ✅ 根据 Zod 架构自动推断输入类型
• ✅ 无 any 类型或类型断言
• ✅ 在编译时验证架构用法

开发者体验

• ✅ 在一个地方定义验证
• ✅ 错误消息保持一致
• ✅ 清晰分离验证逻辑与业务逻辑
• ✅ 易于测试

可维护性

• ✅ 遵循 DRY 原则
• ✅ 在一个地方更改验证逻辑
• ✅ 在多个路由间复用架构
• ✅ 与框架无关的模式（适用于 Express、Fastify、Hono）

模式变体

用于 Express.js/Fastify

export function validatedHandler<T extends z.ZodType>(
  schema: T,
  handler: (input: z.infer<T>, req: Request, res: Response) => Promise<void>
) {
  return async (req: Request, res: Response) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      return res.status(400).json({ error: result.error });
    }
    await handler(result.data, req, res);
  };
}

用于 Hono

import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';

const app = new Hono();

app.get('/schools', zValidator('query', getSchoolsSchema), async (c) => {
  const input = c.req.valid('query');
  const schools = await fetchSchools(input);
  return c.json(schools);
});

相关技能

• toolchains-typescript-validation-zod - Zod 验证模式
• toolchains-nextjs-core - Next.js App Router 模式
• toolchains-universal-security-api-review - API 安全测试
• universal-verification-pre-merge - 合并前验证工作流