夢の終着駅

（一）从浏览器到控制器的高层流程#

简单来说流程如下，具体请见分析源码章节：

1. 浏览器发起请求，包含传参、请求体、Cookie或Header。
2. Web容器（常见的如Tomcat）接受HTTP请求，并转交给Spring容器中的DispatcherServlet。
3. DispatcherServlet调用HandlerMapping匹配该路径的Conroller控制器。
4. HandlerAdapter将HTTP的请求数据绑定到控制器的方法参数上，并执行方法。
5. 执行完后控制器返回渲染模板或JSON对象，DispatcherServlet将结果写回HTTP响应并返回给浏览器

（二）Model / View / Controller 各自职责#

（三）三层模型在 MVC 中的配合#

• 表现层：处理 HTTP、页面渲染，通常对应MVC的 Controller + View。
• 业务层：封装业务逻辑与事务。
• 持久层：直接与数据库交互。

MVC关心的是请求分派以及数据渲染的问题，而三层模型关注职责分离和可维护性。

（一）定位#

DispatcherServlet是Spring MVC的前端控制器，遵循Front Controller模式。所有匹配到该 的请求，由它负责把请求分派给合适的handler，处理返回结果并最终渲染视图或写入响应体。

父类FrameworkServlet负责WebApplicationContext的启动管理以及Servlet生命周期的基础逻辑，使得DispatcherServlet只需专注HTTP请求的处理与分发。

（二）HandlerMapping & HandlerAdapter & ViewResolver & HandlerExceptionResolver#

（三）配置#

传统模式下需要配置web.xml文件：

1
<servlet>
2
  <servlet-name>app</servlet-name>
3
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
4
  <init-param>
5
    <param-name>contextConfigLocation</param-name>
6
    <param-value>/WEB-INF/app-servlet.xml</param-value>
7
  </init-param>
8
  <load-on-startup>1</load-on-startup>
9
</servlet>
10
<servlet-mapping>
11
  <servlet-name>app</servlet-name>
12
  <url-pattern>/</url-pattern>
13
</servlet-mapping>

不过在Spring Boot场景下，会自动配置DispatcherServlet，只需添加spring-boot-starter-web即可，方便又快捷，是当下最为流行的配置方式。

（一）基本用法与常用属性#

1
@RestController
2
@RequestMapping("/user")
3
public class UserController {
4

5
    @RequestMapping("/{id}")
6
    public UserDto getUserInfo(@PathVariable Long id) {
7
    }
8

9
    @RequestMapping("/search")
10
    public List<UserDto> list() {
11
    }
12
}

1
@RequestMapping(path = {"/a", "/b"})

1
@RequestMapping(method = RequestMethod.POST)

1
@RequestMapping(path="/search", params = {"q", "type=user"})

1
@RequestMapping(headers = "X-API-VERSION=1")

1
@RequestMapping(consumes = "application/json")
2
@RequestMapping(produces = "application/json")

（二）衍生注解#

Spring提供了多个基于@RequestMapping的组合注解，更便捷也语义明确：

• @GetMapping
• @PostMapping
• @PutMapping
• @DeleteMapping
• @PatchMapping

这些注解只是语法糖，但在实际代码中更常用，因为更简洁、语义清晰。

（三）路由#

1
@RequestMapping(path="/", headers = "X-API-VERSION=2")

（一）简单数据类型绑定#

Java原始类型、包装类型、String、Enum、Date、UUID 等被认为是简单类型，当控制器方法是简单类型且没有任何注解的时候，Spring会默认将其当作请求参数，等同于加上了@RequestParam注解。

（二）@RequestParam & @PathVariable & @RequestHeader & @CookieValue#

这四个注解的重要参数如下：

• **value / name：**参数名
• **required：**默认true。若为false且参数缺失时会抛出异常
• **defaultValue：**提供默认值并把required属性视为false

1
@GetMapping("/search")
2
public List<User> search(@RequestParam String q,
3
                         @RequestParam(defaultValue = "10") int size,
4
                         @RequestParam(required = false) String tag) {
5
}

1
@GetMapping("/users/{id}")
2
public User detail(@PathVariable("id") Long id) {
3
}

1
@GetMapping("/v")
2
public String v(@RequestHeader(name="X-Api-Version", required=false, defaultValue="1") String ver) {
3
}

1
@GetMapping("/cookie")
2
public void cookie(@CookieValue(name="theme", required=false) Cookie themeCookie) {
3
}

（一）域#

以一次请求为单位的作用域。

生命周期为从请求到Servlet容器开始处理直到响应完成并返回给客户端的全流程。

存活时间短，典型用途是把controller层产生的数据传给视图渲染使用。

需要注意的是，通常情况下我们每个请求是只由一个线程处理的，但是如果在异步调用的情况下会跨线程传递，在此情况需要使用容器提供的AsyncContext将请求包装传递给异步线程。

Request域是天然线程安全。

（二）域#

以一次会话为单位的作用域，可跨多个Request。

生命周期由业务逻辑决定。

典型用途是用户登录权限校验以及socket连接建立。

注意不要把大量数据放入Session，会占用堆空间并提高GC频率。

Session域存在并发问题，需要自行处理逻辑。

（三）Application域#

以整个Web应用为单位的作用域，可跨多个Session。

生命周期与整个Web应用相关联。

典型用途是拦截器与监听器。

与Session域一样，最好不要存放大量数据。

Application域存在并发问题，需要自行处理逻辑。

（一）URL设计#

我们应该使用HTTP方法来表达语义，而不要在URL中使用动词或方法名，也就是说我们提倡使用例如 /user而不是/getUser。

对于集合资源，我们使用/users表示用户集合，用/users/{id}表示单个用户。

对于资源关系，我们应该用层次化来映射，但是需要避免过深嵌套，提倡使用/users/{id}/orders，而不推荐/a/{id}/b/{id}/c/{id}/d/{id}。

对于资源的身份，或者说是访问条件，我们应该使用路径来表示，例如分页：GET /products?category=phone&sort=price_desc&page=2&size=20。

对于版本化处理，我们只推荐两种方式：一是在URL中添加版本号，例如：/v1/users；另一种则是在header中添加属性，第一种简单直观，第二种灵活性和可扩展性更好。

（二）HTTP状态码与响应体设计#

对于HTTP 状态码工程化建议如下：

• 2xx
  • 200 OK：业务逻辑处理成功、返回实体
  • 201 Created：资源已创建，必须返回Location header指向新资源
  • 202 Accepted：异步处理已接受，返回位置或状态查询地址
  • 204 No Content：资源已删除，无返回体
• 3xx
  • 301/308：永久重定向
  • 302/303/307：临时重定向（注意 POST→GET 语义用 303）
• 4xx
  • 400 Bad Request：参数/请求语法错误、JSON 解析失败、验证失败
  • 401 Unauthorized：未认证或认证失败
  • 403 Forbidden：已认证但无权限
  • 404 Not Found：资源不存在
  • 405 Method Not Allowed：方法不允许，一般是HTTP方法错误或是传参错误
  • 409 Conflict：冲突（例如版本冲突或重复资源）
  • 429 Too Many Requests：超出最大并发限制
• 5xx
  • 500 Internal Server Error：服务器异常
  • 503 Service Unavailable：服务暂不可用、降级或维护

其中针对202 Accepted状态码，我们提倡建立SSE或者WS长连接进行轮询其状态，直至返回错误或成功状态。

对于HTTP的不同方法，我们也规范了其响应：

• 针对GET，应该返回200 OK状态码并在响应体中带上JSON格式的访问资源。
• 针对POST，应该返回201 Created状态码，并返回新资源的访问URL
• 针对PUT，应该返回200 OK状态码并返回更新的JSON格式的资源。
• 针对PATCH，响应同PUT。
• 针对DELETE，应该返回204状态码并无返回体。

针对错误响应，我们也应该规范响应体格式：

1
{
2
  "type": "http://example.com/404",
3
  "title": "资源不存在",
4
  "status": 404,
5
  "detail": "访问参数[id]格式错误",
6
  "instance": "/users/attack"
7
}

• type是错误页面的跳转URL，是可选的
• title是错误响应的短标题
• status则是HTTP状态码
• detail是对本次错误的描述
• instance是本次错误请求的URL

（一）@RequestBody#

@RequestBody正如上文所说，其实起到的是一个标记作用，代表该请求的请求体需要被反序列化成Java对象并注入到接口参数中。

除此之外该注解也存在required属性，当为false时允许请求体为null。

（二）@ResponseBody#

该注解其实也是起到一个标注作用，代表其返回的响应体需要被序列化为HTTP响应体，一般是JSON格式字符串。

现在主流的REST场景下提倡后端使用@ResponseBody注解返回JSON格式字符串给前端进行数据渲染，但是每个方法上都要加该注解就显得重复冗余，所以Spring提供了@RestController注解，其等同于@Controller + 类内部每个方法上的@ResponseBody。

（一）RequestEntity#

可以获取请求的HTTP状态码、headers、Cookie等等。

（二）ResponseEntity#

可以自定义响应的HTTP状态码、headers、Cookie等等。

如果需要显式控制 HTTP 状态或 headers时才推荐使用ResponseEntity封装返回响应，其余状况推荐直接返回实体。

（一）@ExceptionHandler & @ControllerAdvice#

@ControllerAdvice是一个跨Controller的增强处理器，用于把错误处理从单个 Controller 提取到集中位置。

@ExceptionHandler用于在标注了@ControllerAdvice的类内声明方法来处理特定类型的异常（可以处理一个或多个异常类型）。

1
@ControllerAdvice(annotations = RestController.class)
2
public class GlobalExceptionHandler {
3

4
    @ExceptionHandler(NotFoundException.class)
5
    public ResponseEntity<?> handleNotFound(NotFoundException ex, HttpServletRequest req) {
6
        var body = Map.of(
7
           // 省略
8
        );
9
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
10
    }
11

12
    // 最后兜底
13
    @ExceptionHandler(Exception.class)
14
    public ResponseEntity<?> handleAny(Exception ex, HttpServletRequest req) {
15
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR);
16
    }
17
}

（二）全局异常处理#

首先需要讲解一下Spring的异常处理链，当DispatcherServlet捕获到HandlerMethod抛出的异常时，会遍历异常处理链，直到其中一个处理器处理成功后停止：

1. **ExceptionHandlerExceptionResolver：**负责处理@ExceptionHandler 与 @ControllerAdvice，也就是我们自定义的异常处理器
2. **ResponseStatusExceptionResolver：**负责处理ResponseStatusException以及被@ResponseStatus注解的异常类。
3. **DefaultHandlerExceptionResolver：**负责处理Spring的内置异常。

@ResponseStatus注解一般用于自定义异常类： @ResponseStatus(HttpStatus.NOT_FOUND)public class NotFoundException extends RuntimeException {}一键获取完整项目代码java运行

可以注册HandlerExceptionResolver来自定义调整异常处理链的顺序。

下面提供一个推荐使用的全局异常处理器模板：

1
@ControllerAdvice
2
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
3

4
    @ExceptionHandler(Exception.class)
5
    protected ResponseEntity<Object> handleBusiness(BusinessException ex, WebRequest request) {
6
        var body = Map.of("status", 409, "title", ex.getMessage());
7
        return handleExceptionInternal(ex, body, new HttpHeaders(), HttpStatus.CONFLICT, request);
8
    }
9

10
    // 重写validation处理，返回统一错误格式
11
    @Override
12
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
13
         MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatus status, WebRequest request) {
14
        var errors = ex.getBindingResult().getFieldErrors().stream()
15
            .map(f -> Map.of("field", f.getField(), "msg", f.getDefaultMessage()))
16
            .toList();
17
        var body = Map.of("status", 400, "title", "Validation Failed", "errors", errors);
18
        return handleExceptionInternal(ex, body, headers, HttpStatus.BAD_REQUEST, request);
19
    }
20
}

（一）Servlet Filter#

Filter是Servlet 规范层面的组件，属于Servlet容器提供的机制，在请求进入DispatcherServlet前被调用，用于实现请求的预处理与响应的后处理。

但是由于顺序最优先，所以其无法直接访问Spring的组件，因为隔了一层拦截器，而且也无法对业务方法参数、注解等进行细粒度拦截。

1
@Configuration
2
public class FilterConfig {
3

4
    @Bean
5
    public FilterRegistrationBean<LogFilter> logFilter() {
6
        FilterRegistrationBean<LogFilter> bean = new FilterRegistrationBean<>();
7
        bean.setFilter(new LogFilter());
8
        bean.addUrlPatterns("/*");
9
        bean.setOrder(1);
10
        return bean;
11
    }
12
}
13

14
@Component
15
@Order(1)
16
public class LogFilter implements Filter {
17

18
    @Override
19
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
20
            throws IOException, ServletException {
21
        HttpServletRequest req = (HttpServletRequest) request;
22
        // 放行
23
        chain.doFilter(request, response);
24
    }
25
}

一般用于安全校验、日志记录等等。

如今推荐在Filter内部进行用户权限校验 自JDK25后虚拟线程相关的新特性得以稳定发布，以后会使用ScopedValue + 虚拟线程来替代如今的ThreadLocal + 平台线程。 关于ScopedValue如果不是很了解的同学可以阅读下面这两篇博客： 带你轻松学习虚拟线程和StructuredTaskScope-CSDN博客 跟进 JDK25：将虚拟线程安全引入生产的权衡与实战_jdk25 线程池-CSDN博客 ScopedValue是以作用域的形式绑定值的，也就是说值的可见性取决于我们在哪个线程、哪个代码块中调用了run方法。 而Filter的设计正好完整包裹住了一次请求经过的全部代码块，如果在Filter中进行用户权限校验的话，run方法也正好包住了这个请求，确保拦截器、控制器、视图等都处在同一个作用域内，这是最简单，同时也是最有效的。

为什么不推荐在Interceptor内部调用run方法？ 因为Filter的回调设计是包住了整个请求链，与作用域的定义很切合，而Interceptor的回调则是分开的另一个方法，也就是说在请求的时候调用的是preHandle方法，响应的时候调用的又是afterCompletion方法，作用域是完全分开的，如果在拦截器中调用run方法，那么在调用完preHandle方法后ScopedValue的作用域就结束了。 因此，如果要使用ScopedValue + 虚拟线程的方案，请将用户权限校验从拦截器迁移至过滤器，具体实现可见我上面发的博客。

（二）Handler Interceptor#

Interceptor 是Spring MVC层面的拦截机制，它拦截的是 Controller 方法调用前后的流程。属于Spring框架控制，不依赖Servlet容器。

因此，其可以访问HandlerMethod、ModelAndView等等。

1
@Configuration
2
public class WebConfig implements WebMvcConfigurer {
3

4
    @Autowired
5
    private AuthInterceptor authInterceptor;
6

7
    @Override
8
    public void addInterceptors(InterceptorRegistry registry) {
9
        registry.addInterceptor(authInterceptor)
10
                .addPathPatterns("/api/**")
11
                .excludePathPatterns("/api/login");
12
    }
13
}
14

15
@Component
16
public class AuthInterceptor implements HandlerInterceptor {
17

18
    // 控制器方法调用前执行
19
    @Override
20
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
21
            throws Exception {
22
        String token = request.getHeader("Authorization");
23
        if (token == null || !token.equals("valid-token")) {
24
            response.setStatus(HttpStatus.UNAUTHORIZED.value());
25
            response.getWriter().write("Unauthorized");
26
            return false;
27
        }
28
        return true;
29
    }
30

31
    // 控制器方法执行后
32
    @Override
33
    public void postHandle(HttpServletRequest request, HttpServletResponse response,
34
                           Object handler, ModelAndView modelAndView) {
35
        System.out.println("postHandle 执行");
36
    }
37

38
    // 整个请求结束后
39
    @Override
40
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
41
                                Object handler, Exception ex) {
42
        System.out.println("afterCompletion 执行");
43
    }
44
}

一般用于权限校验、日志记录或者AOP替代等等。

（一）MVC层#

使用@CrossOrigin注解，当请求到达HandlerMapping阶段的时候会检测是否符合预检请求，若符合，则会直接使用CorsProcessor进行处理，并返回CORS头响应。

@CrossOrigin注解可放在类或方法上，方法的优先级大于类，若匹配才会返回允许响应体。

1
@RestController
2
@RequestMapping("/api")
3
@CrossOrigin(origins = "https://app.example.com", maxAge = 3600)
4
public class ApiController {
5

6
    @PostMapping("/submit")
7
    @CrossOrigin(origins = {"https://a.example.com","https://b.example.com"},
8
                 allowedHeaders = {"Content-Type","X-My-Header"},
9
                 allowCredentials = "true")
10
    public String submit(@RequestBody MyDto dto) {
11
    }
12
}

当然，MVC也支持全局预检请求校验：

1
@Configuration
2
public class WebConfig implements WebMvcConfigurer {
3

4
    @Override
5
    public void addCorsMappings(CorsRegistry registry) {
6
        registry.addMapping("/api/**")
7
                .allowedOrigins("https://app.example.com")
8
                .allowedMethods("GET","POST","PUT","DELETE","OPTIONS")
9
                .allowedHeaders("Content-Type","Authorization")
10
                .exposedHeaders("X-Total-Count")
11
                .allowCredentials(true)
12
                .maxAge(3600);
13
    }
14
}

既然是MVC层，那么触发时机肯定没有Filter层的早，而且无法处理DispatcherServlet以外的请求。

（二）Filter层#

1
@Bean
2
public FilterRegistrationBean<CorsFilter> corsFilterRegistration() {
3
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
4
    CorsConfiguration config = new CorsConfiguration();
5
    config.setAllowedOrigins(List.of("https://app.example.com"));
6
    config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","OPTIONS"));
7
    config.setAllowedHeaders(List.of("*"));
8
    config.setAllowCredentials(true);
9
    config.setMaxAge(3600L);
10
    source.registerCorsConfiguration("/**", config);
11

12
    CorsFilter corsFilter = new CorsFilter(source);
13
    FilterRegistrationBean<CorsFilter> bean = new FilterRegistrationBean<>(corsFilter);
14
    bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
15
    return bean;
16
}

原理都是一致的，只是可处理请求范围和调用时机不一致。

MVC层更为灵活，可扩展性更高；而Filter层的调用时机最早，实际请根据业务逻辑进行权衡。

（一）Servlet 3.0 异步支持#

容器线程可以调用request.startAsync()，获得AsyncContext，然后返回，容器线程释放。你可以在其他线程用AsyncContext.complete() 完成请求或dispatch()将请求重新派发回容器处理。

1
public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
2
    AsyncContext ac = req.startAsync();
3
    ac.setTimeout(60000);
4
    ac.start(() -> {
5
        try {
6
            Thread.sleep(2000);
7
            resp.getWriter().write("done");
8
        } catch(Exception e) {
9
            e.printStackTrace();
10
        } finally {
11
            // 结束响应
12
            ac.complete();
13
        }
14
    });
15
}

可以使用AsyncListener进行生命周期回调的监听：

• onComplete(AsyncEvent)：正常完成时调用。
• onTimeout(AsyncEvent)：超时时调用。
• onError(AsyncEvent)：异常时调用。
• onStartAsync(AsyncEvent)：当 startAsync 再次调用时触发（嵌套 async）。

（二）线程上下文#

当一个请求从容器线程切换到后台线程进行异步处理的时候，当前线程关联的上下文一般不会自动跨线程传播，一般需要自己实现一些逻辑。

但如果使用的是JDK25的虚拟线程，我们完全可以使用结构化并发 + ScopedValue来替代传统的异步编程模式，直接在结构化并发的域中传递当前父线程的ScopedValue，然后开启一个子线程任务等待结束回调即可。

1
ScopedValue<String> USER = ScopedValue.newInstance();
2

3
ScopedValue.where(USER, userId).run(() -> {
4
    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
5
        var fut = scope.fork(() -> test(USER.get()));
6
        scope.join();
7
        scope.throwIfFailed();
8
    }
9
});

（一）匹配映射#

调用DispatcherServlet.getHandler(request)，遍历已经注册的HandlerMapping，按order顺序查找第一个匹配的HandlerExecutionChain并返回。

注意这就是之前CORS校验是否是预检请求的阶段。

（二）获取适配器#

拿着Handler后，调用DispatcherServlet.getHandlerAdapter(handler)，遍历handlerAdapters，查找第一个匹配的适配器并返回，关于适配器的作用在上文也已经提到过了。

（三）触发拦截器preHandle#

调用HandlerExecutionChain.applyPreHandle(request,response)，会正序按order顺序遍历每一个拦截器，并调用其中的preHandle方法，任意拦截器返回false就会跳过第四步，直接执行第五步。

（四）执行方法#

调用RequestMappingHandlerAdapter.handle(HttpServletRequest, HttpServletResponse, Object handler)，执行方法。

内部具体流程为：

先调用InvocableHandlerMethod.invokeAndHandle()遍历解析器链匹配合适的解析器进行方法参数解析，其中@RequestBody的解析器还会根据请求头的Content-Type将请求体反序列化。

接着调用目标方法并获取返回值或者异常。

然后遍历处理器链，匹配合适的处理器来决定是构造ModelAndView还是直接写响应体，其中@Response的处理器会根据响应头的Content-Type将请求体序列化。

（五）触发拦截器postHandle#

调用mappedHandler.applyPostHandle(request, response, mv)，会逆序遍历第三步返回true的拦截器，并调用其中的postHandle方法，一般用于在视图渲染前对执行方法返回体进行修改。

注意这里只会调用第三步返回true的拦截器的方法！

（六）渲染视图#

若ModelAndView为null且当前响应已经写入了响应体了，则直接跳过该步。

反之则调用resolveViewName(modelAndView.getViewName(), locale)遍历ViewResolver直至找到第一个可以渲染的View实例。

调用view.render(model, request, response)进行视图的渲染。

（七）触发拦截器afterCompletion#

调用mappedHandler.triggerAfterCompletion(request, response, null)，逆序遍历第三步返回true的拦截器，并调用其中的afterCompletion方法。

（八）异常处理#

若以上任意步骤抛出了异常，则会被catch块捕获，立即执行processHandlerException(request, response, mappedHandler, ex)，遍历异常解析器，直至匹配后进行处理，具体处理流程上文也已经提到过。