06.8.2.2 Kotlin DSL、协程与 WebFlux
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.8 Kotlin 后端 / 06.8.2 Spring Boot 与 Kotlin
本节要解决的问题
- Spring 的 Kotlin Bean DSL 与函数式路由 DSL 如何组织 Bean 定义和路由?
- Kotlin 协程如何与 Spring MVC / WebFlux 桥接,
suspend控制器、上下文传播与线程模型有哪些坑? - WebFlux 响应式链路中的背压、调度器选择、事务边界与上下文丢失如何处理?
版本前提:Spring Boot 3.2+ / Spring 6.x / Kotlin 2.x / kotlinx-coroutines 1.x / JDK 17+;响应式通用原理(Reactor 机制、Netty 线程模型)见 06.2 与 08 分册,本节只写 Kotlin 协程与 DSL 特化视角。版本敏感项标「待确认」。
06.8.2.2-001 Spring 的 beans { } Kotlin DSL 定位是什么?
一句话结论
beans { } 是函数式 Bean 定义 DSL,用 Kotlin lambda 风格在代码中声明 Bean 及其依赖关系,替代部分 @Configuration 注解配置,类型推导更直接、无注解扫描开销。
概念解释
DSL 在 GenericApplicationContext 等容器上调用 beans { } 块,内部 bean() 方法注册定义。它属于函数式注册路径,不依赖类路径扫描,适合显式组装、库模块与测试上下文。
原理流程
- 创建或获取 ApplicationContext。
- 执行
beans { }配置块。 - 块内
bean()调用向注册表追加 BeanDefinition。 - 容器刷新时按定义实例化。
代码或图示
val context = GenericApplicationContext().apply {
beans {
bean<OrderRepository>()
bean { OrderService(ref(), ref()) }
}
refresh()
}
常见误区
- 以为 DSL 能替代全部自动配置:它只负责显式 Bean 定义,自动配置仍由 Boot 条件装配提供。
- 在 DSL 块里直接 new 协作对象却不注册:该对象脱离容器生命周期。
追问
- DSL 与
@Configuration能否混用?答:可以,两者都向同一注册表追加定义,见共存条目。 - DSL 依赖解析在什么时候发生?答:注册阶段只存定义,实例化在容器刷新阶段。
06.8.2.2-002 Bean DSL 与注解配置相比如何取舍?
一句话结论
注解配置适合组件扫描与自动装配的应用代码;DSL 适合显式编排第三方 Bean、库模块导出与测试上下文;选型看依赖关系是否需要集中、显式地表达。
概念解释
注解配置靠扫描与类型推断,DSL 靠代码显式声明。DSL 中依赖关系一眼可见,不依赖类路径扫描;注解配置在常规业务组件上更简洁。两者解决同一问题的不同风格。
原理流程
- 应用业务组件:注解扫描自动注册。
- 第三方/编排对象:DSL 显式
bean()。 - 测试上下文:DSL 快速组装最小容器。
- 团队内保持一种主风格,局部混用。
代码或图示
// 注解:业务组件
@Service
class NotificationService(private val sender: Sender)
// DSL:编排客户端与第三方对象
beans {
bean<RetryPolicy>()
bean { ThirdPartyClient(ref(), properties.baseUrl) }
}
常见误区
- 全项目强制 DSL:业务组件扫描的便利性被牺牲。
- 在 DSL 里写业务
@Service等价物:职责与注解体系重复。
追问
- DSL 有条件装配能力吗?答:支持条件块,见后续条件条目。
- 库模块推荐哪种?答:库通过自动配置类或 DSL 导出 Bean,由集成方选择;通用 starter 机制见 06.2。
06.8.2.2-003 bean() 方法的参数与类型如何推导?
一句话结论
bean<T>() 直接声明类型;带 lambda 的 bean { } 通过 lambda 返回值推导 Bean 类型;构造参数用 ref() 按类型解析,缺限定符时由容器按类型匹配。
概念解释
DSL 提供重载:类型参数显式泛型、lambda 工厂、引用已有 Bean。返回类型决定容器中 Bean 的可解析类型,lambda 内 ref() 是依赖占位符,刷新时替换为真实 Bean。
原理流程
- 调用
bean<Type>()注册类型定义。 - 或
bean { FactoryClass(ref(), ref()) },lambda 返回实例。 ref<T>()标记构造/方法参数依赖。- 容器刷新时解析
ref()并调用工厂。
代码或图示
beans {
bean<CacheStore>()
bean { ReportService(ref(), ref<CacheStore>()) }
}
常见误区
- lambda 返回类型写宽泛父类导致只能按父类型注入:声明具体返回类型或泛型实参。
ref()不加类型标注又存在多候选:解析歧义。
追问
ref()与构造器注入等价吗?答:作用相同,都是按类型解析容器 Bean。- 能给
ref()指定 Bean 名吗?答:DSL 引用可按名称/限定符解析,具体 API 以 Spring Kotlin DSL 文档为准(待确认)。
06.8.2.2-004 DSL 中如何定义单例与其他作用域 Bean?
一句话结论
默认注册为单例;scope 参数或 DSL 作用域声明可改为原型等其他作用域,作用域在定义阶段确定,实例化行为由容器按作用域管理。
概念解释
Bean 定义携带作用域标志。DSL 默认为单例,需要每次获取新实例时显式声明 prototype 等作用域;作用域选择影响实例数量与销毁管理。
原理流程
bean()注册定义并指定作用域。- 单例:容器创建一份并缓存。
- 原型:每次获取新建。
- 其他作用域(request/session 等)仅在对应 Web 上下文中有效。
代码或图示
beans {
bean { DefaultClient() } // 单例
bean<ReportTemplate>(scope = BeanDefinition.SCOPE_PROTOTYPE)
}
常见误区
- 原型 Bean 注入单例后变成「共享一次实例」:单例持有原型引用,原型不会每次新建;通用作用域原理见 06.2。
- 在非 Web 上下文声明 request 作用域:无对应作用域上下文,获取失败。
追问
- DSL 能定义懒加载吗?答:定义可标记 lazy,实例化推迟到首次获取;具体 DSL 字段以官方文档为准。
- 作用域与线程安全关系?答:单例共享状态需自行保证线程安全。
06.8.2.2-005 DSL 中如何引用已注册的 Bean?
一句话结论
块内用 ref() 按类型引用其他 Bean,返回解析后的实例占位;同一 DSL 块内注册顺序不构成依赖顺序,容器按依赖图在刷新阶段解析。
概念解释
ref() 不在 DSL 编写时取实例,而是在定义中记录依赖,刷新时解析。因此被引用 Bean 定义写在块内前后位置都可以,拓扑排序决定创建顺序。
原理流程
- 工厂 lambda 内写
ref()占位。 - 定义记录依赖类型。
- 容器刷新按依赖图排序创建。
- 把解析实例传入工厂。
代码或图示
beans {
bean { OrderService(ref()) } // 引用下面定义的 Repository
bean<OrderRepository>()
}
常见误区
- 以为块内顺序就是创建顺序:顺序无关,依赖图才决定顺序。
- 在 DSL 块顶层直接调用
ref()取实例:注册阶段实例尚未创建。
追问
- 循环依赖在 DSL 中如何暴露?答:同样在刷新阶段报循环依赖,与注解配置行为一致。
- 集合引用支持吗?答:可注入
List<T>收集同类型 Bean,通用集合注入规则见 06.2。
06.8.2.2-006 DSL 中如何声明生命周期钩子?
一句话结论
工厂 lambda 内可返回实例并配合销毁回调声明;DSL 也提供初始化/销毁回调的 DSL 入口,实例实现 InitializingBean/DisposableBean 同样被容器识别。
概念解释
生命周期回调发生在实例化之后:初始化完成后调用 init 回调,容器关闭时调用 destroy。DSL 注册的 Bean 与注解 Bean 走同一套回调机制。
原理流程
- DSL 工厂创建实例。
- 容器执行初始化回调。
- 请求期正常使用。
- 关闭阶段执行销毁回调释放资源。
代码或图示
beans {
bean {
val client = PoolingClient()
client
}
// 销毁/初始化钩子写法以 DSL 官方 API 为准(待确认)
}
常见误区
- 在工厂 lambda 里启动后台线程却不注册销毁钩子:容器关闭后线程泄漏。
- 把初始化逻辑写进工厂构造期:此时其他依赖可能尚未全部装配完成。
追问
@PostConstruct对 DSL Bean 生效吗?答:生效,注解回调由容器统一识别。- 销毁方法名自动推断规则?答:与注解配置一致,通用规则见 06.2。
06.8.2.2-007 DSL 中如何做条件装配?
一句话结论
DSL 提供条件块或在 bean() 上挂载条件谓词,按类路径、已有 Bean 或环境属性决定定义是否注册;条件在注册求值阶段生效,与注解条件语义对应。
概念解释
条件装配在定义阶段过滤:满足条件才把定义加入注册表。DSL 条件可直接访问 Environment 与注册表,避免为简单条件单独写 Condition 类。
原理流程
- DSL 块读取环境/已有定义。
- 条件谓词求值为真才调用
bean()。 - 不满足则跳过注册。
- 刷新阶段只创建保留的定义。
代码或图示
beans {
if (environment.getProperty("feature.cache") == "redis") {
bean<RedisCacheClient>()
}
}
常见误区
- 在条件判断里实例化目标 Bean:条件阶段只应做元数据判断。
- 条件块依赖其他 Bean 实例:注册阶段实例不存在,只能查定义。
追问
- DSL 条件能复用
@ConditionalOnClass吗?答:可组合使用 Spring 条件接口,通用条件机制见 06.2。 - 条件缺失 Bean 怎么判断?答:按 BeanDefinition 类型检查,不获取实例。
06.8.2.2-008 函数式配置类如何被容器加载?
一句话结论
函数式配置可通过 ApplicationInitializer、编程式注册器或 DSL 上下文初始化器挂载到容器;启动时在刷新前执行配置块,把定义写入注册表。
概念解释
不同于注解配置类被扫描识别,函数式配置是一段可执行代码,需要入口把它接入容器启动流程。入口可以是主类中的显式调用、Initializer 或自动配置提供的注册器。
原理流程
- 容器创建并注册初始化器。
- 刷新前执行函数式配置块。
- 定义写入 BeanDefinitionRegistry。
- 进入常规刷新与实例化。
代码或图示
// 入口示意:在应用初始化阶段执行 DSL 配置
val context = SpringApplicationBuilder(Application::class.java)
.initializers { ctx ->
(ctx as ConfigurableApplicationContext).beans { bean<ExtraClient>() }
}
常见误区
- 写了 DSL 配置块但没有入口挂载:定义永远不进注册表。
- 在 Web 容器启动后才执行配置块:错过了定义注册时机。
追问
- Boot 自动配置能否用 DSL 导出?答:自动配置类仍是主要入口,DSL 可在其内部使用;通用自动配置见 06.2。
- 初始化器执行顺序?答:在上下文刷新前的初始化阶段,通用启动流程见 06.2。
06.8.2.2-009 Kotlin DSL 初始化器如何拿到 ApplicationContext?
一句话结论
DSL 块的接收者提供容器/注册表与 Environment 访问能力;配置代码在块内通过接收者上下文读取环境属性、注册定义,不需要静态获取全局容器。
概念解释
DSL 依赖 lambda 接收者暴露上下文 API。块内可访问环境、注册表与已有定义,块外不应假设容器已就绪。上下文对象把注册能力收敛到配置阶段。
原理流程
- 容器构造 DSL 接收者。
- 配置块在接收者作用域内执行。
- 通过接收者读 Environment、写定义。
- 块结束后接收者能力不再可用。
代码或图示
beans {
// 接收者暴露 environment 与注册能力
val profile = environment.activeProfiles.firstOrNull()
if (profile == "dev") bean<DevInstrumentation>()
}
常见误区
- 把接收者上下文保存为静态字段跨阶段使用:注册阶段上下文不应泄漏到运行期。
- 块内直接获取 Bean 实例:此时实例尚未创建。
追问
- 接收者类型是什么?答:Spring Kotlin DSL 配置上下文对象,具体类型名以官方文档为准(待确认)。
- 能否在 DSL 中发布事件?答:事件发布属于运行期容器能力,配置阶段不应对实例发事件。
06.8.2.2-010 DSL 中如何读取 Environment?
一句话结论
通过 DSL 接收者暴露的 environment 属性读取激活 Profile、属性源与占位符;条件判断在配置阶段基于环境元数据完成,不解析 Bean 实例。
概念解释
Environment 持有 Profile 与属性源视图,DSL 条件常用它做开关判断。读取的是属性文本与 Profile 集合,类型转换在需要时手动完成。
原理流程
- 接收者暴露 Environment。
- 读取属性键、激活 Profile。
- 按条件决定是否注册定义。
- 属性值在后续 Bean 中再做类型绑定。
代码或图示
beans {
val enabled = environment.getProperty("mq.enabled") == "true"
if (enabled) bean<KafkaConsumer>()
}
常见误区
- 在 DSL 里把属性直接绑定成强类型配置类:强类型绑定由
@ConfigurationProperties完成,DSL 只做开关判断。 - 读不到 Profile 就以为环境未加载:检查初始化器执行时机。
追问
- 属性源优先级在 DSL 阶段已确定吗?答:Environment 属性源在上下文准备阶段就绪,优先级规则同通用外部化配置。
- 能读取命令行参数吗?答:可以,命令行属性已纳入 Environment 属性源。
06.8.2.2-011 多模块项目如何组织多段 DSL 配置?
一句话结论
每个模块提供自己的 DSL 配置函数,主应用按模块顺序调用或由初始化器汇总;各段只注册本模块定义,公共依赖通过约定的类型与名称解析,避免跨段直接引用实例。
概念解释
DSL 配置可拆成多个函数,按模块职责分段。汇总入口把各段应用到同一注册表,段之间通过容器类型依赖解耦,而不是在代码里互相持有的中间变量。
原理流程
- 模块 A 定义
configureA(ctx)注册自身 Bean。 - 模块 B 定义
configureB(ctx)。 - 主入口依次应用各段。
- 容器统一按依赖图解析。
代码或图示
fun BeanDefinitionRegistry.orderModule() { /* 注册订单相关 */ }
fun BeanDefinitionRegistry.payModule() { /* 注册支付相关 */ }
常见误区
- 段之间共享局部变量传递实例:绕过容器注册,生命周期失控。
- 模块 DSL 互相依赖对方段先执行:应通过类型依赖让容器排序。
追问
- 库模块如何暴露 DSL?答:导出配置函数或自动配置类,集成方选择挂载方式。
- 多段 DSL 与多配置类顺序等价吗?答:定义注册时机都在刷新前,实例化顺序由依赖图决定。
06.8.2.2-012 DSL 配置与 @Configuration 共存时优先级如何?
一句话结论
两者写入同一注册表,定义按名称与类型参与合并;同名覆盖受容器覆盖策略控制,同类型多候选在注入点按限定符解析,不存在「DSL 优先于注解」的固定优先级。
概念解释
共存时关键是避免重复定义与候选歧义。注册来源不同但机制相同:都是 BeanDefinition。排查重复时区分定义来自 DSL 块还是扫描配置类。
原理流程
- 注解扫描与 DSL 块分别写定义。
- 合并注册表,检查同名与同类型。
- 覆盖策略决定同名取舍。
- 注入点解析候选。
代码或图示
// 注解侧:@Configuration 注册 Client
// DSL 侧:beans { bean<Client>() }
// 合并后确认是否重复定义或需要限定符区分
常见误区
- 以为 DSL 定义一定覆盖注解定义:覆盖由容器策略与注册顺序决定。
- 同类型两套实现不加区分:注入点歧义报错。
追问
- 如何定位某个 Bean 的注册来源?答:查看定义来源描述或启动调试日志,通用排查见 06.2。
- 允许覆盖开关作用于 DSL 定义吗?答:作用于整个注册表,通用覆盖规则见 06.2。
06.8.2.2-013 DSL 中如何自定义 Bean 名称?
一句话结论
bean() 可指定名称参数,未指定时按类型/工厂推导名称;关键集成点需要固定名称时显式命名,避免类重命名导致名称漂移。
概念解释
Bean 名称是容器内引用键。DSL 默认推导规则与注解配置不同,需要按名称注入或对接既有契约时显式传入名称参数。
原理流程
- 调用
bean(name) { ... }指定名称。 - 注册表以该名称保存定义。
- 按名称引用时使用该键。
- 未指定则按 DSL 推导规则生成默认名。
代码或图示
beans {
bean("primarySender") { SmsSender() }
}
常见误区
- 依赖默认推导名做按名称注入:类型调整后默认名变化,引用断裂。
- 自定义名与既有定义冲突:注册表出现同名覆盖。
追问
- 显式名与限定符如何配合?答:按名称解析时使用显式名;通用限定符机制见 06.2。
- 名称大小写约定?答:保持与项目既有 Bean 命名一致。
06.8.2.2-014 DSL 中定义原型作用域要注意什么?
一句话结论
原型定义每次获取新建实例,不由容器缓存销毁;DSL 声明原型作用域后,单例持有原型引用只会得到一份固定实例,需要每次新实例时通过 ObjectProvider 获取。
概念解释
原型作用域的创建时机在获取点。DSL 注册时声明作用域即可,但注入方式决定是否每次新建:直接构造器注入只注入一次,ObjectProvider 才能每次取新实例。
原理流程
- DSL 标记定义为 prototype。
- 直接注入:容器创建一份给单例持有。
ObjectProvider.getObject():每次调用新建。- 原型实例销毁由使用方负责。
代码或图示
beans {
bean<ReportTemplate>(scope = BeanDefinition.SCOPE_PROTOTYPE)
}
// 使用方:ObjectProvider<ReportTemplate> 每次取新实例
常见误区
- 以为标了原型,构造器注入就会每次新建:注入发生一次,实例被固定持有。
- 原型持有外部资源却不释放:容器不回调原型销毁。
追问
- 原型 Bean 有初始化回调吗?答:创建时执行初始化回调,销毁回调不保证执行,通用边界见 06.2。
- Web 作用域能在 DSL 声明吗?答:可以声明,但需对应 Web 上下文存在。
06.8.2.2-015 测试中如何用 DSL 断言 Bean 存在与类型?
一句话结论
构造最小 ApplicationContext 后,按类型或名称获取 Bean 断言;DSL 组装的测试上下文可直接验证定义是否注册、依赖是否解析,不必启动完整应用。
概念解释
单元/切片测试中用 DSL 显式装配最小容器,断言关键 Bean 存在、类型正确、条件装配结果符合预期。测试上下文比完整 Boot 上下文更快启动。
原理流程
- 创建 GenericApplicationContext 并执行 DSL。
- refresh 后按类型获取 Bean。
- 断言非空、类型与关键行为。
- 关闭上下文释放资源。
代码或图示
val ctx = GenericApplicationContext().apply {
beans { bean<OrderService>(ref()) }
bean<OrderRepository>()
refresh()
}
assertNotNull(ctx.getBean(OrderService::class.java))
常见误区
- 测试中不 refresh 就获取 Bean:定义存在但实例未创建。
- 断言只看定义存在不验证实例化:条件之外的实例化问题没覆盖到。
追问
- DSL 测试能替换桩件吗?答:可在 DSL 中注册桩实现替换默认依赖。
- 与
@SpringBootTest如何分工?答:最小容器用 DSL,切片/集成用注解测试;通用测试策略见 06.8.2.3。
06.8.2.2-016 router { } 函数式路由 DSL 在 Spring 中定位是什么?
一句话结论
router { } 是 Spring Web MVC/WebFlux 共用的函数式路由 DSL,把路由谓词与处理器函数组装成 RouterFunction,替代注解控制器的声明式映射,路由定义集中可读。
概念解释
函数式端点由 HandlerFunction 处理请求,由 RouterFunction 匹配路由。Kotlin DSL 以嵌套 lambda 表达路径、方法、谓词与处理器,适合显式路由编排。
原理流程
router { }块内声明路由规则。- 每条规则绑定 HTTP 方法、路径谓词与处理器函数。
- 生成
RouterFunctionBean 注册到容器。 - 请求进入路由函数按顺序匹配。
代码或图示
@Bean
fun routes(userHandler: UserHandler) = router {
GET("/users", userHandler::list)
GET("/users/{id}", userHandler::byId)
}
常见误区
- 以为 DSL 路由只能用于 WebFlux:MVC 也支持函数式端点,见 MVC 协程条目。
- 把业务逻辑写进路由块:路由只做映射,处理器落在 Handler 组件。
追问
- RouterFunction 与注解控制器能共存吗?答:可以,两套端点在同一应用内并行,见混用条目。
- 路由 DSL 属于哪个依赖?答:spring-web 函数式端点支持,WebFlux/MVC 各自接入;通用 Web 框架见 06.2。
06.8.2.2-017 coRouter 与 router 有什么区别?
一句话结论
router 绑定普通 HandlerFunction(同步或返回 Mono/Flux);coRouter 绑定挂起 suspend 处理器函数,直接使用协程签名,无需手动桥接响应式类型。
概念解释
协程版 DSL 让处理器写 suspend 函数,框架在协程上下文中执行。coRouter 内部完成协程与响应式类型桥接,返回值直接是结果对象或 Flow,不必返回 Mono。
原理流程
coRouter { }注册 suspend 处理器。- 请求进入时框架启动协程执行处理器。
- 挂起函数结果由桥接层转换为响应式输出。
- 异常与取消按协程语义传播。
代码或图示
@Bean
fun coRoutes(handler: CoUserHandler) = coRouter {
GET("/users", handler::listSuspend)
GET("/users/{id}", handler::byIdSuspend)
}
常见误区
- 在
router里写 suspend 方法引用:签名不匹配,应改用coRouter。 - 以为 coRouter 只能在 WebFlux 用:MVC 对 suspend 处理器也有支持,边界见后续条目。
追问
- suspend 处理器返回
Flow怎么处理?答:WebFlux 下映射为流式响应;MVC 行为需按版本文档确认(待确认)。 - coRouter 依赖哪个协程桥接模块?答:kotlinx-coroutines-reactor 与 Spring 协程支持,见依赖条目。
06.8.2.2-018 路由块中如何嵌套声明 GET/POST 等方法谓词?
一句话结论
块内按 HTTP 方法调用 GET("/path", handler)、POST(...) 等,每条规则由方法谓词 + 路径谓词 + 处理器组成;同一块内多条规则按声明顺序参与匹配。
概念解释
方法谓词限定 HTTP 动词,路径谓词匹配 URI。Kotlin DSL 方法名直接对应动词,处理器以方法引用或 lambda 形式提供。规则集合构成 RouterFunction。
原理流程
- 块内声明各方法路由。
- 每条规则生成方法 + 路径谓词组合。
- 路由函数按顺序尝试匹配。
- 首个匹配规则的处理器处理请求。
代码或图示
router {
GET("/users", handler::list)
POST("/users", handler::create)
PUT("/users/{id}", handler::update)
DELETE("/users/{id}", handler::delete)
}
常见误区
- 多条规则路径重叠却顺序不当:靠前的宽泛规则先命中,后置规则永远不执行。
- 处理器写成返回
ResponseEntity与直接返回对象混用不一致:按框架约定统一返回类型。
追问
- 路径变量在 DSL 中怎么取?答:处理器接收请求对象,从路径变量读取;见参数提取条目。
- 能否注册通配路径?答:支持路径模式谓词,语法见 Spring 路由谓词文档。
06.8.2.2-019 如何用 path 块做路径前缀嵌套?
一句话结论
path("/api") { } 块内规则共享路径前缀,子路由拼接父子路径;嵌套用于按资源分组,避免每条规则重复写前缀。
概念解释
DSL 支持路径作用域嵌套,块路径与子规则路径拼接。分组内还可统一挂载过滤器、谓词,结构与资源目录对应。
原理流程
- 外层
path("/api")定义前缀。 - 内层规则声明相对路径。
- 最终路径为前缀拼接结果。
- 嵌套作用域内可共享谓词与过滤器。
代码或图示
router {
path("/api") {
path("/users") {
GET("", handler::list)
GET("/{id}", handler::byId)
}
}
}
常见误区
- 拼接时多写或少写斜杠导致路径不匹配:按框架路径模式规则核对。
- 内层规则期望脱离前缀独立匹配:嵌套路径都带外层前缀。
追问
- 嵌套能挂统一过滤器吗?答:可以在作用域内声明过滤器,作用于该分组规则;见过滤器条目。
- 路径变量能跨层定义吗?答:变量在最终匹配路径中提取,层级不影响变量名。
06.8.2.2-020 如何声明 accept 与 contentType 谓词?
一句话结论
DSL 用 accept(...) 匹配请求 Accept 头,contentType(...) 匹配请求 Content-Type;谓词与方法/路径组合,共同决定处理器是否命中。
概念解释
内容协商谓词按媒体类型过滤请求。同一资源路径可按 Accept 或 Content-Type 分发到不同处理器,DSL 谓词方法对应 Spring RequestPredicate。
原理流程
- 规则附加 accept/contentType 谓词。
- 请求头与谓词媒体类型比较。
- 全部谓词满足才命中处理器。
- 不匹配继续尝试下一条规则。
代码或图示
router {
GET("/users", accept(MediaType.APPLICATION_JSON), handler::list)
POST("/users", contentType(MediaType.APPLICATION_JSON), handler::create)
}
常见误区
- 谓词写错媒体类型导致 404/415:核对头值与常量。
- 多条规则只靠 contentType 区分却不排顺序:宽泛规则先匹配可能吞掉请求。
追问
- 谓词组合是 AND 吗?答:同一规则内谓词逻辑与,不同规则之间按顺序尝试;通用谓词模型见 06.2。
- 可自定义谓词吗?答:可以实现请求谓词并组合进 DSL。
06.8.2.2-021 路径变量与请求参数在 DSL 处理器中如何提取?
一句话结论
处理器接收 ServerRequest(WebFlux)或 RequestEntity/请求对象,从 pathVariable("id")、param("q") 读取变量与参数;协程处理器同样从请求对象取值。
概念解释
DSL 不像注解控制器有参数绑定注解,取值显式从请求对象访问。路径变量按名取,查询参数按名取,缺失时返回 null 或按约定处理。
原理流程
- 处理器方法接收请求对象。
pathVariable取路径段,param取查询参数。- 类型转换为业务类型。
- 取不到值走参数校验或错误响应。
代码或图示
fun byId(request: ServerRequest): ServerResponse {
val id = request.pathVariable("id").toLong()
val detail = request.param("detail").orElse(null)
return ServerResponse.ok().bodyValue(userService.get(id))
}
常见误区
- 假设路径变量一定非空:缺失/空字符串需校验后再转换。
- 把参数名写错又无编译检查:运行期才取不到值。
追问
- 请求体如何读?答:WebFlux 用
awaitBody/body,见协程桥接条目;MVC 从请求对象读体。 - 路径变量类型转换失败怎么办?答:捕获转换异常返回 400,全局异常处理器统一处理。
06.8.2.2-022 谓词如何组合与取反?
一句话结论
同一规则内多个谓词默认逻辑与;DSL 提供谓词组合能力表达 and/or,自定义谓词可与内置谓词合并;路由规则之间是顺序匹配关系,不是谓词求并。
概念解释
谓词布尔模型:单规则内 AND 组合,规则间按顺序短路匹配。复杂匹配条件拆成多条规则或组合谓词,避免在一条规则里堆过多条件。
原理流程
- 规则挂载若干谓词。
- 请求依次通过谓词检查。
- 全部满足进入处理器。
- 任一不满足尝试下一条规则。
代码或图示
router {
GET("/search", request.param("q").isPresent, handler::search)
}
常见误区
- 把规则间关系当成 OR 谓词:顺序匹配,前置宽泛规则优先命中。
- 谓词里访问请求体做匹配:体只能消费一次,谓词阶段不宜读取。
追问
- 谓词能读 Header/Cookie 吗?答:可以按请求头构造自定义谓词。
- 谓词求值有性能要求吗?答:路由匹配在请求路径上执行,谓词保持轻量,重逻辑放处理器。
06.8.2.2-023 DSL 路由中如何挂过滤器?
一句话结论
路由块内可用 filter 声明处理器前/后拦截逻辑,作用于分组或单条规则;过滤器在谓词匹配后、处理器执行前后包裹调用链。
概念解释
函数式路由过滤器对应 Web 过滤器链的局部版本,可做日志、鉴权、请求改写。嵌套作用域内的过滤器只影响该分组规则。
原理流程
- 规则命中后进入过滤器链。
- 过滤器前置逻辑执行。
- 调用处理器。
- 过滤器后置逻辑处理响应。
代码或图示
router {
path("/admin") {
filter { request, next ->
val authorized = checkAuth(request)
if (authorized) next(request) else ServerResponse.status(401).build()
}
GET("/dashboard", handler::dashboard)
}
}
常见误区
- 过滤器里读取请求体后处理器再读:体流不可重复消费,需包装缓存。
- 分组过滤器与全局过滤器职责重复:先划清全局与局部边界。
追问
- 过滤器能中断链吗?答:可以直接返回错误响应,不调用
next。 - 与 Servlet Filter / WebFlux Filter 关系?答:全局过滤器走容器过滤器链,DSL filter 是路由级包装;通用过滤器链见 06.2。
06.8.2.2-024 函数式路由如何处理错误响应?
一句话结论
处理器返回状态码 ServerResponse/ResponseEntity,异常由框架异常处理器转换;函数式端点不强制抛 MVC 风格异常,可在处理器内显式构建错误响应。
概念解释
错误处理分两层:处理器内显式返回错误状态;未捕获异常交给框架映射。函数式风格更倾向显式返回响应对象,异常处理器作为兜底。
原理流程
- 处理器执行业务逻辑。
- 可预期错误直接构建错误响应返回。
- 未捕获异常进入异常处理链。
- 映射为标准错误响应与状态码。
代码或图示
fun byId(request: ServerRequest): ServerResponse {
val user = service.find(request.pathVariable("id"))
?: return ServerResponse.notFound().build()
return ServerResponse.ok().bodyValue(user)
}
常见误区
- 处理器内吞掉异常返回模糊 500:可预期的 404/400 应显式构造。
- 依赖注解
@ExceptionHandler处理函数式端点:异常处理器仍可生效,但路由自身错误响应需自行构建。
追问
- 响应体序列化由谁完成?答:ServerResponse 经消息转换器写出,通用消息转换见 06.2。
- 协程处理器异常如何传播?答:按协程异常语义桥接到框架错误信号,见异常传播条目。
06.8.2.2-025 函数式路由与注解控制器能否混用?
一句话结论
可以共存:RouterFunction Bean 与 @Controller 映射在同一应用内分别注册,请求按各自映射规则匹配;混用需划清职责边界,避免同一路径两套处理。
概念解释
两种端点机制不互斥。注解控制器适合参数绑定与校验注解体系,函数式路由适合集中编排与协程 DSL。同一应用可按模块选择,但同一路径不应双重映射。
原理流程
- 容器同时注册控制器映射与 RouterFunction。
- 请求到达后分别进入对应映射体系。
- 命中哪套由路径与规则决定。
- 消息转换与响应写出复用同一套基础设施。
代码或图示
// 注解侧
@RestController
@RequestMapping("/legacy")
class LegacyController
// 函数式侧
@Bean
fun modernRoutes() = router { GET("/modern", modernHandler::show) }
常见误区
- 两套机制映射同一路径:匹配顺序不确定,行为难以预测。
- 混用导致团队风格割裂:应在模块层面约定主选方式。
追问
- 路由优先级谁高?答:两套映射各自按规则匹配,通用映射顺序见 06.2;重叠路径需避免。
- 混用下过滤器如何统一?答:全局过滤器作用于所有端点,路由级 filter 只影响函数式规则。
06.8.2.2-026 如何编写 coHandlerFunction 协程处理器?
一句话结论
协程处理器是 suspend (请求) -> 响应 签名函数,通过方法引用或 lambda 挂到 coRouter;内部可直接调用其他挂起函数,框架负责协程执行与响应式桥接。
概念解释
HandlerFunction 的协程版本把请求处理声明为挂起函数。处理器内组合多个远程/数据库挂起调用,无需手动管理 Mono 回调;返回值为结果对象或 Flow。
原理流程
- 定义
suspend处理器函数,接收请求。 - 解析参数,调用服务层挂起方法。
- 构造响应对象返回。
coRouter引用该函数注册路由。
代码或图示
suspend fun list(request: ServerRequest): ServerResponse {
val users = userService.findAllSuspend()
return ServerResponse.ok().bodyValue(users)
}
@Bean
fun routes() = coRouter { GET("/users", ::list) }
常见误区
- 处理器不是 suspend 却调用阻塞服务:阻塞事件循环线程,见调度条目。
- 处理器内手动
runBlocking等待协程:多余且占用线程,见 runBlocking 陷阱条目。
追问
- 处理器返回 DTO 还是响应包装?答:可直接返回对象由消息转换器序列化,或包装 ServerResponse;按项目约定统一。
- 协程处理器能访问 Reactor Context 吗?答:需经桥接元素读取,见上下文传播条目。
06.8.2.2-027 DSL 中如何构建响应实体?
一句话结论
函数式端点用 ServerResponse.ok().bodyValue(...) 等链式构建状态码与响应体;协程处理器返回构建好的响应对象,body 写入由框架消息转换器完成。
概念解释
响应构建 DSL 表达状态码、头、体与内容类型。区别于注解控制器直接返回对象,函数式端点显式构建响应包装;流式响应使用 body 写 Flux/Flow。
原理流程
- 按结果选状态码构造响应 builder。
- 设置头、内容类型。
- 写入响应体(对象、流式发布者)。
- 返回响应对象交给框架写出。
代码或图示
ServerResponse
.status(HttpStatus.CREATED)
.contentType(MediaType.APPLICATION_JSON)
.bodyValue(newUser)
常见误区
- 响应体重复消费流:体发布者只能订阅一次。
- 状态码与业务结果不匹配:可预期错误应返回对应 4xx/5xx。
追问
- 响应头怎么加?答:builder 上
header(name, value)链式调用。 - 流式响应怎么写?答:body 传入 Flux 或 Flow,见 SSE/流式条目。
06.8.2.2-028 RouterFunction Bean 如何注册到容器?
一句话结论
把 RouterFunction(或 coRouter 结果)声明为 @Bean,容器检测到函数式路由 Bean 并注册到 handler 映射;无需额外控制器扫描。
概念解释
函数式路由容器通过检测 RouterFunction 类型 Bean 接入请求映射。DSL 生成结果作为单个 Bean 返回,容器将其纳入路由映射表。
原理流程
@Bean方法返回 router DSL 结果。- 容器识别 RouterFunction 类型。
- 注册到函数式路由映射。
- 请求匹配时调用对应处理器。
代码或图示
@Bean
fun userRoutes(handler: UserHandler) = router {
GET("/users", handler::list)
}
常见误区
- DSL 结果没有返回为 Bean:只是局部变量,不进容器映射。
- 处理器组件未注册:方法引用的 Handler 需为容器 Bean 或 DSL 中构造。
追问
- 多个 RouterFunction Bean 如何排序?答:按顺序/优先级元数据参与匹配,通用规则见 06.2。
- 能按模块提供多个路由 Bean 吗?答:可以,各模块声明各自 RouterFunction Bean。
06.8.2.2-029 DSL 中如何映射静态资源?
一句话结论
静态资源通常由资源处理器映射配置处理;函数式 DSL 主要负责动态端点,静态资源服务通过资源处理器路径配置接入,不必为每个静态文件写路由规则。
概念解释
静态资源不走 HandlerFunction 业务逻辑,由资源处理器从类路径/文件系统提供。DSL 路由表关注动态 API,静态映射在 Web 资源配置中声明。
原理流程
- 配置资源处理器路径与位置。
- 请求静态路径由资源处理器匹配。
- 找到资源文件写出。
- 未命中走默认静态映射或 404。
代码或图示
// 静态资源映射在 Web 配置中;router DSL 只声明动态端点
@Configuration
open class WebConfig : WebFluxConfigurer {
override fun addResourceHandlers(registry: ResourceHandlerRegistry) {
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/")
}
}
常见误区
- 为静态目录写 GET 通配路由再读文件:重复造资源处理器能力。
- 把动态路由前缀与静态路径混淆:请求匹配串扰。
追问
- 资源缓存策略在哪配?答:资源处理器配置缓存周期与链,通用静态资源机制见 06.2。
- 函数式端点能返回文件资源吗?答:可以在处理器中返回资源体,但常规静态资源仍走资源处理器。
06.8.2.2-030 多条路由规则顺序与路径冲突如何处理?
一句话结论
RouterFunction 按声明顺序短路匹配,宽泛规则应后置;路径冲突时先核对规则顺序与谓词宽度,必要时收窄谓词或拆分路径,保证每条规则可被命中。
概念解释
规则匹配是有序列表遍历:第一个谓词全满足的规则接管请求。把 /** 或宽泛路径写在前面会吞掉后续精确规则。调试时按顺序检查谓词宽度。
原理流程
- 列出全部路由规则与谓词。
- 核对路径重叠关系。
- 精确规则前置,宽泛兜底规则后置。
- 冲突路径收窄谓词或拆分资源前缀。
代码或图示
router {
GET("/users/{id}", handler::byId) // 精确规则在前
GET("/users/**", handler::fallback) // 宽泛兜底在后
}
常见误区
- 宽泛规则声明在前:后续规则永不执行。
- 谓词条件写得相同却期望两条都能命中:只能命中先匹配的一条。
追问
- 如何查看实际匹配顺序?答:开启路由映射调试日志,列出 RouterFunction 解析后的规则顺序。
- 注解控制器与函数式规则重叠怎么办?答:避免同路径双重映射,统一归属一套机制。
06.8.2.2-031 Kotlin 协程在 WebFlux 应用中处于什么地位?
一句话结论
协程是 WebFlux 的 Kotlin 一等编程模型:suspend 处理器与 Flow 替代回调式 Mono/Flux 链路,框架通过 kotlinx-coroutines-reactor 桥接响应式类型,同时保留直接使用 Reactor 类型的能力。
概念解释
WebFlux 底层仍是 Reactor 响应式流,协程在其上提供更直接的顺序式代码风格。桥接层在 suspend 函数与 Mono/Flux 之间转换,背压与线程调度仍由响应式运行时约束。
原理流程
- WebFlux 接收请求,进入响应式处理链。
- suspend 处理器在桥接层启动协程。
- 挂起点让出线程,恢复时继续执行。
- 结果桥接为响应式序列写出。
代码或图示
@RestController
class UserController(private val service: UserService) {
@GetMapping("/{id}")
suspend fun byId(@PathVariable id: Long): User = service.findSuspend(id)
}
常见误区
- 以为用了协程就脱离响应式线程约束:阻塞调用仍会占用事件循环线程。
- 协程与 Reactor 类型随意混用无边界:桥接点应集中在 Web 层,服务层保持单一模型。
追问
- 协程模型必须配 WebFlux 吗?答:MVC 也支持 suspend 控制器,但完整流式/背压模型在 WebFlux 更自然。
- 桥接模块是哪个?答:kotlinx-coroutines-reactor,见依赖条目。
06.8.2.2-032 suspend 函数与 Mono/Flux 之间如何桥接?
一句话结论
suspend 单值用 Mono.awaitSingle()/mono { } 互转,流用 Flow 与 Flux 通过 asFlow()/asFlux() 转换;桥接在边界做一次,避免链路中反复转换。
概念解释
Reactor 类型是响应式发布者,suspend 是协程单值挂起函数。桥接扩展把发布者订阅包装为挂起等待,或把协程结果包装为发布者。反复转换增加上下文与异常处理复杂度。
原理流程
- Reactor 侧:
awaitSingle/awaitFirst挂起等待首个值。 - 协程侧:
mono { }调用 suspend 函数并包装为 Mono。 - 流:Flow 与 Flux 互相转换并传播背压。
- 异常与取消沿桥接通道传递。
代码或图示
// Reactor -> suspend
val user: User = monoUser.awaitSingle()
// suspend -> Reactor
val mono: Mono<User> = mono { service.findSuspend(id) }
// Flow <-> Flux
val flow: Flow<User> = fluxUsers.asFlow()
val flux: Flux<User> = flow.asFlux()
常见误区
- 在一段链路里多次 suspend↔Mono 转换:上下文丢失与异常包装风险升高。
- 把 Flux 当普通集合
awaitSingle:多元素流不能按单值取。
追问
- 桥接扩展来自哪个库?答:kotlinx-coroutines-reactor 提供 Mono/Flux 扩展。
- 空值如何桥接?答:Mono 空对应 suspend 返回 null,需以可空类型表达。
06.8.2.2-033 Web 服务中 runBlocking 有什么陷阱?
一句话结论
runBlocking 在协程外阻塞当前线程等待内部协程完成;Web 处理器里使用它会占用事件循环或工作线程,抵消响应式/协程的非阻塞收益,还可能造成线程池耗尽。
概念解释
runBlocking 是桥接同步世界的入口,应只出现在 main、测试或必须同步返回的边界。请求处理线程本身已被框架调度,内部再 runBlocking 等于把异步流程拉回阻塞等待。
原理流程
- 请求线程进入处理器。
runBlocking阻塞该线程直到内部协程结束。- 期间线程不能处理其他请求。
- 高并发下线程被占满,吞吐下降。
代码或图示
// 错误:在 suspend 控制器里再 runBlocking
@GetMapping("/bad")
fun bad(): User = runBlocking { service.findSuspend(id) }
// 正确:控制器直接 suspend
@GetMapping("/good")
suspend fun good(): User = service.findSuspend(id)
常见误区
- 以为 runBlocking 只是「起个协程」:它语义是阻塞等待,不是异步派发。
- 在工具类里默认 runBlocking 暴露同步 API:把阻塞语义扩散到 Web 链路。
追问
- 哪里允许 runBlocking?答:应用 main 入口、测试、与同步库对接的隔离边界;测试用
runTest替代。 - 遗留阻塞服务被协程调用怎么办?答:用
withContext(Dispatchers.IO)包裹阻塞调用,见调度条目。
06.8.2.2-034 suspend 控制器运行在什么调度上下文?
一句话结论
suspend 控制器由框架在响应式调度上桥接执行,默认延续所在请求调度;阻塞式工作应显式切到 Dispatchers.IO,CPU 密集用 Dispatchers.Default,不要假设固定线程。
概念解释
协程不绑定固定线程,挂起后可在任意调度器恢复。WebFlux 请求初始运行在事件循环桥接上下文,重活切到 IO 调度器;线程名在挂起前后可能变化,不能依赖 ThreadLocal 固定。
原理流程
- 请求到达,框架创建协程上下文。
- suspend 处理器在该上下文执行。
- 阻塞调用经
withContext切到指定调度器。 - 恢复后回到调用点上下文继续。
代码或图示
suspend fun report(id: Long): Report = withContext(Dispatchers.IO) {
blockingJdbcQuery(id)
}
常见误区
- 假设处理器全程在同一线程:协程恢复可换线程,ThreadLocal 不可靠。
- 不切调度器直接在事件循环跑阻塞 IO:阻塞事件循环,整体吞吐受损。
追问
- 如何查看协程运行线程?答:日志打印
Thread.currentThread().name,注意挂起前后可能不同。 - 调度器线程池大小在哪配?答:对应 Dispatcher 的池配置,IO 与 Default 池参数见协程文档。
06.8.2.2-035 Dispatchers.IO、Default、Main 如何选择?
一句话结论
阻塞 IO 用 Dispatchers.IO,CPU 密集计算用 Dispatchers.Default,UI 主线程用 Main(服务端一般不用);服务端 Web 代码主要在前两者之间选择,按操作类型切调度器。
概念解释
调度器决定协程在哪个线程池运行。IO 池面向阻塞等待,Default 池面向并发计算。错配会导致池利用率失衡:阻塞任务占 Default 会饿死计算,计算任务占 IO 浪费线程。
原理流程
- 判断任务是等待 IO 还是消耗 CPU。
- IO:
withContext(Dispatchers.IO)包裹阻塞调用。 - 计算:
withContext(Dispatchers.Default)。 - 子协程继承父上下文,除非显式切换。
代码或图示
suspend fun loadAndAggregate(id: Long): Summary {
val rows = withContext(Dispatchers.IO) { blockingSelect(id) }
return withContext(Dispatchers.Default) { rows.aggregate() }
}
常见误区
- 所有协程都跑在默认调度器:阻塞 IO 与计算互相干扰。
- 服务端引用
Dispatchers.Main:Main 绑定 UI 线程,服务端环境无该调度器。
追问
- IO 调度器共享多少线程?答:上限与队列策略见 kotlinx-coroutines 文档,版本相关(待确认)。
- 自定义线程池能作为调度器吗?答:可通过
asCoroutineDispatcher()包装执行器。
06.8.2.2-036 协程上下文切换为什么会导致 ThreadLocal 丢失?
一句话结论
ThreadLocal 绑定线程,协程挂起后恢复可能换到另一个线程,原线程上的 ThreadLocal 值不会自动跟随;协程上下文是 CoroutineContext,与线程局部存储是两套机制,跨线程恢复时 ThreadLocal 读不到原值。
概念解释
响应式与协程都允许任务在事件循环与工作线程间迁移。请求级上下文(用户身份、traceId)若存在 ThreadLocal,换线程后丢失。需要随协程传播的上下文应放进 CoroutineContext 元素或响应式 Context。
原理流程
- 请求入口线程把上下文写入 ThreadLocal。
- 协程挂起(等待远程调用/DB)。
- 恢复时调度到其他线程。
- 新线程 ThreadLocal 为空,读到 null。
代码或图示
// 风险:ThreadLocal 在跨线程恢复后丢失
val tl = ThreadLocal<String>()
suspend fun process() {
tl.set("user-1")
delay(10) // 挂起后可能换线程
println(tl.get()) // 新线程上为 null
}
常见误区
- 以为协程与线程一一对应:挂起恢复可换线程,ThreadLocal 不保证跟随。
- 在响应式链路依赖 ThreadLocal 存请求状态:换线程即丢。
追问
- 日志 MDC 怎么避免丢失?答:用上下文传播方案把 MDC 值挂到协程/响应式上下文,见 MDC 条目。
- 如何在新线程恢复时复制 ThreadLocal?答:需要自定义上下文元素或线程工厂复制机制,不能依赖默认行为。
06.8.2.2-037 协程链路中 MDC 日志上下文如何传播?
一句话结论
MDC 基于 ThreadLocal,协程换线程后默认丢失;需把 traceId/用户标识作为 CoroutineContext 元素携带,或用桥接库在调度恢复时回填 MDC,保证跨线程日志带同一上下文。
概念解释
链路追踪与请求标识需要贯穿异步链路。协程方案自定义上下文元素保存 MDC map,在协程恢复调度时把元素值写回当前线程 MDC,结束时清理;响应式方案则从 Reactor Context 读取并回填。
原理流程
- 入口把 traceId 写入协程上下文元素。
- 协程执行前后在调度点同步 MDC。
- 跨线程恢复时从上下文元素恢复 MDC。
- 协程结束清理线程 MDC,避免线程复用串号。
代码或图示
// 思路:上下文元素携带 MDC 快照,调度恢复时回填(具体桥接实现以所用追踪库为准,待确认)
class MdcContext(val map: Map<String, String>) : AbstractCoroutineContextElement(MdcContext)
常见误区
- 只在入口线程设置 MDC 就期望全链路日志带值:跨线程后读不到。
- 协程结束不清理 MDC:线程被复用后上一请求的标识串到下一请求。
追问
- Spring 响应式日志如何传递 traceId?答:通过响应式 Context 与日志桥接,通用可观测性见 08 分册。
- 调试时如何确认 MDC 丢失?答:打印日志线程名与 MDC 值,对比挂起前后线程变化。
06.8.2.2-038 不依赖 ThreadLocal 如何携带请求级上下文?
一句话结论
实现 AbstractCoroutineContextElement 把上下文数据挂到 CoroutineContext,随协程父子关系传播;元素在协程构建时传入,恢复时从当前上下文读取,不依赖线程局部存储。
概念解释
CoroutineContext 是协程自身的上下文集合,父子协程继承元素。自定义元素实现上下文键,把请求标识、租户ID等放进去,链路任意挂起点都能读取。
原理流程
- 定义上下文元素与对应 Key。
- 入口启动协程时传入元素。
- 子协程继承上下文,元素可达。
- 处理逻辑从
coroutineContext读取元素值。
代码或图示
class TenantContext(val tenantId: String) :
AbstractCoroutineContextElement(TenantContext) {
companion object Key : CoroutineContext.Key<TenantContext>
}
suspend fun currentTenant(): String? =
coroutineContext[TenantContext]?.tenantId
常见误区
- 把可变对象放进上下文元素又在多协程共享修改:元素应不可变,更新通过新元素替换。
- 子协程用独立作用域启动却不传上下文:元素不自动跨作用域传播。
追问
- 与 Reactor Context 如何对应?答:协程元素与 Reactor Context 桥接时互相映射,见下一条。
- 上下文元素能携带数据库连接吗?答:连接资源通常由事务/连接池管理,上下文只携带标识而非资源句柄。
06.8.2.2-039 Reactor Context 与协程上下文如何互相映射?
一句话结论
响应式链路上 Reactor Context 随发布者传播,协程桥接层把 Context 条目映射到 CoroutineContext;读取时从桥接元素取,反向写入需经桥接通道,不能直接把 ThreadLocal 搬过去。
概念解释
Reactor Context 是订阅级上下文,与订阅者绑定;CoroutineContext 是协程级上下文。桥接扩展在两者之间传递键值对,入口把请求上下文放入 Reactor Context,协程侧通过对应元素读取。
原理流程
- 响应式链上游写入 Context 条目。
- 桥接层启动协程时映射到协程上下文元素。
- suspend 处理器读取元素值。
- 反向新增上下文需走响应式上下文写入口。
代码或图示
// Reactor 侧写入上下文(示意):deferContextual { ctx -> ... }
// 协程侧经桥接扩展读取;具体键名与 API 以 reactor-kotlin 桥接文档为准(待确认)
常见误区
- 以为 Reactor Context 像 ThreadLocal 全局可读:它只随订阅链路向下游传播。
- 在协程里直接改 Reactor Context:Context 不可变,需在响应式上游重新写入。
追问
- 上下文条目何时建立?答:订阅时由链路上游的上下文写操作填充。
- 桥接失败会怎样?答:协程侧读不到条目得到 null,需在入口校验必备上下文。
06.8.2.2-040 awaitBody / awaitBodyOrNull 如何提取请求体?
一句话结论
协程处理器用 awaitBody<T>() 挂起读取并反序列化请求体,awaitBodyOrNull() 允许空体;它们是 WebFlux 请求体的协程扩展,替代手动订阅 Reactor 请求体。
概念解释
请求体是异步流,协程扩展把等待体完成包装为挂起调用。类型参数指定反序列化目标,消息转换器完成 JSON→对象;空体场景用 OrNull 变体避免抛空体异常。
原理流程
- 处理器调用
awaitBody挂起等待体接收完成。 - 消息转换器反序列化为目标类型。
- 得到对象继续业务处理。
- 空体用 OrNull 返回 null,自行判空。
代码或图示
suspend fun create(request: ServerRequest): ServerResponse {
val body = request.awaitBody<CreateUserRequest>()
val saved = service.create(body)
return ServerResponse.ok().bodyValue(saved)
}
常见误区
- 先读一次体再 awaitBody:请求体流只能消费一次,重复读取失败。
- 非空场景用 OrNull 却不判空:下游 NPE。
追问
- 体大小限制在哪配?答:WebFlux 请求体大小限制与消息转换器配置,通用 Web 配置见 06.2。
- 反序列化失败异常映射到什么状态?答:4xx 请求错误,由异常处理器转换。
06.8.2.2-041 Reactor 到 suspend 的常用桥接 API 有哪些?
一句话结论
单值用 awaitSingle/awaitFirst/awaitSingleOrNull,序列用 asFlow(),挂起函数包回 Mono 用 mono { }/flux { };选择 API 时明确发布者是单值还是流。
概念解释
桥接扩展按发布者形态分组:单值等待首个/唯一值,空值用 OrNull 变体;多元素流转 Flow;协程结果包装回响应式发布者。API 选错会在元素数量假设上出错。
原理流程
- 判断 Reactor 类型:Mono 单值或 Flux 多元素。
- 单值调用 await 系列挂起取结果。
- 多元素
asFlow转协程流处理。 - 出口按需包装回 Mono/Flux。
代码或图示
val maybe: User? = monoUser.awaitSingleOrNull()
val all: Flow<Item> = fluxItems.asFlow()
val back: Mono<User> = mono { service.findSuspend(id) }
常见误区
- Flux 调用
awaitSingle:假设只有一个元素,多余元素触发异常。 - 对空 Mono 用非空 await:拿到空值抛异常,应用 OrNull 变体。
追问
- 这些扩展来自哪个模块?答:kotlinx-coroutines-reactor。
- 桥接时异常如何传递?答:发布者错误作为协程异常抛出,取消信号对应协程取消。
06.8.2.2-042 协程异常如何在 Web 链路中传播与处理?
一句话结论
协程异常沿父协程传播,未捕获异常经桥接层转为响应式错误信号;可在处理器/服务层用 try/catch 处理,或注册 CoroutineExceptionHandler 兜底,但 Web 层最终仍由框架异常处理器映射状态码。
概念解释
协程异常语义:子协程失败向上取消父作用域,异常传播到根。Web 入口根协程的未处理错误被桥接给 Reactor 错误信号,再进入框架异常处理链。业务可预期错误应在局部捕获转换。
原理流程
- 协程内抛异常。
- 沿作用域层级向上传播,相关子协程被取消。
- 桥接层把异常转为错误信号。
- 框架异常处理器映射为错误响应。
代码或图示
suspend fun handle(request: ServerRequest): ServerResponse = try {
ServerResponse.ok().bodyValue(service.find(id))
} catch (ex: NotFoundException) {
ServerResponse.notFound().build()
}
常见误区
- 依赖
CoroutineExceptionHandler在服务层吞异常:未处理异常仍会取消作用域,局部 try/catch 更可控。 - 捕获后不返回响应也不重抛:处理器挂起无输出,请求挂起直至超时。
追问
- 子协程异常会取消兄弟协程吗?答:默认结构化并发下失败向上传播并取消作用域内其他子协程。
- 异常处理器能拿到协程上下文吗?答:可通过桥接与上下文元素补充日志信息。
06.8.2.2-043 请求取消与协程取消语义如何对应?
一句话结论
客户端断开/请求超时会取消 Web 处理链,协程收到取消信号,挂起点抛 CancellationException;协作式取消要求在长任务中定期检查状态,资源清理放在 finally。
概念解释
协程取消是协作式的:信号到达后,挂起点响应取消;不挂起的紧密循环不会自动停止。请求取消后应释放外部资源(连接、临时文件、下游调用),避免泄漏。
原理流程
- 客户端断开或框架超时。
- 处理链向下传播取消信号。
- 协程在挂起点抛 CancellationException。
finally块清理资源,无需向客户端写响应。
代码或图示
suspend fun stream(): Flow<Item> = flow {
val resource = acquire()
try {
resource.readItems().collect { emit(it) }
} finally {
resource.close() // 取消时仍执行清理
}
}
常见误区
- 取消后继续执行阻塞重任务:不检查取消状态,占用资源。
- 在
finally里再做挂起调用未处理取消:清理逻辑也可能被取消中断。
追问
CancellationException要重新抛吗?答:应保留并向上传播,不要当成普通业务异常吞掉。- 如何检查协程是否取消?答:
ensureActive()或isActive,在循环中定期调用。
06.8.2.2-044 服务层如何用 withTimeout 控制协程执行时限?
一句话结论
withTimeout(ms) { } 在超时后取消作用域并抛 TimeoutCancellationException,用于限制单个下游调用或聚合流程;超时预算应按整体请求时限拆分,避免子任务超时吃掉全部预算。
概念解释
协程超时是结构化取消:到期取消内部协程并清理。可预期超时在局部捕获转换为降级响应;超时异常属于取消类异常,不要与普通业务异常混淆处理。
原理流程
- 进入
withTimeout块启动限时协程。 - 业务挂起调用在预算内完成则返回结果。
- 到期未完成,取消内部协程并抛超时异常。
- 局部捕获后走降级或错误响应。
代码或图示
suspend fun profile(id: Long): Profile = try {
withTimeout(500) { service.loadProfile(id) }
} catch (ex: TimeoutCancellationException) {
Profile.anonymous(id)
}
常见误区
- 不区分超时取消与请求取消:都属取消异常,清理逻辑一致但业务映射不同。
- 每个嵌套调用都设超时且总和大于请求预算:整体仍可能超时。
追问
withTimeoutOrNull区别?答:超时返回 null 而不抛异常,适合可选降级分支。- 超时后下游调用还在跑吗?答:取消信号传播到支持取消的挂起点,不协作的阻塞任务需单独隔离。
06.8.2.2-045 如何用 async/awaitAll 并发编排多个下游调用?
一句话结论
同一作用域内 async { } 启动并发子协程,awaitAll 等待全部结果;适合并行聚合多个独立下游,比顺序挂起缩短总耗时,子任务异常会取消整个作用域。
概念解释
结构化并发:父作用域内启动的 async 任务受父协程管理。任务间无依赖才并行;任一失败默认取消其余任务并向上传播异常。需要容错的任务单独捕获或降级。
原理流程
- 创建子任务 Deferred 列表,各自 async 调用下游。
- 子协程并发执行。
awaitAll收集全部结果。- 异常按结构化取消规则处理。
代码或图示
suspend fun dashboard(id: Long): Dashboard = coroutineScope {
val profile = async { userService.profile(id) }
val orders = async { orderService.orders(id) }
val stats = async { statsService.summary(id) }
Dashboard(profile.await(), orders.await(), stats.await())
}
常见误区
- 有依赖关系的任务也并行启动:第二个任务需要第一个结果,不能放入同一批 async。
- 单个下游失败拖垮整个聚合:需要逐项容错时在 async 内部捕获返回降级值。
追问
- 并发度如何限制?答:用信号量或有限调度器限制同时在跑的任务数,见并发上限条目。
- async 启动后不 await 会怎样?答:父作用域等待子协程完成,未 await 的 Deferred 仍受结构化管理。
06.8.2.2-046 协程服务方法与 Spring 事务边界如何划分?
一句话结论
声明式事务由代理在方法边界开启/提交事务;suspend 方法被代理增强时,事务边界仍是方法调用前后,内部挂起期间持有事务连接,跨挂起不要让事务边界扩散到长流程。
概念解释
事务绑定连接与线程/上下文。协程挂起期间连接需保持可用,事务方法内不应做长等待或跨协程并发远程调用。通用事务传播与隔离原理见 06.2,这里只关注协程下的边界风险。
原理流程
- 进入事务增强的 suspend 方法,开启事务获取连接。
- 方法内挂起调用期间事务上下文保持。
- 方法正常返回提交,异常回滚。
- 挂起切换线程时事务资源需能跟随上下文。
代码或图示
@Transactional
suspend fun placeOrder(command: CreateOrder): Order {
val order = orderRepository.save(command)
paymentClient.charge(order) // 事务内远程调用需谨慎
return order
}
常见误区
- 事务方法内并发 async 多个任务共享同一事务:连接与事务上下文并非天然跨子协程共享,行为需以实现验证(待确认)。
- 事务边界包住远程调用/消息发送:长事务占连接,失败回滚成本高。
追问
- suspend 事务方法在 WebFlux 下如何工作?答:响应式事务管理器与协程桥接的配合需核对 Spring 版本支持(待确认);阻塞 JDBC 不应直接进入响应式链路。
- 事务上下文跨线程如何传递?答:由事务管理器与上下文机制保证,不要手动把连接放进 ThreadLocal。
06.8.2.2-047 标注 @Transactional 的 suspend 方法行为有何注意点?
一句话结论
注解能否生效取决于代理是否覆盖 suspend 方法;Kotlin 方法需可被代理开放,且事务管理器支持对应运行时;阻塞 JPA 事务与协程/响应式链路不要混在同一方法内。
概念解释
声明式事务走 AOP 代理,suspend 方法仍是容器 Bean 方法。代理生成条件与普通服务一致:类/方法可开放;但事务资源在协程挂起期间的持有方式,依赖响应式/阻塞事务实现,版本支持需核对。
原理流程
- 容器为服务生成事务代理。
- 外部调用经过代理进入事务方法。
- 事务管理器开启事务,执行 suspend 方法。
- 返回提交或异常回滚。
代码或图示
@Service
open class OrderService {
@Transactional
open suspend fun confirm(id: Long) { /* 库操作 */ }
}
常见误区
- 同类自调用事务方法:绕过代理,事务不生效(通用自调用问题见 06.2)。
- 在响应式服务里直接用阻塞 JDBC 仓库加事务:阻塞事件循环且事务模型不匹配。
追问
- 如何验证事务生效?答:查看事务日志/连接持有时间,单测验证回滚行为;通用事务验证见 06.2。
- 响应式事务用什么实现?答:响应式数据访问与事务管理器,具体支持矩阵以 Spring 文档为准(待确认)。
06.8.2.2-048 容器 Bean 如何持有生命周期受控的 CoroutineScope?
一句话结论
长生命周期组件(后台任务、推送)应持有与 Bean 生命周期绑定的 CoroutineScope,在销毁回调中取消;不要使用全局 GlobalScope,避免 Bean 销毁后协程泄漏。
概念解释
组件内启动的后台协程需要作用域归属。自定义作用域绑定 SupervisorJob + 调度器,Bean 销毁时 cancel() 取消全部子协程。GlobalScope 生命周期独立于容器,无法随 Bean 关闭。
原理流程
- Bean 构造时创建
CoroutineScope(SupervisorJob() + dispatcher)。 - 后台任务在该作用域内 launch。
- 任务异常被 SupervisorJob 隔离,不连带取消其他任务。
@PreDestroy取消作用域,终止子协程。
代码或图示
@Service
class FeedProducer {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
fun start() = scope.launch { /* 后台推送 */ }
@PreDestroy
fun shutdown() = scope.cancel()
}
常见误区
- 直接
GlobalScope.launch:Bean 销毁后协程继续运行,引用泄漏。 - 作用域用普通 Job:一个子任务失败取消全部后台任务,按需选 SupervisorJob。
追问
- 作用域调度器选哪个?答:后台计算用 Default,异步 IO 用 IO;不要用 Main。
- 取消后正在执行的任务如何收尾?答:在
finally释放资源,协程响应取消信号后退出。
06.8.2.2-049 suspend 函数中如何安全包裹阻塞调用?
一句话结论
用 withContext(Dispatchers.IO) { blockingCall() } 把阻塞调用切到 IO 调度器执行,避免占用当前事件循环/默认线程;阻塞库封装在边界,服务层其余代码保持挂起风格。
概念解释
suspend 函数内部不应直接跑阻塞 IO。withContext 切换调度器在独立线程执行阻塞块,返回时切回原上下文。把阻塞依赖集中封装,调用方只看到 suspend 接口。
原理流程
- 识别调用是阻塞 JDBC/同步 HTTP/文件 IO。
withContext(IO)包裹该调用。- 阻塞在线程池执行,等待期间不占用原线程。
- 结果返回原协程上下文。
代码或图示
suspend fun findUser(id: Long): User? = withContext(Dispatchers.IO) {
blockingJdbcTemplate.queryForObject(id)
}
常见误区
- 阻塞调用不切调度器直接写在 suspend 函数里:事件循环被阻塞。
- 包裹粒度过大:把整个业务流程切到 IO,损失调度合理性。
追问
- 阻塞 HTTP 客户端能这样包吗?答:可以,但更推荐换响应式/协程客户端,减少线程等待。
- withContext 会创建新协程吗?答:切换的是上下文,协程父子关系保持不变。
06.8.2.2-050 Tomcat 阻塞线程模型与 Netty 事件循环模型有何区别?
一句话结论
MVC(Tomcat)每请求占用一个阻塞线程,线程在等待 IO 期间挂起在容器侧;WebFlux(Netty)少量事件循环线程非阻塞调度,IO 等待不占线程,协程在其上以非阻塞方式编排。
概念解释
阻塞模型线程数承接并发数,线程等待 DB/远程时空闲占用;响应式模型事件循环回调驱动,等待期间线程可处理其他请求。通用线程模型原理见 06.2,这里只对照协程适配。
原理流程
- MVC:请求分配线程 → 阻塞等待 → 线程释放回池。
- WebFlux:请求注册回调 → 事件循环处理就绪事件。
- 协程挂起对应非阻塞等待,恢复时回调调度。
- 阻塞代码进 WebFlux 会卡住事件循环。
代码或图示
MVC:线程池 ≈ 并发请求数;IO 等待期间线程被占用
WebFlux:事件循环少量线程;等待回调,阻塞调用必须隔离
常见误区
- 把 MVC 的线程池思维搬到 WebFlux:加大事件循环线程数解决不了阻塞调用问题。
- 在 WebFlux 里混用阻塞 JDBC:事件循环被阻塞,吞吐崩塌。
追问
- 协程在两种模型上都跑吗?答:MVC 支持 suspend 控制器但底层仍是 Servlet 线程;WebFlux 才是完整非阻塞链路。
- 如何判断当前是否阻塞线程?答:看线程名与阻塞栈,事件循环线程名通常含
reactor-http。
06.8.2.2-051 WebFlux 链路中调用阻塞 JDBC 有什么风险?
一句话结论
阻塞 JDBC 调用会让当前事件循环线程卡在等待数据库响应,期间无法处理其他请求;高并发下事件循环线程被占满,整体响应式链路退化甚至雪崩,必须隔离到阻塞线程池或换响应式驱动。
概念解释
WebFlux 事件循环线程数量少,职责是调度非阻塞事件。阻塞 DB 调用不释放线程,等待期间事件循环空置。隔离方案:阻塞仓库放独立线程池包装,或使用响应式关系驱动与响应式事务。
原理流程
- 事件循环线程执行到阻塞 JDBC。
- 线程阻塞等待数据库返回。
- 期间不能调度其他就绪请求。
- 并发升高后事件循环耗尽,延迟与错误上升。
代码或图示
// 不推荐:WebFlux 处理器直接阻塞
@GetMapping("/users/{id}")
fun bad(@PathVariable id: Long) = jdbcTemplate.queryForObject(...)
// 隔离思路:阻塞访问放入独立调度边界(是否符合项目架构需评审)
suspend fun good(id: Long) = withContext(boundedBlockingPool) { jdbcTemplate.query(id) }
常见误区
- 以为加
@Async就能进 WebFlux:异步线程与响应式链路上下文不天然打通。 - 用连接池大小掩盖事件循环阻塞:事件循环耗尽先于连接池问题暴露。
追问
- 响应式关系驱动有哪些?答:R2DBC 体系;通用数据访问选型见 05 分册。
- 遗留阻塞系统如何接入响应式模块?答:独立边界隔离调用并限制并发,见遗留接入场景条目。
06.8.2.2-052 协程代码调试与堆栈有什么特点?
一句话结论
协程挂起切换线程后异常堆栈可能不完整,开启协程调试模式(含调试 agent/堆栈恢复)可保留父子协程链;生产环境堆栈按异常传播链排查,配合日志上下文标识定位请求。
概念解释
默认模式下协程状态机优化会裁剪堆栈,跨线程异常只显示当前栈段。调试模式在 JVM agent 支持下保留协程创建与挂起链,便于开发定位;生产依赖日志 traceId 串联。
原理流程
- 开发环境开启协程调试代理/模式。
- 异常发生时保留协程链堆栈。
- 生产环境通过请求上下文标识关联日志。
- 按挂起点与下游调用逐层定位。
代码或图示
// 调试入口:JVM 启动参数附加 kotlinx-coroutines 调试 agent(具体参数以库文档为准,待确认)
// 排查:traceId -> 入口协程 -> 挂起点 -> 下游错误栈段
常见误区
- 生产开启完整调试模式:有性能开销,按环境选择。
- 堆栈缺帧就判断代码未执行:可能是状态机裁剪,结合日志确认。
追问
- 协程名如何设置便于日志识别?答:
CoroutineName元素加入上下文,日志打印名称与线程。 - 异常链在哪查看?答:协程异常保留根因,桥接为响应式错误信号后由框架记录。
06.8.2.2-053 StateFlow/Flow 与响应式返回类型如何选择?
一句话结论
Flow 是协程冷流,适合在 WebFlux 出口表示流式结果;StateFlow 是持当前值的热状态流,适合组件内状态订阅,不直接作为单次 HTTP 响应模型。按数据流是单次结果、冷流还是状态订阅选型。
概念解释
Flow 与 Reactor Flux 概念对应:冷流每次订阅执行发射;StateFlow 持有最新状态,多订阅者共享当前值。HTTP 请求/响应是订阅驱动的冷流场景,组件内状态同步才用 StateFlow。
原理流程
- 单次值:suspend 返回对象或 Mono。
- 流式序列:Flow/Flux 随订阅发射元素。
- 组件内可变状态:StateFlow 维护当前值并广播更新。
- 出口按协议映射为响应式流。
代码或图示
// 流式出口
fun events(): Flow<Event> = eventSource.subscribeAsFlow()
// 组件内状态
val status: StateFlow<UiState> = MutableStateFlow(UiState.Idle)
常见误区
- 把 StateFlow 当普通集合一次性读取:它是热状态订阅模型。
- 在请求出口暴露组件内部 StateFlow:生命周期与请求订阅不匹配。
追问
- Flow 与 Flux 互转 API?答:
asFlow()/asFlux(),见桥接条目。 - 冷流取消如何传播?答:订阅取消时 Flow 协程被取消,清理在
finally。
06.8.2.2-054 控制器返回 Flow 在 WebFlux 下如何写出流式响应?
一句话结论
返回 Flow<T> 由桥接适配为响应式序列,元素逐个序列化写出;适合 SSE/分块流式场景,背压从订阅端沿 Flow 传播,取消时 Flow 协程终止。
概念解释
Flow 出口被消息转换器/响应式适配器接收,订阅后逐个元素发射。媒体类型决定是 JSON 数组、分块还是 SSE;Flow 的挂起发射点配合背压,下游慢时暂停生产。
原理流程
- 控制器返回 Flow。
- 桥接层订阅 Flow。
- 元素到达即序列化写入响应。
- 取消/完成时终止 Flow 并清理资源。
代码或图示
@GetMapping(path = ["/events"], produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
fun events(): Flow<ServerEvent> = eventStream.subscribeAsFlow()
常见误区
- Flow 内一次性攒全量再发射:失去流式意义。
- 流不响应取消:订阅结束后继续生产元素。
追问
- Flow 背压如何体现?答:协程挂起在发射点,下游慢时
emit暂停,与响应式背压桥接。 - 错误元素如何中断流?答:Flow 抛异常转为错误信号,连接按异常处理关闭。
06.8.2.2-055 Reactor 类型的 Kotlin 互操作扩展包含哪些?
一句话结论
kotlinx-coroutines-reactor 提供 Mono/Flux 的挂起等待、Flow 互转、上下文桥接扩展;Spring WebFlux 对 Kotlin 控制器提供 suspend/Flow 返回支持,扩展集中在边界层使用。
概念解释
互操作扩展把 Java/Reactor API 包装为协程友好调用:await 系列取单值、asFlow 转流、包装协程结果回发布者。业务代码优先用协程模型,扩展只在与 Reactor 类型对接的边界出现。
原理流程
- 引入 coroutines-reactor 依赖。
- 边界接收 Mono/Flux 时用扩展挂起转换。
- 出口需要发布者时用包装扩展。
- 内部服务层保持 suspend/Flow 签名。
代码或图示
val publisher: Flux<Item> = sourceFlux
val flow: Flow<Item> = publisher.asFlow()
常见误区
- 服务层签名到处是 Mono/Flux 又到处转 Flow:模型割裂,上下文与异常处理复杂。
- 遗漏依赖导致扩展方法不可用:编译期报 unresolved 扩展。
追问
- 扩展随哪个依赖引入?答:kotlinx-coroutines-reactor,与 Spring WebFlux starter 配合。
- 版本对齐要求?答:协程库、Reactor、Spring 版本兼容矩阵需核对(待确认)。
06.8.2.2-056 WebFlux 背压与协程是什么关系?
一句话结论
背压由响应式订阅链路在订阅端声明需求并向上游传播;协程 Flow 通过挂起发射点适配背压,下游慢时生产协程在 emit 挂起等待,而不是无限缓冲。
概念解释
响应式流协议定义下游请求需求与上游发射节奏。Flow 的挂起发射天然适配:emit 在下游未取走元素时挂起,背压信号映射到挂起/恢复。桥接层保证两端节奏一致。
原理流程
- 下游订阅并请求一定数量元素。
- 上游按需求生产,Flow emit 受背压约束。
- 下游处理慢,emit 挂起暂停生产。
- 需求恢复后继续发射。
代码或图示
fun feed(): Flow<Row> = flow {
rows.forEach { emit(it) } // 背压时 emit 挂起
}
常见误区
- 以为协程模型不需要背压:Flow 仍需配合下游速率,缓冲策略选择不当会堆积内存。
- 用无限缓冲强行跟上快速上游:内存上涨风险。
追问
- 背压溢出错策略有哪些?答:缓冲、最新值替换、丢弃,见溢出策略条目。
- 阻塞迭代的源如何接入 Flow?答:用
flow { }包装并注意取消与调度。
06.8.2.2-057 响应式链路中调度器选择如何避免阻塞?
一句话结论
事件循环线程只做非阻塞调度,阻塞操作必须切到隔离调度器/线程池;CPU 密集计算避免长时间占用事件循环,按操作类型分配 Default/IO 池,保持事件循环快速回调。
概念解释
调度器错配是响应式服务主要性能事故来源。事件循环被阻塞后所有请求排队;隔离调度池承载阻塞与重计算,事件循环只编排回调。协程 withContext 是切池的显式手段。
原理流程
- 事件循环接收请求并编排非阻塞链。
- 阻塞/重计算段切到独立池执行。
- 完成回调恢复事件循环继续。
- 监控事件循环阻塞时长与池队列。
代码或图示
suspend fun enriched(id: Long): Enriched = withContext(Dispatchers.IO) {
val base = blockingLoad(id)
withContext(Dispatchers.Default) { base.enrich() }
}
常见误区
- 在事件循环上做加解密、序列化重计算:长任务占住循环。
- 所有阻塞调用共用无界池:池失控后内存与线程数上涨。
追问
- 如何监控事件循环阻塞?答:响应式指标与线程阻塞告警,通用可观测性见 08 分册。
- 自定义池如何限定并发?答:有界线程池 + 队列策略,包装为调度器。
06.8.2.2-058 为什么不能占用 Netty 事件循环线程做阻塞操作?
一句话结论
事件循环线程数量少且承担大量连接的事件调度,一次阻塞等待会让该循环上所有其他连接排队;阻塞调用应移出循环,这是 WebFlux 非阻塞模型的硬约束。
概念解释
Netty 事件循环以少量线程轮询多路连接。线程被阻塞 IO 占用期间,就绪事件无法被处理,连接延迟堆积。协程挂起是非阻塞等待,与阻塞线程等待性质完全不同。
原理流程
- 事件循环线程处理某请求。
- 线程同步阻塞等待 DB/HTTP 响应。
- 同循环其他连接事件无法调度。
- 并发上升导致延迟放大。
代码或图示
// 禁止:事件循环线程内
blockingJdbc.query(...)
Thread.sleep(...)
synchronized (lock) { blockingWork() }
常见误区
- 把「协程挂起」当成「阻塞线程」:挂起释放线程,阻塞不释放。
- 用同步客户端库嵌在响应式链中:隐式阻塞事件循环。
追问
- 怎么识别事件循环线程?答:线程名含 reactor-http-nio,栈上出现阻塞调用即可定位。
- 必须用同步库时怎么办?答:隔离到独立线程池并限制并发,避免回占事件循环。
06.8.2.2-059 响应式链路中 ThreadLocal 不可靠的根因是什么?
一句话结论
响应式链路上同一请求的不同片段可能在不同线程执行,ThreadLocal 绑定线程而不绑定请求,跨线程片段读不到入口线程设置的值;请求上下文必须走 Reactor Context 或协程上下文传播。
概念解释
响应式调度把回调提交到不同线程,线程池复用也让 ThreadLocal 残留风险更高。请求级数据(用户、租户、traceId)属于订阅上下文,不是线程局部变量。
原理流程
- 入口线程设置 ThreadLocal。
- 某操作回调切换到池线程。
- 新线程 ThreadLocal 为空。
- 读不到入口数据,应改用响应式/协程上下文。
代码或图示
// 不可靠:依赖 ThreadLocal 传用户
val currentUser = ThreadLocal<User>()
// 可靠:上下文随订阅/协程传播
常见误区
- 框架文档里的安全上下文在响应式下也用 ThreadLocal 取:响应式安全上下文有专门读取方式,见 Security 条目。
- 线程池提交任务时复制 ThreadLocal:需显式传递,默认不复制。
追问
- 哪些框架已经提供响应式上下文传播?答:安全上下文、链路追踪有适配桥接,通用机制见 06.2/08 分册。
- 自定义请求数据放哪里?答:Reactor Context 或 CoroutineContext 元素。
06.8.2.2-060 协程处理器中如何获取当前请求交换对象?
一句话结论
函数式处理器从方法参数接收 ServerRequest;注解式 suspend 控制器按需注入 ServerWebExchange 或从上下文取请求信息,避免在服务层静态全局获取请求对象。
概念解释
请求对象绑定在当前交换上下文,协程跨线程后不能靠 ThreadLocal 取。显式参数传递最直接;服务层需要的请求信息应提取为参数值传入,而让服务层不依赖 Web 对象。
原理流程
- 入口处理器/控制器拿到请求对象。
- 提取路径、头、体等所需信息。
- 以普通参数传入服务层。
- 服务层不持有 Web 交换引用。
代码或图示
@GetMapping("/{id}")
suspend fun detail(@PathVariable id: Long, exchange: ServerWebExchange): Result {
val trace = exchange.request.headers.firstHeader("X-Trace")
return service.find(id, trace)
}
常见误区
- 在底层服务层静态取当前请求:响应式下线程不固定,取不到且污染分层。
- 把整个 exchange 传给服务层:服务层耦合 Web 模型。
追问
- 函数式路由取请求对象吗?答:处理器签名接收
ServerRequest,从其方法读参数。 - 请求属性跨协程如何带?答:放入上下文元素或作为方法参数传递。
06.8.2.2-061 延迟响应与 awaitExchange 在协程中如何使用?
一句话结论
需要基于交换对象做延迟处理时,协程扩展提供等待交换/响应的挂起点;响应式延迟(等待异步信号再写响应)应通过挂起或 Flow 表达,不要在事件循环上 sleep 阻塞。
概念解释
部分场景需要先注册回调、等待外部信号再返回响应。协程用挂起等待替代回调嵌套,等待期间释放线程;延迟时长由超时与取消约束,避免请求悬挂。
原理流程
- 处理器进入挂起等待信号/交换就绪。
- 等待期间线程释放。
- 信号到达恢复协程,构造响应。
- 超时/取消按规则退出。
代码或图示
suspend fun waitResult(): ServerResponse {
val result = signal.awaitFirst() // 挂起等待异步信号
return ServerResponse.ok().bodyValue(result)
}
常见误区
- 用
delay轮询等待结果:应等信号/事件,避免空转延迟。 - 延迟响应不设超时:连接悬挂占用资源直到网关超时。
追问
- 长轮询如何实现?答:挂起等待条件或超时返回,见 SSE/长轮询场景条目。
- awaitExchange 具体 API 归属?答:Spring WebFlux Kotlin 扩展,名称与可用性以官方文档为准(待确认)。
06.8.2.2-062 SSE 推送与 Flow 如何配合?
一句话结论
SSE 端点返回 Flow 并声明 text/event-stream 媒体类型,元素逐个作为事件推送;Flow 订阅对应 SSE 连接,取消订阅即断开连接,资源在 finally 释放。
概念解释
SSE 是服务端单向流式推送,响应式/Flow 天然适合。连接建立后订阅流,事件持续发射;客户端断开触发取消,Flow 协程终止并清理订阅源。
原理流程
- 端点返回 Flow,produces 设为 SSE 类型。
- 框架订阅 Flow,逐元素写事件流。
- 事件源更新推动 Flow 发射。
- 断开订阅取消 Flow,清理资源。
代码或图示
@GetMapping(value = ["/events"], produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
fun stream(): Flow<Event> = eventBus.subscribeAsFlow()
常见误区
- 推送源是热状态却忘了取消订阅:连接断开后订阅残留。
- SSE 事件缺 id/注释字段:协议兼容性按前端要求补充。
追问
- 心跳保活怎么加?答:Flow 周期性发射注释/心跳事件,配合超时配置。
- 多连接广播用什么源?答:共享热流(如 StateFlow/SharedFlow),见流类型条目。
06.8.2.2-063 文件上传在响应式/协程链路如何流式接收?
一句话结论
上传文件按数据片段流接收,协程/响应式 API 逐块读取写入存储;避免把整个上传体缓冲到内存,大文件按流落盘,背压控制读取与写入节奏。
概念解释
多部分上传在 WebFlux 中是数据片段流,处理器订阅片段写入目标存储。协程场景通过流收集或逐块处理,内存占用与文件大小解耦;完成后返回结果响应。
原理流程
- 接收上传片段流。
- 逐块写入文件/对象存储。
- 背压调节读取速度。
- 流完成返回结果,异常/取消清理临时文件。
代码或图示
suspend fun upload(exchange: ServerWebExchange): ServerResponse {
exchange.multipartData().awaitSingle()
// 按片段流式落盘;具体 multipart 协程 API 以 WebFlux Kotlin 文档为准(待确认)
}
常见误区
- 一次性收集全部字节到内存:大文件导致内存溢出。
- 取消/失败时不删临时文件:磁盘残留。
追问
- 上传大小限制在哪配?答:WebFlux multipart 大小限制与临时目录配置,通用 Web 配置见 06.2。
- 大文件落盘后如何校验?答:流式计算哈希,避免二次全量读取。
06.8.2.2-064 流背压溢出策略:缓冲、最新值、丢弃如何选?
一句话结论
生产快消费慢时选择溢出策略:缓冲保数据但占内存,最新值替换只保留最新状态,丢弃旧元素适合可刷新事件;按数据是否允许丢失与内存预算选择。
概念解释
背压溢出发生在上游速率超过下游处理能力。策略定义超出需求的元素如何处置:无界/有界缓冲、保留最新、丢弃头尾。事件可丢选丢弃/最新,订单/日志不可丢选有界缓冲并监控积压。
原理流程
- 下游需求低于上游生产。
- 溢出元素进入策略处理。
- 缓冲队列积压或替换/丢弃。
- 监控队列长度与丢弃计数。
代码或图示
// 思路:Flow/Flux 上配置缓冲容量与溢出策略
// buffer(capacity, BufferOverflow.DROP_OLDEST) 等(API 以所用流库为准)
常见误区
- 无界缓冲应对突发流量:内存无限增长风险。
- 关键数据用丢弃策略:丢失后无法补偿。
追问
- 积压指标看什么?答:队列长度、丢弃计数、上下游速率差;通用可观测性见 08 分册。
- 背压恢复后缓冲如何排空?答:下游提速后队列按需求消费,策略保持配置不变。
06.8.2.2-065 冷流与热流在控制器返回中如何区分?
一句话结论
冷流每次订阅重新执行生产逻辑(查询、扫描),热流订阅共享已有数据源(事件总线、状态);控制器返回前确认流类型,避免每次订阅重复重算或错误共享可变状态。
概念解释
Flow 默认冷流:订阅才执行流块。SharedFlow/StateFlow 是热流:数据源独立于订阅存在。HTTP 请求通常订阅冷流;多连接广播用热流。混用会导致重复生产或状态串扰。
原理流程
- 冷流:订阅 → 执行流块 → 发射 → 取消结束。
- 热流:源持续运行,订阅者接当前/后续值。
- 出口按协议订阅。
- 取消只影响冷流执行或热流订阅。
代码或图示
// 冷流:每次订阅执行查询
fun scan(): Flow<Row> = flow { dao.stream().collect { emit(it) } }
// 热流:共享事件源
val bus: SharedFlow<Event> = MutableSharedFlow()
常见误区
- 把冷流结果缓存成单例供多请求共享:改变语义,注意状态隔离。
- 热流在每个请求内新建:失去共享意义且浪费资源。
追问
- StateFlow 与 SharedFlow 区别?答:StateFlow 持当前值、去重;SharedFlow 配置回放订阅参数,协程文档有详述。
- 冷流里启动的资源在哪释放?答:
finally块,订阅取消时执行。
06.8.2.2-066 WebClient 在协程场景下如何使用?
一句话结论
WebClient 响应式客户端可通过协程扩展 awaitBody/awaitExchange 挂起调用,或返回 Flow 接收流式响应;服务端用 WebClient 调下游时与本链路共享非阻塞模型,避免再起同步 HTTP 客户端。
概念解释
WebClient 基于 Reactor,协程扩展把请求-响应包装为挂起调用。响应式客户端连接池复用非阻塞连接,与 WebFlux 服务端模型一致;同步 RestTemplate 不适合直接进入响应式链。
原理流程
- 构建 WebClient 实例与连接池配置。
- 请求链式构造 URI/头/体。
- 协程扩展挂起等待响应体或交换。
- 错误与超时按响应式/协程语义处理。
代码或图示
suspend fun fetchProfile(id: Long): Profile =
webClient.get().uri("/profiles/{id}", id)
.awaitBody<Profile>()
常见误区
- WebClient 调用后又
block():破坏非阻塞模型。 - 每次请求新建 WebClient 实例:连接池无法复用。
追问
- WebClient 连接池怎么配?答:底层 reactor Netty 连接池参数,通用客户端配置见 06.2。
- 流式响应怎么收?答:
bodyToFlux后asFlow(),或协程扩展流式接口。
06.8.2.2-067 如何限制并发调用的协程数量?
一句话结论
用信号量限制同时在跑的协程数,或用有限调度器/线程池约束并发;批量任务按许可获取/释放,避免下游与自身资源被无限并发打满。
概念解释
async 批量启动不受限时并发数等于任务数。信号量在执行前 acquire、结束 release,控制临界区并发;隔离池也能从线程数层面兜底。两种方式按场景组合。
原理流程
- 创建许可数有限的信号量。
- 每个任务执行前获取许可。
- 任务结束释放许可。
- 超额任务排队等待,不占用下游资源。
代码或图示
val semaphore = Semaphore(permits = 20)
suspend fun process(item: Item) = coroutineScope {
semaphore.acquire()
try { work(item) } finally { semaphore.release() }
}
常见误区
- 只靠调度器限制并发:IO 调度器线程数不等于业务并发上限,信号量更贴近下游配额。
- 获取许可后异常路径未释放:
finally释放保证许可归还。
追问
- 信号量是协程友好的吗?答:
kotlinx-coroutines提供挂起式信号量,不阻塞线程等待许可。 - 批量分批还有什么手段?答:
chunked分批处理,配合信号量控制每批并发。
06.8.2.2-068 响应式链路中的超时与降级如何编排?
一句话结论
下游调用设超时,失败/超时走降级分支返回兜底数据;协程用 withTimeout 与 try/catch,响应式用超时操作符与 fallback,降级结果要提前定义且不污染主链路上下文。
概念解释
高可用编排包含超时预算、错误分类、降级回退。超时避免悬挂连接,降级保证部分可用。可预期错误在局部捕获转换,未处理错误交给全局异常处理器。
原理流程
- 调用下游设置超时。
- 成功返回主结果。
- 超时/业务错误捕获,构造降级值。
- 降级不可用时返回明确错误响应。
代码或图示
suspend fun recommendation(id: Long): Reco = try {
withTimeout(300) { recoClient.similar(id) }
} catch (ex: Exception) {
Reco.default()
}
常见误区
- 降级里再做同步阻塞远程调用:降级路径也占资源。
- 超时异常与取消异常混为一谈:取消应向上传播,超时才走降级。
追问
- 重试放哪一层?答:客户端边界有限次数重试,配合退避;通用容错见 06.2/09 分册。
- 降级数据一致性如何标注?答:响应中标记降级来源,便于客户端识别。
06.8.2.2-069 响应式错误信号如何映射为 HTTP 500/4xx?
一句话结论
未捕获异常进入框架异常处理链,按异常类型映射状态码;业务异常应携带明确类别(404/400/409),兜底未分类错误映射 500,避免内部细节泄漏到响应体。
概念解释
错误信号从桥接层传到异常处理器。可预期领域异常映射 4xx,系统异常映射 5xx;响应体只暴露通用错误码与消息,堆栈与细节记日志。通用异常处理原理见 06.1,这里关注协程/响应式链路传递。
原理流程
- 协程/流抛异常转为错误信号。
- 异常处理器按类型匹配映射规则。
- 构造错误响应与状态码。
- 细节记录服务端日志。
代码或图示
// 领域异常 -> 404;未分类 -> 500(处理器实现见项目全局异常配置)
class NotFoundException(msg: String) : RuntimeException(msg)
常见误区
- 所有异常都返回 500:客户端无法区分可重试与参数错误。
- 响应体直接带堆栈/SQL 细节:安全与信息泄漏风险。
追问
- 流中途错误如何响应?答:已发送部分元素后错误会中断流,按协议关闭并记录错误。
- 异常处理器能拿到协程上下文吗?答:经桥接传递的上下文元素可补充日志与错误码。
06.8.2.2-070 压测协程 Web 服务应关注哪些指标?
一句话结论
关注请求延迟分布、吞吐、事件循环/工作线程占用、下游连接池与队列积压、取消与错误率;协程服务重点看是否有阻塞操作泄漏到事件循环,以及背压积压是否转化为内存增长。
概念解释
压测不只看 QPS:线程占用反映阻塞泄漏,队列长度反映背压积压,连接池等待反映下游瓶颈。协程调度切换下,单请求线程停留时间与阻塞栈是排查重点。
原理流程
- 梯度加压,记录延迟分位与错误率。
- 采集线程池/事件循环指标。
- 检查流队列、连接池等待与内存趋势。
- 定位阻塞点、背压瓶颈与下游依赖。
代码或图示
// 指标清单:QPS、P50/P95/P99、错误率、事件循环阻塞、
// IO 池队列、下游连接池等待、流积压数、堆内存趋势
常见误区
- 只看平均延迟:P99 长尾往往来自阻塞与排队。
- 压测环境无下游隔离:下游瓶颈被误判为协程问题。
追问
- 如何定位阻塞事件循环的调用?答:线程名 + 阻塞栈采样,找到同步 JDBC/HTTP/锁调用。
- 背压积压如何在压测中体现?答:队列长度上涨、内存增长、下游处理速率跟不上。
06.8.2.2-071 Spring MVC 如何支持 suspend 控制器方法?
一句话结论
MVC 通过异步请求机制桥接 suspend 方法:控制器挂起时释放 Servlet 线程,协程完成后恢复写响应;底层仍是 Servlet 异步上下文,与 WebFlux 的响应式运行时不同。
概念解释
Spring MVC 6 支持控制器返回挂起函数结果,桥接为 DeferredResult/异步处理。suspend 方法内等待协程时不占用请求线程,但 MVC 服务层通常仍是阻塞仓库,非阻塞收益有限。
原理流程
- 请求进入 MVC 控制器。
- suspend 方法启动协程并挂起等待。
- Servlet 异步上下文释放原线程。
- 协程完成后写回响应,恢复异步请求。
代码或图示
@RestController
class MvcController {
@GetMapping("/{id}")
suspend fun detail(@PathVariable id: Long): Detail = service.findSuspend(id)
}
常见误区
- 以为 MVC 上 suspend 等于完整响应式:异步桥接存在,但阻塞数据访问仍占线程。
- 在 MVC suspend 方法里混 WebFlux 类型:两套运行时不应交叉。
追问
- MVC 协程支持从哪个 Spring 版本开始?答:Spring Framework 6 基线能力,具体支持边界以官方文档为准(待确认)。
- 阻塞仓库和 suspend 控制器能共存吗?答:能调用,但阻塞调用仍占用隔离线程,见共存条目。
06.8.2.2-072 MVC 中 DeferredResult/Callable 与协程如何桥接?
一句话结论
MVC 异步原语 Callable/DeferredResult 是协程桥接的底层承接:suspend 控制器被适配为异步结果,协程完成设置结果,异常设置错误;业务代码一般直接写 suspend 方法,不手动操作异步原语。
概念解释
Callable 在工作线程执行返回结果,DeferredResult 异步设置结果或错误。协程桥接把挂起完成事件映射到这些原语的设置方法。理解桥接有助于排查 MVC 异步超时与错误传播。
原理流程
- 框架把 suspend 处理器包装为异步任务。
- 协程执行,完成回调设置 DeferredResult 结果。
- 异常回调设置错误结果。
- MVC 异步上下文写出响应。
代码或图示
// 桥接示意:suspend fun handle() -> 异步 DeferredResult
// 成功 -> setResult(value);异常 -> setErrorResult(ex)
常见误区
- 在控制器里既写 suspend 又手动 new DeferredResult:双重异步包装,状态混乱。
- 忽略 MVC 异步超时配置:挂起超过异步超时被中断。
追问
- 异步超时配置在哪?答:MVC 异步请求超时与拦截器配置,通用 MVC 原理见 06.2。
- Callable 的线程池由谁提供?答:MVC 异步任务执行器配置,通用机制见 06.2。
06.8.2.2-073 MVC 场景下 runBlocking 为何仍是反模式?
一句话结论
即使在 MVC 阻塞线程模型中,runBlocking 也只是把协程等待绑定在当前 Servlet 线程上,不增加非阻塞收益;控制器应直接声明 suspend 由框架桥接,工具边界才允许 runBlocking。
概念解释
MVC 线程本就为请求占用,runBlocking 额外引入协程调度包装却不释放线程,徒增复杂度。仅在必须调用同步接口的适配边界使用 runBlocking,控制器与服务层不默认使用。
原理流程
- 控制器若 runBlocking,当前线程阻塞等待内部协程。
- 线程不释放,Servlet 异步桥接被绕过。
- 协程调度优势没有体现。
- 正确写法是 suspend 方法交由框架桥接。
代码或图示
// 不推荐:MVC 控制器内 runBlocking
@GetMapping("/bad")
fun bad(): Out = runBlocking { service.suspendCall() }
// 推荐:suspend 方法由 MVC 异步桥接
@GetMapping("/good")
suspend fun good(): Out = service.suspendCall()
常见误区
- 认为 MVC 是阻塞模型就该到处 runBlocking:桥接已提供挂起支持。
- runBlocking 内切换 Dispatcher:外层线程仍被阻塞等待。
追问
- 测试里用 runBlocking 可以吗?答:测试可用
runTest替代;main 入口允许 runBlocking。 - 同步遗留库包装成 suspend 怎么做?答:
withContext(IO)包裹,而不是在 Web 层 runBlocking。
06.8.2.2-074 MVC 协程调度与 Servlet 异步线程如何配合?
一句话结论
MVC 下协程在框架提供的异步执行环境中调度,请求线程释放后由异步任务/调度器恢复;阻塞工作仍需线程池承载,协程调度器选择与 WebFlux 类似,但运行时承接不同。
概念解释
Servlet 异步上下文允许线程释放后继续处理。协程挂起恢复由任务执行器或调度器驱动,阻塞调用隔离到工作线程池。理解点:MVC 的线程池仍是请求并发的主要承接资源。
原理流程
- 请求线程启动异步协程任务。
- 挂起点释放请求线程。
- 恢复时由异步执行器/调度器安排线程。
- 阻塞任务在隔离池执行。
代码或图示
suspend fun place(order: Order) = withContext(Dispatchers.IO) {
blockingRepository.save(order)
}
常见误区
- 假设 MVC suspend 释放线程后不占任何资源:异步任务与隔离池仍承接并发。
- 把 WebFlux 调度器结论直接套到 MVC:线程池配置与执行器模型不同。
追问
- MVC 异步任务执行器怎么配?答:通过 MVC 异步配置注册执行器,通用配置见 06.2。
- 协程取消对应 Servlet 异步取消吗?答:客户端断开传播到协程取消,异步请求结束,具体行为以版本实现为准(待确认)。
06.8.2.2-075 coRouter 能在 MVC 应用中使用吗?
一句话结论
函数式路由 router 在 MVC 与 WebFlux 都可用;coRouter 的 suspend 处理器依赖协程桥接支持,MVC 是否完整支持协程版函数式路由需按版本核对,不要假设两套运行时行为一致(待确认)。
概念解释
RouterFunction 是 Spring Web 通用函数式端点抽象,MVC 与 WebFlux 各自有适配。协程版 DSL 与 suspend 处理器的支持程度随框架版本演进,选型前核对对应运行时文档。
原理流程
- 确认应用运行时是 MVC 还是 WebFlux。
- 查框架文档对函数式路由与协程处理器的支持矩阵。
- 选用对应 DSL 与处理器签名。
- 测试异步桥接与错误传播行为。
代码或图示
// WebFlux:coRouter + suspend 处理器
// MVC:先核对 RouterFunction 与协程支持版本,再决定 DSL 写法
常见误区
- 把 WebFlux coRouter 片段原样复制到 MVC 工程:处理器签名与桥接可能不匹配。
- 未验证就上线协程函数式端点:异步行为需测试覆盖。
追问
- RouterFunction Bean 在 MVC 如何接入?答:由 MVC 函数式端点映射检测注册,通用机制见 06.2。
- 版本不确定时怎么落地?答:MVC 优先注解控制器,WebFlux 用协程函数式路由。
06.8.2.2-076 MVC 控制器返回 Mono/Flow 是什么行为?
一句话结论
MVC 对响应式类型返回值的支持有限:多数场景应返回普通结果或 suspend 结果;把 Mono/Flux 当作 MVC 返回类型,行为取决于框架版本适配,不应在 MVC 工程主推响应式类型签名(待确认)。
概念解释
MVC 运行时不基于 Reactor,响应式类型返回值虽可能被适配承接,但流语义、背压与线程模型不完整。协程 Flow 同理,跨运行时混用容易产生意外阻塞或订阅问题。
原理流程
- 控制器声明返回 Mono/Flux/Flow。
- MVC 适配器判断是否支持该返回类型。
- 支持则桥接订阅写出,不支持按类型解析失败。
- 流语义在 MVC 上不保证完整背压。
代码或图示
// WebFlux 推荐:返回 Flow 流式写出
// MVC 推荐:返回普通 DTO 或 suspend 结果,不主推 Flux/Flow
常见误区
- 同一个控制器代码想同时跑 MVC 和 WebFlux:返回类型语义不同,应分运行时设计。
- 在 MVC 里返回 Flux 期望 SSE 流式:流式能力以 WebFlux 支持为准。
追问
- 如何确认版本支持?答:查 Spring Framework MVC 返回值类型解析文档,列出版本基线(待确认)。
- 跨运行时复用服务层怎么做?答:服务层保持领域逻辑,Web 层按运行时选择签名。
06.8.2.2-077 阻塞服务层与协程控制器如何安全共存?
一句话结论
控制器 suspend 化后,阻塞服务调用必须在隔离调度器中执行;明确划分非阻塞 Web 边界与阻塞服务边界,不要把阻塞仓库直接暴露在事件循环线程上调用。
概念解释
共存不等于混用:Web 层协程编排,阻塞数据访问通过隔离边界调用。服务接口可提供 suspend 包装,内部 withContext(IO) 承接阻塞实现;上层看不到同步阻塞细节。
原理流程
- Web 控制器 suspend 签名。
- 服务接口定义 suspend 方法。
- 实现内部切到 IO 池调用阻塞仓库。
- 返回结果延续协程链路。
代码或图示
class BlockingUserRepository { fun find(id: Long): User? = jdbc.query(...) }
class UserService(private val repo: BlockingUserRepository) {
suspend fun find(id: Long): User? = withContext(Dispatchers.IO) { repo.find(id) }
}
常见误区
- 阻塞仓库方法直接在 suspend 控制器里调:事件循环/异步线程被阻塞。
- 包装层不隔离线程:阻塞压力回到 Web 线程。
追问
- 长期演进方向?答:逐步换响应式/协程数据访问,减少阻塞边界;通用数据访问选型见 05 分册。
- 隔离池并发怎么控?答:有界池 + 信号量,避免阻塞任务无限排队。
06.8.2.2-078 MVC 协程方法上的事务边界有何注意点?
一句话结论
MVC 事务仍由代理在方法边界管理,事务内持有阻塞连接;suspend 方法挂起期间连接需保持可用,事务边界不要包住异步等待或远程调用,避免长事务占连接。
概念解释
MVC 数据访问通常是阻塞 JDBC,事务连接绑定在执行线程。协程切线程时事务上下文能否跟随,取决于事务管理器实现;稳妥做法是事务方法内只做数据库操作,远程/异步调用放到事务外。
原理流程
- 事务代理进入方法开启事务。
- 阻塞仓库操作使用事务连接。
- 挂起/切线程期间上下文传递需验证。
- 方法返回提交,异常回滚。
代码或图示
@Transactional
suspend fun update(id: Long, cmd: UpdateCmd) = withContext(Dispatchers.IO) {
repository.update(id, cmd) // 事务内仅数据访问
}
// 远程通知在事务提交后再调用
常见误区
- 事务方法内
async并发子任务:事务连接与上下文共享行为未验证,风险高。 - 事务边界包住消息发送/远程调用:回滚成本高、连接持有久。
追问
- 事务上下文跨协程线程如何保证?答:以所用事务管理器与 Spring 版本行为为准,需实测验证(待确认)。
- 事务提交后动作怎么挂?答:事务提交事件或方法返回后触发,通用事务机制见 06.2。
06.8.2.2-079 MVC/WebFlux 拦截器与协程上下文如何配合?
一句话结论
拦截器在请求链路前后置执行,协程上下文在处理器协程内可用;拦截器读到的请求数据应提取为上下文元素传入,不能依赖拦截器线程与处理器协程是同一线程。
概念解释
拦截器(HandlerInterceptor/过滤器)在框架链路层工作,协程在处理器内运行。入口提取的身份、traceId 放入上下文元素,供协程读取;拦截器本身不感知协程内部调度。
原理流程
- 拦截器预处理读取请求头/属性。
- 提取数据放入请求上下文或协程上下文元素。
- 处理器协程内读取元素。
- 拦截器后置处理响应。
代码或图示
// 拦截器:解析身份并写入请求属性;协程侧从上下文/参数读取
// 不要假设拦截器线程 == 协程恢复线程
常见误区
- 拦截器把身份放 ThreadLocal,协程跨线程读取:丢失。
- 在拦截器里启动协程做业务逻辑:职责越界,协程应归属处理器/服务。
追问
- WebFlux 过滤器与 MVC 拦截器差异?答:运行时链路不同,通用过滤器原理见 06.2。
- 上下文元素从拦截器到协程怎么传?答:经框架请求上下文桥接或在入口处理器构造元素传入。
06.8.2.2-080 如何选型:MVC + 协程 还是 WebFlux?
一句话结论
以阻塞数据访问与团队熟悉度为主、无强流式/高并发非阻塞需求时选 MVC + 协程;需要完整非阻塞流式、背压与响应式生态时选 WebFlux + 协程,不要为了「协程」名义上 WebFlux 却保留阻塞仓库。
概念解释
选型核心是运行时与数据访问模型是否匹配。MVC 成熟、阻塞栈简单;WebFlux 吞吐与流式能力强,但要求链路全非阻塞。协程在两者都可作为写法层,不能改变运行时线程模型本质。
原理流程
- 评估数据访问:阻塞 JDBC 还是响应式驱动。
- 评估需求:普通 CRUD 还是 SSE/流式/高并发。
- 评估团队响应式经验与遗留系统兼容。
- 选定运行时,服务层按对应模型设计。
代码或图示
阻塞栈 + 常规业务 -> MVC(可配合 suspend 控制器)
流式/背压/全链路非阻塞 -> WebFlux + 协程
阻塞仓库硬上 WebFlux -> 风险高,需先改造数据访问
常见误区
- 只看到协程语法就选 WebFlux:运行时约束比语法重要。
- MVC 工程盲目引入 Flux/响应式客户端:跨运行时复杂度上升。
追问
- 能否一个应用同时包含两套栈?答:技术上可隔离模块,但维护成本高,应作为过渡而非常态。
- 选型文档参考?答:Spring 官方 MVC/WebFlux 选型说明,通用 Web 框架对比见 06.2。
06.8.2.2-081 协程 Web 应用需要哪些依赖?
一句话结论
WebFlux 应用引入 spring-boot-starter-webflux,协程能力依赖 kotlinx-coroutines-core 与桥接模块;与 Reactor 互操作引入 kotlinx-coroutines-reactor,版本与 Boot/Kotlin 基线对齐。
概念解释
starter 提供 Web 运行时与 Reactor;协程核心库提供挂起、调度器、Flow;reactor 桥接提供 Mono/Flux 扩展。MVC 工程协程控制器所需桥接由对应 Spring 协程支持模块提供,依赖清单按运行时确定。
原理流程
- 按运行时选 webmvc 或 webflux starter。
- 加入 coroutines-core。
- 响应式互操作加入 coroutines-reactor。
- 版本由 Boot BOM 与 Kotlin 版本协调核对。
代码或图示
// build.gradle.kts 依赖示意;具体坐标与版本以官方 BOM 为准(待确认)
// implementation("org.springframework.boot:spring-boot-starter-webflux")
// implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
常见误区
- 只引 coroutines-core 不引 reactor 桥接:Mono/Flux 扩展不可用。
- 协程库版本与 Reactor/Spring 不匹配:桥接编译或运行异常。
追问
- coroutines-core 是 transitive 引入吗?答:可能被桥接模块带入,显式声明更稳妥。
- 版本对齐查哪里?答:Boot 依赖清单与 Kotlin/协程兼容矩阵,标待确认项实测。
06.8.2.2-082 kotlinx-coroutines-reactor 模块承担什么角色?
一句话结论
它是协程与 Reactor 之间的桥接层:提供 Mono/Flux 挂起扩展、Flow 互转、上下文桥接与 mono{}/flux{} 包装;WebFlux Kotlin 代码依赖它把两套模型接起来。
概念解释
没有桥接模块,协程代码只能自己订阅 Reactor 发布者、管理回调与异常。桥接扩展封装订阅等待、取消传播、错误转换与上下文映射,边界代码得以用挂起风格书写。
原理流程
- Reactor 发布者进入桥接扩展。
- 桥接订阅发布者,挂起协程等待信号。
- 元素/完成/错误/取消映射到协程语义。
- 反向包装协程结果为发布者。
代码或图示
// 桥接能力:awaitSingle、asFlow、mono{}、asFlux、上下文元素映射
val users: Flow<User> = client.list().asFlow()
常见误区
- 把桥接模块当协程核心库:它只负责 Reactor 互操作,核心调度在 coroutines-core。
- 桥接层散落业务链路:边界集中转换,内部保持单一模型。
追问
- 还有哪些桥接模块?答:针对不同响应式/异步库有对应桥接;Spring 生态主要用 reactor 桥接。
- 模块缺失报什么错?答:扩展方法 unresolved 或运行时缺少桥接类。
06.8.2.2-083 awaitBody 缺省请求体时常见什么 NPE 或异常?
一句话结论
期望非空体的端点调用 awaitBody<T>(),请求无体或体为空时桥接抛缺失体异常;应在确有体的端点使用,可能为空的场景用 OrNull 变体并判空,避免把空值当非空解引用。
概念解释
请求体存在性由协议保证,POST/PUT 可能无体、GET 通常无体。非空 await 对空体直接失败;空体场景返回 null,业务决定是否报错。异常在读取阶段暴露,而不是反序列化后字段 NPE。
原理流程
- 处理器调用非空 awaitBody。
- 桥接检查请求体是否存在。
- 无体抛缺失体异常;有体反序列化。
- OrNull 变体无体返回 null。
代码或图示
suspend fun create(request: ServerRequest): ServerResponse {
val body = request.awaitBodyOrNull<CreateUserRequest>()
?: return ServerResponse.badRequest().build()
return ServerResponse.ok().bodyValue(service.create(body))
}
常见误区
- GET 端点也 awaitBody:方法语义与体存在性不符。
- OrNull 返回 null 后不判空直接传给服务:NPE。
追问
- 反序列化缺字段报什么?答:构造器非空参数缺失,反序列化异常,见 Kotlin 配置/实体相关分册。
- 如何在文档声明体必填?答:API 契约标注请求体,测试覆盖无体场景。
06.8.2.2-084 未绑定作用域的 launch 如何造成协程泄漏?
一句话结论
在组件里直接用全局作用域或未保存引用的 launch,协程生命周期脱离容器 Bean;Bean 销毁后任务仍在运行,持有引用导致内存与线程泄漏,必须使用组件受控作用域。
概念解释
GlobalScope.launch 的协程不归属任何 Job,没有统一取消点。局部 launch 的 Deferred/Job 若不保存,无法在销毁时取消。组件作用域把后台任务纳入 Bean 生命周期管理。
原理流程
- 组件启动后台协程但作用域不可控。
- Bean 销毁,协程未被取消。
- 协程持有组件引用,对象无法回收。
- 线程/内存随泄漏累积。
代码或图示
// 错误:GlobalScope
@Suppress("GlobalCoroutineUsage")
GlobalScope.launch { poll() }
// 正确:组件作用域,销毁时 cancel
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
常见误区
- 以为 launch 出栈就自动结束:协程独立于调用函数生命周期。
- 后台任务不保存 Job 引用:无法单独取消。
追问
- 临时一次性任务用什么作用域?答:
coroutineScope/supervisorScope在请求或函数边界内结构化管理。 - 泄漏如何排查?答:线程栈、协程列表与堆引用分析,通用内存排查见 01 分册。
06.8.2.2-085 日志 traceId 在协程链路丢失如何排查?
一句话结论
先确认入口是否把 traceId 放进了可传播上下文(Reactor Context/协程元素),再检查跨线程恢复时 MDC 回填是否执行;日志线程名与 MDC 值对照挂起前后,定位丢失的调度点。
概念解释
丢失分两类:上下文根本没放进去,或放了但跨线程没回填 MDC。前者查入口过滤器/桥接写入,后者查调度恢复时的 MDC 同步逻辑。框架自带追踪适配通常已处理,自定义上下文需自行桥接。
原理流程
- 入口日志确认 traceId 已生成。
- 检查上下文写入位置与键名。
- 在挂起前后日志打印线程与 MDC。
- 定位切换线程后未回填的环节,补上下文传播。
代码或图示
// 排查链:入口 MDC -> 上下文写入 -> 挂起点 -> 恢复线程 MDC -> 下游日志
// 对比线程名变化与 MDC 是否跟随
常见误区
- 只在入口线程设 MDC 就期望跨线程保留:ThreadLocal 不自动传播。
- 自定义 traceId 未接入追踪桥接:日志间无法关联。
追问
- 框架追踪何时自动传播?答:Micrometer/链路追踪适配在响应式与协程链路上的传播机制,通用可观测性见 08 分册。
- 线程池复用残留 MDC 怎么办?答:任务结束清理 MDC,避免上一请求标识串号。
06.8.2.2-086 IO 调度器线程池大小如何评估与配置?
一句话结论
Dispatchers.IO 默认按上限共享,阻塞任务多时应按下游容量与并发目标评估隔离池;不要无限依赖默认 IO 池,阻塞任务隔离为有界池并设置队列与拒绝策略。
概念解释
IO 池面向阻塞等待,线程数可高于 CPU 核数,但下游连接数、数据库会话与内存是硬上限。默认池参数由协程库设定,自定义池按压测结果调整,配合信号量限制业务并发。
原理流程
- 统计阻塞任务类型与单任务占用时长。
- 按下游连接配额与目标并发算线程需求。
- 创建有界池包装为调度器。
- 压测观察队列、等待时间与下游拒绝。
代码或图示
// 自定义有界池思路:Executors.newFixedThreadPool(n).asCoroutineDispatcher()
// 用完显式 close() 释放调度器;具体工厂 API 以协程文档为准(待确认)
常见误区
- 把 CPU 密集任务放 IO 池:池利用率与线程数模型不匹配。
- 无界队列堆积阻塞任务:内存与延迟失控。
追问
- 默认 IO 池上限是多少?答:以 kotlinx-coroutines 文档版本说明为准(待确认),不凭记忆写死。
- 池参数压测看什么?答:队列长度、线程活跃数、任务等待耗时、下游连接等待。
06.8.2.2-087 协程测试如何用 runTest 编写?
一句话结论
协程单元测试用 runTest 提供测试调度器,虚拟时间推进延时,断言挂起结果与异常;相比 runBlocking,runTest 不真实等待超时,测试更快且可检验延迟行为。
概念解释
runTest 启动测试协程并替换调度器,delay 由虚拟时钟跳过。适合验证 suspend 函数、Flow 时序与超时分支;需要真实时间的场景才用 runBlocking。
原理流程
- 测试函数标注测试框架并在
runTest内执行。 - 被测 suspend 函数在测试调度器运行。
delay虚拟推进,立即到达后续断言。- 断言结果、异常或流序列。
代码或图示
@Test
fun `returns default after timeout`() = runTest {
val result = service.retryWithTimeout()
assertEquals(Expected.default(), result)
}
常见误区
- 用 runBlocking 测含 delay 的逻辑:测试真实等待,变慢且受环境影响。
- runTest 里启动未收集的后台协程:结构化作用域结束可能取消或泄漏未断言任务。
追问
- Flow 序列断言用什么?答:测试收集或配合 Turbine 类流测试工具,见测试分册条目。
- 测试调度器能切真实 IO 吗?答:需要隔离声明调度器并替换,默认测试调度器不跑阻塞 IO。
06.8.2.2-088 协程返回 DTO 时序列化要注意什么?
一句话结论
suspend 方法返回的 DTO 仍是普通 data class,序列化由消息转换器完成;协程/Flow 只负责数据产出,DTO 设计满足不可变、可反序列化与 Jackson Kotlin 模块要求,避免在响应类型里暴露协程/内部对象。
概念解释
Web 出口把领域对象映射为 DTO 再序列化。Flow 元素类型应是可序列化 DTO;内部协程作用域、连接、仓储引用不能进入返回对象。Jackson Kotlin 模块要求见容器集成分册。
原理流程
- 服务返回领域模型。
- 映射为响应 DTO(data class)。
- 框架消息转换器序列化。
- Flow 逐元素映射后发射。
代码或图示
data class UserDto(val id: Long, val nickname: String)
fun Flow<User>.toDto(): Flow<UserDto> = map { UserDto(it.id, it.nickname) }
常见误区
- 直接把实体/领域对象暴露给前端:字段泄露与懒加载序列化问题。
- DTO 含可变引用或内部状态:序列化行为不稳定。
追问
- Flow 元素序列化媒体类型?答:按端点 produces 配置,JSON 数组或 SSE 事件。
- 序列化失败在哪层暴露?答:消息转换器阶段转为 500/400,由异常处理器映射。
06.8.2.2-089 Spring 6 对 suspend 控制器的支持基线是什么?
一句话结论
suspend 控制器与协程处理器支持属于 Spring Framework 6 对 Kotlin 协程的集成能力,运行时支持程度(MVC/WebFlux、返回类型)按 6.x 小版本演进,具体清单以官方参考文档为准(待确认)。
概念解释
Spring 5 时代响应式类型为主,6.x 完善 Kotlin 协程桥接。Boot 3.x 对应 Spring 6.x 基线,使用 suspend 签名前核对所用小版本的支持范围,不把新版行为假设到旧版本。
原理流程
- 确定 Spring Framework 小版本。
- 查官方文档协程支持章节。
- 核对 MVC/WebFlux 控制器、返回类型与桥接模块。
- 测试验证异步行为后上线。
代码或图示
// 核对项:suspend 控制器、Flow 返回、coRouter、异步取消与异常传播
// 版本敏感行为标「待确认」,不编造小版本引入日期
常见误区
- 照搬新版本协程特性到旧 Boot/Spring:编译或运行时不支持。
- 以为协程支持跨运行时完全一致:MVC 与 WebFlux 能力边界不同。
追问
- 如何查版本基线?答:Spring Framework 参考文档 Kotlin 章节与 Boot 发行说明。
- 不确定的 API 怎么办?答:写最小可运行示例验证行为,标注待确认。
06.8.2.2-090 Kotlin 2.x 与协程库版本如何对齐?
一句话结论
协程库版本需与 Kotlin 编译器版本、Spring/Reactor 桥接兼容;以官方兼容矩阵与 Boot BOM 为准选择,不自行混搭最新版,升级 Kotlin 时同步核对协程与桥接模块。
概念解释
协程库按 Kotinet 语言特性演进,编译器版本过新会要求较新协程库,桥接模块又依赖 Reactor 与 Spring 版本。三者构成兼容集合,单独升级任一项都可能出现二进制不兼容。
原理流程
- 锁定 Kotlin 编译器版本。
- 选兼容的 coroutines-core/reactor 版本。
- 核对 Spring Boot BOM 管理的 Reactor/Spring 版本。
- 编译与集成测试验证后固定版本。
代码或图示
// 兼容链:Kotlin 2.x <-> coroutines 1.x <-> reactor 桥接 <-> Spring 6.x
// 具体版本号以兼容矩阵与 BOM 为准(待确认)
常见误区
- 协程库单独升最新:可能与编译器或桥接模块不兼容。
- 不查 BOM 手动锁死 Reactor 版本:与 Spring 依赖冲突。
追问
- 版本冲突报什么现象?答:类签名/方法缺失、桥接扩展异常,编译或启动期暴露。
- 升级顺序建议?答:先 Boot/Spring 基线,再编译器,最后协程库对齐矩阵。
06.8.2.2-091 场景:并发聚合三个下游接口如何编排?
一句话结论
三个无依赖下游用 async 并发启动,awaitAll 收集结果;各自设置超时与容错,整体限定并发度,任一下游失败按业务策略决定快速失败还是降级补齐。
概念解释
聚合接口总耗时应接近最慢下游而非三者之和。并发前确认任务无依赖;共享上下文(身份、租户)通过上下文元素传递;下游异常分类处理,避免一个失败拖垮全部可选结果。
原理流程
- 读取公共上下文参数。
- 三个 async 分别调用下游,内部设超时。
- awaitAll 收集成功结果。
- 失败项降级补默认值或整体返回错误。
代码或图示
suspend fun dashboard(id: Long): Dashboard = coroutineScope {
val profile = asyncCatching { profileClient.get(id) }
val orders = asyncCatching { orderClient.orders(id) }
val stats = asyncCatching { statsClient.summary(id) }
Dashboard(profile.getOrNull(), orders.getOrNull(), stats.getOrNull())
}
常见误区
- 下游之间有数据依赖却并行:第二个任务缺少第一个结果。
- 不设超时:慢下游拖住整个人聚合接口。
追问
- 并发度需要控制吗?答:三任务可不加信号量,批量场景必须限流。
- 部分失败如何响应?答:响应中标注降级字段,前端按可用字段渲染。
06.8.2.2-092 场景:长轮询与 SSE 推送怎么选?
一句话结论
服务端主动持续推送、多事件流式输出选 SSE(Flow 事件流);客户端单次等待一个结果再重新请求选长轮询;按浏览器/网关兼容性、连接数与事件频率决策。
概念解释
SSE 单连接持续推送,适合实时通知、进度流;长轮询请求挂起等待结果后返回,客户端再发请求,兼容性好但每次重建请求。协程挂起都能承载两种等待,资源模型不同。
原理流程
- 判断事件频率与方向:持续推 vs 单次等。
- SSE:端点返回 Flow 事件流,连接保持。
- 长轮询:挂起等待条件/超时后返回,客户端重连。
- 配合心跳、超时与取消清理资源。
代码或图示
// SSE
@GetMapping(produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
fun events(): Flow<Event> = bus.subscribeAsFlow()
常见误区
- 长轮询在服务端用 Thread.sleep 阻塞:应挂起等待信号。
- SSE 连接不设心跳/超时:代理层断开后连接残留。
追问
- 网关超时对 SSE 影响?答:反向代理与负载均衡空闲超时需大于心跳间隔。
- 多实例广播怎么做?答:事件总线跨实例共享(消息队列/ PubSub),通用推送架构见 09 分册。
06.8.2.2-093 场景:阻塞遗留服务如何接入响应式模块?
一句话结论
在边界用隔离线程池包装阻塞调用为 suspend 接口,限制并发与超时;响应式模块内部不直接引用阻塞 API,长期逐步替换为响应式/协程数据访问,过渡期监控阻塞边界队列与线程占用。
概念解释
遗留仓库、同步 SDK 无法一夜改造。先建防腐层:阻塞实现藏在适配器后,对外暴露 suspend 方法,内部切 IO 隔离池;响应式编排只依赖适配器接口。边界并发受信号量保护。
原理流程
- 识别阻塞依赖清单。
- 定义 suspend 端口接口。
- 适配器内部
withContext(隔离池)调用阻塞实现。 - 监控边界,逐步替换阻塞实现。
代码或图示
interface UserPort { suspend fun find(id: Long): User? }
class BlockingUserAdapter(private val legacy: LegacyUserDao) : UserPort {
override suspend fun find(id: Long): User? =
withContext(legacyPool) { legacy.find(id) }
}
常见误区
- 适配器把阻塞异常直接抛进响应式链未转换:错误分类丢失。
- 隔离池无界:阻塞积压压垮应用。
追问
- 过渡期限流参数怎么定?答:按遗留系统连接配额与压测结果设许可数。
- 替换顺序?答:先读路径后写路径,数据访问先于业务逻辑改造。
06.8.2.2-094 场景:用户身份如何在协程链路传递?
一句话结论
入口从认证上下文解析身份,封装为不可变上下文元素随协程传播;服务层从上下文取身份,不依赖 ThreadLocal,子协程继承元素,跨线程恢复时身份仍可读。
概念解释
身份是请求级上下文数据。响应式安全上下文有专门读取适配;进入协程后转为自定义元素或经桥接映射。传递链路:过滤器/拦截器解析 → 上下文元素 → 服务/下游调用携带。
原理流程
- 入口过滤器解析认证主体。
- 构造身份元素放入协程/响应式上下文。
- 服务层读取元素作为操作人。
- 下游调用透传必要身份标识。
代码或图示
class CurrentUser(val id: Long, val roles: Set<String>) :
AbstractCoroutineContextElement(CurrentUser) {
companion object Key : CoroutineContext.Key<CurrentUser>
}
常见误区
- 身份存 ThreadLocal:跨线程恢复丢失。
- 子协程独立作用域未继承上下文:身份取不到。
追问
- 安全上下文在 WebFlux 怎么读?答:响应式安全上下文适配读取,通用 Security 机制见 06.8.2.3 与 06.2。
- 下游调用要传身份吗?答:按审计与鉴权需要透传用户标识,避免内部越权。
06.8.2.2-095 场景:请求取消后如何保证资源清理?
一句话结论
资源获取与释放配对写在 try/finally,取消信号触发后 finally 仍执行;流订阅结束、连接、临时文件、锁在 finally 释放,协程取消异常不阻断清理逻辑。
概念解释
请求取消不是异常忽略:被取消协程在挂起点终止,finally 块保证资源释放。清理动作避免再做不可中断的阻塞操作;需要确认释放结果时记录日志,不阻塞等待已取消请求。
原理流程
- 资源在协程开始处获取。
try执行业务/流发射。- 取消或完成进入
finally。 - 释放连接、关闭流、删除临时文件。
代码或图示
suspend fun process(): Result {
val client = acquire()
try {
return client.work()
} finally {
client.close()
}
}
常见误区
- 资源释放写在成功路径末尾:取消时跳过释放。
- finally 里再挂起调用未处理取消:清理本身被中断。
追问
- 外部连接池会兜底回收吗?答:池有回收机制,但主动关闭更可靠;泄漏仍需监控。
- 流订阅取消清理点在哪?答:Flow 的
finally/onCompletion,订阅结束即触发。
06.8.2.2-096 场景:背压导致内存上涨如何排查?
一句话结论
从流队列与缓冲入手:检查上游生产速率、下游消费速率、溢出策略与缓冲容量;内存上涨伴随队列长度增长,定位积压节点,调整缓冲策略、限流或扩容消费能力。
概念解释
响应式内存上涨通常来自未消费元素堆积。排查链路:堆转储看集合持有 → 定位流缓冲/队列 → 对比上下游速率 → 确认溢出策略是缓冲还是丢弃。协程 Flow 积压体现在发射挂起与未消费元素。
原理流程
- 监控堆内存与队列长度趋势。
- 堆转储定位积压集合所属流。
- 对比生产/消费速率与下游瓶颈。
- 调整策略:限上游、扩消费、改丢弃/最新值。
代码或图示
// 排查:内存增长 -> 队列/缓冲持有 -> 上游速率 vs 下游速率 -> 溢出策略
// 处置:背压限流、有界缓冲、丢弃策略、消费扩容
常见误区
- 直接加堆内存掩盖积压:根因未除,最终仍 OOM。
- 无界缓冲日志/事件流:突发流量直接撑爆内存。
追问
- 指标看哪些?答:队列长度、元素待处理数、丢弃计数、GC 频率;通用可观测性见 08 分册。
- 下游慢是数据库还是外部接口?答:分段压测区分瓶颈节点。
06.8.2.2-097 场景:DSL 路由与注解控制器路径冲突如何处理?
一句话结论
列出两套映射的路径与谓词,取消同路径双重映射;按模块归属保留一套机制,重叠路径收窄谓词或拆分前缀,启动后验证实际匹配规则与顺序。
概念解释
冲突表现为请求落到非预期处理器。排查时分别导出函数式路由表与注解映射表,按方法+路径+谓词比对。混用阶段建议新模块用 DSL、旧模块保留注解,逐步收敛而非并行重叠。
原理流程
- 导出两套端点映射清单。
- 比对路径、HTTP 方法、内容谓词。
- 重叠处确定归属,删除或改路径。
- 测试各路径命中预期处理器。
代码或图示
// 核对:RouterFunction 规则表 + @RequestMapping 表
// 同路径只保留一套;前缀隔离两个模块
常见误区
- 依赖「注解优先/DSL 优先」假设:匹配顺序按框架规则,需实测。
- 谓词不同但路径相同:仍可能按谓词分发,边界模糊。
追问
- 如何打印全部映射?答:Actuator 映射端点或启动调试日志,通用端点探测见 06.2。
- 过渡期两套机制怎么注释?答:路由归属在模块文档标明,避免后人重复添加。
06.8.2.2-098 场景:响应式客户端重试如何编排?
一句话结论
客户端边界对可重试错误设置有限次数与退避间隔,区分可重试错误(超时、5xx、连接失败)与不可重试错误(4xx、业务失败);协程代码用重试包裹挂起调用,重试预算计入整体超时。
概念解释
重试是容错第一道,但盲目重试放大下游压力。错误分类后只对幂等、可重试操作重试;退避避免雪崩,次数与总超时受限。非幂等写操作重试需配合幂等键。
原理流程
- 调用下游捕获异常/错误状态。
- 判断是否可重试与是否幂等。
- 可重试则按退避等待后重试。
- 超过次数走降级或错误响应。
代码或图示
suspend fun fetchWithRetry(id: Long): Profile =
retry(attempts = 3, backoff = 100) {
client.getProfile(id)
}
常见误区
- 所有异常都重试:4xx 与业务错误重试无意义且放大流量。
- 重试不设总预算:多次重试叠加超过接口超时。
追问
- 退避策略有哪些?答:固定间隔、指数退避、抖动;通用容错见 09 分册。
- 写操作重试前提?答:接口幂等或携带幂等键,避免重复扣款/下单。
06.8.2.2-099 综合:协程 Web 服务如何划分正确边界?
一句话结论
边界分三层:Web 层接收请求并用 suspend/Flow 编排,服务层保持领域逻辑与 suspend 签名,基础设施层隔离阻塞客户端/仓库;上下文沿协程传播,阻塞操作只出现在基础设施隔离边界。
概念解释
清晰边界让协程模型贯通:Web 不直接碰阻塞 SDK,服务不依赖 Web 对象,基础设施负责调度隔离与桥接。每层签名一致使用协程类型,跨边界转换集中在适配器。
原理流程
- Web 层:参数解析、响应构建、流式出口。
- 服务层:领域编排、事务边界、并发控制。
- 基础设施层:阻塞/响应式客户端、仓库、调度隔离。
- 上下文元素贯穿各层。
代码或图示
Controller(suspend/Flow) -> Service(suspend) -> Repository/Client(隔离实现)
阻塞调用只在基础设施 withContext 边界内
常见误区
- 服务层直接拿 Web 请求对象:分层耦合,难测试。
- 阻塞 SDK 散落在服务层:隔离边界失控。
追问
- 边界怎么验证?答:依赖方向单向,服务层不 import Web 类型;代码评审与架构扫描检查。
- 跨层上下文怎么传?答:方法参数 + 协程上下文元素,不用 ThreadLocal。
06.8.2.2-100 综合:从阻塞 MVC 迁移到协程化的步骤与风险是什么?
一句话结论
按「依赖与运行时评估 → 服务层 suspend 化 → Web 层控制器迁移 → 阻塞访问隔离或替换 → 测试与压测」逐步推进;主要风险是阻塞调用残留事件循环、上下文丢失、事务边界扩散与版本支持不足,每步用测试与指标兜底。
概念解释
迁移不是把 fun 改成 suspend 即可:运行时、数据访问、上下文传播、事务与测试都要配套。先明确目标是 MVC 协程化还是完整 WebFlux,再按边界逐模块改造,避免全量切换风险。
原理流程
- 评估运行时目标、数据访问阻塞程度与团队经验。
- 基础设施层包装阻塞调用为 suspend 端口。
- 服务层改 suspend,编排并发与超时。
- Web 层迁移控制器/路由,补上下文传播。
- 测试协程行为,压测线程与背压指标。
代码或图示
步骤:依赖对齐 -> 端口 suspend 化 -> 服务层编排 -> Web 层迁移
风险点:阻塞残留、上下文丢失、事务长边界、版本不支持、测试缺协程断言
常见误区
- 一步全量重写:回滚困难,风险集中。
- 只改语法不改阻塞栈:名义协程,实际仍阻塞。
- 忽略测试迁移:旧同步测试无法验证 suspend 行为。
追问
- 哪些模块先试点?答:无强事务、读多写少的新模块或低风险接口。
- 迁移完成验收看什么?答:事件循环无阻塞、上下文日志完整、压测延迟与吞吐达标、测试覆盖取消与超时分支。
参考来源
- Spring Framework Reference: Kotlin support — Spring 对 Kotlin 协程、配置与 DSL 的集成说明。
- Spring Framework Reference: WebFlux Kotlin 支持 — WebFlux 协程控制器、函数式路由与桥接能力。
- Kotlin 官方文档: Coroutines guide — 协程上下文、调度器、Flow、结构化并发与取消语义。
- Spring Framework Reference: Web MVC — MVC 异步请求、控制器返回类型与拦截器机制。
- Project Reactor Reference — 响应式流、背压、调度器与错误处理模型。
待整理清单
- [ ] 核对当前 Spring Boot 3.2+ / Spring 6.x 小版本对 MVC 与 WebFlux suspend 控制器、Flow 返回的支持清单
- [ ] 核对 kotlinx-coroutines 1.x 与 Kotlin 2.x、Reactor、Spring 的兼容矩阵最低版本
- [ ] 验证响应式事务管理器与 suspend 方法的事务上下文跨协程行为
- [ ] 确认项目所用 WebClient/Reactor 桥接扩展的确切 API 名称与签名
- [ ] 梳理遗留阻塞服务清单与隔离池并发参数,补压测数据
- [ ] 收集生产环境协程泄漏、MDC 丢失、事件循环阻塞的真实案例归类