【后端】【Java】一文深入理解 Spring Boot RESTful 风格接口开发

深入理解 Spring Boot RESTful 风格接口开发

一、什么是 RESTful？

RESTful 是一种基于 REST（Representational State Transfer，表述性状态转移） 架构风格的 Web 接口设计规范。

在 RESTful 风格中：

• 一切皆资源

• 通过 URL 表示资源

• 通过 HTTP 方法描述对资源的操作

• 使用统一的数据格式进行交互（通常是 JSON）

Spring Boot 天生适合用于构建 RESTful 风格接口，因此在现代 Java Web 开发中被广泛采用。

---

二、RESTful 的核心设计思想

1️⃣ 资源导向（Resource-Oriented）

RESTful 强调"资源"而不是"动作"。

❌ 不推荐：

/getUserById?id=1
/deleteUser?id=1

✅ 推荐：

/users/1

资源通常使用 名词复数 表示：

• /users

• /orders

• /products

---

2️⃣ 使用 HTTP 方法表示行为

HTTP 方法	含义	示例
GET	查询资源	GET /users/1
POST	创建资源	POST /users
PUT	更新资源（整体）	PUT /users/1
PATCH	更新资源（部分）	PATCH /users/1
DELETE	删除资源	DELETE /users/1

URL 不变，行为由 HTTP 方法决定，这是 RESTful 的核心思想之一。

---

3️⃣ 无状态（Stateless）

RESTful 接口要求：

• 服务端 不保存客户端状态

• 每次请求都包含完整信息（参数、Token 等）

这使得系统：

• 更易扩展

• 更适合分布式和微服务架构

---

4️⃣ 统一数据格式

目前最常见的数据交互格式是 JSON，相比 XML：

• 更轻量

• 可读性更好

• 前后端支持更友好

---

三、Spring Boot 对 RESTful 的天然支持

Spring Boot 基于 Spring MVC，提供了大量用于 REST 开发的注解，极大降低了开发成本。

---

四、Spring Boot RESTful 常用注解详解

1️⃣ @RestController

@RestController
public class UserController {
}

等价于：

@Controller
@ResponseBody

👉 表示该类中所有方法返回的都是 JSON 数据，而不是视图页面。

---

2️⃣ 请求映射相关注解

@RequestMapping

通用映射注解：

@RequestMapping(value = "/users", method = RequestMethod.GET)

推荐使用语义更清晰的派生注解：

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping

示例：

@GetMapping("/users")
public List<User> listUsers() {
    return userService.findAll();
}

---

3️⃣ @PathVariable（路径参数）

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.findById(id);
}

URL 示例：

GET /users/1

👉 RESTful 强烈推荐使用路径参数来定位资源

---

4️⃣ @RequestParam（查询参数）

@GetMapping("/users")
public List<User> queryUsers(@RequestParam String name) {
    return userService.findByName(name);
}

URL 示例：

GET /users?name=Tom

---

5️⃣ @RequestBody（请求体）

用于接收 JSON 数据：

@PostMapping("/users")
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

前端请求体示例：

{
  "name": "Tom",
  "age": 20
}

---

五、RESTful 接口完整示例

1️⃣ 实体类

public class User {
    private Long id;
    private String name;
    private Integer age;

    // getter & setter
}

---

2️⃣ Controller 示例

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

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "Tom", 20);
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return user;
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id,
                           @RequestBody User user) {
        user.setId(id);
        return user;
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        // 删除逻辑
    }
}

---

六、JSON 序列化与反序列化原理

Spring Boot 默认使用 Jackson 进行 JSON 处理。

✔ 序列化

Java 对象 → JSON

✔ 反序列化

JSON → Java 对象

开发者通常无需手动处理 ，Spring Boot 会通过 HttpMessageConverter 自动完成。

---

七、常用 Jackson 注解

1️⃣ @JsonIgnore

@JsonIgnore
private String password;

👉 返回 JSON 时忽略该字段

---

2️⃣ @JsonProperty

@JsonProperty("user_name")
private String name;

👉 自定义 JSON 字段名

---

3️⃣ @JsonFormat

@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime createTime;

👉 常用于时间字段格式化

---

八、RESTful 接口设计最佳实践

✅ URL 使用名词复数

✅ 不在 URL 中出现动词

✅ 正确使用 HTTP 状态码

✅ 统一返回结构

✅ 接口版本控制（如 /api/v1/users）

示例返回结构：

{
  "code": 200,
  "message": "success",
  "data": {}
}

---

九、总结

Spring Boot 提供了极其完善的 RESTful 开发支持，使得：

• 接口定义简洁清晰

• JSON 处理高度自动化

• 易于前后端分离

• 适合微服务架构

掌握 RESTful 风格，不仅是学会几个注解，更重要的是 理解资源导向和统一接口设计思想。

---