RESTful Web 服务详解

RESTful Web 服务是一种基于 Representational State Transfer (REST) 架构风格的 Web 服务，它利用 HTTP 协议来传输数据，支持多种数据格式如 JSON 和 XML。在 Spring 框架中，通过简单配置和注解可以轻松实现 RESTful Web 服务。在本文中，我们将介绍如何创建 RESTful 控制器，使用 @RestController 注解，处理请求和响应格式，以及处理异常的最佳实践。

创建 RESTful 控制器

RESTful 控制器用于处理 HTTP 请求并返回相应的数据。Spring 提供了一套完整的注解和工具来帮助开发者快速创建 RESTful 控制器。

使用 @RestController 注解

@RestController 注解是 Spring 提供的一个方便的注解，它结合了 @Controller 和 @ResponseBody，简化了控制器的开发。

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping
    public List<User> getAllUsers() {
        // 返回所有用户
        return userService.findAll();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        // 创建并返回新用户
        return userService.save(user);
    }
}

在这个例子中，UserController 类使用 @RestController 注解标注，表明它是一个 RESTful 控制器。@RequestMapping 注解用于定义基础 URL 路径，@GetMapping 和 @PostMapping 分别用于处理 GET 和 POST 请求。

请求和响应格式

RESTful Web 服务常使用 JSON 和 XML 作为数据格式。Spring Boot 默认使用 Jackson 库将对象转换为 JSON 格式，也支持其他格式如 XML。

返回 JSON 格式

JSON 是 RESTful 服务中最常用的数据格式。Spring Boot 默认配置了 Jackson 作为 JSON 处理库，控制器方法返回的对象会自动转换为 JSON。

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping
    public List<Product> getAllProducts() {
        return productService.findAll();
    }
}

在这个例子中，getAllProducts 方法返回一个 List<Product> 对象，Spring Boot 会自动将其转换为 JSON 格式的响应。

返回 XML 格式

要支持 XML 格式，需要在依赖中添加 Jackson XML 扩展：

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
</dependency>

然后，在控制器方法中设置返回的媒体类型为 XML：

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping(produces = MediaType.APPLICATION_XML_VALUE)
    public List<Product> getAllProducts() {
        return productService.findAll();
    }
}

在这个例子中，getAllProducts 方法将返回的媒体类型设置为 XML，Spring Boot 会自动将对象转换为 XML 格式的响应。

处理异常

在 RESTful Web 服务中，处理异常是确保服务可靠性和用户体验的关键。Spring 提供了 @ExceptionHandler 和 @ControllerAdvice 注解，用于全局处理控制器中的异常。

使用 @ExceptionHandler

@ExceptionHandler 注解用于在控制器中定义特定异常的处理方法。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @GetMapping("/{id}")
    public Order getOrderById(@PathVariable Long id) {
        return orderService.findById(id)
            .orElseThrow(() -> new OrderNotFoundException("Order not found with id " + id));
    }

    @ExceptionHandler(OrderNotFoundException.class)
    public ResponseEntity<String> handleOrderNotFoundException(OrderNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

在这个例子中，handleOrderNotFoundException 方法使用 @ExceptionHandler 注解处理 OrderNotFoundException 异常，并返回 404 状态码和错误消息。

使用 @ControllerAdvice

@ControllerAdvice 注解用于定义全局异常处理类，统一处理多个控制器中的异常。

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 {

    @ExceptionHandler(OrderNotFoundException.class)
    public ResponseEntity<String> handleOrderNotFoundException(OrderNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleGeneralException(Exception ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

在这个例子中，GlobalExceptionHandler 类使用 @ControllerAdvice 注解标注，定义了两个异常处理方法，分别处理 OrderNotFoundException 和其他所有异常。

总结

通过本文的讲解，我们了解了如何在 Spring 中创建 RESTful 控制器，使用 @RestController 注解，处理请求和响应格式（包括 JSON 和 XML），以及如何通过 @ExceptionHandler 和 @ControllerAdvice 进行异常处理。