前后端数据校验与异常处理统一方案-源码库

前后端数据校验与异常处理统一方案：告别数据混乱与异常失控

在多年的全栈开发中，我深刻体会到：数据校验和异常处理如果各自为政，就会像两个说不同语言的团队在合作——沟通成本高，还容易出错。今天我要分享的这套统一方案，是我们团队经过多个项目迭代总结出来的最佳实践。

为什么需要统一的数据校验方案？

记得在早期项目中，我们前端用一套校验规则，后端又用另一套，结果用户提交时前端说“没问题”，后端却说“数据格式错误”。这种体验就像在餐厅点菜，服务员说“有这道菜”，厨师却说“做不了”。统一方案就是要解决这种尴尬。

第一步：定义统一的数据校验规则

我们选择 JSON Schema 作为校验标准的“通用语言”，因为它既能在前端使用，也能在后端使用。下面是我们用户注册接口的校验规则示例：


// user-schema.js
export const userRegisterSchema = {
  type: "object",
  required: ["username", "email", "password"],
  properties: {
    username: {
      type: "string",
      minLength: 3,
      maxLength: 20,
      pattern: "^[a-zA-Z0-9_]+$"
    },
    email: {
      type: "string",
      format: "email"
    },
    password: {
      type: "string",
      minLength: 6,
      maxLength: 32
    },
    age: {
      type: "number",
      minimum: 0,
      maximum: 150
    }
  }
};

踩坑提示：定义 schema 时要考虑前后端的一致性，比如邮箱格式、密码强度等规则要完全一致。

第二步：前端校验实现

在前端，我们使用 ajv 库进行校验。这里有个实战经验：校验失败时要给用户明确的错误提示。


// frontend-validation.js
import Ajv from "ajv";

const ajv = new Ajv();
const validate = ajv.compile(userRegisterSchema);

export function validateUserData(userData) {
  const isValid = validate(userData);
  if (!isValid) {
    // 将错误信息转换为用户友好的提示
    const errors = validate.errors.map(error => {
      return `${error.dataPath} ${error.message}`;
    });
    throw new ValidationError("数据校验失败", errors);
  }
  return true;
}

// 在组件中使用
try {
  validateUserData(formData);
  // 校验通过，发送请求
} catch (error) {
  if (error instanceof ValidationError) {
    // 显示友好的错误提示
    showErrorMessages(error.details);
  }
}

第三步：后端校验加固

前端校验是为了用户体验，后端校验是为了数据安全。我们使用相同的 schema 在后端进行二次校验：


// backend-validation.js
const Ajv = require("ajv");
const ajv = new Ajv();

function validateRequestBody(schema) {
  return (req, res, next) => {
    const validate = ajv.compile(schema);
    const isValid = validate(req.body);
    
    if (!isValid) {
      return res.status(400).json({
        code: "VALIDATION_ERROR",
        message: "请求参数校验失败",
        details: validate.errors
      });
    }
    next();
  };
}

// 在路由中使用
app.post('/api/register', 
  validateRequestBody(userRegisterSchema),
  userController.register
);

第四步：统一异常处理

异常处理的关键是格式统一。我们定义了标准的错误响应格式：


// error-handler.js
class AppError extends Error {
  constructor(code, message, details = null) {
    super(message);
    this.code = code;
    this.details = details;
  }
}

class ValidationError extends AppError {
  constructor(message, details) {
    super("VALIDATION_ERROR", message, details);
  }
}

class BusinessError extends AppError {
  constructor(message, details) {
    super("BUSINESS_ERROR", message, details);
  }
}

// 全局错误处理中间件
function errorHandler(err, req, res, next) {
  if (err instanceof AppError) {
    return res.status(400).json({
      code: err.code,
      message: err.message,
      details: err.details,
      timestamp: new Date().toISOString()
    });
  }
  
  // 未知错误
  console.error('Unexpected error:', err);
  res.status(500).json({
    code: "INTERNAL_ERROR",
    message: "服务器内部错误",
    timestamp: new Date().toISOString()
  });
}

第五步：前后端错误信息映射

为了让前端能直接显示后端返回的错误，我们建立了错误码映射表：


// error-mapping.js
export const errorMessages = {
  VALIDATION_ERROR: "数据校验失败，请检查输入",
  BUSINESS_ERROR: "业务逻辑错误",
  USER_EXISTS: "用户已存在",
  INVALID_CREDENTIALS: "用户名或密码错误"
};

// 前端错误处理
function handleApiError(error) {
  const message = errorMessages[error.code] || error.message;
  showToast(message);
  
  // 如果是校验错误，可以细化显示
  if (error.code === 'VALIDATION_ERROR' && error.details) {
    highlightErrorFields(error.details);
  }
}