REST API 开发：高效处理错误与异常

引言：为什么 REST API 需要专业的错误处理

在微服务架构盛行的今天，REST API 已成为前后端交互的核心通道。一个设计良好的 API 不仅要能正确处理请求，更需要在出现错误时提供清晰、一致的反馈。根据统计，超过 60% 的 API 调用失败源于不规范的错误处理，这直接导致用户体验下降、调试成本增加，甚至引发安全漏洞。

本文将系统讲解 REST API 开发中的错误处理策略，涵盖从 HTTP 状态码规范到自定义错误响应设计的全流程，通过 Spring Boot 和 Express.js 的代码示例，帮助开发者构建更健壮的 API 服务。

REST API 常见错误类型解析

4xx 客户端错误

• 400 Bad Request：请求参数格式错误（如 JSON 解析失败）
• 401 Unauthorized：未认证的请求（缺少或无效的 Token）
• 403 Forbidden：认证通过但权限不足
• 404 Not Found：请求的资源不存在
• 409 Conflict：资源状态冲突（如重复提交）

5xx 服务器错误

• 500 Internal Server Error：服务器内部未捕获的异常
• 502 Bad Gateway：网关或代理服务器收到无效响应
• 503 Service Unavailable：服务暂时不可用（如数据库连接池耗尽）

提示：根据 HTTP/1.1 规范，4xx 错误表示客户端问题，5xx 表示服务端问题。正确使用状态码能减少客户端的调试成本。

错误处理的核心原则

1. 统一错误响应格式

{
  "timestamp": "2026-10-02T08:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "code": "VALIDATION_FAILED",
  "message": "用户名不能包含特殊字符",
  "path": "/api/users",
  "details": [
    {
      "field": "username",
      "rejectedValue": "admin@123",
      "message": "只能包含字母和数字"
    }
  ]
}

2. 错误信息分级处理

3. 避免泄露敏感信息

❌ 错误示例：

{
  "message": "SQLState: 28P01, 密码不正确"
}

✅ 正确做法：

{
  "message": "用户名或密码错误",
  "code": "AUTH_FAILED"
}

主流框架的异常捕获实现

Spring Boot 实现方案

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 处理方法参数校验失败
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
        List<FieldError> fieldErrors = ex.getBindingResult().getFieldErrors();
        List<ErrorDetail> details = fieldErrors.stream()
            .map(error -> new ErrorDetail(
                error.getField(),
                error.getRejectedValue(),
                error.getDefaultMessage()))
            .collect(Collectors.toList());

        ErrorResponse response = new ErrorResponse(
            HttpStatus.BAD_REQUEST.value(),
            "VALIDATION_FAILED",
            "参数校验失败",
            details);

        return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
    }

    // 处理数据库操作异常
    @ExceptionHandler(DataIntegrityViolationException.class)
    public ResponseEntity<ErrorResponse> handleDataExceptions(DataIntegrityViolationException ex) {
        // 通过异常消息判断具体类型
        if (ex.getMessage().contains("duplicate key")) {
            return ResponseEntity.status(HttpStatus.CONFLICT)
                .body(new ErrorResponse(409, "DUPLICATE_KEY", "数据已存在"));
        }
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse(500, "DB_ERROR", "数据库操作失败"));
    }
}

Express.js 实现方案

// 自定义错误类
class AppError extends Error {
  constructor(message, statusCode, code) {
    super(message);
    this.statusCode = statusCode;
    this.code = code;
    this.isOperational = true;
    Error.captureStackTrace(this, this.constructor);
  }
}

// 全局错误处理中间件
app.use((err, req, res, next) => {
  err.statusCode = err.statusCode || 500;
  err.code = err.code || 'INTERNAL_ERROR';

  const response = {
    status: err.statusCode,
    error: err.code,
    message: err.isOperational ? err.message : '服务器内部错误',
    stack: process.env.NODE_ENV === 'development' ? err.stack : null
  };

  // 特定错误处理
  if (err.name === 'ValidationError') {
    response.status = 400;
    response.code = 'VALIDATION_FAILED';
    response.details = err.errors.map(e => ({
      field: e.path,
      message: e.message
    }));
  }

  res.status(err.statusCode).json(response);
});

// 使用示例
app.post('/api/users', async (req, res, next) => {
  try {
    if (!isValidUsername(req.body.username)) {
      throw new AppError('用户名格式无效', 400, 'INVALID_USERNAME');
    }
    // 业务逻辑...
  } catch (err) {
    next(err);
  }
});

实战案例：数据库查询异常处理

场景描述

当用户查询不存在的订单时，API 应返回 404 状态码；当数据库连接失败时，应返回 503 并重试机制。

Spring Boot 实现

@GetMapping("/orders/{id}")
public ResponseEntity<?> getOrder(@PathVariable Long id) {
    try {
        Order order = orderService.getById(id);
        if (order == null) {
            throw new ResourceNotFoundException("订单不存在");
        }
        return ResponseEntity.ok(order);
    } catch (ResourceNotFoundException ex) {
        throw new AppException(HttpStatus.NOT_FOUND, "ORDER_NOT_FOUND", ex.getMessage());
    } catch (CannotGetJdbcConnectionException ex) {
        throw new AppException(HttpStatus.SERVICE_UNAVAILABLE, "DB_CONNECTION_FAILED", 
            "数据库服务暂时不可用，请稍后重试");
    }
}

响应结构设计

interface ErrorResponse {
  timestamp: string;       // ISO 8601 时间格式
  status: number;          // HTTP 状态码
  error: string;           // 状态码描述（如 "Not Found"）
  code: string;            // 业务错误码
  message: string;         // 用户友好提示
  path?: string;           // 请求路径
  details?: ErrorDetail[]; // 详细错误信息
  retryAfter?: number;     // 重试建议时间（毫秒）
}

常见问题

Q：如何选择合适的 HTTP 状态码？

A：遵循以下决策树：

1. 客户端问题 → 4xx
2. 服务器问题 → 5xx
3. 资源不存在 → 404
4. 权限问题 → 403（认证失败用 401）
5. 业务冲突 → 409
6. 请求体过大 → 413

Q：是否需要记录所有错误日志？

A：建议分级记录：

• 操作型错误（如参数校验）→ INFO 级别
• 业务型错误（如订单已存在）→ WARN 级别
• 系统级错误（如数据库连接失败）→ ERROR 级别
• 未捕获异常 → FATAL 级别并触发告警

小结

优秀的错误处理机制是 REST API 成熟度的重要标志。通过本文的学习，你应该掌握：

1. 正确使用 HTTP 状态码传达错误类型
2. 设计结构化的错误响应格式
3. 在主流框架中实现全局异常捕获
4. 区分公开错误信息和内部调试信息

建议在实际项目中建立错误码规范文档，并使用 Postman 或 Swagger 等工具进行错误响应测试。记住：好的错误处理不仅能提升开发效率，更是保障系统稳定性的最后一道防线。