【后端】【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 方法表示行为

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 风格，不仅是学会几个注解，更重要的是理解资源导向和统一接口设计思想。