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

目录

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

一、RESTful API 设计规范

1.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 参数绑定注解

2.2 元数据获取注解

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

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

2.3 作用域注解

三、静态资源处理策略

3.1 配置方式对比

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 控制序列化字段。