npm install nestjs-zod zod

import { createZodDto } from 'nestjs-zod'
import { z } from 'zod'

const CredentialsSchema = z.object({
  username: z.string(),
  password: z.string(),
})

// 需要类来使用 DTO 作为类型
class CredentialsDto extends createZodDto(CredentialsSchema) {}

@Controller('auth')
class AuthController {
  // 使用全局 ZodValidationPipe (推荐)
  async signIn(@Body() credentials: CredentialsDto) {}
  async signIn(@Param() signInParams: SignInParamsDto) {}
  async signIn(@Query() signInQuery: SignInQueryDto) {}

  // 使用路由级别 ZodValidationPipe
  @UsePipes(ZodValidationPipe)
  async signIn(@Body() credentials: CredentialsDto) {}
}

// 使用控制器级别 ZodValidationPipe
@UsePipes(ZodValidationPipe)
@Controller('auth')
class AuthController {
  async signIn(@Body() credentials: CredentialsDto) {}
}

import { createZodDto } from 'nestjs-zod/dto'

import { ZodValidationPipe } from 'nestjs-zod'
import { APP_PIPE } from '@nestjs/core'

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useClass: ZodValidationPipe,
    },
  ],
})
export class AppModule {}

import { ZodValidationPipe } from 'nestjs-zod'

// 控制器级别
@UsePipes(ZodValidationPipe)
class AuthController {}

class AuthController {
  // 路由级别
  @UsePipes(ZodValidationPipe)
  async signIn() {}
}

import { ZodValidationPipe } from 'nestjs-zod'
import { UserDto, UserSchema } from './auth.contracts'

// 使用 schema
@UsePipes(new ZodValidationPipe(UserSchema))
// 使用 DTO
@UsePipes(new ZodValidationPipe(UserDto))
class AuthController {}

import { createZodValidationPipe } from 'nestjs-zod'

const MyZodValidationPipe = createZodValidationPipe({
  // 提供自定义验证异常工厂
  createValidationException: (error: ZodError) =>
    new BadRequestException('出错了'),
})

@UseGuards(new ZodGuard('body', CredentialsSchema))
@UseZodGuard('body', CredentialsSchema)

import { ZodGuard } from 'nestjs-zod'

// 控制器级别
@UseZodGuard('body', CredentialsSchema)
@UseZodGuard('params', CredentialsDto)
class MyController {}

class MyController {
  // 路由级别
  @UseZodGuard('query', CredentialsSchema)
  @UseZodGuard('body', CredentialsDto)
  async signIn() {}
}

import { createZodGuard } from 'nestjs-zod'

const MyZodGuard = createZodGuard({
  // 提供自定义验证异常工厂
  createValidationException: (error: ZodError) =>
    new BadRequestException('出错了'),
})

import { validate } from 'nestjs-zod'

validate(wrongThing, UserDto, (zodError) => new MyException(zodError)) // 抛出 MyException

const validatedUser = validate(
  user,
  UserDto,
  (zodError) => new MyException(zodError)
) // 成功时返回类型化的值

import { validate } from 'nestjs-zod'

// 验证失败时抛出 MyException
validate(wrongThing, UserDto, (zodError) => new MyException(zodError)) 

// 验证成功时返回类型化的值
const validatedUser = validate(
  user,
  UserDto,
  (zodError) => new MyException(zodError)
)

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "code": "too_small",
      "minimum": 8,
      "type": "string",
      "inclusive": true,
      "message": "String must contain at least 8 character(s)",
      "path": ["password"]
    }
  ]
}

const exception = new ZodValidationException(error)

@Catch(ZodValidationException)
export class ZodValidationExceptionFilter implements ExceptionFilter {
  catch(exception: ZodValidationException) {
    exception.getZodError() // -> 返回 ZodError
  }
}

@Module({
  ...
  providers: [
    ...,
    { provide: APP_INTERCEPTOR, useClass: ZodSerializerInterceptor },
  ],
})
export class AppModule {}

const UserSchema = z.object({ username: string() })

export class UserDto extends createZodDto(UserSchema) {}

@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @ZodSerializerDto(UserDto)
  getUser(id: number) {
    // 原生服务方法默认返回 { username: string, password: string }
    return this.userService.findOne(id) 
  }
}

import { patchNestJsSwagger } from 'nestjs-zod'

patchNestJsSwagger()

import { z } from 'zod'

const CredentialsSchema = z.object({
  username: z.string().describe('用户名字段'),
  password: z.string().describe('密码字段'),
})

import { zodToOpenAPI } from 'nestjs-zod'
import { z } from 'zod'

const SignUpSchema = z.object({
  username: z.string().min(8).max(20),
  password: z.string().min(8).max(20),
  sex: z
    .enum(['male', 'female', 'nonbinary'])
    .describe('我们尊重您的性别选择'),
  social: z.record(z.string().url())
})

const openapi = zodToOpenAPI(SignUpSchema)

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 8,
      "maxLength": 20
    },
    "password": {
      "type": "string",
      "minLength": 8,
      "maxLength": 20
    },
    "sex": {
      "description": "我们尊重您的性别选择",
      "type": "string",
      "enum": ["male", "female", "nonbinary"]
    },
    "social": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "format": "uri"
      }
    },
    "birthDate": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["username", "password", "sex", "social", "birthDate"]
}

import { patchNestJsSwagger } from 'nestjs-zod';
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  patchNestJsSwagger();
}h

// 1. 期望用户输入为 "string" 类型
// 2. 期望用户输入为有效日期 (通过 new Date 验证)
z.dateString()

// 转换为 Date 实例
// (在链式调用末尾使用，但要在 "describe" 之前)
z.dateString().cast()

// 期望字符串符合 RFC3339 的 "full-date" 格式
z.dateString().format('date')

// [默认格式]
// 期望字符串符合 RFC3339 的 "date-time" 格式
z.dateString().format('date-time')

// 期望日期是过去时间
z.dateString().past()

// 期望日期是将来时间
z.dateString().future()

// 期望年份大于或等于 2000
z.dateString().minYear(2000)

// 期望年份小于或等于 2025
z.dateString().maxYear(2025)

// 期望日期是工作日
z.dateString().weekDay()

// 期望日期是周末
z.dateString().weekend()

'past' | 'future'

// 期望用户输入为 "string" 类型
z.password()

// 期望密码长度大于或等于 8
z.password().min(8)

// 期望密码长度小于或等于 100
z.password().max(100)

// 期望密码至少包含一个数字
z.password().atLeastOne('digit')

// 期望密码至少包含一个小写字母
z.password().atLeastOne('lowercase')

// 期望密码至少包含一个大写字母
z.password().atLeastOne('uppercase')

// 期望密码至少包含一个特殊符号
z.password().atLeastOne('special')

z.json()

const error = {
  code: 'custom',
  message: '无效的日期，应该是过去时间',
  params: {
    isNestJsZod: true,
    code: 'invalid_date_string_direction',

    // payload 总是以扁平形式存在于此
    expected: 'past',
  },
  path: ['date'],
}

import { isNestJsZodIssue, NestJsZodIssue, ZodIssue } from '@nest-zod/z/frontend'

function mapToFormErrors(issues: ZodIssue[]) {
  for (const issue of issues) {
    if (isNestJsZodIssue(issue)) {
      // issue 是 NestJsZodIssue 类型
    }
  }
}

- import { z } from 'nestjs-zod/z'
+ import { z } from '@nest-zod/z'