1 / 4概念
Routing
Spring MVC 把一次 HTTP 请求拆成一条可替换的处理器链,数据访问层把连接与事务收进方法边界之外的代理。两者的接缝就在 controller 调 service 的那一行:协议转换在此结束,工作单元在此开始。
1 概念
1.1 一句话定义
Spring MVC 是以 DispatcherServlet 为入口的请求调度器,它找到处理器、解析参数、调用方法、转换返回值。数据访问层则把连接、事务与持久化上下文包进代理,让一次方法调用对应一个工作单元。
1.2 它解决什么问题
- 协议与领域分离:controller 只做 HTTP 数据到对象的转换,不承载用例。
- 统一的失败形状:约束注解与全局异常处理把校验失败收敛成一种响应。
- 声明式事务:边界写在方法签名上,不必手写提交与回滚。
- 连接复用:连接池把建连成本摊到请求之外。
- 可控的查询代价:分页、抓取策略与批量操作都有显式开关。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| bean 定义、条件评估与配置绑定 | Container and Configuration |
| 认证、CORS 与 CSRF 在链上的位置 | Security and Operations |
| 隔离级别、锁与 MVCC 的理论 | Transactions & Concurrency |
| 索引、执行计划与范式设计 | Relational Databases |
| 类加载与线程模型 | JVM Runtime |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
DispatcherServlet | 前端控制器,请求的统一入口 | 不是业务 controller |
HandlerMapping | 请求到处理器的映射 | 不负责参数解析 |
HandlerAdapter | 以统一方式调用处理器 | 不是映射的替代品 |
| 参数解析器 | 把请求数据转成方法参数 | 与消息转换器分工不同 |
HttpMessageConverter | 请求体与响应体的序列化 | 只管 body,不管表单字段 |
HandlerInterceptor | MVC 层的前后置钩子 | 与 filter 不在同一层 |
@ControllerAdvice | 跨 controller 的异常与绑定处理 | 管不到 filter 层异常 |
@Transactional | 声明事务边界 | 靠代理生效 |
| 传播行为 | 遇到已有事务时的策略 | 不是隔离级别 |
| 工作单元 | 一次事务内的持久化上下文 | 不是一次请求 |
| N+1 | 一次查询带出 N 次关联查询 | 与批量抓取相对 |
2 机制
2.1 心智模型
一次请求是一条固定形状的管道:定位处理器、适配调用、解析参数、转换返回值、写回响应。一次数据库写入是代理包住的一段方法体:进入时取连接并开启事务,正常返回则提交,抛出运行期异常则回滚。
2.2 机制拆解
- 请求链:
DispatcherServlet从HandlerMapping取得处理器,交给HandlerAdapter调用;参数由解析器从路径、查询串、请求体与头里取出,返回值由处理器写回,序列化交给HttpMessageConverter。 - 两层拦截:filter 在 Servlet 容器里,早于
DispatcherServlet,看不到处理器;interceptor 在 MVC 里,能读HandlerMethod上的注解。 - 参数绑定:简单类型走类型转换与格式化,复杂对象走数据绑定,请求体走消息转换器;绑定失败抛
BindException。 - 校验:绑定完成后由 Jakarta Bean Validation 接手,
@Valid让嵌套对象一并校验,@Validated打开分组与方法级约束,失败时抛MethodArgumentNotValidException。 - 错误映射:
@ExceptionHandler按异常类型就近匹配,@ControllerAdvice把它提升为全局规则,ResponseEntityExceptionHandler提供默认状态码映射。 - 内容协商:按
Accept、路径后缀与默认类型选出媒体类型,找不到可生产的类型时返回 406。 - 事务代理:
@Transactional由BeanPostProcessor生成的代理实现,进入前按传播行为决定加入还是新建,退出时按回滚规则提交或回滚。 - 持久化上下文:实体在事务内被托管,事务结束即分离,分离后访问未加载的关联会抛
LazyInitializationException。
2.3 完整枚举
请求处理链的完整组件:
| 组件 | 职责 |
|---|---|
Filter | Servlet 层拦截,可改写请求与响应 |
DispatcherServlet | 调度中心,串起后续组件 |
HandlerMapping | 按路径、方法、头匹配处理器 |
HandlerAdapter | 以统一方式调用处理器 |
HandlerMethodArgumentResolver | 把请求数据解析成方法参数 |
HandlerMethodReturnValueHandler | 把返回值写成响应 |
HttpMessageConverter | 读写请求体与响应体 |
HandlerInterceptor | 处理器执行前后的钩子 |
HandlerExceptionResolver | 把异常转成响应 |
ViewResolver | 把视图名解析成模板 |
事务传播行为的完整取值:
| 传播行为 | 已有事务时 | 适用 |
|---|---|---|
REQUIRED | 加入 | 默认,绝大多数用例 |
REQUIRES_NEW | 挂起并新建 | 审计日志、需要独立提交 |
SUPPORTS | 加入,无则不用事务 | 只读查询 |
NOT_SUPPORTED | 挂起,不用事务 | 长耗时非事务操作 |
MANDATORY | 加入,无则抛异常 | 必须由上层开启 |
NEVER | 抛异常 | 禁止在事务内调用 |
NESTED | 建立保存点 | 局部失败可回滚 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 请求线程 | 200 | server.tomcat.threads.max 的默认值 |
| 连接池上限 | 10 | HikariCP 默认,按数据库容量调 |
| 连接超时 | 30 秒 | connectionTimeout 的默认值 |
| 默认分页大小 | 20 | spring.data.web.pageable.default-page-size |
| 事务超时 | 无 | 不设则跟随连接与语句超时 |
3 实践
3.1 最小示例
@RestController
@RequestMapping("/orders")
class OrderController {
private final OrderService orders;
OrderController(OrderService orders) { this.orders = orders; }
@GetMapping
Page<OrderDto> list(@PageableDefault(size = 20) Pageable page) {
return orders.page(page).map(OrderDto::from);
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
OrderDto create(@Valid @RequestBody CreateOrder body) {
return OrderDto.from(orders.place(body));
}
}
@Service
class OrderService {
private final OrderRepository repo;
OrderService(OrderRepository repo) { this.repo = repo; }
@Transactional
public Order place(CreateOrder body) {
return repo.save(Order.place(body.sku(), body.qty()));
}
}
追踪:POST /orders 进入 DispatcherServlet 后,RequestMappingHandlerMapping 匹配到 create,HandlerAdapter 调用 RequestResponseBodyMethodProcessor,后者用 Jackson 的转换器把 JSON 读成 CreateOrder;@Valid 在绑定之后执行,失败即抛 MethodArgumentNotValidException,请求不会到达 service。
controller 调 orders.place 时进的是事务代理:代理按 REQUIRED 取连接并开启事务,repo.save 在持久化上下文里插入一行,方法正常返回则提交。响应体随后由转换器写出,@ResponseStatus 把状态码定为 201。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 定义路由 | @GetMapping / @PostMapping | 也可用 @RequestMapping 聚合 |
| 取路径变量 | @PathVariable | 名字与占位符对齐 |
| 读请求体 | @RequestBody | 由消息转换器反序列化 |
| 声明校验 | @Valid 加约束注解 | 级联校验标在字段上 |
| 分页 | Pageable 进、Page 出 | 需要分页参数解析器 |
| 统一异常 | @RestControllerAdvice | 按异常类型就近匹配 |
| 开事务 | @Transactional | 调用方不能是同一个类 |
| 设超时 | @Transactional(timeout = 5) | 秒为单位,超时抛异常 |
| 看 SQL | logging.level.org.hibernate.SQL=DEBUG | 配合 show-sql |
| 调连接池 | spring.datasource.hikari.maximum-pool-size | 对齐数据库连接上限 |
3.3 标准流程
- controller 只负责适配 HTTP 与校验,不写业务分支。
- service 承载用例,repository 只负责读写与查询。
- 事务内只碰数据库不变式,远程调用放到事务外。
- DTO 与实体分离,响应不直接返回实体。
- 列表接口一律分页,深分页改用游标。
- 错误统一由 advice 映射,controller 里不写兜底的 try-catch。
3.4 与相邻技术的组合
- Container and Configuration:事务代理本身就是
BeanPostProcessor的产物,配置错误会让注解静默失效。 - Security and Operations:filter 早于 MVC,认证失败不会进入 controller。
- Relational Databases:索引决定分页代价,无索引的深分页会退化成全表扫描。
- Transactions & Concurrency:隔离级别由数据库实现,注解只是把它传下去。
- 前端契约:分页形状与错误形状一旦发布就是兼容性承诺。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| Web 模型 | MVC / WebFlux | 线程模型与阻塞库兼容性 |
| 数据访问 | JPA / JDBC / jOOQ / MyBatis | SQL 控制力与映射成本 |
| 事务边界 | service / repository | 代理范围与连接占用 |
| 传播行为 | REQUIRED / REQUIRES_NEW | 连接数与独立提交 |
| 分页方式 | offset / keyset | 深分页代价 |
| 序列化 | Jackson / 其他 | 契约兼容与字段命名 |
3.6 决策规则
- 工作单元由 service 的公开方法界定,controller 不持有事务。
- 自调用会绕过代理,把事务方法移到另一个 bean。
- 用实体图或抓取连接解决 N+1,不要靠延迟到视图层掩盖。
- 深分页用 keyset,不用大 offset。
- 写接口带幂等键,重试才不会重复插入。
- 连接池按数据库容量设,不按请求线程数设。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| Spring Data JPA | 派生查询、领域模型 | 复杂 SQL 表达别扭 | CRUD 为主的领域 |
JdbcTemplate | SQL 完全可控 | 手写映射 | 报表、批量 |
| jOOQ | 类型安全 SQL | 需要代码生成 | 复杂查询 |
| MyBatis | SQL 与映射分离 | SQL 留在字符串里 | 遗留 SQL 迁移 |
| WebFlux 加 R2DBC | 高并发、背压 | 生态窄、阻塞库不兼容 | 网关、流式接口 |
3.8 何时不该用
- 只读报表查询,JPA 的映射成本高于收益。
- 需要数据库特有语法时,派生查询会写出错误的 SQL。
- 响应式链路里不要混入阻塞的 JPA。
- 大批量 ETL 用 ORM 是灾难,改用批处理或原生 SQL。
- 事务里不要发 HTTP 请求,超时会拖住连接。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
@Transactional 不生效 | 自调用、非 public,或对象不是 bean | 移到另一个 bean |
| 接口 500 且无栈信息 | 异常被吞或缺少 advice | 补全局异常处理 |
| 400 没有字段信息 | 校验未触发 | 补 @Valid 与约束注解 |
| 列表接口出现 N+1 | 懒加载逐条触发 | 抓取连接或实体图 |
| 连接池耗尽 | 事务里做远程调用 | 缩短事务、拆出远程调用 |
| 深分页越来越慢 | offset 扫描全表 | 改 keyset 分页 |
| 提交后查不到数据 | 只读事务,或缓存未失效 | 检查事务与缓存顺序 |
| 响应体序列化循环 | 双向关联直接返回 | 用 DTO |
| 乐观锁冲突返回 500 | 未捕获 OptimisticLockingFailureException | 映射成 409 |
| 事务超时但连接未归还 | 池参数不当或连接泄漏 | 开 leakDetectionThreshold |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| controller 里开事务 | 协议层绑死事务 | service 承载用例 |
| 实体直接作为 API 返回 | 契约随表结构漂移 | DTO |
| 事务里调第三方接口 | 连接被长时间占用 | 事务外调用加重试 |
ddl-auto=update 上生产 | 表结构随实体漂移,无法回滚 | 迁移工具 |
| 捕获异常后返回 null | 调用方无法区分失败 | 抛出并统一映射 |
4.3 可观测信号
请求侧看 http.server.requests 的 p95、状态码分布与按路径的耗时;数据库侧看连接池活跃数、等待数、获取连接耗时、慢 SQL 与事务回滚次数。两侧要对齐同一时间窗,才能分清是线程不够还是连接不够。
4.4 安全 / 性能 / 一致性边界
- 安全边界:参数绑定与校验只挡格式,不挡越权,查询必须自带租户与权限条件。
- 事务边界:事务不覆盖响应写出,也不覆盖缓存失效,提交与响应之间的失败会留下不一致。
- 性能边界:连接数不是并发数,池子放大只是把压力推到数据库。
- 一致性边界:重试、幂等与提交顺序共同决定最终状态,缺一项就会重复写入。