罗罗编程学习记录
本页内容 展开查看

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() 方法注册定义。它属于函数式注册路径,不依赖类路径扫描,适合显式组装、库模块与测试上下文。

原理流程

  1. 创建或获取 ApplicationContext。
  2. 执行 beans { } 配置块。
  3. 块内 bean() 调用向注册表追加 BeanDefinition。
  4. 容器刷新时按定义实例化。

代码或图示

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 中依赖关系一眼可见,不依赖类路径扫描;注解配置在常规业务组件上更简洁。两者解决同一问题的不同风格。

原理流程

  1. 应用业务组件:注解扫描自动注册。
  2. 第三方/编排对象:DSL 显式 bean()。
  3. 测试上下文:DSL 快速组装最小容器。
  4. 团队内保持一种主风格,局部混用。

代码或图示

// 注解:业务组件
@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。

原理流程

  1. 调用 bean<Type>() 注册类型定义。
  2. 或 bean { FactoryClass(ref(), ref()) },lambda 返回实例。
  3. ref<T>() 标记构造/方法参数依赖。
  4. 容器刷新时解析 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 等作用域;作用域选择影响实例数量与销毁管理。

原理流程

  1. bean() 注册定义并指定作用域。
  2. 单例:容器创建一份并缓存。
  3. 原型:每次获取新建。
  4. 其他作用域(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 定义写在块内前后位置都可以,拓扑排序决定创建顺序。

原理流程

  1. 工厂 lambda 内写 ref() 占位。
  2. 定义记录依赖类型。
  3. 容器刷新按依赖图排序创建。
  4. 把解析实例传入工厂。

代码或图示

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 走同一套回调机制。

原理流程

  1. DSL 工厂创建实例。
  2. 容器执行初始化回调。
  3. 请求期正常使用。
  4. 关闭阶段执行销毁回调释放资源。

代码或图示

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 类。

原理流程

  1. DSL 块读取环境/已有定义。
  2. 条件谓词求值为真才调用 bean()。
  3. 不满足则跳过注册。
  4. 刷新阶段只创建保留的定义。

代码或图示

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 或自动配置提供的注册器。

原理流程

  1. 容器创建并注册初始化器。
  2. 刷新前执行函数式配置块。
  3. 定义写入 BeanDefinitionRegistry。
  4. 进入常规刷新与实例化。

代码或图示

// 入口示意:在应用初始化阶段执行 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。块内可访问环境、注册表与已有定义,块外不应假设容器已就绪。上下文对象把注册能力收敛到配置阶段。

原理流程

  1. 容器构造 DSL 接收者。
  2. 配置块在接收者作用域内执行。
  3. 通过接收者读 Environment、写定义。
  4. 块结束后接收者能力不再可用。

代码或图示

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 集合,类型转换在需要时手动完成。

原理流程

  1. 接收者暴露 Environment。
  2. 读取属性键、激活 Profile。
  3. 按条件决定是否注册定义。
  4. 属性值在后续 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 配置可拆成多个函数,按模块职责分段。汇总入口把各段应用到同一注册表,段之间通过容器类型依赖解耦,而不是在代码里互相持有的中间变量。

原理流程

  1. 模块 A 定义 configureA(ctx) 注册自身 Bean。
  2. 模块 B 定义 configureB(ctx)。
  3. 主入口依次应用各段。
  4. 容器统一按依赖图解析。

代码或图示

fun BeanDefinitionRegistry.orderModule() { /* 注册订单相关 */ }
fun BeanDefinitionRegistry.payModule() { /* 注册支付相关 */ }

常见误区

  • 段之间共享局部变量传递实例:绕过容器注册,生命周期失控。
  • 模块 DSL 互相依赖对方段先执行:应通过类型依赖让容器排序。

追问

  • 库模块如何暴露 DSL?答:导出配置函数或自动配置类,集成方选择挂载方式。
  • 多段 DSL 与多配置类顺序等价吗?答:定义注册时机都在刷新前,实例化顺序由依赖图决定。

06.8.2.2-012 DSL 配置与 @Configuration 共存时优先级如何?

一句话结论

两者写入同一注册表,定义按名称与类型参与合并;同名覆盖受容器覆盖策略控制,同类型多候选在注入点按限定符解析,不存在「DSL 优先于注解」的固定优先级。

概念解释

共存时关键是避免重复定义与候选歧义。注册来源不同但机制相同:都是 BeanDefinition。排查重复时区分定义来自 DSL 块还是扫描配置类。

原理流程

  1. 注解扫描与 DSL 块分别写定义。
  2. 合并注册表,检查同名与同类型。
  3. 覆盖策略决定同名取舍。
  4. 注入点解析候选。

代码或图示

// 注解侧:@Configuration 注册 Client
// DSL 侧:beans { bean<Client>() }
// 合并后确认是否重复定义或需要限定符区分

常见误区

  • 以为 DSL 定义一定覆盖注解定义:覆盖由容器策略与注册顺序决定。
  • 同类型两套实现不加区分:注入点歧义报错。

追问

  • 如何定位某个 Bean 的注册来源?答:查看定义来源描述或启动调试日志,通用排查见 06.2。
  • 允许覆盖开关作用于 DSL 定义吗?答:作用于整个注册表,通用覆盖规则见 06.2。

06.8.2.2-013 DSL 中如何自定义 Bean 名称?

一句话结论

bean() 可指定名称参数,未指定时按类型/工厂推导名称;关键集成点需要固定名称时显式命名,避免类重命名导致名称漂移。

概念解释

Bean 名称是容器内引用键。DSL 默认推导规则与注解配置不同,需要按名称注入或对接既有契约时显式传入名称参数。

原理流程

  1. 调用 bean(name) { ... } 指定名称。
  2. 注册表以该名称保存定义。
  3. 按名称引用时使用该键。
  4. 未指定则按 DSL 推导规则生成默认名。

代码或图示

beans {
    bean("primarySender") { SmsSender() }
}

常见误区

  • 依赖默认推导名做按名称注入:类型调整后默认名变化,引用断裂。
  • 自定义名与既有定义冲突:注册表出现同名覆盖。

追问

  • 显式名与限定符如何配合?答:按名称解析时使用显式名;通用限定符机制见 06.2。
  • 名称大小写约定?答:保持与项目既有 Bean 命名一致。

06.8.2.2-014 DSL 中定义原型作用域要注意什么?

一句话结论

原型定义每次获取新建实例,不由容器缓存销毁;DSL 声明原型作用域后,单例持有原型引用只会得到一份固定实例,需要每次新实例时通过 ObjectProvider 获取。

概念解释

原型作用域的创建时机在获取点。DSL 注册时声明作用域即可,但注入方式决定是否每次新建:直接构造器注入只注入一次,ObjectProvider 才能每次取新实例。

原理流程

  1. DSL 标记定义为 prototype。
  2. 直接注入:容器创建一份给单例持有。
  3. ObjectProvider.getObject():每次调用新建。
  4. 原型实例销毁由使用方负责。

代码或图示

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 上下文更快启动。

原理流程

  1. 创建 GenericApplicationContext 并执行 DSL。
  2. refresh 后按类型获取 Bean。
  3. 断言非空、类型与关键行为。
  4. 关闭上下文释放资源。

代码或图示

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 表达路径、方法、谓词与处理器,适合显式路由编排。

原理流程

  1. router { } 块内声明路由规则。
  2. 每条规则绑定 HTTP 方法、路径谓词与处理器函数。
  3. 生成 RouterFunction Bean 注册到容器。
  4. 请求进入路由函数按顺序匹配。

代码或图示

@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。

原理流程

  1. coRouter { } 注册 suspend 处理器。
  2. 请求进入时框架启动协程执行处理器。
  3. 挂起函数结果由桥接层转换为响应式输出。
  4. 异常与取消按协程语义传播。

代码或图示

@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。

原理流程

  1. 块内声明各方法路由。
  2. 每条规则生成方法 + 路径谓词组合。
  3. 路由函数按顺序尝试匹配。
  4. 首个匹配规则的处理器处理请求。

代码或图示

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 支持路径作用域嵌套,块路径与子规则路径拼接。分组内还可统一挂载过滤器、谓词,结构与资源目录对应。

原理流程

  1. 外层 path("/api") 定义前缀。
  2. 内层规则声明相对路径。
  3. 最终路径为前缀拼接结果。
  4. 嵌套作用域内可共享谓词与过滤器。

代码或图示

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。

原理流程

  1. 规则附加 accept/contentType 谓词。
  2. 请求头与谓词媒体类型比较。
  3. 全部谓词满足才命中处理器。
  4. 不匹配继续尝试下一条规则。

代码或图示

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 或按约定处理。

原理流程

  1. 处理器方法接收请求对象。
  2. pathVariable 取路径段,param 取查询参数。
  3. 类型转换为业务类型。
  4. 取不到值走参数校验或错误响应。

代码或图示

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 组合,规则间按顺序短路匹配。复杂匹配条件拆成多条规则或组合谓词,避免在一条规则里堆过多条件。

原理流程

  1. 规则挂载若干谓词。
  2. 请求依次通过谓词检查。
  3. 全部满足进入处理器。
  4. 任一不满足尝试下一条规则。

代码或图示

router {
    GET("/search", request.param("q").isPresent, handler::search)
}

常见误区

  • 把规则间关系当成 OR 谓词:顺序匹配,前置宽泛规则优先命中。
  • 谓词里访问请求体做匹配:体只能消费一次,谓词阶段不宜读取。

追问

  • 谓词能读 Header/Cookie 吗?答:可以按请求头构造自定义谓词。
  • 谓词求值有性能要求吗?答:路由匹配在请求路径上执行,谓词保持轻量,重逻辑放处理器。

06.8.2.2-023 DSL 路由中如何挂过滤器?

一句话结论

路由块内可用 filter 声明处理器前/后拦截逻辑,作用于分组或单条规则;过滤器在谓词匹配后、处理器执行前后包裹调用链。

概念解释

函数式路由过滤器对应 Web 过滤器链的局部版本,可做日志、鉴权、请求改写。嵌套作用域内的过滤器只影响该分组规则。

原理流程

  1. 规则命中后进入过滤器链。
  2. 过滤器前置逻辑执行。
  3. 调用处理器。
  4. 过滤器后置逻辑处理响应。

代码或图示

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 风格异常,可在处理器内显式构建错误响应。

概念解释

错误处理分两层:处理器内显式返回错误状态;未捕获异常交给框架映射。函数式风格更倾向显式返回响应对象,异常处理器作为兜底。

原理流程

  1. 处理器执行业务逻辑。
  2. 可预期错误直接构建错误响应返回。
  3. 未捕获异常进入异常处理链。
  4. 映射为标准错误响应与状态码。

代码或图示

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。同一应用可按模块选择,但同一路径不应双重映射。

原理流程

  1. 容器同时注册控制器映射与 RouterFunction。
  2. 请求到达后分别进入对应映射体系。
  3. 命中哪套由路径与规则决定。
  4. 消息转换与响应写出复用同一套基础设施。

代码或图示

// 注解侧
@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。

原理流程

  1. 定义 suspend 处理器函数,接收请求。
  2. 解析参数,调用服务层挂起方法。
  3. 构造响应对象返回。
  4. 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。

原理流程

  1. 按结果选状态码构造响应 builder。
  2. 设置头、内容类型。
  3. 写入响应体(对象、流式发布者)。
  4. 返回响应对象交给框架写出。

代码或图示

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 返回,容器将其纳入路由映射表。

原理流程

  1. @Bean 方法返回 router DSL 结果。
  2. 容器识别 RouterFunction 类型。
  3. 注册到函数式路由映射。
  4. 请求匹配时调用对应处理器。

代码或图示

@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 资源配置中声明。

原理流程

  1. 配置资源处理器路径与位置。
  2. 请求静态路径由资源处理器匹配。
  3. 找到资源文件写出。
  4. 未命中走默认静态映射或 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 按声明顺序短路匹配,宽泛规则应后置;路径冲突时先核对规则顺序与谓词宽度,必要时收窄谓词或拆分路径,保证每条规则可被命中。

概念解释

规则匹配是有序列表遍历:第一个谓词全满足的规则接管请求。把 /** 或宽泛路径写在前面会吞掉后续精确规则。调试时按顺序检查谓词宽度。

原理流程

  1. 列出全部路由规则与谓词。
  2. 核对路径重叠关系。
  3. 精确规则前置,宽泛兜底规则后置。
  4. 冲突路径收窄谓词或拆分资源前缀。

代码或图示

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 之间转换,背压与线程调度仍由响应式运行时约束。

原理流程

  1. WebFlux 接收请求,进入响应式处理链。
  2. suspend 处理器在桥接层启动协程。
  3. 挂起点让出线程,恢复时继续执行。
  4. 结果桥接为响应式序列写出。

代码或图示

@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 是协程单值挂起函数。桥接扩展把发布者订阅包装为挂起等待,或把协程结果包装为发布者。反复转换增加上下文与异常处理复杂度。

原理流程

  1. Reactor 侧:awaitSingle/awaitFirst 挂起等待首个值。
  2. 协程侧:mono { } 调用 suspend 函数并包装为 Mono。
  3. 流:Flow 与 Flux 互相转换并传播背压。
  4. 异常与取消沿桥接通道传递。

代码或图示

// 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 等于把异步流程拉回阻塞等待。

原理流程

  1. 请求线程进入处理器。
  2. runBlocking 阻塞该线程直到内部协程结束。
  3. 期间线程不能处理其他请求。
  4. 高并发下线程被占满,吞吐下降。

代码或图示

// 错误:在 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 固定。

原理流程

  1. 请求到达,框架创建协程上下文。
  2. suspend 处理器在该上下文执行。
  3. 阻塞调用经 withContext 切到指定调度器。
  4. 恢复后回到调用点上下文继续。

代码或图示

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 浪费线程。

原理流程

  1. 判断任务是等待 IO 还是消耗 CPU。
  2. IO:withContext(Dispatchers.IO) 包裹阻塞调用。
  3. 计算:withContext(Dispatchers.Default)。
  4. 子协程继承父上下文,除非显式切换。

代码或图示

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。

原理流程

  1. 请求入口线程把上下文写入 ThreadLocal。
  2. 协程挂起(等待远程调用/DB)。
  3. 恢复时调度到其他线程。
  4. 新线程 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 读取并回填。

原理流程

  1. 入口把 traceId 写入协程上下文元素。
  2. 协程执行前后在调度点同步 MDC。
  3. 跨线程恢复时从上下文元素恢复 MDC。
  4. 协程结束清理线程 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等放进去,链路任意挂起点都能读取。

原理流程

  1. 定义上下文元素与对应 Key。
  2. 入口启动协程时传入元素。
  3. 子协程继承上下文,元素可达。
  4. 处理逻辑从 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,协程侧通过对应元素读取。

原理流程

  1. 响应式链上游写入 Context 条目。
  2. 桥接层启动协程时映射到协程上下文元素。
  3. suspend 处理器读取元素值。
  4. 反向新增上下文需走响应式上下文写入口。

代码或图示

// 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 变体避免抛空体异常。

原理流程

  1. 处理器调用 awaitBody 挂起等待体接收完成。
  2. 消息转换器反序列化为目标类型。
  3. 得到对象继续业务处理。
  4. 空体用 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 选错会在元素数量假设上出错。

原理流程

  1. 判断 Reactor 类型:Mono 单值或 Flux 多元素。
  2. 单值调用 await 系列挂起取结果。
  3. 多元素 asFlow 转协程流处理。
  4. 出口按需包装回 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 错误信号,再进入框架异常处理链。业务可预期错误应在局部捕获转换。

原理流程

  1. 协程内抛异常。
  2. 沿作用域层级向上传播,相关子协程被取消。
  3. 桥接层把异常转为错误信号。
  4. 框架异常处理器映射为错误响应。

代码或图示

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。

概念解释

协程取消是协作式的:信号到达后,挂起点响应取消;不挂起的紧密循环不会自动停止。请求取消后应释放外部资源(连接、临时文件、下游调用),避免泄漏。

原理流程

  1. 客户端断开或框架超时。
  2. 处理链向下传播取消信号。
  3. 协程在挂起点抛 CancellationException。
  4. 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,用于限制单个下游调用或聚合流程;超时预算应按整体请求时限拆分,避免子任务超时吃掉全部预算。

概念解释

协程超时是结构化取消:到期取消内部协程并清理。可预期超时在局部捕获转换为降级响应;超时异常属于取消类异常,不要与普通业务异常混淆处理。

原理流程

  1. 进入 withTimeout 块启动限时协程。
  2. 业务挂起调用在预算内完成则返回结果。
  3. 到期未完成,取消内部协程并抛超时异常。
  4. 局部捕获后走降级或错误响应。

代码或图示

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 任务受父协程管理。任务间无依赖才并行;任一失败默认取消其余任务并向上传播异常。需要容错的任务单独捕获或降级。

原理流程

  1. 创建子任务 Deferred 列表,各自 async 调用下游。
  2. 子协程并发执行。
  3. awaitAll 收集全部结果。
  4. 异常按结构化取消规则处理。

代码或图示

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,这里只关注协程下的边界风险。

原理流程

  1. 进入事务增强的 suspend 方法,开启事务获取连接。
  2. 方法内挂起调用期间事务上下文保持。
  3. 方法正常返回提交,异常回滚。
  4. 挂起切换线程时事务资源需能跟随上下文。

代码或图示

@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 方法。代理生成条件与普通服务一致:类/方法可开放;但事务资源在协程挂起期间的持有方式,依赖响应式/阻塞事务实现,版本支持需核对。

原理流程

  1. 容器为服务生成事务代理。
  2. 外部调用经过代理进入事务方法。
  3. 事务管理器开启事务,执行 suspend 方法。
  4. 返回提交或异常回滚。

代码或图示

@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 关闭。

原理流程

  1. Bean 构造时创建 CoroutineScope(SupervisorJob() + dispatcher)。
  2. 后台任务在该作用域内 launch。
  3. 任务异常被 SupervisorJob 隔离,不连带取消其他任务。
  4. @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 接口。

原理流程

  1. 识别调用是阻塞 JDBC/同步 HTTP/文件 IO。
  2. withContext(IO) 包裹该调用。
  3. 阻塞在线程池执行,等待期间不占用原线程。
  4. 结果返回原协程上下文。

代码或图示

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,这里只对照协程适配。

原理流程

  1. MVC:请求分配线程 → 阻塞等待 → 线程释放回池。
  2. WebFlux:请求注册回调 → 事件循环处理就绪事件。
  3. 协程挂起对应非阻塞等待,恢复时回调调度。
  4. 阻塞代码进 WebFlux 会卡住事件循环。

代码或图示

MVC:线程池 ≈ 并发请求数;IO 等待期间线程被占用
WebFlux:事件循环少量线程;等待回调,阻塞调用必须隔离

常见误区

  • 把 MVC 的线程池思维搬到 WebFlux:加大事件循环线程数解决不了阻塞调用问题。
  • 在 WebFlux 里混用阻塞 JDBC:事件循环被阻塞,吞吐崩塌。

追问

  • 协程在两种模型上都跑吗?答:MVC 支持 suspend 控制器但底层仍是 Servlet 线程;WebFlux 才是完整非阻塞链路。
  • 如何判断当前是否阻塞线程?答:看线程名与阻塞栈,事件循环线程名通常含 reactor-http。

06.8.2.2-051 WebFlux 链路中调用阻塞 JDBC 有什么风险?

一句话结论

阻塞 JDBC 调用会让当前事件循环线程卡在等待数据库响应,期间无法处理其他请求;高并发下事件循环线程被占满,整体响应式链路退化甚至雪崩,必须隔离到阻塞线程池或换响应式驱动。

概念解释

WebFlux 事件循环线程数量少,职责是调度非阻塞事件。阻塞 DB 调用不释放线程,等待期间事件循环空置。隔离方案:阻塞仓库放独立线程池包装,或使用响应式关系驱动与响应式事务。

原理流程

  1. 事件循环线程执行到阻塞 JDBC。
  2. 线程阻塞等待数据库返回。
  3. 期间不能调度其他就绪请求。
  4. 并发升高后事件循环耗尽,延迟与错误上升。

代码或图示

// 不推荐: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 串联。

原理流程

  1. 开发环境开启协程调试代理/模式。
  2. 异常发生时保留协程链堆栈。
  3. 生产环境通过请求上下文标识关联日志。
  4. 按挂起点与下游调用逐层定位。

代码或图示

// 调试入口:JVM 启动参数附加 kotlinx-coroutines 调试 agent(具体参数以库文档为准,待确认)
// 排查:traceId -> 入口协程 -> 挂起点 -> 下游错误栈段

常见误区

  • 生产开启完整调试模式:有性能开销,按环境选择。
  • 堆栈缺帧就判断代码未执行:可能是状态机裁剪,结合日志确认。

追问

  • 协程名如何设置便于日志识别?答:CoroutineName 元素加入上下文,日志打印名称与线程。
  • 异常链在哪查看?答:协程异常保留根因,桥接为响应式错误信号后由框架记录。

06.8.2.2-053 StateFlow/Flow 与响应式返回类型如何选择?

一句话结论

Flow 是协程冷流,适合在 WebFlux 出口表示流式结果;StateFlow 是持当前值的热状态流,适合组件内状态订阅,不直接作为单次 HTTP 响应模型。按数据流是单次结果、冷流还是状态订阅选型。

概念解释

Flow 与 Reactor Flux 概念对应:冷流每次订阅执行发射;StateFlow 持有最新状态,多订阅者共享当前值。HTTP 请求/响应是订阅驱动的冷流场景,组件内状态同步才用 StateFlow。

原理流程

  1. 单次值:suspend 返回对象或 Mono。
  2. 流式序列:Flow/Flux 随订阅发射元素。
  3. 组件内可变状态:StateFlow 维护当前值并广播更新。
  4. 出口按协议映射为响应式流。

代码或图示

// 流式出口
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 的挂起发射点配合背压,下游慢时暂停生产。

原理流程

  1. 控制器返回 Flow。
  2. 桥接层订阅 Flow。
  3. 元素到达即序列化写入响应。
  4. 取消/完成时终止 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 类型对接的边界出现。

原理流程

  1. 引入 coroutines-reactor 依赖。
  2. 边界接收 Mono/Flux 时用扩展挂起转换。
  3. 出口需要发布者时用包装扩展。
  4. 内部服务层保持 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 在下游未取走元素时挂起,背压信号映射到挂起/恢复。桥接层保证两端节奏一致。

原理流程

  1. 下游订阅并请求一定数量元素。
  2. 上游按需求生产,Flow emit 受背压约束。
  3. 下游处理慢,emit 挂起暂停生产。
  4. 需求恢复后继续发射。

代码或图示

fun feed(): Flow<Row> = flow {
    rows.forEach { emit(it) } // 背压时 emit 挂起
}

常见误区

  • 以为协程模型不需要背压:Flow 仍需配合下游速率,缓冲策略选择不当会堆积内存。
  • 用无限缓冲强行跟上快速上游:内存上涨风险。

追问

  • 背压溢出错策略有哪些?答:缓冲、最新值替换、丢弃,见溢出策略条目。
  • 阻塞迭代的源如何接入 Flow?答:用 flow { } 包装并注意取消与调度。

06.8.2.2-057 响应式链路中调度器选择如何避免阻塞?

一句话结论

事件循环线程只做非阻塞调度,阻塞操作必须切到隔离调度器/线程池;CPU 密集计算避免长时间占用事件循环,按操作类型分配 Default/IO 池,保持事件循环快速回调。

概念解释

调度器错配是响应式服务主要性能事故来源。事件循环被阻塞后所有请求排队;隔离调度池承载阻塞与重计算,事件循环只编排回调。协程 withContext 是切池的显式手段。

原理流程

  1. 事件循环接收请求并编排非阻塞链。
  2. 阻塞/重计算段切到独立池执行。
  3. 完成回调恢复事件循环继续。
  4. 监控事件循环阻塞时长与池队列。

代码或图示

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 占用期间,就绪事件无法被处理,连接延迟堆积。协程挂起是非阻塞等待,与阻塞线程等待性质完全不同。

原理流程

  1. 事件循环线程处理某请求。
  2. 线程同步阻塞等待 DB/HTTP 响应。
  3. 同循环其他连接事件无法调度。
  4. 并发上升导致延迟放大。

代码或图示

// 禁止:事件循环线程内
blockingJdbc.query(...)
Thread.sleep(...)
synchronized (lock) { blockingWork() }

常见误区

  • 把「协程挂起」当成「阻塞线程」:挂起释放线程,阻塞不释放。
  • 用同步客户端库嵌在响应式链中:隐式阻塞事件循环。

追问

  • 怎么识别事件循环线程?答:线程名含 reactor-http-nio,栈上出现阻塞调用即可定位。
  • 必须用同步库时怎么办?答:隔离到独立线程池并限制并发,避免回占事件循环。

06.8.2.2-059 响应式链路中 ThreadLocal 不可靠的根因是什么?

一句话结论

响应式链路上同一请求的不同片段可能在不同线程执行,ThreadLocal 绑定线程而不绑定请求,跨线程片段读不到入口线程设置的值;请求上下文必须走 Reactor Context 或协程上下文传播。

概念解释

响应式调度把回调提交到不同线程,线程池复用也让 ThreadLocal 残留风险更高。请求级数据(用户、租户、traceId)属于订阅上下文,不是线程局部变量。

原理流程

  1. 入口线程设置 ThreadLocal。
  2. 某操作回调切换到池线程。
  3. 新线程 ThreadLocal 为空。
  4. 读不到入口数据,应改用响应式/协程上下文。

代码或图示

// 不可靠:依赖 ThreadLocal 传用户
val currentUser = ThreadLocal<User>()

// 可靠:上下文随订阅/协程传播

常见误区

  • 框架文档里的安全上下文在响应式下也用 ThreadLocal 取:响应式安全上下文有专门读取方式,见 Security 条目。
  • 线程池提交任务时复制 ThreadLocal:需显式传递,默认不复制。

追问

  • 哪些框架已经提供响应式上下文传播?答:安全上下文、链路追踪有适配桥接,通用机制见 06.2/08 分册。
  • 自定义请求数据放哪里?答:Reactor Context 或 CoroutineContext 元素。

06.8.2.2-060 协程处理器中如何获取当前请求交换对象?

一句话结论

函数式处理器从方法参数接收 ServerRequest;注解式 suspend 控制器按需注入 ServerWebExchange 或从上下文取请求信息,避免在服务层静态全局获取请求对象。

概念解释

请求对象绑定在当前交换上下文,协程跨线程后不能靠 ThreadLocal 取。显式参数传递最直接;服务层需要的请求信息应提取为参数值传入,而让服务层不依赖 Web 对象。

原理流程

  1. 入口处理器/控制器拿到请求对象。
  2. 提取路径、头、体等所需信息。
  3. 以普通参数传入服务层。
  4. 服务层不持有 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 阻塞。

概念解释

部分场景需要先注册回调、等待外部信号再返回响应。协程用挂起等待替代回调嵌套,等待期间释放线程;延迟时长由超时与取消约束,避免请求悬挂。

原理流程

  1. 处理器进入挂起等待信号/交换就绪。
  2. 等待期间线程释放。
  3. 信号到达恢复协程,构造响应。
  4. 超时/取消按规则退出。

代码或图示

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 协程终止并清理订阅源。

原理流程

  1. 端点返回 Flow,produces 设为 SSE 类型。
  2. 框架订阅 Flow,逐元素写事件流。
  3. 事件源更新推动 Flow 发射。
  4. 断开订阅取消 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 中是数据片段流,处理器订阅片段写入目标存储。协程场景通过流收集或逐块处理,内存占用与文件大小解耦;完成后返回结果响应。

原理流程

  1. 接收上传片段流。
  2. 逐块写入文件/对象存储。
  3. 背压调节读取速度。
  4. 流完成返回结果,异常/取消清理临时文件。

代码或图示

suspend fun upload(exchange: ServerWebExchange): ServerResponse {
    exchange.multipartData().awaitSingle()
    // 按片段流式落盘;具体 multipart 协程 API 以 WebFlux Kotlin 文档为准(待确认)
}

常见误区

  • 一次性收集全部字节到内存:大文件导致内存溢出。
  • 取消/失败时不删临时文件:磁盘残留。

追问

  • 上传大小限制在哪配?答:WebFlux multipart 大小限制与临时目录配置,通用 Web 配置见 06.2。
  • 大文件落盘后如何校验?答:流式计算哈希,避免二次全量读取。

06.8.2.2-064 流背压溢出策略:缓冲、最新值、丢弃如何选?

一句话结论

生产快消费慢时选择溢出策略:缓冲保数据但占内存,最新值替换只保留最新状态,丢弃旧元素适合可刷新事件;按数据是否允许丢失与内存预算选择。

概念解释

背压溢出发生在上游速率超过下游处理能力。策略定义超出需求的元素如何处置:无界/有界缓冲、保留最新、丢弃头尾。事件可丢选丢弃/最新,订单/日志不可丢选有界缓冲并监控积压。

原理流程

  1. 下游需求低于上游生产。
  2. 溢出元素进入策略处理。
  3. 缓冲队列积压或替换/丢弃。
  4. 监控队列长度与丢弃计数。

代码或图示

// 思路:Flow/Flux 上配置缓冲容量与溢出策略
// buffer(capacity, BufferOverflow.DROP_OLDEST) 等(API 以所用流库为准)

常见误区

  • 无界缓冲应对突发流量:内存无限增长风险。
  • 关键数据用丢弃策略:丢失后无法补偿。

追问

  • 积压指标看什么?答:队列长度、丢弃计数、上下游速率差;通用可观测性见 08 分册。
  • 背压恢复后缓冲如何排空?答:下游提速后队列按需求消费,策略保持配置不变。

06.8.2.2-065 冷流与热流在控制器返回中如何区分?

一句话结论

冷流每次订阅重新执行生产逻辑(查询、扫描),热流订阅共享已有数据源(事件总线、状态);控制器返回前确认流类型,避免每次订阅重复重算或错误共享可变状态。

概念解释

Flow 默认冷流:订阅才执行流块。SharedFlow/StateFlow 是热流:数据源独立于订阅存在。HTTP 请求通常订阅冷流;多连接广播用热流。混用会导致重复生产或状态串扰。

原理流程

  1. 冷流:订阅 → 执行流块 → 发射 → 取消结束。
  2. 热流:源持续运行,订阅者接当前/后续值。
  3. 出口按协议订阅。
  4. 取消只影响冷流执行或热流订阅。

代码或图示

// 冷流:每次订阅执行查询
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 不适合直接进入响应式链。

原理流程

  1. 构建 WebClient 实例与连接池配置。
  2. 请求链式构造 URI/头/体。
  3. 协程扩展挂起等待响应体或交换。
  4. 错误与超时按响应式/协程语义处理。

代码或图示

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,控制临界区并发;隔离池也能从线程数层面兜底。两种方式按场景组合。

原理流程

  1. 创建许可数有限的信号量。
  2. 每个任务执行前获取许可。
  3. 任务结束释放许可。
  4. 超额任务排队等待,不占用下游资源。

代码或图示

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,降级结果要提前定义且不污染主链路上下文。

概念解释

高可用编排包含超时预算、错误分类、降级回退。超时避免悬挂连接,降级保证部分可用。可预期错误在局部捕获转换,未处理错误交给全局异常处理器。

原理流程

  1. 调用下游设置超时。
  2. 成功返回主结果。
  3. 超时/业务错误捕获,构造降级值。
  4. 降级不可用时返回明确错误响应。

代码或图示

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,这里关注协程/响应式链路传递。

原理流程

  1. 协程/流抛异常转为错误信号。
  2. 异常处理器按类型匹配映射规则。
  3. 构造错误响应与状态码。
  4. 细节记录服务端日志。

代码或图示

// 领域异常 -> 404;未分类 -> 500(处理器实现见项目全局异常配置)
class NotFoundException(msg: String) : RuntimeException(msg)

常见误区

  • 所有异常都返回 500:客户端无法区分可重试与参数错误。
  • 响应体直接带堆栈/SQL 细节:安全与信息泄漏风险。

追问

  • 流中途错误如何响应?答:已发送部分元素后错误会中断流,按协议关闭并记录错误。
  • 异常处理器能拿到协程上下文吗?答:经桥接传递的上下文元素可补充日志与错误码。

06.8.2.2-070 压测协程 Web 服务应关注哪些指标?

一句话结论

关注请求延迟分布、吞吐、事件循环/工作线程占用、下游连接池与队列积压、取消与错误率;协程服务重点看是否有阻塞操作泄漏到事件循环,以及背压积压是否转化为内存增长。

概念解释

压测不只看 QPS:线程占用反映阻塞泄漏,队列长度反映背压积压,连接池等待反映下游瓶颈。协程调度切换下,单请求线程停留时间与阻塞栈是排查重点。

原理流程

  1. 梯度加压,记录延迟分位与错误率。
  2. 采集线程池/事件循环指标。
  3. 检查流队列、连接池等待与内存趋势。
  4. 定位阻塞点、背压瓶颈与下游依赖。

代码或图示

// 指标清单: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 服务层通常仍是阻塞仓库,非阻塞收益有限。

原理流程

  1. 请求进入 MVC 控制器。
  2. suspend 方法启动协程并挂起等待。
  3. Servlet 异步上下文释放原线程。
  4. 协程完成后写回响应,恢复异步请求。

代码或图示

@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 异步超时与错误传播。

原理流程

  1. 框架把 suspend 处理器包装为异步任务。
  2. 协程执行,完成回调设置 DeferredResult 结果。
  3. 异常回调设置错误结果。
  4. 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,控制器与服务层不默认使用。

原理流程

  1. 控制器若 runBlocking,当前线程阻塞等待内部协程。
  2. 线程不释放,Servlet 异步桥接被绕过。
  3. 协程调度优势没有体现。
  4. 正确写法是 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 的线程池仍是请求并发的主要承接资源。

原理流程

  1. 请求线程启动异步协程任务。
  2. 挂起点释放请求线程。
  3. 恢复时由异步执行器/调度器安排线程。
  4. 阻塞任务在隔离池执行。

代码或图示

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 处理器的支持程度随框架版本演进,选型前核对对应运行时文档。

原理流程

  1. 确认应用运行时是 MVC 还是 WebFlux。
  2. 查框架文档对函数式路由与协程处理器的支持矩阵。
  3. 选用对应 DSL 与处理器签名。
  4. 测试异步桥接与错误传播行为。

代码或图示

// 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 同理,跨运行时混用容易产生意外阻塞或订阅问题。

原理流程

  1. 控制器声明返回 Mono/Flux/Flow。
  2. MVC 适配器判断是否支持该返回类型。
  3. 支持则桥接订阅写出,不支持按类型解析失败。
  4. 流语义在 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) 承接阻塞实现;上层看不到同步阻塞细节。

原理流程

  1. Web 控制器 suspend 签名。
  2. 服务接口定义 suspend 方法。
  3. 实现内部切到 IO 池调用阻塞仓库。
  4. 返回结果延续协程链路。

代码或图示

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,事务连接绑定在执行线程。协程切线程时事务上下文能否跟随,取决于事务管理器实现;稳妥做法是事务方法内只做数据库操作,远程/异步调用放到事务外。

原理流程

  1. 事务代理进入方法开启事务。
  2. 阻塞仓库操作使用事务连接。
  3. 挂起/切线程期间上下文传递需验证。
  4. 方法返回提交,异常回滚。

代码或图示

@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 放入上下文元素,供协程读取;拦截器本身不感知协程内部调度。

原理流程

  1. 拦截器预处理读取请求头/属性。
  2. 提取数据放入请求上下文或协程上下文元素。
  3. 处理器协程内读取元素。
  4. 拦截器后置处理响应。

代码或图示

// 拦截器:解析身份并写入请求属性;协程侧从上下文/参数读取
// 不要假设拦截器线程 == 协程恢复线程

常见误区

  • 拦截器把身份放 ThreadLocal,协程跨线程读取:丢失。
  • 在拦截器里启动协程做业务逻辑:职责越界,协程应归属处理器/服务。

追问

  • WebFlux 过滤器与 MVC 拦截器差异?答:运行时链路不同,通用过滤器原理见 06.2。
  • 上下文元素从拦截器到协程怎么传?答:经框架请求上下文桥接或在入口处理器构造元素传入。

06.8.2.2-080 如何选型:MVC + 协程 还是 WebFlux?

一句话结论

以阻塞数据访问与团队熟悉度为主、无强流式/高并发非阻塞需求时选 MVC + 协程;需要完整非阻塞流式、背压与响应式生态时选 WebFlux + 协程,不要为了「协程」名义上 WebFlux 却保留阻塞仓库。

概念解释

选型核心是运行时与数据访问模型是否匹配。MVC 成熟、阻塞栈简单;WebFlux 吞吐与流式能力强,但要求链路全非阻塞。协程在两者都可作为写法层,不能改变运行时线程模型本质。

原理流程

  1. 评估数据访问:阻塞 JDBC 还是响应式驱动。
  2. 评估需求:普通 CRUD 还是 SSE/流式/高并发。
  3. 评估团队响应式经验与遗留系统兼容。
  4. 选定运行时,服务层按对应模型设计。

代码或图示

阻塞栈 + 常规业务 -> 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 协程支持模块提供,依赖清单按运行时确定。

原理流程

  1. 按运行时选 webmvc 或 webflux starter。
  2. 加入 coroutines-core。
  3. 响应式互操作加入 coroutines-reactor。
  4. 版本由 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 发布者、管理回调与异常。桥接扩展封装订阅等待、取消传播、错误转换与上下文映射,边界代码得以用挂起风格书写。

原理流程

  1. Reactor 发布者进入桥接扩展。
  2. 桥接订阅发布者,挂起协程等待信号。
  3. 元素/完成/错误/取消映射到协程语义。
  4. 反向包装协程结果为发布者。

代码或图示

// 桥接能力: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。

原理流程

  1. 处理器调用非空 awaitBody。
  2. 桥接检查请求体是否存在。
  3. 无体抛缺失体异常;有体反序列化。
  4. 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 生命周期管理。

原理流程

  1. 组件启动后台协程但作用域不可控。
  2. Bean 销毁,协程未被取消。
  3. 协程持有组件引用,对象无法回收。
  4. 线程/内存随泄漏累积。

代码或图示

// 错误: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 同步逻辑。框架自带追踪适配通常已处理,自定义上下文需自行桥接。

原理流程

  1. 入口日志确认 traceId 已生成。
  2. 检查上下文写入位置与键名。
  3. 在挂起前后日志打印线程与 MDC。
  4. 定位切换线程后未回填的环节,补上下文传播。

代码或图示

// 排查链:入口 MDC -> 上下文写入 -> 挂起点 -> 恢复线程 MDC -> 下游日志
// 对比线程名变化与 MDC 是否跟随

常见误区

  • 只在入口线程设 MDC 就期望跨线程保留:ThreadLocal 不自动传播。
  • 自定义 traceId 未接入追踪桥接:日志间无法关联。

追问

  • 框架追踪何时自动传播?答:Micrometer/链路追踪适配在响应式与协程链路上的传播机制,通用可观测性见 08 分册。
  • 线程池复用残留 MDC 怎么办?答:任务结束清理 MDC,避免上一请求标识串号。

06.8.2.2-086 IO 调度器线程池大小如何评估与配置?

一句话结论

Dispatchers.IO 默认按上限共享,阻塞任务多时应按下游容量与并发目标评估隔离池;不要无限依赖默认 IO 池,阻塞任务隔离为有界池并设置队列与拒绝策略。

概念解释

IO 池面向阻塞等待,线程数可高于 CPU 核数,但下游连接数、数据库会话与内存是硬上限。默认池参数由协程库设定,自定义池按压测结果调整,配合信号量限制业务并发。

原理流程

  1. 统计阻塞任务类型与单任务占用时长。
  2. 按下游连接配额与目标并发算线程需求。
  3. 创建有界池包装为调度器。
  4. 压测观察队列、等待时间与下游拒绝。

代码或图示

// 自定义有界池思路: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。

原理流程

  1. 测试函数标注测试框架并在 runTest 内执行。
  2. 被测 suspend 函数在测试调度器运行。
  3. delay 虚拟推进,立即到达后续断言。
  4. 断言结果、异常或流序列。

代码或图示

@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 模块要求见容器集成分册。

原理流程

  1. 服务返回领域模型。
  2. 映射为响应 DTO(data class)。
  3. 框架消息转换器序列化。
  4. 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 签名前核对所用小版本的支持范围,不把新版行为假设到旧版本。

原理流程

  1. 确定 Spring Framework 小版本。
  2. 查官方文档协程支持章节。
  3. 核对 MVC/WebFlux 控制器、返回类型与桥接模块。
  4. 测试验证异步行为后上线。

代码或图示

// 核对项: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 版本。三者构成兼容集合,单独升级任一项都可能出现二进制不兼容。

原理流程

  1. 锁定 Kotlin 编译器版本。
  2. 选兼容的 coroutines-core/reactor 版本。
  3. 核对 Spring Boot BOM 管理的 Reactor/Spring 版本。
  4. 编译与集成测试验证后固定版本。

代码或图示

// 兼容链:Kotlin 2.x <-> coroutines 1.x <-> reactor 桥接 <-> Spring 6.x
// 具体版本号以兼容矩阵与 BOM 为准(待确认)

常见误区

  • 协程库单独升最新:可能与编译器或桥接模块不兼容。
  • 不查 BOM 手动锁死 Reactor 版本:与 Spring 依赖冲突。

追问

  • 版本冲突报什么现象?答:类签名/方法缺失、桥接扩展异常,编译或启动期暴露。
  • 升级顺序建议?答:先 Boot/Spring 基线,再编译器,最后协程库对齐矩阵。

06.8.2.2-091 场景:并发聚合三个下游接口如何编排?

一句话结论

三个无依赖下游用 async 并发启动,awaitAll 收集结果;各自设置超时与容错,整体限定并发度,任一下游失败按业务策略决定快速失败还是降级补齐。

概念解释

聚合接口总耗时应接近最慢下游而非三者之和。并发前确认任务无依赖;共享上下文(身份、租户)通过上下文元素传递;下游异常分类处理,避免一个失败拖垮全部可选结果。

原理流程

  1. 读取公共上下文参数。
  2. 三个 async 分别调用下游,内部设超时。
  3. awaitAll 收集成功结果。
  4. 失败项降级补默认值或整体返回错误。

代码或图示

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 单连接持续推送,适合实时通知、进度流;长轮询请求挂起等待结果后返回,客户端再发请求,兼容性好但每次重建请求。协程挂起都能承载两种等待,资源模型不同。

原理流程

  1. 判断事件频率与方向:持续推 vs 单次等。
  2. SSE:端点返回 Flow 事件流,连接保持。
  3. 长轮询:挂起等待条件/超时后返回,客户端重连。
  4. 配合心跳、超时与取消清理资源。

代码或图示

// 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 隔离池;响应式编排只依赖适配器接口。边界并发受信号量保护。

原理流程

  1. 识别阻塞依赖清单。
  2. 定义 suspend 端口接口。
  3. 适配器内部 withContext(隔离池) 调用阻塞实现。
  4. 监控边界,逐步替换阻塞实现。

代码或图示

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,子协程继承元素,跨线程恢复时身份仍可读。

概念解释

身份是请求级上下文数据。响应式安全上下文有专门读取适配;进入协程后转为自定义元素或经桥接映射。传递链路:过滤器/拦截器解析 → 上下文元素 → 服务/下游调用携带。

原理流程

  1. 入口过滤器解析认证主体。
  2. 构造身份元素放入协程/响应式上下文。
  3. 服务层读取元素作为操作人。
  4. 下游调用透传必要身份标识。

代码或图示

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 块保证资源释放。清理动作避免再做不可中断的阻塞操作;需要确认释放结果时记录日志,不阻塞等待已取消请求。

原理流程

  1. 资源在协程开始处获取。
  2. try 执行业务/流发射。
  3. 取消或完成进入 finally。
  4. 释放连接、关闭流、删除临时文件。

代码或图示

suspend fun process(): Result {
    val client = acquire()
    try {
        return client.work()
    } finally {
        client.close()
    }
}

常见误区

  • 资源释放写在成功路径末尾:取消时跳过释放。
  • finally 里再挂起调用未处理取消:清理本身被中断。

追问

  • 外部连接池会兜底回收吗?答:池有回收机制,但主动关闭更可靠;泄漏仍需监控。
  • 流订阅取消清理点在哪?答:Flow 的 finally/onCompletion,订阅结束即触发。

06.8.2.2-096 场景:背压导致内存上涨如何排查?

一句话结论

从流队列与缓冲入手:检查上游生产速率、下游消费速率、溢出策略与缓冲容量;内存上涨伴随队列长度增长,定位积压节点,调整缓冲策略、限流或扩容消费能力。

概念解释

响应式内存上涨通常来自未消费元素堆积。排查链路:堆转储看集合持有 → 定位流缓冲/队列 → 对比上下游速率 → 确认溢出策略是缓冲还是丢弃。协程 Flow 积压体现在发射挂起与未消费元素。

原理流程

  1. 监控堆内存与队列长度趋势。
  2. 堆转储定位积压集合所属流。
  3. 对比生产/消费速率与下游瓶颈。
  4. 调整策略:限上游、扩消费、改丢弃/最新值。

代码或图示

// 排查:内存增长 -> 队列/缓冲持有 -> 上游速率 vs 下游速率 -> 溢出策略
// 处置:背压限流、有界缓冲、丢弃策略、消费扩容

常见误区

  • 直接加堆内存掩盖积压:根因未除,最终仍 OOM。
  • 无界缓冲日志/事件流:突发流量直接撑爆内存。

追问

  • 指标看哪些?答:队列长度、元素待处理数、丢弃计数、GC 频率;通用可观测性见 08 分册。
  • 下游慢是数据库还是外部接口?答:分段压测区分瓶颈节点。

06.8.2.2-097 场景:DSL 路由与注解控制器路径冲突如何处理?

一句话结论

列出两套映射的路径与谓词,取消同路径双重映射;按模块归属保留一套机制,重叠路径收窄谓词或拆分前缀,启动后验证实际匹配规则与顺序。

概念解释

冲突表现为请求落到非预期处理器。排查时分别导出函数式路由表与注解映射表,按方法+路径+谓词比对。混用阶段建议新模块用 DSL、旧模块保留注解,逐步收敛而非并行重叠。

原理流程

  1. 导出两套端点映射清单。
  2. 比对路径、HTTP 方法、内容谓词。
  3. 重叠处确定归属,删除或改路径。
  4. 测试各路径命中预期处理器。

代码或图示

// 核对:RouterFunction 规则表 + @RequestMapping 表
// 同路径只保留一套;前缀隔离两个模块

常见误区

  • 依赖「注解优先/DSL 优先」假设:匹配顺序按框架规则,需实测。
  • 谓词不同但路径相同:仍可能按谓词分发,边界模糊。

追问

  • 如何打印全部映射?答:Actuator 映射端点或启动调试日志,通用端点探测见 06.2。
  • 过渡期两套机制怎么注释?答:路由归属在模块文档标明,避免后人重复添加。

06.8.2.2-098 场景:响应式客户端重试如何编排?

一句话结论

客户端边界对可重试错误设置有限次数与退避间隔,区分可重试错误(超时、5xx、连接失败)与不可重试错误(4xx、业务失败);协程代码用重试包裹挂起调用,重试预算计入整体超时。

概念解释

重试是容错第一道,但盲目重试放大下游压力。错误分类后只对幂等、可重试操作重试;退避避免雪崩,次数与总超时受限。非幂等写操作重试需配合幂等键。

原理流程

  1. 调用下游捕获异常/错误状态。
  2. 判断是否可重试与是否幂等。
  3. 可重试则按退避等待后重试。
  4. 超过次数走降级或错误响应。

代码或图示

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 对象,基础设施负责调度隔离与桥接。每层签名一致使用协程类型,跨边界转换集中在适配器。

原理流程

  1. Web 层:参数解析、响应构建、流式出口。
  2. 服务层:领域编排、事务边界、并发控制。
  3. 基础设施层:阻塞/响应式客户端、仓库、调度隔离。
  4. 上下文元素贯穿各层。

代码或图示

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,再按边界逐模块改造,避免全量切换风险。

原理流程

  1. 评估运行时目标、数据访问阻塞程度与团队经验。
  2. 基础设施层包装阻塞调用为 suspend 端口。
  3. 服务层改 suspend,编排并发与超时。
  4. Web 层迁移控制器/路由,补上下文传播。
  5. 测试协程行为,压测线程与背压指标。

代码或图示

步骤:依赖对齐 -> 端口 suspend 化 -> 服务层编排 -> Web 层迁移
风险点:阻塞残留、上下文丢失、事务长边界、版本不支持、测试缺协程断言

常见误区

  • 一步全量重写:回滚困难,风险集中。
  • 只改语法不改阻塞栈:名义协程,实际仍阻塞。
  • 忽略测试迁移:旧同步测试无法验证 suspend 行为。

追问

  • 哪些模块先试点?答:无强事务、读多写少的新模块或低风险接口。
  • 迁移完成验收看什么?答:事件循环无阻塞、上下文日志完整、压测延迟与吞吐达标、测试覆盖取消与超时分支。

参考来源

待整理清单

  • [ ] 核对当前 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 丢失、事件循环阻塞的真实案例归类