编辑“︁Spring REST概念”︁

= Spring REST概念 =

== 介绍 ==
'''Spring REST''' 是 [[Spring Framework]] 中用于构建 [[RESTful]] Web 服务的模块。REST（Representational State Transfer）是一种架构风格，它使用 [[HTTP]] 协议的标准方法（如 GET、POST、PUT、DELETE）来实现资源的创建、读取、更新和删除（CRUD）操作。Spring REST 提供了简洁的方式来开发轻量级、可扩展的 Web 服务，适用于前后端分离的现代应用程序。

Spring REST 的核心组件包括：
* '''[[@RestController]]'''：标注一个类为 REST 控制器，处理 HTTP 请求并返回响应。
* '''[[@RequestMapping]]'''：定义 URL 路径与控制器方法的映射关系。
* '''[[@RequestBody]]''' 和 '''[[@ResponseBody]]'''：分别用于解析请求体和构造响应体。
* '''[[ResponseEntity]]'''：封装 HTTP 响应，包括状态码、头部信息和响应体。

== RESTful 架构原则 ==
RESTful 服务遵循以下核心原则：
1. '''无状态'''：每个请求必须包含所有必要信息，服务器不存储客户端状态。
2. '''统一接口'''：使用标准的 HTTP 方法（GET、POST、PUT、DELETE）操作资源。
3. '''资源标识'''：每个资源通过 URI（如 <code>/api/users/1</code>）唯一标识。
4. '''表述性'''：资源可以以多种格式（JSON、XML）表示。

== 代码示例：基本 REST 控制器 ==
以下是一个简单的 Spring REST 控制器示例，管理用户资源：

<syntaxhighlight lang="java">
@RestController
@RequestMapping("/api/users")
public class UserController {

    private List<User> users = new ArrayList<>();

    // 获取所有用户
    @GetMapping
    public ResponseEntity<List<User>> getAllUsers() {
        return ResponseEntity.ok(users);
    }

    // 根据ID获取用户
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        User user = users.stream()
                        .filter(u -> u.getId().equals(id))
                        .findFirst()
                        .orElse(null);
        return user != null ? ResponseEntity.ok(user) : ResponseEntity.notFound().build();
    }

    // 创建用户
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        users.add(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
}
</syntaxhighlight>

=== 输入与输出示例 ===
* '''GET /api/users'''（获取所有用户）：
  <syntaxhighlight lang="json">
  []
  </syntaxhighlight>

* '''POST /api/users'''（创建用户）：
  请求体：
  <syntaxhighlight lang="json">
  { "id": 1, "name": "Alice", "email": "alice@example.com" }
  </syntaxhighlight>
  响应：
  <syntaxhighlight lang="json">
  { "id": 1, "name": "Alice", "email": "alice@example.com" }
  </syntaxhighlight>

* '''GET /api/users/1'''（获取ID为1的用户）：
  响应：
  <syntaxhighlight lang="json">
  { "id": 1, "name": "Alice", "email": "alice@example.com" }
  </syntaxhighlight>

== 实际应用场景 ==
Spring REST 常用于以下场景：
1. '''移动应用后端'''：为 iOS/Android 应用提供数据接口。
2. '''单页应用（SPA）'''：与前端框架（如 React、Angular）交互。
3. '''微服务架构'''：作为微服务的入口点，暴露 API 供其他服务调用。

=== 案例：电子商务 API ===
假设我们需要为电商平台开发商品管理 API：

<syntaxhighlight lang="java">
@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping
    public List<Product> listProducts() { /* ... */ }

    @PostMapping
    public Product addProduct(@RequestBody Product product) { /* ... */ }

    @PutMapping("/{id}")
    public Product updateProduct(@PathVariable Long id, @RequestBody Product product) { /* ... */ }
}
</syntaxhighlight>

== 高级特性 ==
对于高级用户，Spring REST 还支持：
* '''HATEOAS'''（超媒体驱动）：通过 <code>Spring HATEOAS</code> 添加资源链接。
* '''验证'''：使用 <code>@Valid</code> 校验请求体。
* '''异常处理'''：通过 <code>@ControllerAdvice</code> 全局处理异常。
* '''文档化'''：集成 <code>SpringDoc OpenAPI</code> 生成 API 文档。

== 总结 ==
Spring REST 提供了一种高效、标准化的方式构建 RESTful 服务。通过注解和内置组件，开发者可以快速实现资源操作、状态管理和内容协商。无论是初学者还是高级用户，都能通过 Spring REST 构建符合行业标准的 Web API。

<mermaid>
sequenceDiagram
    Client->>+Server: GET /api/users/1
    Server->>+Database: 查询用户ID=1
    Database-->>-Server: 返回用户数据
    Server-->>-Client: 200 OK + JSON数据
</mermaid>

<math>
REST = \left\{ \text{Resources}, \text{HTTP Methods}, \text{Stateless}, \text{Uniform Interface} \right\}
</math>

[[Category:后端框架]]
[[Category:Spring]]
[[Category:Spring REST]]