基于NestJS+GraphQL+React+Apollo技术栈的REST与GraphQL通用验证错误格式设计咨询

我在几个基于NestJS + React的全栈项目里正好踩过这个统一验证错误格式的坑，之前也遇到过类型化不足、前后端映射容易出错的问题，分享下我总结出来的一套简洁且类型安全的方案，应该能解决你的需求：

第一步：定义跨端统一的错误结构 #

首先要在前后端（建议用TypeScript共享类型定义，比如放在项目的共享目录或者私有npm包）约定好验证错误的核心结构，避免前后端各自为战：

// 通用验证错误项类型
export interface ValidationErrorItem {
  field: string;       // 触发错误的字段名（比如email、password）
  code: string;        // 错误标识（比如'email.uniq'、'password.minLength'，方便前端映射多语言）
  message?: string;    // 可选：后端返回的默认提示，前端可覆盖
}

// 统一的验证错误响应结构
export interface ValidationErrorResponse {
  statusCode: number;
  error: string;       // 固定为'Validation Error'，方便前端识别
  details: ValidationErrorItem[];
}

第二步：后端（REST/GraphQL）统一输出格式 #

REST接口处理 #

调整NestJS的全局ValidationPipe，让它输出我们约定好的结构：

import { ValidationPipe, ValidationError, BadRequestException } from '@nestjs/common';

app.useGlobalPipes(
  new ValidationPipe({
    exceptionFactory: (errors: ValidationError[]) => {
      const details: ValidationErrorItem[] = errors.map(error => {
        // 把class-validator的约束名转成更简洁的code格式
        const constraintKey = Object.keys(error.constraints)[0];
        // 比如把@UniqEmail的约束名'uniqEmail'转成'email.uniq'
        const normalizedCode = `${error.property}.${constraintKey.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
        return {
          field: error.property,
          code: normalizedCode,
          message: error.constraints[constraintKey]
        };
      });
      return new BadRequestException({
        statusCode: 400,
        error: 'Validation Error',
        details
      } as ValidationErrorResponse);
    },
    transform: true,
    whitelist: true
  }),
);

GraphQL接口处理 #

利用NestJS GraphQL模块的formatError，把class-validator的错误转换成统一结构：

import { GraphQLError } from 'graphql';
import { ValidationErrorResponse } from './shared-types';

export function formatGraphQLValidationError(error: GraphQLError): GraphQLError {
  // 判断是否为验证错误（class-validator的错误会挂载在originalError里）
  const originalError = error.extensions?.originalError as any;
  if (originalError?.response?.details) {
    const validationDetails = originalError.response.details as ValidationErrorItem[];
    return new GraphQLError('Validation Error', {
      extensions: {
        code: 'BAD_REQUEST',
        details: validationDetails,
        // 保留其他必要的扩展字段
        ...error.extensions
      }
    });
  }

  // 非验证错误按原有逻辑处理
  if (error.extensions?.code === 'INTERNAL_SERVER_ERROR') {
    return { ...error, message: '服务器内部错误' };
  }
  return error;
}

// 在GraphQL模块配置中使用
GraphQLModule.forRoot({
  // 其他配置...
  formatError: formatGraphQLValidationError
})

第三步：前端统一错误解析与映射 #

不管是REST请求（Axios）还是GraphQL突变（Apollo），都用一个通用函数来解析错误，结合多语言库（比如react-i18next）完成映射：

import { useTranslation } from 'react-i18next';
import { ValidationErrorItem } from '../shared-types';

// 通用验证错误解析函数
export function parseValidationErrors(error: any): Record<string, string> {
  const errors: Record<string, string> = {};
  let details: ValidationErrorItem[] = [];

  // 处理REST请求错误（Axios）
  if (error.response?.data?.details) {
    details = error.response.data.details;
  }
  // 处理GraphQL错误（Apollo）
  else if (error.graphQLErrors?.length) {
    error.graphQLErrors.forEach((gqlErr: any) => {
      if (gqlErr.extensions?.details) {
        details = [...details, ...gqlErr.extensions.details];
      }
    });
  }

  // 结合i18n映射多语言提示
  const { t } = useTranslation();
  details.forEach(item => {
    errors[item.field] = t(`validation.${item.code}`);
  });

  return errors;
}

// 在React表单中使用（以Formik为例）
// REST提交示例
async function handleSubmit(values: { email: string; password: string }) {
  try {
    await axios.post('/auth/register', values);
    // 成功逻辑
  } catch (err) {
    const validationErrors = parseValidationErrors(err);
    setErrors(validationErrors);
  }
}

// GraphQL突变示例
const [register] = useMutation(REGISTER_MUTATION, {
  onError: (err) => {
    const validationErrors = parseValidationErrors(err);
    setErrors(validationErrors);
  }
});

额外优化建议 #

1. 类型共享：把ValidationErrorItem这类跨端类型放在项目的共享目录，或者打包成私有npm包，前后端共用，彻底避免类型不匹配的问题。
2. 约束名标准化：自定义class-validator装饰器时，把约束名设得更简洁（比如@UniqEmail的约束名直接用'uniq'，而不是'uniqEmail'），这样生成的code更清晰。
3. 错误码统一：不管REST还是GraphQL，验证错误的code都统一为'BAD_REQUEST'，前端只需要判断这个code就能快速识别是验证错误。

内容的提问来源于stack exchange，提问作者Michael Rerberg