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