Spring Boot REST API 异常处理：构建健壮的全局与局部策略

// ItemNotExistException.java
public class ItemNotExistException extends RuntimeException {
    public ItemNotExistException(String message) {
        super(message);
    }
}

// ItemService.java
import org.springframework.stereotype.Service;
import java.util.Optional;

@Service
public class ItemService {

    // 假设存在一个 ItemRepository
    // @Autowired
    // private ItemRepository itemRepository;

    public Optional<Item> getSpecificItem(Long itemId) {
        // 模拟从数据库查询，如果不存在则抛出自定义异常
        if (itemId == 1L) { // 假设ID为1的商品存在
            return Optional.of(new Item(1L, "示例商品"));
        } else {
            throw new ItemNotExistException("ID为 " + itemId + " 的商品不存在");
        }
        // 实际应用中会是类似 itemRepository.findById(itemId).orElseThrow(...)
    }

    // 辅助类，仅用于示例
    static class Item {
        private Long id;
        private String name;

        public Item(Long id, String name) {
            this.id = id;
            this.name = name;
        }
        // Getters and Setters
        public Long getId() { return id; }
        public void setId(Long id) { this.id = id; }
        public String getName() { return name; }
        public void setName(String name) { this.name = name; }
    }
}

// GlobalExceptionHandler.java
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 处理 ItemNotExistException 异常
     * 返回 HTTP 404 Not Found 状态码和错误信息
     */
    @ExceptionHandler(ItemNotExistException.class)
    public ResponseEntity<String> handleItemNotExistException(ItemNotExistException ex) {
        // 可以在这里记录日志
        System.err.println("捕获到 ItemNotExistException: " + ex.getMessage());
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }

    /**
     * 处理所有未被特定处理器捕获的泛型 Exception
     * 返回 HTTP 500 Internal Server Error 状态码和通用错误信息
     */
    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleGenericException(Exception ex) {
        System.err.println("捕获到通用 Exception: " + ex.getMessage());
        return new ResponseEntity<>("服务器内部错误：" + ex.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }

    // 可以根据需要添加更多针对其他自定义异常的处理器
    // @ExceptionHandler(AnotherBusinessException.class)
    // public ResponseEntity<String> handleAnotherBusinessException(AnotherBusinessException ex) {
    //     return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    // }
}

// ItemController.java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.Optional;

@RestController
@RequestMapping("/items")
public class ItemController {

    @Autowired
    private ItemService itemService;

    @GetMapping("/{id}")
    public ResponseEntity<ItemService.Item> getItem(@PathVariable Long id) {
        Optional<ItemService.Item> item = itemService.getSpecificItem(id);
        // 如果服务层抛出异常，这里不需要额外的orElseGet，因为异常会被下面的ExceptionHandler捕获
        return item.map(ResponseEntity::ok).orElseGet(() -> ResponseEntity.notFound().build());
    }

    /**
     * 控制器内部的异常处理器，仅对当前控制器生效
     * 当 ItemNotExistException 发生时，返回 HTTP 404 Not Found 状态码和错误信息
     */
    @ExceptionHandler(ItemNotExistException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND) // 可以通过 @ResponseStatus 设置 HTTP 状态码
    public String handleItemNotExistLocally(ItemNotExistException ex) {
        System.err.println("控制器内部捕获到 ItemNotExistException: " + ex.getMessage());
        return ex.getMessage(); // 示例：直接返回错误信息字符串
        // 更专业的做法是返回一个自定义的错误响应体对象，Spring 会自动将其序列化为 JSON
        // return new ErrorResponse(HttpStatus.NOT_FOUND.value(), ex.getMessage());
    }
}