惊呆了!Spring Boot接口定义:8种逆天玩法

环境：SpringBoot3.4.2

1. 简介

在项目开发里，借助 @RestController/@Controller 注解定义接口是常见且便捷的方式。然而，接口定义方法远不止于此。

本篇问自己将深入探讨Spring Boot支持的 8 种定义接口的独特方式，为开发者拓宽思路。不同方法各有适用场景与优势，开发者可根据项目需求、架构设计、团队规范等灵活选用。掌握多种接口定义手段，有助于优化项目结构、提升代码可维护性与扩展性，让开发者在面对复杂业务场景时，能更高效、合理地实现接口功能，满足多样化开发需求。

2.实战案例

2.1 使用@Controller注解

@Controller注解用于标识一个类为控制器组件。它负责接收HTTP请求、调用业务逻辑，并返回视图或数据。通常与@RequestMapping等配合使用，定义请求路径映射，这是最常见的接口定义方式。

@RestController
@RequestMapping("/api")
public class ApiController {
  @GetMapping("")
  public ResponseEntity<?> query() {
    return ResponseEntity.ok(new User("Pack", 22)) ;
  }
}

下面接口返回一个视图

@Controller
public class ApiController {
  @GetMapping("/home/index")
  public ModelAndView index() {
    return new ModelAndView("index") ;
  }
}

2.2 实现Controller接口

该Controller接口能够像 HttpServlet 一样接收 HttpServletRequest 和 HttpServletResponse 实例，但可参与 MVC 工作流。控制器类似于 Struts Action 的概念。

Controller 接口明确设计为在 HttpServletRequest 和 HttpServletResponse 对象上操作，与 HttpServlet 类似。充分利用 Servlet API 的全部功能。

@Component("/controller/api")
public class ApiController implements Controller {
  @Override
  public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) throws Exception {
    response.setContentType("text/html;charset=utf-8") ;
    response.getWriter().println("<h1>实现Controller接口定义Web接口</h1>");
    return null ;
  }
}

在handleRequest方法中我们可以直接通过Servlet API输出响应，也可以返回视图对象。

2.3 实现HttpRequestHandler接口

用于处理 HTTP 请求组件的简易处理器接口，类似于 Servlet。该接口仅声明抛出
jakarta.servlet.ServletException 和 java.io.IOException，以便在任何
jakarta.servlet.http.HttpServlet 中使用。本质上，此接口相当于精简为单一核心 handle 方法的 HttpServlet 直等价物。

@Component("/handler/api")
public class HttpHandlerController implements HttpRequestHandler {
  @Override
  public void handleRequest(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
    response.setContentType("text/html;charset=utf-8") ;
    response.getWriter().println("<h3>实现HttpRequestHandler接口定义Web接口</h3>");
  }
}

此种实现方式与2.2中除了返回值不一样外，其它基本没有什么区别。该接口其实与下面的接口定义方式是有关联的。

2.4 注册HttpRequestHandlerServlet

简易的 HttpServlet 实现，其功能委托给Spring 应用上下文中定义的 HttpRequestHandler Bean；简单说，该类不会自行处理请求，而是委托给注册的HttpRequestHandler处理。

首先，定义HttpRequestHandler Bean

@Component
public class UserHttpHandler implements HttpRequestHandler {
  @Override
  public void handleRequest(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
    response.setContentType("text/html;charset=utf-8") ;
    response.getWriter().println("<h3>通过注册HttpRequestHandlerServlet实现接口</h3>");
  }
}

最后，定义注册HttpRequestHandlerServlet

@Bean
ServletRegistrationBean<HttpRequestHandlerServlet> userHandlerServlet() {
  ServletRegistrationBean<HttpRequestHandlerServlet> registrar = new ServletRegistrationBean<>() ;
  registrar.setServlet(new HttpRequestHandlerServlet()) ;
  registrar.setName("userHttpHandler") ;
  registrar.addUrlMappings("/user/handler") ;
  return registrar ;
}

注意：这里setName设置的名称必须上面 UserHttpHandler Bean的名称一致。

2.5 实现Servlet接口

在很久很久以前，开发者常需亲手编写 Servlet 程序，在代码中逐行处理 HTTP 请求与响应，再通过 web.xml 配置繁琐的映射规则，将 URL 路径与 Servlet 类名逐一绑定，以搭建动态 Web 服务的底层架构。该技术过时了吗？没有，只是我们现在不需要直接去编写Servlet了，如我们现在都是通过注解@Controller就可以声明接口了，但是其底层还是通过Servlet来实现接口的调用。

@Component("/products")
public class ProductServlet extends HttpServlet {
  private static final long serialVersionUID = 1L;


  private final ObjectMapper objectMapper ;
  public ProductServlet(ObjectMapper objectMapper) {
    this.objectMapper = objectMapper;
  }
  @Override
  protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    resp.setContentType("application/json;charset=utf-8") ;
    List<Product> datas = List.of(
        new Product("Spring Boot3实战案例150讲", BigDecimal.valueOf(70)),
        new Product("Spring 全家桶源码详解", BigDecimal.valueOf(70))
      ) ;
    String result = this.objectMapper.writeValueAsString(datas) ;
    resp.getWriter().println(result) ;
  }


  public static record Product(String name, BigDecimal price) {}
}

执行结果

说明：上面，我们通过@Component("/products")声明了该接口的访问路径，默认情况下，是不能访问的，我们还需要定义如下HandlerAdapter。

@Bean
SimpleServletHandlerAdapter simpleServletHandlerAdapter() {
  return new SimpleServletHandlerAdapter() ;
}

除此之外，我们还可以使用@WebServlet("/product")声明，同时使用如下注解开启扫描功能：

// 修改注解 
@WebServlet("/products")
public class ProductServlet extends HttpServlet {}
// 开启扫描功能 


@SpringBootApplication
@ServletComponentScan
public class SpringBootComprehensiveApplication {}

通过上面的方式也是可以注册接口。当然你想用ServletRegistrationBean方式也可以。

2.6 实现HandlerFunction接口

HandlerFunction是个函数式接口，表示一个处理请求的函数。接口签名如下：

@FunctionalInterface
public interface HandlerFunction<T extends ServerResponse> {
  T handle(ServerRequest request) throws Exception;
}

说明：

• ServerRequest: 提供对 HTTP 方法、URI、请求头以及查询参数的访问，而请求体的访问则通过其提供的 body 相关方法实现。
• ServerResponse: 提供对 HTTP 响应的访问，且因其不可变特性，需通过构建器（build）方法创建实例。可利用构建器设置响应状态码、添加响应头或提供响应体。

@Component
public class StorageHandler implements HandlerFunction<ServerResponse> {
  @Override
  public ServerResponse handle(ServerRequest request) throws Exception {
    String id = request.pathVariable("id") ;
    return ServerResponse.ok()
        .body("查询编号为【" + id + "】的库存信息") ;
  }
}

如何才能使得上面的实现能够处理请求呢？我们需要通过RouterFunction声明接口。

@Bean
RouterFunction<ServerResponse> storageRouter(StorageHandler storageHandler) {
  return RouterFunctions.route()
      .GET("/storages/{id}", storageHandler)
      .build() ;
}

关于这种函数式接口定义方式，你可以查看下面文章：

你以为只有Controller一种接口定义方式？详解Web函数式接口

2.7 使用@HttpExchange注解

尽管 @HttpExchange 的核心用途是通过生成的代理对象来抽象化 HTTP 客户端代码，但该注解的 HTTP 接口本身是一个不区分客户端与服务器端使用场景的契约规范。除简化客户端代码外，也存在特定场景：服务器端通过 HTTP 接口暴露其 API 供客户端调用。

@HttpExchange("/persons")
interface PersonService {
  @GetExchange("/{id}")
  Person getPerson(@PathVariable Long id);


  public static record Person(Long id, String name) {}
}

接下来，我们定义Controller接口，实现上面的接口。

@RestController
public class PersonController implements PersonService {
  public Person getPerson(@PathVariable Long id) {
    return new Person(id, "姓名 - " + id) ;
  }
}

2.8 注册静态资源

在项目中常需处理对静态资源的访问需求，而在 Spring Boot 环境下，开发者能够非常便捷地注册任意目录或路径下的资源，使其可通过网络对外提供服务。

接下，我们注册本地磁盘目录下的资源对外服务。

@Configuration
public class WebApiConfig implements WebMvcConfigurer {
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/pack/resources/**")
      .addResourceLocations("file:/d:/images/") ;
  }
}