1.1 RESTful架构风格概述
RESTful像是一套建筑设计的通用语言。它让不同系统之间的交流变得优雅而高效。REST这个词来自Roy Fielding的博士论文，全称是Representational State Transfer。你可以把它理解为一种设计Web服务的指导思想。
想象你在餐厅点餐。你不会直接冲进厨房对厨师喊“我要牛排”，而是通过服务员传递请求。RESTful API就扮演着服务员的角色，它使用标准的HTTP方法来完成各种操作。GET用来获取资源，POST用于创建新资源，PUT负责更新，DELETE则处理删除。
RESTful有六个核心约束条件。客户端-服务器分离让前后端各司其职。无状态意味着每次请求都包含所有必要信息。缓存可以显著提升性能。统一接口确保交互方式的一致性。分层系统提供更好的扩展性。按需代码是可选的，允许客户端下载并执行代码。
我记得第一次接触RESTful时，最打动我的是它的简洁性。之前参与的一个项目使用SOAP协议，配置复杂且笨重。转向RESTful后，接口变得直观易懂，前端同事再也不用为理解复杂的XML结构而头疼了。
1.2 SpringMVC对RESTful的支持特性
SpringMVC为RESTful开发提供了全方位的支持。它像一位贴心的助手，把复杂的技术细节封装起来，让开发者能专注于业务逻辑。
@RestController注解是个聪明的设计。它结合了@Controller和@ResponseBody的功能。使用这个注解的类会自动将方法返回值序列化为JSON或XML。这省去了手动设置响应体的麻烦。Spring会根据请求的Accept头来决定返回格式，支持JSON、XML等多种数据格式。
HTTP方法映射做得相当灵活。除了标准的@RequestMapping，还有更具体的@GetMapping、@PostMapping等快捷注解。这让代码意图更加清晰。方法级别的注解让URI路径设计变得直观，读代码时能快速理解每个端点的作用。
消息转换机制是另一个亮点。HttpMessageConverter负责在Java对象和HTTP消息之间进行转换。Jackson库通常被用来处理JSON序列化。你几乎感受不到转换过程的存在，就像魔法一样自动完成。
内容协商让同一个接口能返回不同格式的数据。客户端通过Accept头指定期望的响应格式，Spring会自动选择匹配的转换器。这种设计极大地提升了API的灵活性。
1.3 Java优学网RESTful学习路径介绍
在Java优学网，我们设计了一条循序渐进的学习路径。这个路径基于多年教学经验总结而成，帮助学员平稳地掌握RESTful开发。
入门阶段从理解HTTP协议开始。我们会用两周时间深入讲解HTTP方法、状态码和头部信息。很多初学者会跳过这部分，但扎实的HTTP基础是写好RESTful API的前提。接着是SpringMVC核心概念，包括DispatcherServlet的工作机制和请求处理流程。
中级阶段聚焦实际开发技能。注解的使用是重点内容，我们会通过大量实例展示各种注解的应用场景。参数绑定和验证是另一个关键模块，学员将学会如何处理不同类型的请求参数。这个阶段还会介绍基本的错误处理机制。
高级阶段涉及架构设计思想。我们强调资源建模的重要性，指导学员如何设计合理的URI结构。统一响应格式和异常处理是保证API一致性的关键。性能优化和安全性也会在这个阶段详细讨论。
实践环节贯穿整个学习过程。每个理论模块都配有相应的编码练习。我们特别设计了从简单到复杂的项目案例，让学员在真实场景中应用所学知识。结业项目要求独立完成一个完整的RESTful服务，这能很好地检验学习成果。
学习过程中，我建议不要急于求成。很多学员想跳过基础直接学习高级特性，这往往适得其反。稳扎稳打地掌握每个概念，才能在后续开发中游刃有余。
2.1 @RestController与@Controller区别
这两个注解经常让初学者困惑。其实它们的区别很直观，就像普通信件和明信片的差别。
@Controller是SpringMVC的传统选择。它标识的类通常用于返回视图名称，配合视图解析器渲染HTML页面。想象你在经营一家实体店，顾客进来后你不仅提供商品，还要负责店面布置和导购服务。@Controller就是这样，它处理请求的同时还要考虑页面展示。
@RestController则专为RESTful API设计。它本质上是@Controller和@ResponseBody的组合。使用这个注解的类，所有方法返回值都会直接写入HTTP响应体，而不是跳转到视图。这就像一家只做外卖的餐厅，顾客下单后直接拿到包装好的食物，不需要考虑用餐环境。
我记得第一次混用这两个注解时闹过笑话。在一个应该返回JSON数据的接口上用了@Controller，结果Spring一直在寻找对应的视图文件。后来加上@ResponseBody注解才解决问题。改用@RestController后，代码立刻简洁了很多。
从技术层面看，@RestController在Spring 4.0引入，专门简化RESTful服务的开发。它自动为所有方法添加@ResponseBody，省去了重复注解的麻烦。如果你正在构建API服务，@RestController几乎总是更好的选择。
2.2 @RequestMapping及其变体注解
@RequestMapping是SpringMVC中最基础也最强大的映射注解。它像交通指挥中心，负责将HTTP请求路由到正确的处理方法。
最基本的用法是指定URI路径。你可以定义类级别的@RequestMapping为所有方法设置基础路径，再在方法级别添加具体路径。这种分层设计让代码组织更加清晰。支持Ant风格的通配符，让路径匹配变得灵活。
HTTP方法映射是另一个重要特性。早期需要在@RequestMapping中指定method属性，现在有了更简洁的替代方案。@GetMapping、@PostMapping、@PutMapping、@DeleteMapping这些注解让意图表达更明确。看到@GetMapping就知道这个方法用于数据查询，不会修改服务器状态。
参数约束可以进一步细化匹配条件。通过params属性限制请求必须包含某些参数，headers属性检查特定的HTTP头。这些特性让路由更加精确，避免模糊匹配导致的问题。
实际开发中，我倾向于使用具体的HTTP方法注解。代码可读性更好，IDE的智能提示也更准确。只有在需要复杂匹配条件时，才会回归到原始的@RequestMapping。
2.3 参数绑定注解@PathVariable、@RequestParam
参数绑定让HTTP请求中的数据自动映射到方法参数。这就像有个智能助手帮你拆解快递包裹，把里面的物品分门别类放好。
@PathVariable用于从URI路径中提取变量。在RESTful设计中，资源标识符通常嵌入在路径里。比如/users/{id}中的id部分。使用@PathVariable可以将这个动态部分绑定到方法参数。支持正则表达式验证，确保参数格式符合预期。
@RequestParam处理查询字符串参数。那些跟在问号后面的键值对，比如?page=1&size=20。可以指定默认值，当请求中没有对应参数时使用。required属性控制参数是否必须，避免因缺少参数而抛出异常。
参数类型转换是自动进行的。Spring会将字符串形式的请求参数转换为目标类型。支持基本类型、集合、甚至自定义对象的转换。这种自动化大大减少了模板代码。
有个项目让我深刻体会到参数绑定的价值。之前手动从HttpServletRequest获取参数，代码冗长且容易出错。改用注解后，方法签名直接声明需要的参数，既简洁又安全。参数验证也变得更加直观。
2.4 请求体处理注解@RequestBody
@RequestBody专注于处理请求体内容。它像专业的翻译官，将HTTP请求中的原始数据转换为Java对象。
这个注解通常用于POST、PUT等包含请求体的方法。Spring会根据Content-Type头选择对应的消息转换器。JSON格式最常用，Jackson库负责在JSON字符串和Java对象间来回转换。也支持XML、表单数据等其他格式。
数据绑定过程相当智能。它会匹配JSON属性名与Java对象的字段名，自动完成赋值。支持嵌套对象和集合类型，能够处理复杂的数据结构。验证注解可以配合使用，确保数据的正确性。
反序列化配置很灵活。可以通过@JsonIgnore忽略某些字段，@JsonProperty自定义字段映射。这些细粒度控制让数据转换更加精确。
实际使用中要注意内容协商。确保客户端发送的Content-Type与服务器期望的一致。我曾经遇到一个坑，前端发送的是JSON字符串但Content-Type设置错误，导致反序列化失败。正确的MIME类型设置很关键。
消息转换器的配置也值得关注。Spring Boot自动配置了常用的转换器，特殊需求时可以自定义。比如添加对Protocol Buffers或MessagePack的支持，优化API性能。 { "code": 200, "message": "操作成功", "data": {
"id": 123,
"name": "张三"
} }
public class UserDTO {
@NotBlank(message = "用户名不能为空")
@Size(min = 2, max = 20, message = "用户名长度2-20字符")
private String username;
@Email(message = "邮箱格式不正确")
private String email;
}
@RestController @RequestMapping("/api/users") public class UserController {
@GetMapping
public PageResult<UserVO> listUsers(
@RequestParam(defaultValue = "1") int page,
@RequestParam(defaultValue = "10") int size,
@RequestParam(required = false) String keyword) {
// 分页查询逻辑
}
@PostMapping
public UserVO createUser(@Valid @RequestBody CreateUserRequest request) {
// 创建用户逻辑
}
@PutMapping("/{userId}")
public UserVO updateUser(@PathVariable Long userId,
@Valid @RequestBody UpdateUserRequest request) {
// 更新用户逻辑
}
}
