1. 引言
Spring MVC 自 5.1 版本起引入了一个非常实用的特性：接口驱动的控制器（Interface Driven Controllers）。这一特性允许我们通过 Java 接口来定义 Web 请求的映射关系，从而实现更清晰、更可复用的控制器设计。
本篇文章将围绕这个特性展开，适合已经熟悉 Spring MVC 基础的开发者，帮助你避免重复代码，提高代码结构的整洁性。
2. 背景与痛点
在传统的 Spring MVC 控制器开发中，我们通常通过注解来定义接口行为，比如：
@PostMapping("/save/{id}")
@ResponseBody
public Book save(@RequestBody Book book, @PathVariable int id) {
// 实现逻辑
}
这种写法对于单一控制器来说没有问题，但当我们有多个控制器需要实现相同的方法签名和请求映射时，就会出现大量重复的注解代码，违反了 DRY 原则。
在普通的 Java 类中，我们会通过接口来统一方法签名。但控制器的“灵魂”其实是在注解上，而不是方法签名本身。因此，接口本身并不能直接携带这些注解信息，这就导致了代码冗余。
Spring 5.1 解决了这个问题：现在控制器接口上的注解也可以被 Spring MVC 正确识别并用于映射请求。
3. 实践：接口驱动的控制器
3.1. 示例场景
我们以一个简单的图书管理系统为例，构建一个包含以下功能的控制器：
- 获取所有图书
- 根据 ID 获取单个图书
- 保存图书数据
我们将通过接口来定义这些方法及其请求映射。
3.2. 定义接口
首先定义一个接口 BookOperations，并在其中使用 Spring 的注解来描述请求映射：
@RequestMapping("/default")
public interface BookOperations {
@GetMapping("/")
List<Book> getAll();
@GetMapping("/{id}")
Optional<Book> getById(@PathVariable int id);
@PostMapping("/save/{id}")
void save(@RequestBody Book book, @PathVariable int id);
}
这个接口不仅定义了方法签名，还通过注解明确了每个方法对应的请求方式、路径、参数等。
3.3. 实现控制器
接下来，我们创建一个控制器类 BookController 来实现这个接口：
@RestController
@RequestMapping("/book")
public class BookController implements BookOperations {
@Override
public List<Book> getAll() {
// 实现逻辑
}
@Override
public Optional<Book> getById(int id) {
// 实现逻辑
}
@Override
public void save(Book book, int id) {
// 实现逻辑
}
}
✅ 关键点：
- 控制器必须加上
@RestController或@Controller注解，否则 Spring 不会将其识别为控制器。 - 控制器类上可以加
@RequestMapping，用于覆盖接口中的路径定义。 - 接口和控制器都可以使用注解，控制器上的注解优先级更高，类似 Java 的继承机制。
3.4. 验证接口是否生效
启动应用后，可以通过如下命令验证接口是否生效：
curl http://localhost:8081/book/
如果你看到返回了图书列表，说明接口定义的映射已经成功被控制器继承。
4. 注意事项与踩坑提醒
⚠️ 接口与控制器的映射冲突问题：
如果你有多个控制器实现同一个接口，并且它们的路径定义不够清晰，可能会导致如下异常：
Caused by: java.lang.IllegalStateException: Ambiguous mapping.
✅ 解决办法：
- 在控制器类上加上明确的
@RequestMapping，避免路径冲突。 - 合理划分接口职责，避免一个接口被多个控制器复用过多。
5. 总结
Spring 5.1 引入的接口驱动控制器特性，让我们可以：
- 将控制器的请求映射定义抽象到接口中
- 实现接口复用，减少重复注解
- 提高代码结构的清晰度和可维护性
这个特性非常适合在多版本接口、模块化开发或微服务架构中使用，是提升代码质量的利器之一。
完整示例代码可以参考我们的 GitHub 仓库。