Spring MVC 全栈指南：RESTful 架构、核心注解与 JSON 实战解析

目录

1. RESTful API 设计规范
2. Spring MVC 核心注解解析
3. 静态资源处理策略
4. JSON 数据交互全解
5. 高频问题与最佳实践

---

一、RESTful API 设计规范

1.1 核心原则

原则	说明	示例 URI
资源为中心	URI 使用名词（复数形式）	/users ✔️ /getUser ❌
HTTP 方法语义化	GET（查）、POST（增）、PUT（改）、DELETE（删）	DELETE /users/1
无状态通信	服务端不保存客户端会话状态	每次请求携带完整认证信息

1.2 完整代码示例

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

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        return user != null ? 
            ResponseEntity.ok(user) : 
            ResponseEntity.notFound().build();
    }

    @PostMapping
    public ResponseEntity<User> createUser(@Valid @RequestBody User user) {
        User savedUser = userService.save(user);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                .path("/{id}").buildAndExpand(savedUser.getId());
        return ResponseEntity.created(location).body(savedUser);
    }
}

1.3 高级技巧

• HATEOAS 实现（响应中嵌入资源链接）：

@GetMapping("/{id}/orders")
public CollectionModel<Order> getUserOrders(@PathVariable Long id) {
    List<Order> orders = orderService.findByUserId(id);
    Link selfLink = linkTo(methodOn(UserController.class).getUserOrders(id)).withSelfRel();
    return CollectionModel.of(orders, selfLink);
}

• 响应示例：

{
  "content": [ ... ],
  "_links": {
    "self": { "href": "/users/1/orders" }
  }
}

---

二、Spring MVC 核心注解解析

2.1 参数绑定注解

注解	作用场景	示例代码
@PathVariable	从 URI 路径提取变量	@GetMapping("/{id}") → id=1
@RequestParam	绑定查询参数（支持默认值）	@RequestParam(name="page", defaultValue="1")
@RequestBody	将请求体 JSON 映射到 Java 对象	public User createUser(@RequestBody User user)

2.2 元数据获取注解

// 获取 Cookie 值
@GetMapping("/session")
public String getSession(@CookieValue("JSESSIONID") String sessionId) { ... }

// 读取请求头
@GetMapping("/headers")
public String getHeader(@RequestHeader("User-Agent") String userAgent) { ... }

2.3 作用域注解

注解	作用域	生命周期
@SessionAttribute	读取 Session 属性	用户会话期间有效
@ModelAttribute	预加载模型数据	每次请求前执行

---

三、静态资源处理策略

3.1 配置方式对比

方式	配置示例	适用场景
缺省 Servlet 放行	web.xml 配置 <servlet-mapping>	传统项目兼容
resources 标签	<mvc:resources mapping="/img/**" location="/img/"/>	明确指定资源目录
default-servlet-handler	<mvc:default-servlet-handler/>	快速放行所有静态资源

3.2 常见问题

• JSP 未被放行：需通过视图解析器处理，不属于静态资源。
• 路径冲突 ：避免控制器映射与静态资源路径重叠（如 /js/** 与 /js/controller）。

---

四、JSON 数据交互全解

4.1 响应 JSON 配置

@RestController // = @Controller + @ResponseBody
public class ApiController {

    @GetMapping("/city/{id}")
    public City getCity(@PathVariable int id) {
        return cityService.findById(id);
    }
}

4.2 序列化控制

@Data
public class Product {
    @JsonIgnore
    private String internalCode; // 不序列化

    @JsonFormat(pattern = "yyyy-MM-dd")
    private Date createTime;     // 日期格式化
}

4.3 依赖配置

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.14.0</version>
</dependency>

---

五、高频问题与最佳实践

5.1 常见错误

1. RESTful 路径设计混乱
   • ❌ /getUserOrders?userId=1 → ✅ GET /users/1/orders
2. HTTP 方法误用
   • ❌ 用 POST 请求更新资源 → ✅ 使用 PUT/PATCH
3. JSON 日期序列化错误
   • 解决方案：@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")

5.2 性能优化

• 静态资源缓存 ：配置 Cache-Control 头减少重复请求。
• Jackson 延迟加载 ：对大数据集使用 @JsonView 控制序列化字段。