06.8.4.1 Koin 模块、作用域与限定符
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.8 Kotlin 后端 / 06.8.4 Koin 与依赖注入
本节要解决的问题
本篇覆盖 Koin 4.x 的核心模型:module 定义块、single/factory/scoped 等 definition 语义、qualifier 与 named、启动入口、模块拆分与 includes、作用域生命周期、KMP 适配、Koin Annotations 与 KSP,以及懒加载与解析时机。DI 方案对比、测试替换、循环依赖与架构边界在 06.8.4.2 展开,本篇不复述;4.x 相对 3.x 的 API 调整处标注「待确认」并给出验证点。
06.8.4.1-001 Koin 在 DI 生态中的定位是什么?
一句话结论
Koin 是纯 Kotlin 的运行时 DI 框架:用 DSL 声明依赖关系,无注解处理器、无编译期代码生成,容器在运行时按类型解析;轻量、上手快,但编译期安全弱于 Dagger 一类方案。
概念解释
Koin 不生成实现类,也不靠反射注入字段(具体内部机制以当前版本源码为准,待确认),而是在模块 DSL 里用 lambda 描述「怎么构造对象」。解析发生在首次 get/inject 时。它适合 Ktor、KMP 与 Compose 项目,服务端场景同样可用。
原理流程
- 编写 module,用 definition 描述类型与构造方式。
startKoin注册模块并启动容器。- 组件通过
get()或by inject()解析依赖。 - 容器按类型(与 qualifier、scope)查找 definition 并按语义提供实例。
代码或图示
val appModule = module {
single { UserRepository(get()) }
single { UserService(get()) }
}
startKoin { modules(appModule) }
常见误区
- 以为 Koin 像 Dagger 一样编译期校验缺失依赖:缺失依赖在运行时解析才报错。
- 以为 Koin 需要注解处理器:核心 DSL 方案不需要,注解方案另配 KSP。
追问
- Koin 适合什么项目?答:追求轻量、无构建期生成步骤、KMP 共享模块的项目。
- 编译期安全弱在哪?答:依赖缺失、类型不匹配要到运行时或测试阶段暴露,详见 06.8.4.2。
06.8.4.1-002 module { } 定义块里能做什么?
一句话结论
module { } 是依赖声明容器,内部用 single/factory/scoped 等 definition 注册类型与构造 lambda,也可声明绑定、属性引用与模块内组织。
概念解释
模块是一组 definition 的集合,可按功能、层或平台拆分。块内 lambda 接收 ModuleDefinition 接收者,definition 之间通过 get() 引用彼此。模块本身不持有业务状态,状态由 definition 语义决定。
原理流程
- 创建
module { }。 - 在块内注册各 definition。
- definition lambda 内用
get()解析参数。 - 模块整体传入
startKoin或includes。
代码或图示
val repoModule = module {
single { UserRepository(get()) }
}
val serviceModule = module {
single { UserService(get()) }
}
常见误区
- 在 module 块里直接 new 对象并写业务初始化逻辑:构造应放在 definition lambda 内。
- 一个模块堆全部 definition,拆分与复用困难。
追问
- 模块能互相引用吗?答:通过
includes组合,跨模块依赖在解析时按类型查找。 - 模块块内能写条件分支吗?答:可按属性选择 definition,但条件装配能力有限,具体支持见后续题目。
06.8.4.1-003 single definition 的单例语义是什么?
一句话结论
single 在容器生命周期内提供同一实例:definition 首次解析时创建,之后所有解析复用该实例;实例化时机默认是首次解析,线程安全由容器保证。
概念解释
single 对应应用级单例,容器存活期间不重建。构造 lambda 只执行一次。有状态的 single 要注意并发共享;需要每次新建的对象用 factory。容器关闭时 single 实例的释放回调见后续题目。
原理流程
- 注册
single { X(get()) }。 - 首次解析时执行构造 lambda,缓存实例。
- 后续解析返回缓存实例。
- 容器关闭时实例随容器释放。
代码或图示
val module = module {
single { HttpClient() }
single { UserService(get()) }
}
常见误区
- 以为 single 在类加载时就创建:默认懒加载,首次解析才构造。
- 把有状态、非线程安全的对象注册成 single,并发访问出问题。
追问
- single 实例能手动替换吗?答:测试中可覆盖模块定义,见 06.8.4.2;运行时替换属于非常规操作。
- 单例构造抛异常会怎样?答:首次解析时异常向上抛出,容器内不保留半成品实例(具体行为待确认)。
06.8.4.1-004 factory definition 与 single 有什么区别?
一句话结论
factory 每次解析都执行构造 lambda 返回新实例,不缓存;适合无状态或每次调用需要独立实例的对象。
概念解释
factory 不持有实例缓存,解析成本是每次构造。对象内部不应保存跨调用状态。需要复用昂贵资源(客户端、连接池)用 single;需要独立生命周期的短对象用 factory。
原理流程
- 注册
factory { X() }。 - 每次
get<X>()执行构造 lambda。 - 返回新实例,容器不缓存。
- 实例生命周期由使用方持有。
代码或图示
val module = module {
factory { OrderForm() } // 每次请求新表单对象
single { OrderService(get()) }
}
常见误区
- 把重型客户端注册成 factory,每次解析重建资源。
- factory 实例被长期缓存到 single 字段,失去独立实例意义。
追问
- factory 能接收每次不同的参数吗?答:可以配合
parametersOf传构造参数,见后续题目。 - factory 依赖 single 会怎样?答:factory 每次新建,但其依赖的 single 仍复用。
06.8.4.1-005 scoped definition 的生命周期由谁管理?
一句话结论
scoped 实例绑定到一个显式创建的 Koin 作用域内,作用域内复用,作用域关闭后实例释放;生命周期比 single 短、比 factory 长。
概念解释
作用域是容器内的一条实例生命周期线,由 scope ID 标识。scoped definition 在该作用域内首次解析创建并缓存,作用域关闭时调用释放回调并丢弃实例。服务端可把请求、会话等边界映射为作用域;具体 scope API 在 4.x 的名称需对照文档确认(待确认)。
原理流程
- 注册
scoped { X() },通常配合 scope 声明。 - 业务代码创建作用域实例。
- 作用域内解析 scoped 实例并缓存。
- 作用域关闭,实例释放。
代码或图示
val module = module {
scope<RequestScope> {
scoped { RequestContext() }
}
}
常见误区
- 以为 scoped 类似请求级自动作用域:作用域需要显式创建与关闭。
- 作用域关闭后仍持有其中实例引用,状态与资源不释放。
追问
- 作用域怎么创建和关闭?答:通过
getOrCreateScope/scopeOf一类 API,用完调用close();准确 API 名待确认。 - scoped 能依赖 single 吗?答:可以,作用域内实例可引用容器级单例。
06.8.4.1-006 viewModel definition 在服务端有意义吗?
一句话结论
viewModel definition 主要面向 Android/Compose 平台的生命周期组件,服务端 Web 场景一般用 single/scoped;是否在 4.x 服务端模块中保留该定义类型需对照文档确认(待确认)。
概念解释
viewModel 定义与平台生命周期(如 ViewModelStore)绑定,服务端没有对应宿主概念。服务端对象生命周期按请求、会话或应用级划分,对应 scoped 或 single。跨端共享模块里避免只在某平台有意义的定义类型。
原理流程
- 识别组件生命周期归属平台。
- 服务端选择 single/scoped。
- 移动端使用 viewModel。
- 共享 commonMain 定义保持平台中立。
代码或图示
// 服务端示例
module {
single { OrderService(get()) }
scoped { RequestContext() }
}
常见误区
- 服务端照搬移动端模块,引入 viewModel 定义却无宿主解析。
- 在 commonMain 暴露平台特定 definition,KMP 编译/解析报错。
追问
- KMP 共享模块怎么放平台差异定义?答:commonMain 声明中立接口,平台模块提供实现,见 KMP 题目。
- 4.x 中 viewModel 是否移动到独立模块?答:待确认,查当前依赖坐标与文档。
06.8.4.1-007 qualifier 与 named 怎么区分同类型多实现?
一句话结论
当同一接口有多个实现时,用 qualifier(限定符)给 definition 打标签,解析时按类型加限定符选择实现;named("字符串") 是最常用的 qualifier 构造方式。
概念解释
容器默认按类型查找,同类型多个定义会产生歧义。qualifier 作为第二查找维度,字符串名或类型标签均可。定义侧与解析侧使用同一 qualifier 才能命中。未带 qualifier 解析多实现会报歧义/缺失异常。
原理流程
- 接口有多个实现。
- 注册时各自带 qualifier。
- 解析时传入相同 qualifier。
- 容器按类型 + qualifier 匹配 definition。
代码或图示
module {
single<PaymentGateway>(named("alipay")) { AlipayGateway() }
single<PaymentGateway>(named("wechat")) { WechatGateway() }
}
val gateway: PaymentGateway = koin.get(named("alipay"))
常见误区
- 定义侧与解析侧 qualifier 拼写不一致,运行时找不到。
- 同类型多实现却不区分,解析抛歧义异常。
追问
- qualifier 能用类型而不是字符串吗?答:可以用类型限定符,具体 API 形式待确认。
- 多实现怎么批量注入?答:可声明集合绑定注入全部实现,见后续题目。
06.8.4.1-008 startKoin 与 koinApplication 有什么区别?
一句话结论
startKoin 启动全局持有 Koin 容器实例,供全局解析;koinApplication 构建独立容器实例,便于多容器隔离或测试,不设置全局状态。
概念解释
startKoin 在应用初始化时调用,把容器登记为全局 Koin 实例,业务代码可通过全局入口解析。koinApplication 返回 KoinApplication 对象,容器引用由持有方管理,测试或多模块场景可避免全局污染。具体 API 在 4.x 的形态待确认。
原理流程
- 应用启动选择启动方式。
startKoin注册模块并设置全局实例。koinApplication仅构建实例,手动持有引用。- 解析从对应容器获取。
代码或图示
// 全局启动
startKoin { modules(appModule) }
// 独立容器
val app = koinApplication { modules(testModule) }
val repo = app.koin.get<UserRepository>()
常见误区
- 测试里用
startKoin污染全局容器,用例间状态串扰。 - 独立容器忘记持有引用,GC 后容器失效。
追问
- 服务端应用用哪种?答:常规服务端用
startKoin单容器;测试用独立容器或模块替换。 - 全局容器能重启吗?答:关闭后重新启动,具体 close API 见后续题目。
06.8.4.1-009 模块 includes 怎么组织大型应用?
一句话结论
大模块按功能或层拆成多个 module,用 includes 组合成根模块;根模块统一传入启动,子模块独立复用与测试。
概念解释
includes 是模块间静态组合:父模块声明包含子模块,启动时一起注册。拆分让 definition 按业务域归类,公共模块被多个根模块复用。模块间依赖通过类型解析,不要求 includes 顺序(解析时机决定可见性,待确认 4.x 顺序规则)。
原理流程
- 按领域拆分细粒度模块。
- 聚合模块用
includes(aModule, bModule)组合。 - 启动只注册根模块。
- 测试可单独装载子模块。
代码或图示
val dataModule = module { /* repos */ }
val domainModule = module { /* services */ }
val appModule = module {
includes(dataModule, domainModule)
}
常见误区
- 模块循环 includes,启动或解析时出问题。
- 拆分过细导致模块依赖关系难以追踪。
追问
- includes 顺序影响解析吗?答:definition 查找按类型全局匹配,顺序通常不影响;重复定义的覆盖规则见后续题目。
- 共享模块怎么复用?答:抽公共 module,多个应用根模块 includes 它。
06.8.4.1-010 依赖是启动时解析还是首次使用时解析?
一句话结论
默认懒加载:definition 在首次被 get/inject 解析时才构造;启动只注册定义,不实例化 bean。是否支持 eager 预初始化以当前版本能力为准(待确认)。
概念解释
懒加载降低启动开销,未使用的定义不会构造。代价是首次访问承担构造耗时,构造错误延迟到运行时暴露。需要预热的重型组件可在启动后主动解析。依赖图在解析时递归展开:构造参数缺失会在该 definition 首次解析时报错。
原理流程
- 启动注册所有 definition。
- 首次解析某类型,容器查找 definition。
- 构造参数递归
get,按需实例化。 - 按语义缓存实例。
代码或图示
startKoin { modules(appModule) }
// 此时 single 尚未构造
val service: UserService = get() // 首次解析触发构造链
常见误区
- 以为启动后所有单例已就绪,启动监控看不到首次访问延迟。
- 构造链深层缺失依赖,启动不报错,首次调用才失败。
追问
- 怎么提前发现缺失依赖?答:用
checkModules在启动/测试时校验图完整,见 06.8.4.2。 - 需要预热怎么做?答:启动后主动
get关键 bean;是否有 eager 定义选项待确认。
06.8.4.1-011 注入方式有哪几种:构造参数注入、get 与 by inject?
一句话结论
主流是构造注入:definition lambda 里用 get() 取依赖传给构造函数;组件内部可用 by inject() 委托懒解析,或在持有 Koin 引用处直接 get()。
概念解释
构造注入让依赖显式出现在构造参数,便于测试与审查。by inject() 在属性首次访问时解析,属于字段注入式写法,隐藏依赖关系。服务端推荐构造注入,减少组件对容器的感知。
原理流程
- definition lambda 内
get()解析构造参数。 - 组件构造函数接收依赖。
- 需要延迟时用
by inject()委托。 - 解析失败在对应时机抛出异常。
代码或图示
class UserService(val repo: UserRepository)
module {
single { UserService(get()) } // 构造注入
}
class Controller {
val service: UserService by inject() // 属性委托
}
常见误区
- 组件内到处
get()直接取容器,形成服务定位器反模式。 - 属性注入使依赖不可见,单测无法显式传参。
追问
- 构造注入与字段注入哪个好?答:构造注入优先,依赖显式、可测;字段注入仅在框架强制场景使用。
by inject与get()时机差在哪?答:委托懒解析,get()立即解析。
06.8.4.1-012 定义之间的依赖怎么声明?
一句话结论
在 definition 构造 lambda 内用 get() 引用其他已注册类型,容器解析时递归构造;依赖类型必须在某模块中可解析,否则解析时报缺失。
概念解释
依赖声明是 lambda 内的 get<X>() 调用,Koin 不做显式依赖清单。构造参数按类型匹配,需要限定符时传入 qualifier。依赖链深度在解析时展开,循环依赖在运行时暴露(详见 06.8.4.2)。
原理流程
- 外层 definition 调用
get()。 - 容器查找内层类型 definition。
- 内层构造参数继续解析。
- 递归完成后返回实例组装外层。
代码或图示
module {
single { PasswordEncoder() }
single { UserRepository(get()) }
single { UserService(get(), get()) }
}
常见误区
- 依赖类型未注册,首次解析才报
NoBeanDefFound。 - 构造参数顺序与
get()调用顺序错位。
追问
- 依赖可选怎么办?答:用
getOrNull,缺失时返回 null;具体 API 名待确认。 - 依赖带 qualifier 怎么写?答:
get<X>(named("..."))。
06.8.4.1-013 作用域怎么创建、绑定与关闭?
一句话结论
先定义 scope 关联的标记类型与 scoped definition,业务侧按 ID 创建作用域实例,在作用域内解析对象,用完关闭释放;具体 API 名称以 4.x 文档为准(待确认)。
概念解释
作用域用一个标记类型(或 qualifier)描述「哪一类生命周期」,用 scope ID 区分该类下的具体实例。同一标记类型可有多个并行作用域。关闭作用域后,其中 scoped 实例不再可用。服务端请求级作用域需要在请求开始创建、结束关闭。
原理流程
- 模块内
scope<Marker> { scoped { ... } }。 - 请求开始
getOrCreateScope(scopeId, qualifier<Marker>())。 - 作用域内
scope.get<X>()解析实例。 - 请求结束
scope.close()。
代码或图示
class RequestMarker
val module = module {
scope<RequestMarker> {
scoped { RequestContext() }
}
}
val scope = koin.getOrCreateScope("req-1", qualifier<RequestMarker>())
val ctx = scope.get<RequestContext>()
scope.close()
常见误区
- 只创建不关闭,scoped 实例堆积泄漏。
- 作用域 ID 冲突,不同请求拿到同一作用域实例。
追问
- 作用域能嵌套吗?答:部分版本支持父子作用域,查找沿父链向上;能力与 API 待确认。
- 作用域关闭后 single 还能用吗?答:single 属容器级,不受子作用域关闭影响。
06.8.4.1-014 作用域内实例复用规则是什么?
一句话结论
同一作用域内多次解析同一 scoped definition 返回同一实例;不同作用域之间实例隔离,互不共享。
概念解释
scoped 缓存挂在作用域实例上,而不是容器级。作用域 A 与 B 各自持有独立副本。作用域内也可解析 single,single 仍走容器缓存。理解「缓存挂在哪一层」是区分 single/scoped/factory 的关键。
原理流程
- 作用域内首次解析 scoped 类型,创建并缓存到该作用域。
- 同作用域再次解析命中缓存。
- 另一作用域解析创建独立实例。
- 作用域关闭,其缓存丢弃。
代码或图示
val s1 = koin.getOrCreateScope("a", qualifier<RequestMarker>())
val s2 = koin.getOrCreateScope("b", qualifier<RequestMarker>())
// s1.get<RequestContext>() !== s2.get<RequestContext>()
常见误区
- 以为 scoped 全局复用一次。
- 跨作用域传递 scoped 实例引用,关闭后使用失效。
追问
- 请求级对象该用 scoped 还是 single?答:每请求独立状态用 scoped;无状态共享用 single。
- scoped 实例之间能互相注入吗?答:可以,同作用域解析,关闭时机一致。
06.8.4.1-015 作用域 ID 与标记类型分别解决什么问题?
一句话结论
标记类型区分「哪一类生命周期」,scope ID 区分「同类下的第几个实例」;两者组合定位一个具体作用域。
概念解释
scope<RequestMarker> 声明请求类作用域的定义集合;创建时用 ID(如请求 ID)标识具体作用域。多个请求并行时各持自己的 ID 与实例集。缺少 ID 维度无法区分同类并发作用域。
原理流程
- 定义侧用标记类型圈定 scoped definition。
- 创建作用域时指定标记类型与唯一 ID。
- 解析按作用域实例查找。
- 按 ID 关闭对应作用域。
代码或图示
val scope = koin.getOrCreateScope(requestId, qualifier<RequestMarker>())
常见误区
- 用固定 ID 创建作用域,并发请求互相覆盖。
- 标记类型混用,解析到错误的作用域定义集。
追问
- ID 用什么生成?答:请求 ID 或会话 ID,保证同一生命周期内稳定、跨实例唯一。
- 找不到作用域会怎样?答:解析 scoped 类型时报作用域缺失异常,具体类型待确认。
06.8.4.1-016 类型 qualifier 与字符串 named 怎么选?
一句话结论
字符串 named 简单直接,适合有限的命名实现;类型 qualifier 利用类型系统避免拼写错误,适合复杂模块;两者都是 qualifier,解析侧必须对齐。
概念解释
qualifier 本质是查找键,字符串易重构遗漏,类型限定符在编译期更安全。团队约定统一一种风格。限定符不参与实例行为,只用于选择 definition。
原理流程
- 注册 definition 时附带 qualifier。
- 解析时传入同值 qualifier。
- 容器按类型 + qualifier 匹配。
- 未命中抛缺失异常。
代码或图示
// 字符串限定符
single<Gateway>(named("alipay")) { AlipayGateway() }
// 类型限定符(API 形式待确认)
single<Gateway>(qualifier<Alipay>()) { AlipayGateway() }
常见误区
- 同一项目混用两种风格,查找键不统一。
- 重命名字符串后解析侧漏改。
追问
- 限定符能作为枚举吗?答:按版本支持情况选择字符串或类型;自定义键类型需对照文档(待确认)。
- 限定符参与 equals/hashCode 吗?答:作为查找键参与匹配,实例本身行为不受影响。
06.8.4.1-017 接口与实现怎么绑定(bind / binds)?
一句话结论
注册时用实现类构造,再通过 bind 把同一实例暴露为接口类型;解析接口类型时拿到该实现实例。
概念解释
definition 默认按构造返回类型注册。需要面向接口解析时,用 bind 追加接口绑定,binds 追加多个。同一实例同时满足多个类型查找。接口抽象便于替换实现与测试。
原理流程
single { Impl() }构造实现。.bind<Interface>()追加类型绑定。get<Interface>()命中该实例。- 多接口用
binds(...)一次追加。
代码或图示
interface UserRepository
class SqlUserRepository : UserRepository
module {
single { SqlUserRepository() }.bind<UserRepository>()
}
val repo: UserRepository = get()
常见误区
- 只注册实现类,按接口解析找不到。
- 同一接口绑多个实现又不加 qualifier,产生歧义。
追问
- 构造函数参数用接口还是实现?答:依赖接口,便于替换。
- bind 后实例缓存按哪个类型?答:同一 definition 实例,绑定类型共享缓存。
06.8.4.1-018 模块加载顺序与重复定义覆盖规则是什么?
一句话结论
后加载的模块 definition 可覆盖先加载的同类型定义;覆盖行为受 override 配置控制,具体默认规则与告警在 4.x 需对照文档确认(待确认)。
概念解释
测试替换、环境差异化实现常通过覆盖定义实现。重复注册同类型同 qualifier 时,容器选择哪一个取决于加载顺序与覆盖开关。生产代码应避免隐式覆盖,测试替换显式声明。
原理流程
- 先注册基础模块。
- 后加载模块同类型定义覆盖前者。
- 解析时取生效 definition。
- 未允许覆盖时重复定义可能告警或报错。
代码或图示
val prodModule = module { single<Gateway> { AlipayGateway() } }
val testModule = module(override = true) { single<Gateway> { FakeGateway() } }
常见误区
- 依赖隐式覆盖替换实现,生产环境哪个生效难以排查。
- 模块顺序调整后实现悄悄变化。
追问
- 测试怎么安全替换?答:用专门的测试模块覆盖并在结束后卸载/重置,见 06.8.4.2。
- 怎么发现重复定义?答:开启 Koin 日志或用校验模块检查重复注册。
06.8.4.1-019 getOrNull 与可选注入怎么用?
一句话结论
依赖可能缺失时用 getOrNull 返回 null,避免缺失异常打断流程;非可选依赖应直接 get,让缺失在启动校验阶段暴露。
概念解释
getOrNull 查找不到 definition 时返回 null 而不是抛异常。它适用于可选插件、扩展点场景。业务必需依赖用可选解析会把缺陷延后到空指针,应避免。具体方法名在 4.x 待确认。
原理流程
- 调用
getOrNull<X>()。 - 命中 definition 则返回实例。
- 未命中返回 null。
- 调用方判空处理。
代码或图示
val audit: AuditLogger? = getOrNull()
audit?.log(event)
常见误区
- 必需依赖也用
getOrNull,空值一路传导。 - 可选扩展点未注册却无日志,问题难定位。
追问
- 可选组件缺失要记录吗?答:应记录调试日志,便于发现未装配的扩展点。
- 与
get异常类型区别?答:get抛缺失异常,getOrNull返回 null。
06.8.4.1-020 泛型类型在 Koin 解析时会遇到类型擦除问题吗?
一句话结论
JVM 泛型擦除可能导致 Repository<User> 与 Repository<Order> 被当作同一原始类型;需要区分时用 qualifier 保留区分信息,具体泛型匹配能力以 4.x 实现为准(待确认)。
概念解释
Koin 查找键基于可获取的类型信息。运行时泛型实参被擦除,容器难以仅凭 Repository<T> 区分泛型参数。常见做法:为不同泛型实例加 qualifier,或定义具体子类型。定义集合绑定可处理同类型多实现。
原理流程
- 注册泛型包装类型 definition。
- 解析时类型信息受擦除限制。
- 必要时用 qualifier 区分。
- 复杂泛型场景评估是否拆具体类型。
代码或图示
single(named("user")) { UserRepository() }
single(named("order")) { OrderRepository() }
常见误区
- 以为
get<Repository<User>>()能按泛型实参区分实例。 - 泛型包装多实例混用 qualifier 缺失,解析到错误实现。
追问
- KMP/JS 平台类型擦除行为不同吗?答:各平台类型表示有差异,跨端共享定义需分别验证(待确认)。
- 怎么验证泛型解析?答:写最小用例注册两个泛型实例,断言解析结果。
06.8.4.1-021 集合绑定怎么注入某接口的全部实现?
一句话结论
多个同接口实现可被作为集合整体注入,容器汇总所有匹配 definition;具体集合绑定 API 形式在 4.x 需对照文档确认(待确认)。
概念解释
策略链、插件注册一类场景需要遍历全部实现。集合注入避免手动枚举每个 qualifier。新增实现只需注册 definition,集合自动包含。注意集合内实例的生命周期与各自 definition 语义一致。
原理流程
- 多个 definition 绑定同一接口。
- 解析集合类型触发汇总。
- 容器按定义顺序收集实例。
- 使用方遍历执行。
代码或图示
module {
single<Validator> { EmailValidator() }
single<Validator> { PhoneValidator() }
// 注入 List<Validator>;汇总 API 名称待确认
}
常见误区
- 集合内混入重复实现,校验/执行重复。
- 依赖集合顺序做优先级,却未定义注册顺序约定。
追问
- 集合元素顺序可控吗?答:按注册顺序,需要优先级时显式排序字段。
- 能注入 Map 按名索引吗?答:按版本能力评估,否则在应用层用 qualifier 集合自行组织。
06.8.4.1-022 实例生命周期钩子 onClose 怎么用?
一句话结论
definition 可注册关闭回调,在容器或作用域关闭时释放资源(连接池、客户端、文件句柄);具体回调 API 名称在 4.x 待确认。
概念解释
持有外部资源的 bean 不能只靠 GC 释放。关闭钩子在容器/作用域关闭时执行,按定义逆序或注册顺序调用。后台线程、HTTP 客户端、消息消费者都应登记释放逻辑。
原理流程
- definition 内获取资源并注册关闭回调。
- 容器/作用域正常关闭。
- 回调执行资源释放。
- 未释放的资源在进程退出前泄漏。
代码或图示
single {
val client = HttpClient()
// 关闭回调 API 形式待确认
client
}
常见误区
- bean 持有线程池/连接池却不登记关闭,服务停机时资源不释放。
- 回调内抛异常影响其他 bean 关闭,回调要做好容错。
追问
- 关闭顺序有保证吗?答:按容器实现的关闭顺序,跨 bean 依赖在回调中不要再取其他 bean(待确认)。
- 作用域 bean 也有钩子吗?答:作用域关闭时触发,与容器关闭分别管理。
06.8.4.1-023 Koin 容器的整体生命周期是什么?
一句话结论
容器从启动注册模块开始,到 closeKoin/容器实例关闭结束;期间管理 single 缓存与各作用域,关闭后实例与释放回调一并清理。
概念解释
应用进程通常单容器,生命周期与进程一致。测试中频繁启停容器需要确保旧容器已关闭,避免全局状态残留。容器关闭后再解析 bean 会报错。模块卸载是容器生命周期内的局部操作。
原理流程
- 启动:注册模块 definition。
- 运行:按语义解析、缓存实例。
- 关闭:执行释放回调,清理缓存与作用域。
- 关闭后容器不可用。
代码或图示
startKoin { modules(appModule) }
// ... 运行期使用
closeKoin() // 具体关闭 API 待确认
常见误区
- 测试用例间不关闭容器,单例状态串扰。
- 容器关闭后后台任务继续解析 bean,报错。
追问
- 一个进程能有多个容器吗?答:
koinApplication可建独立实例,全局只保留一个默认实例。 - 容器能热加载模块吗?答:支持运行时加载/卸载模块,见后续题目。
06.8.4.1-024 KMP 项目里 Koin 怎么组织共享模块?
一句话结论
commonMain 声明平台中立的接口与 module,平台模块提供实际实现定义;Koin 在各端启动时装载公共模块加平台模块。平台差异通过 expect/actual 或平台模块注入解决。
概念解释
KMP 共享代码不能依赖平台特定类。公共 module 只引用接口类型,实现在 androidMain/iosMain/JVM 端各自注册。公共模块的 definition 解析到哪份实现由端侧模块决定。Koin 对 KMP 的支持范围与 API 在 4.x 需对照文档确认(待确认)。
原理流程
- commonMain 定义接口与公共 module。
- 平台端写实现类。
- 平台 module 注册接口绑定。
- 各端启动装载公共 + 平台模块。
代码或图示
// commonMain
expect interface Settings
val commonModule = module {
single<Settings> { get() } // 平台提供绑定
}
常见误区
- commonMain 直接引用平台类,共享代码编译失败。
- 平台模块漏注册实现,公共代码解析缺失。
追问
- Koin 在 JS/Wasm 平台支持如何?答:按当前版本兼容矩阵确认,待确认。
- 共享模块能放 scoped 定义吗?答:可以,但作用域创建由各端宿主负责。
06.8.4.1-025 Koin Annotations 与 KSP 解决什么问题?
一句话结论
Koin Annotations 用注解标记类并配合 KSP 在编译期生成模块装配代码,减少手写 DSL;与纯 DSL 方案二选一或混用,注解处理器坐标与生成产物在 4.x 需对照文档确认(待确认)。
概念解释
DSL 手写模块列表,注解方案在类上标注 @Single/@Factory 等,KSP 扫描生成 module 类。注解减少样板,但多了编译期处理器参与。模块组合通过 @Module 与 includes 注解声明。
原理流程
- 类上加定义类型注解。
- KSP 编译期扫描并生成 Koin module。
- 启动装载生成模块。
- 解析行为与 DSL 定义一致。
代码或图示
@Single
class UserRepository @Inject constructor(/* ... */)
@Module
@Includes(RepositoryModule::class)
interface AppModule
常见误区
- 同时维护 DSL 与注解两套注册,定义重复或冲突。
- 未配置 KSP 插件,注解不生成代码,运行时找不到 bean。
追问
- 注解方案需要构造注入注解吗?答:按注解库约定标记构造与参数,具体注解名待确认。
- 生成代码在哪查看?答:KSP 生成目录,编译产物中检查生成 module。
06.8.4.1-026 注解方案与 DSL 方案怎么取舍?
一句话结论
小项目/快速上手用 DSL 直观;大模块、类数量多、希望减少手写模块列表时评估注解方案;团队统一一种风格,避免混合维护成本。
概念解释
DSL 集中可读,依赖关系在模块文件一目了然;注解分散在类上,新增类自动纳入模块但全局图需看生成结果。编译期处理器增加构建链环节。选型结合团队对构建复杂度的接受度。
原理流程
- 评估模块规模与新人上手成本。
- DSL:集中维护定义文件。
- 注解:类级标注 + KSP 生成。
- 项目内不混用两套注册机制。
代码或图示
DSL:module 文件集中声明
注解:类上标注,KSP 生成 module
常见误区
- 混合使用导致同一类被注册两次。
- 注解生成模块未被启动装载,类标注了却不生效。
追问
- 注解方案对 KMP 友好吗?答:KSP 支持 KMP,但各平台生成与装配需验证(待确认)。
- 从 DSL 迁注解要分步吗?答:按模块逐步迁移,先双跑核对 bean 清单再切。
06.8.4.1-027 属性 properties 怎么注入配置值?
一句话结论
Koin 容器可装载属性键值对,definition 内通过 getProperty 读取配置;适合把外部配置注入 bean,属性来源可以是代码、环境或 properties 文件。
概念解释
属性是容器级键值配置,与 bean definition 分离。bean 构造时读取属性组装配置对象。属性缺失时返回默认值或抛异常,行为按 API 约定。环境变量/配置文件接入方式在 06.8.5.2 展开,这里只讲 Koin 属性机制。
原理流程
- 启动时装载 properties。
- definition 内
getProperty("key")读取。 - 配置对象随 bean 构造注入。
- 缺失键按默认值或报错处理。
代码或图示
startKoin {
propertiesOf("db.poolSize" to "20")
module { single { DbConfig(poolSize = getProperty("db.poolSize").toInt()) } }
}
常见误区
- 属性值类型转换在构造时隐式完成,格式错误抛转换异常。
- 敏感配置直接进容器属性,注意日志不打印。
追问
- 属性支持层级/类型化读取吗?答:按版本能力评估,复杂配置建议先组装类型安全配置对象再注入。
- 属性能运行时更新吗?答:属性装载后通常不可变,热更新见配置章节。
06.8.4.1-028 factory 怎么接收每次调用传入的参数?
一句话结论
factory definition 可声明参数,解析时用 parametersOf(...) 传入每次调用不同的值,容器把参数交给构造 lambda。
概念解释
factory 每次新建,天然适合携带调用上下文参数。参数在解析点传入,不进入容器缓存。需要固定配置走 single 构造参数;需要每次变化的值走 factory 参数。参数类型与顺序在 definition lambda 内声明。
原理流程
- 注册
factory { (p: Params) -> X(p) }。 - 解析时
get<X> { parametersOf(arg) }。 - 容器把参数传给 lambda。
- 每次解析使用本次参数新建实例。
代码或图示
factory { (userId: Long) -> UserSession(userId) }
val session: UserSession = get { parametersOf(1001L) }
常见误区
- 把应长期持有对象做成 factory 靠参数传依赖。
- 参数类型不匹配,解析时报参数异常。
追问
- scoped 能传参数吗?答:作用域创建时可带作用域参数,具体 API 待确认。
- 多参数顺序怎么保证?答:按声明顺序传参,复杂参数封装成数据类。
06.8.4.1-029 模块怎么按环境区分装配?
一句话结论
基础模块共享,环境差异通过额外模块覆盖或按条件选择 definition;配置值从属性读取,环境判断在启动装配层完成。
概念解释
dev/test/prod 的差异主要是实现替换与参数配置。装配策略:装载公共模块,再按环境装载对应模块覆盖实现。避免在 definition lambda 内散落环境判断。条件注册能力(按属性开关)以 4.x 支持情况为准(待确认)。
原理流程
- 启动读取环境标识。
- 装载公共模块。
- 按环境追加对应模块。
- 配置属性注入差异参数。
代码或图示
val modules = listOf(commonModule) + when (env) {
"prod" -> listOf(prodModule)
else -> listOf(devModule)
}
startKoin { modules(modules) }
常见误区
- 环境判断写进业务 bean 构造逻辑。
- 测试模块在生产装配路径中被意外装载。
追问
- 条件注册有 DSL 支持吗?答:检查版本是否提供 conditional definition;没有则在装配层选择模块。
- 环境配置敏感值怎么进容器?答:见配置章节,从环境变量/Secret 注入,不写死。
06.8.4.1-030 可选注入与平台插件式注册怎么组织?
一句话结论
扩展点定义接口,各插件模块注册实现,主服务用集合注入或 getOrNull 取用;未注册时主流程降级运行。
概念解释
插件/拦截器/策略一类扩展点天然适合多实现注册。主流程不依赖具体插件存在,缺失时走默认行为。扩展模块可独立启停,容器按注册情况汇总。顺序与默认实现约定在团队规范中明确。
原理流程
- 定义扩展点接口。
- 各实现模块注册 definition。
- 主服务解析集合或可选单例。
- 缺失时降级到默认逻辑。
代码或图示
interface Exporter { fun export(data: String) }
// 主服务:未注册则跳过导出
val exporters: List<Exporter> = getOrNull() ?: emptyList()
常见误区
- 扩展点缺失时主流程直接报错,插件化失去意义。
- 扩展实现间隐式顺序依赖未声明。
追问
- 扩展实现怎么发现?答:模块显式注册,不靠类路径扫描(Koin 核心不做自动扫描,待确认)。
- 扩展配置怎么传?答:通过属性或独立配置对象注入。
06.8.4.1-031 Koin 日志怎么开启,怎么调试模块定义?
一句话结论
启动时配置 Koin 日志级别,可查看 definition 注册、解析与缺失告警;调试时打印模块定义树与解析路径,定位未注册/歧义定义。
概念解释
运行时 DI 的问题多表现为解析失败,日志能显示查找类型、qualifier 与命中情况。日志级别在开发期开到 debug,生产收敛。日志 API 名称在 4.x 待确认。
原理流程
- 启动配置日志级别。
- 观察注册阶段定义清单。
- 解析失败时日志给出查找键。
- 对照模块定义查漏补缺。
代码或图示
startKoin {
// 日志级别配置 API 待确认
modules(appModule)
}
常见误区
- 生产开 debug 日志,bean 解析日志量过大。
- 只看异常消息,不看日志中的查找类型与 qualifier。
追问
- 怎么导出全部 definition 清单?答:通过容器 API 遍历模块定义(方法名待确认),用于评审与测试校验。
- 解析失败先查什么?答:类型名、qualifier、作用域是否匹配,模块是否装载。
06.8.4.1-032 模块内部状态与 definition 捕获外部变量有什么坑?
一句话结论
definition lambda 捕获外部可变状态会让单例行为依赖闭包快照;容器管理的应是可重建的对象,外部配置通过参数显式注入。
概念解释
DSL 块内引用外部变量,lambda 捕获该引用。若外部变量后续变化,单例构造时看到的值可能不符合预期。共享可变状态进 single 还引入并发问题。配置应在启动时固化为对象再注入。
原理流程
- 模块定义构造 lambda。
- 捕获外部只读配置尚可,捕获可变状态有风险。
- 单例首次解析按捕获值构造。
- 后续外部变量变化不影响已构造实例。
代码或图示
fun buildModule(port: Int) = module {
single { ServerConfig(port) } // 显式参数,不捕获可变引用
}
常见误区
- 在 module 块里读可变全局变量,构造结果不确定。
- 闭包持有大对象引用,模块生命周期内无法释放。
追问
- 配置对象怎么传入模块?答:工厂函数接收配置参数生成 module,definition 引用参数。
- 单例内部可变状态怎么处理?答:优先无状态;必须有状态则做好并发同步并评估生命周期。
06.8.4.1-033 单例构造的线程安全是怎样的?
一句话结论
容器保证 single 首次构造在并发解析下的安全可见性;构造 lambda 不应依赖外部线程状态,实例自身的并发安全仍需自己保证。具体初始化同步机制以源码为准(待确认)。
概念解释
多个线程同时首次解析同一 single,容器避免重复构造与半初始化暴露。这不等于实例方法线程安全:实例内部可变字段仍需同步。构造 lambda 内做重计算会阻塞首次解析线程。
原理流程
- 并发线程请求同一 single。
- 容器同步首次构造。
- 构造完成后所有线程获得同一实例。
- 实例内部并发访问由实现负责。
代码或图示
single { Counter() } // 实例内部计数需自行保证线程安全
常见误区
- 把 DI 容器的初始化安全当成实例线程安全。
- 构造 lambda 内启动线程或做重 IO,首次解析阻塞放大。
追问
- 构造慢的 bean 怎么优化?答:拆分重资源、延迟到真正需要时,或启动预热;避免构造链过长。
- 并发重复构造会怎样?答:容器层应只构造一次;若观察到多实例,检查 definition 类型是否误写为 factory。
06.8.4.1-034 模块拆分按功能还是按层?
一句话结论
服务端按业务功能聚合模块更利于边界清晰:每个功能模块包含自己的 service/repository 定义,公共基础设施模块单独抽出;按层拆模块会导致跨功能依赖难以追踪。
概念解释
按层拆分(所有 repository 一个模块、所有 service 一个模块)与代码架构方向不一致,功能变更要动多个模块。按功能拆分后模块内聚该功能的装配关系,公共客户端、配置等放基础模块。模块划分与 Gradle 模块化配合,见 06.8.5.3。
原理流程
- 识别业务功能边界。
- 功能模块装配自身 service 与 repository。
- 跨功能共享组件入基础模块。
- 根模块 includes 各功能模块。
代码或图示
appModule
├─ userModule(UserService + UserRepository)
├─ orderModule(OrderService + OrderRepository)
└─ commonModule(HttpClient、配置)
常见误区
- 按层拆模块,一个功能的定义散落在三处。
- 基础模块反向依赖业务模块,方向倒置。
追问
- 模块边界怎么审查?答:检查模块间依赖方向与注入类型,架构守护测试见 06.8.5.3。
- 小服务需要多模块吗?答:少量 definition 可单模块,随功能增长再拆。
06.8.4.1-035 第三方库实例怎么纳入 Koin 管理?
一句话结论
第三方客户端、驱动器等在 definition 中构造并登记绑定,纳入容器生命周期与关闭回调;不要在各处直接 new,便于统一替换与资源释放。
概念解释
HTTP 客户端、数据库驱动、消息生产者等都是重型资源,纳入 single 管理可复用实例、统一关闭。构造参数从配置对象读取。包装一层接口也便于测试替换。第三方类不受我们控制,但实例装配归容器管理。
原理流程
- 在模块中注册第三方类型 single。
- 构造读取配置属性。
- 登记关闭回调释放资源。
- 业务代码通过接口/类型解析使用。
代码或图示
module {
single { HttpClient(config = get()) }
single { UserService(get()) }
}
常见误区
- 各处直接构造客户端,连接/线程池多份实例。
- 第三方资源未登记关闭,停机泄漏。
追问
- 第三方库自己的单例要再包一层吗?答:避免双重单例,确认库实例复用策略后再纳入容器。
- 怎么为第三方实例做测试替身?答:依赖我们自己的接口包装,测试覆盖接口绑定。
06.8.4.1-036 怎么在 DI 层用装饰器包装实现?
一句话结论
定义接口的主实现,再注册装饰器 definition 接收接口类型并包装;解析接口时按注册链或 qualifier 选择外层装饰器,横切逻辑(日志、监控、鉴权)在包装层完成。
概念解释
装饰器在不修改主实现的情况下叠加行为。Koin 中装饰器构造函数接收被包装的接口实例。多层装饰时注册顺序决定包裹层次,需要明确哪层在外。装饰器本身注册为接口类型绑定。
原理流程
- 主实现注册为接口类型。
- 装饰器 definition 注入接口实例并包装。
- 解析外层类型得到装饰后实例。
- 调用链依次经过各装饰层。
代码或图示
interface Service { fun run() }
class RealService : Service
class LoggingService(val inner: Service) : Service { /* 日志 */ }
module {
single<Service> { LoggingService(get()) }
single { RealService() }
}
常见误区
- 装饰器与被装饰者同类型注册产生递归解析。
- 装饰顺序与预期相反,日志/监控层级错乱。
追问
- 多层装饰怎么固定顺序?答:显式逐层注入,定义链写清楚;集合注入不保证装饰嵌套。
- 装饰器需要 qualifier 吗?答:多套包装策略时用 qualifier 区分。
06.8.4.1-037 Kotlin object 单例与 Koin single 有什么区别?
一句话结论
object 是语言级单例,类加载即实例化、无法替换;Koin single 由容器管理生命周期、可替换、可注入依赖。需要 DI 管理与测试替换的对象用 Koin single。
概念解释
object 实例在类加载时创建,构造逻辑不受容器控制,依赖只能自己获取。Koin single 按容器语义懒加载、构造参数可注入、测试可覆盖。无状态纯工具函数更适合 object;有依赖、需替换的服务走 Koin。
原理流程
- object:类加载时 JVM 创建唯一实例。
- Koin single:首次解析时容器构造并缓存。
- 测试中 Koin 定义可被模块替换。
- object 无法在测试中替换。
代码或图示
object MathUtils { fun add(a: Int, b: Int) = a + b } // 无状态工具
module { single { UserService(get()) } } // 有依赖、可替换
常见误区
- 把需要数据库/客户端依赖的服务写成 object,内部自己取全局资源。
- 以为 object 也能被 Koin 覆盖替换。
追问
- object 能注册进 Koin 吗?答:可把 object 实例作为 definition 提供,但失去容器管理意义。
- 工具类要注入配置吗?答:需要配置就改成普通类由容器管理。
06.8.4.1-038 模块 includes 出现循环会怎样?
一句话结论
模块间静态 includes 循环通常在启动或解析时暴露问题;模块组合应是有向无环图,公共模块被依赖而不反向引用业务模块。
概念解释
includes 表达装配组合,definition 之间才是运行时依赖。循环 includes 让模块归属混乱,启动校验可能报错或产生意外覆盖。排查时画模块依赖图,切断回边。
原理流程
- 梳理各模块 includes 关系。
- 检测是否存在环。
- 公共能力下沉到基础模块。
- 业务模块单向依赖基础模块。
代码或图示
userModule → commonModule
orderModule → commonModule
commonModule 不反向引用 user/order
常见误区
- 两个业务模块互相 includes,共享代码未下沉。
- 依赖方向与代码包方向不一致。
追问
- 运行时循环依赖(bean 互相注入)与模块循环一样吗?答:不一样,前者是构造参数环,后者是模块组合环;都需治理,详见 06.8.4.2。
- 怎么自动检查模块环?答:架构守护测试扫描模块依赖关系。
06.8.4.1-039 Koin 与 Spring 注解混用要注意什么?
一句话结论
同一服务端应用应选定一套 DI 体系,避免 Koin 容器与 Spring 容器并行管理同一对象;混用会导致两套生命周期、替换与事务边界割裂。
概念解释
Spring 用注解与容器管理 bean,Koin 用 DSL/注解管理自己的容器。两套容器互不可见,对象跨容器传递时生命周期与代理行为不一致。Ktor + Koin 技术栈不引入 Spring;Spring Boot 项目保留 Spring DI,不另起 Koin 容器。
原理流程
- 确认项目主框架与 DI 体系。
- 依赖装配全部走主容器。
- 跨体系适配在边界层手动桥接。
- 评审中禁止新增第二套容器定义。
代码或图示
Ktor 服务:Koin 容器
Spring Boot 服务:Spring 容器
不要在同一进程并行装配两套业务 bean
常见误区
- 部分类交 Spring、部分类交 Koin,事务与代理失效。
- 以为两套容器能自动共享单例。
追问
- 迁移期怎么过渡?答:按模块逐步切换,过渡期明确桥接对象归属,不长期保留双容器。
- 框架自带 DI 与 Koin 冲突点?答:检查框架插件是否自行管理组件生命周期,避免重复包装。
06.8.4.1-040 重复注册同类型定义怎么定位冲突?
一句话结论
同类型同 qualifier 被注册多次时,开启 Koin 日志查看注册清单,定位重复模块;生产代码消除重复,测试替换走显式覆盖模块。
概念解释
重复定义可能来自模块误 includes 两次、公共与业务模块都注册了同一类型。解析时取哪个定义取决于覆盖规则。定位手段:列出全部 definition 按类型分组,找重复键。校验模块可在测试阶段发现冲突。
原理流程
- 开启注册日志或导出定义清单。
- 按类型 + qualifier 分组找重复。
- 判断是误重复还是有意覆盖。
- 移除重复或显式标注覆盖。
代码或图示
排查路径:解析结果不对 → 导出 definition 清单 → 同类型多条 → 核对模块来源
常见误区
- 依赖后注册覆盖先注册,行为随模块顺序漂移。
- 重复注册未告警,问题到运行时才显现。
追问
- 怎么在 CI 阶段拦截重复定义?答:
checkModules或自定义校验遍历定义键,重复即失败。 - 多实现是合法重复吗?答:合法多实现必须带不同 qualifier 或走集合绑定。
06.8.4.1-041 启动后解析失败的排查流程是什么?
一句话结论
按「查找键 → 模块是否装载 → 类型/qualifier/作用域是否匹配 → 依赖链缺失」逐层排查,先拿异常中的类型与限定符,再核对模块定义。
概念解释
运行时缺失异常携带查找类型与 qualifier。常见原因:模块未 includes、接口未 bind、解析侧 qualifier 拼错、在错误作用域解析 scoped、依赖链某一环未注册。按定义树向上游找第一个缺失节点。
原理流程
- 记录异常类型:缺失/歧义/作用域不存在。
- 核对目标模块是否装入启动模块树。
- 核对类型绑定与 qualifier 一致性。
- 递归检查构造参数 definition。
代码或图示
NoBeanDefFound(UserRepository)
→ userModule 是否装载
→ 是否 bind<UserRepository>
→ 其依赖 DataSource 是否注册
常见误区
- 只看报错的顶层类型,忽略底层缺失依赖。
- 在错误作用域里解析 scoped bean,误判为未注册。
追问
- 怎么提前暴露?答:启动跑模块校验(见 06.8.4.2),测试覆盖解析路径。
- 异常包装层级怎么读?答:沿 cause 链找到原始缺失类型。
06.8.4.1-042 definition 构造抛异常时容器怎么包装?
一句话结论
构造 lambda 内异常会在解析时向上抛出,通常被包装为 Koin 异常并携带触发 definition;已构造成功的依赖与半成品实例的处理按版本实现为准(待确认)。
概念解释
构造失败可能来自配置非法、外部资源连不上、参数转换错误。容器不会吞掉异常,但会附加查找上下文。调用方需区分构造失败与业务运行异常。重试策略不能简单重复解析失败 bean。
原理流程
- 解析触发构造 lambda。
- 内部抛出原始异常。
- 容器包装并附 definition 信息。
- 异常传给解析点,容器状态按实现保留或回滚。
代码或图示
single { HttpClient(config) } // 配置非法时构造抛异常
常见误区
- 构造 lambda 内吞异常返回半成品对象,问题延后爆发。
- 把构造异常当业务异常重试,反复失败。
追问
- 构造期连外部资源合理吗?答:重型外部连接可在构造时建立,但失败要快速暴露;更稳妥是懒连接配合健康检查。
- 怎么定位是哪个 definition 抛的?答:看异常堆栈与 Koin 日志中的 definition 名。
06.8.4.1-043 模块文件的文档化约定有哪些?
一句话结论
模块文件按功能命名并头部注释说明职责、包含的 definition 与依赖;definition 命名表达业务意图,便于评审时快速理解装配图。
概念解释
DI 装配图是架构文档的一部分。模块名、bean 类型、qualifier 都应可读。复杂作用域与装饰链在文件头说明。团队约定注释格式,避免模块文件变成无人维护的配置泥团。
原理流程
- 模块文件头写职责与依赖方向。
- definition 按依赖层次排列。
- 多实现 qualifier 注明用途。
- 评审时同时检查装配关系。
代码或图示
// 用户模块:装配用户相关 service 与 repository,依赖 commonModule 的数据源
val userModule = module { /* ... */ }
常见误区
- 模块文件名与内容不符,definition 散落难追溯。
- qualifier 用无意义字符串,新人无法理解实现差异。
追问
- 装配图要单独维护文档吗?答:代码即图,必要时用生成的定义清单补充,不手工复制易过期图表。
- bean 命名规范?答:类型名表达职责,避免
Helper/Manager泛称。
06.8.4.1-044 Koin 内部注册表大致是什么结构?
一句话结论
概念上容器维护一张 definition 注册表,查找键由类型、qualifier、作用域组成;single 缓存挂在容器或作用域上,factory 不缓存。具体内部数据结构以 4.x 源码为准(待确认)。
概念解释
理解注册表模型有助于排查查找失败:definition 描述构造方式与语义,实例缓存按层维护。查找时先定位作用域,再按键匹配 definition。编译期 Koin 不生成代码,注册表在运行时由 DSL 填充。
原理流程
- 启动把各模块 definition 写入注册表。
- 解析按键查找 definition。
- 按 single/scoped/factory 语义取或建实例。
- 缓存实例挂对应生命周期层。
代码或图示
注册表:(类型, qualifier, scope) → definition
缓存:容器级 single 表 / 作用域级 scoped 表 / factory 无缓存
常见误区
- 以为 Koin 用反射扫描类路径自动注册。
- 混淆 definition 注册与实例缓存两张表。
追问
- 注册表怎么遍历?答:容器暴露模块/定义访问 API(方法名待确认),用于校验与调试。
- 注册表面积影响启动速度吗?答:注册是轻量登记,主要成本在实例化而非表大小。
06.8.4.1-045 解析时类型、qualifier、作用域如何共同匹配?
一句话结论
查找依次限定作用域上下文、类型与 qualifier;三者同时命中才解析成功,任一不匹配即报缺失或歧义。
概念解释
在某作用域内解析时,先在该作用域定义集内查找,未命中再向上游/容器级查找(具体查找顺序待确认)。类型不匹配、qualifier 不一致都会落空。多实现未加 qualifier 时同键多条构成歧义。
原理流程
- 确定解析所在作用域。
- 按类型筛选候选 definition。
- 按 qualifier 精确匹配。
- 命中唯一 definition 则构造/取缓存,否则报错。
代码或图示
val g: Gateway = scope.get(named("alipay"))
// 匹配条件:scope 内 + Gateway 类型 + alipay qualifier
常见误区
- 类型对了但 qualifier 不一致,误判为未注册。
- 在容器级解析 scoped 类型,作用域上下文缺失。
追问
- 查找会跨作用域向上吗?答:父子作用域查找链按版本实现确认(待确认)。
- 歧义异常与缺失异常怎么区分?答:候选多条为歧义,零条为缺失。
06.8.4.1-046 不同 definition 语义的缓存分别挂在哪?
一句话结论
single 缓存挂容器,scoped 缓存挂作用域,factory 不缓存;理解缓存层级是选型与排查实例重复问题的基础。
概念解释
同一类型被误注册成不同语义,实例共享行为完全不同。排查「为什么拿到新实例」时先看 definition 类型。作用域关闭释放 scoped 缓存,容器关闭释放 single 缓存。
原理流程
- single:容器级缓存一份。
- scoped:每个作用域一份缓存。
- factory:每次新建,无缓存。
- 关闭按层级释放。
代码或图示
容器缓存:single 实例
作用域缓存:scoped 实例
无缓存:factory 实例
常见误区
- 期望复用却写成 factory,资源反复创建。
- 期望独立实例却写成 single,状态串扰。
追问
- 同一类型能注册多种语义吗?答:可用不同 qualifier 区分,但容易混淆,应在评审中明确。
- 缓存实例怎么排查身份?答:日志或断言
===比较实例引用。
06.8.4.1-047 启动耗时由模块加载还是实例化决定?
一句话结论
模块加载只是登记 definition,成本很低;启动耗时主要来自预热解析的 bean 构造与外部资源连接。默认懒加载下,启动快但首次访问承担构造耗时。
概念解释
startKoin 遍历模块写入注册表,不构造业务对象。若启动时主动 get 关键 bean,构造链与外部连接计入启动时间。优化启动:减少启动预热、延迟非关键资源、拆分构造链。
原理流程
- 启动:注册 definition。
- 预热解析:递归构造 bean 并建连接。
- 运行期:首次访问懒构造。
- 耗时分别统计注册阶段与实例化阶段。
代码或图示
启动耗时 ≈ 模块注册 + 预热 bean 构造 + 外部连接建立
常见误区
- 把所有 single 启动预热,启动时间被重型资源拖长。
- 启动快但首请求慢,未监控首次解析延迟。
追问
- 怎么知道哪些 bean 被预热?答:统计启动期解析日志与构造耗时。
- 冷启动敏感场景怎么平衡?答:核心链路预热,非关键懒加载。
06.8.4.1-048 Koin 解析依赖是否依赖反射?
一句话结论
核心 DSL 方案通过构造 lambda 显式提供实例,不依赖反射读取构造函数;注解方案由 KSP 在编译期生成装配代码。是否在个别场景使用反射以 4.x 源码为准(待确认)。
概念解释
DSL 里 single { X(get(), get()) } 的构造关系写死在 lambda 中,容器只需调用 lambda。这与反射注入字段的框架不同。减少反射也意味着 GraalVM/AOT 下风险较低,但仍需验证(见 06.8.4.2)。
原理流程
- DSL lambda 已包含构造调用。
- 容器调用 lambda 解析参数。
- 不扫描构造函数签名。
- 注解方案在编译期完成等价信息生成。
代码或图示
single { UserService(get(), get()) } // 构造关系由 lambda 显式表达
常见误区
- 以为所有 DI 框架都靠反射注入。
- 误以为 Koin 能自动扫描类路径注册。
追问
- 字段注入需要反射吗?答:
by inject委托由容器提供,具体实现机制待确认。 - 反射少带来什么好处?答:AOT 兼容面更广,运行时行为可预期。
06.8.4.1-049 Koin 在 GraalVM/AOT 下有哪些注意点?
一句话结论
DSL 方案无编译期生成、反射使用少,相对友好;但运行时解析、动态代理与资源加载仍需在 GraalVM 下验证。AOT 冲突的深入对比在 06.8.4.2 展开。
概念解释
GraalVM 原生镜像要求反射、动态代理、类加载在编译期可枚举。Koin 运行时注册表由代码显式构造,风险低于反射型框架;但 bean 内部使用的库若有反射/动态代理仍需登记。是否完全兼容 4.x 需实际构建验证(待确认)。
原理流程
- 用 DSL 显式装配,避免反射注入。
- 原生镜像构建跑通启动与解析。
- 登记第三方库的反射/代理配置。
- 监控运行期类加载告警。
代码或图示
AOT 检查:无运行时类扫描 / 无字段反射注入 / 第三方库反射已登记
常见误区
- 认为 Koin 零反射就自动兼容原生镜像。
- bean 内部动态加载类,镜像构建期未纳入。
追问
- 编译期 DI 方案在 AOT 下优势?答:依赖关系编译期固化,无运行时查找,详见 06.8.4.2。
- 怎么验证兼容性?答:产出原生镜像跑集成测试,记录告警与缺失配置。
06.8.4.1-050 Gradle 多模块项目里 Koin 模块怎么分布?
一句话结论
每个 Gradle 业务模块提供自己的 Koin module,应用模块汇总 includes;基础模块提供公共组件 module,模块间只依赖公开接口,装配不跨模块乱取实现。
概念解释
Gradle 模块化与 Koin 模块对应:代码模块边界即装配边界。业务模块导出自己的 module 供应用聚合。共享实现放基础模块。避免上层模块直接 new 下层实现破坏封装。
原理流程
- Gradle 模块按功能划分。
- 各模块定义内部 Koin module。
- 应用根模块 includes 全部业务模块。
- 模块间通过接口交互。
代码或图示
:app ──includes── :user-module ── :common
└─ userModule └─ commonModule
常见误区
- 装配集中在 app 模块引用各层实现类,模块封装失效。
- 公共模块依赖业务模块,Gradle 依赖方向倒置。
追问
- 模块间 bean 怎么协作?答:依赖公共接口,实现由各自模块注册。
- Gradle 模块化详细规则?答:见 06.8.5.3 分层架构与模块化。
06.8.4.1-051 插件/扩展点怎么注册进容器并被发现?
一句话结论
扩展点接口定义在公共模块,各插件模块注册实现;主模块集合注入全部实现。Koin 核心不做类路径自动扫描,新增插件必须显式注册 definition(待确认是否有扫描扩展)。
概念解释
插件化依赖显式装配:插件模块被 includes 后,其实现自然进入集合。主服务启动时汇总扩展点。扩展实现的优先级、启停钩子在接口约定中定义。
原理流程
- 公共模块定义扩展接口。
- 插件模块注册接口实现。
- 根模块 includes 插件模块。
- 主服务集合注入并遍历。
代码或图示
interface Plugin { val id: String; fun start() }
// 各插件模块:single<Plugin> { OrderPlugin() }
常见误区
- 期待自动扫描发现插件,漏注册后扩展点缺失。
- 插件实现无默认优先级约定,执行顺序不确定。
追问
- 插件启停生命周期怎么管理?答:实现容器关闭回调或扩展接口 start/stop,由主服务编排。
- 插件配置怎么隔离?答:每插件独立配置对象注入。
06.8.4.1-052 后台任务组件与作用域生命周期怎么配合?
一句话结论
后台任务持有的 bean 生命周期要明确:任务自身用 single 管理,请求级数据不能带进后台线程;长生命周期组件登记关闭回调,停机时优雅停止。
概念解释
后台调度器、消费者是应用级 single;请求上下文属于 scoped,不能被异步任务长期持有。任务需要的数据在触发时显式传入。关闭时先停止新任务、等待在途任务完成,再释放组件。
原理流程
- 后台组件注册为 single。
- 触发任务时从作用域取所需数据快照传入。
- 任务内不依赖已关闭作用域。
- 容器关闭时回调停止调度与消费。
代码或图示
single { BackgroundScheduler(get()) } // 应用级
// 请求数据在提交任务时复制为不可变快照
常见误区
- 后台任务持有请求作用域实例,作用域关闭后使用失效。
- 后台线程池未登记关闭,停机时任务被硬中断。
追问
- 协程后台任务用什么作用域?答:应用级 CoroutineScope 由 single 持有,随容器关闭取消,见 06.8.5.3。
- 请求级 bean 怎么传给异步任务?答:传值对象快照,不传实例引用。
06.8.4.1-053 测试中如何复用公共模块定义?
一句话结论
公共生产模块可在测试中直接装载,差异实现用覆盖模块替换;测试装配与生产装配分离,避免测试替身污染生产模块。测试替换的具体 API 在 06.8.4.2 展开。
概念解释
复用生产 module 减少测试装配重复。需要替身时追加覆盖模块,而不是修改生产定义。测试结束重置容器。公共模块应无硬编码环境依赖,便于测试装载。
原理流程
- 测试装载公共生产模块。
- 追加测试覆盖模块。
- 执行断言。
- 重置/关闭容器。
代码或图示
startKoin { modules(commonModule, fakeRepoModule) }
常见误区
- 在生产模块里留测试开关,两套行为混杂。
- 测试容器未重置,用例间单例串扰。
追问
- 公共模块连外部资源怎么办?答:重资源定义可被测试模块覆盖,或延迟到解析时。
- 测试模块组织方式?答:见 06.8.4.2 测试替换与 checkModules。
06.8.4.1-054 definition 与类的可见性(internal/public)有什么约束?
一句话结论
definition 注册的类型与构造对容器可见即可;跨 Gradle 模块暴露的接口需 public,实现类可 internal,只要提供接口绑定。
概念解释
Koin 解析按类型查找,类可见性影响跨模块引用。暴露给其他模块解析的类型必须 public;模块内实现可以 internal,但绑定接口需 public。注解方案的可见性要求按 KSP 约定。
原理流程
- 跨模块解析的接口声明为 public。
- 实现类保持 internal。
- 模块内 bind 接口到实现。
- 外部只 get 接口类型。
代码或图示
public interface Exporter
internal class CsvExporter : Exporter
module { single<Exporter> { CsvExporter() } }
常见误区
- 跨模块解析 internal 类型,编译可见性报错。
- 实现类暴露为 public,模块边界泄漏。
追问
- internal 类能被 Koin 注册吗?答:同模块内可以;跨模块引用受 Kotlin 可见性限制。
- 注解方案对可见性有额外要求吗?答:按 KSP 生成代码访问范围确认(待确认)。
06.8.4.1-055 data class 适合作为注入实例吗?
一句话结论
纯数据载体 data class 可作为配置/模型对象注入,但无行为、无依赖的普通数据更适合按需构造;需要复用或携带依赖的服务用普通类注册。
概念解释
data class 主打值相等与不可变。把请求/配置数据注册进容器通常没有必要,它应在使用处构造。容器管理的多是有行为、有依赖、需要复用的组件。配置 data class 可在启动时组装后作为 single 注入。
原理流程
- 判断对象是值还是组件。
- 值对象按需构造,不进容器。
- 配置值对象启动时组装注册。
- 服务组件注册 definition。
代码或图示
data class DbConfig(val poolSize: Int) // 配置可注入
data class OrderView(...) // 接口响应,按需构造
常见误区
- 把每条请求的 data class 注册成 single,状态串扰。
- 可变 data class 注册单例,并发修改。
追问
- 不可变配置为什么可以 single?答:启动后不变,多线程只读安全。
- data class 带方法算组件吗?答:有依赖与行为时按服务类处理。
06.8.4.1-056 协程作用域与 bean 持有怎么协调?
一句话结论
应用级协程作用域由 single 持有并随容器关闭取消;bean 不要持有请求级协程作用域,异步任务使用独立作用域管理生命周期。
概念解释
CoroutineScope 是可关闭资源,纳入容器管理与 bean 释放一致。请求级协程作用域随请求结束取消,不能被 single 捕获长期使用。调度器与线程池配置在组件内部明确。
原理流程
- 应用级 scope 注册为 single。
- bean 在该 scope 内启动后台协程。
- 容器关闭时取消 scope。
- 请求级 scope 局部创建局部使用。
代码或图示
single { CoroutineScope(SupervisorJob() + Dispatchers.IO) }
常见误区
- single 持有请求 scope,请求结束后协程泄漏。
- 不取消协程,停机时后台任务不受控。
追问
- bean 内直接用 GlobalScope 好吗?答:不推荐,生命周期不受容器管理。
- 协程调度器选择?答:IO 阻塞操作用 IO 调度器,见数据访问章节。
06.8.4.1-057 怎么记录 bean 解析用于排查与审计?
一句话结论
开发期开启解析日志记录类型、qualifier 与解析时机;生产收敛为关键 bean 初始化指标,避免每次解析打日志。
概念解释
解析日志帮助定位首次构造时机与依赖链。生产环境全量解析日志量过大,只记录启动预热与异常解析。bean 清单与初始化耗时可作为指标上报。
原理流程
- 开发环境 debug 级别输出解析记录。
- 记录类型、限定符、来源模块。
- 生产只上报初始化失败与耗时指标。
- 日志不打印敏感配置内容。
代码或图示
调试日志:resolve UserService → UserRepository → DataSource
指标:bean.init.latency{bean=...}
常见误区
- 生产开启全量解析日志,日志体积膨胀。
- 日志打印 bean 内敏感配置值。
追问
- 怎么统计 bean 初始化耗时?答:包装构造阶段计时,上报直方图。
- 解析记录能替代模块校验吗?答:不能,校验在启动期主动检查全图,日志只覆盖实际解析路径。
06.8.4.1-058 Koin 4.x 的依赖坐标与包名有哪些要注意的?
一句话结论
Koin 4.x 的核心、日志、KMP、注解处理器模块坐标与 3.x 可能不同,引入前对照官方发布说明核对 artifact 名与版本;本项目基线 Koin 4.x,具体坐标以官方仓库为准(待确认)。
概念解释
版本升级常伴随模块拆分与包名调整。服务端只需要核心模块;Android/Compose 相关模块按需引入。注解方案额外引入 KSP 处理器。混用 3.x 与 4.x 依赖会导致 API 不兼容。
原理流程
- 查官方当前版本与模块清单。
- 按平台引入对应 artifact。
- 编译核对 import 包名。
- 运行验证解析行为。
代码或图示
待确认:4.x 核心 artifact 坐标、注解/KSP 模块坐标、包名前缀
常见误区
- 照搬 3.x 教程坐标,依赖解析失败或版本混用。
- 引入多余平台模块,构建链变重。
追问
- 怎么确认实际版本?答:查构建文件解析后的依赖树与 Koin 发布说明。
- 升级 3→4 有哪些迁移点?答:对照 changelog 的 breaking changes,API 改名逐项适配(待确认清单)。
06.8.4.1-059 常见启动错误有哪些典型形态?
一句话结论
典型错误包括模块未装载导致缺失、接口未 bind、qualifier 不匹配、作用域未创建、循环依赖、重复定义歧义;按异常类型对照排查清单逐项核对。
概念解释
运行时 DI 错误集中在解析阶段。缺失是零候选,歧义是多候选,作用域错误是上下文不对,循环依赖是构造链成环。异常消息通常带类型与限定符信息。
原理流程
- 分类异常:缺失/歧义/作用域/循环。
- 核对模块装载与类型绑定。
- 核对 qualifier 与作用域 ID。
- 循环依赖重构依赖方向。
代码或图示
缺失:检查模块/绑定/qualifier
歧义:检查多实现是否区分
作用域:检查 scope 是否创建
循环:重构构造依赖
常见误区
- 所有错误都重新 startKoin,不分析根因。
- 忽略异常 cause 链,漏掉底层缺失节点。
追问
- 启动不报错但行为不对?答:检查是否解析到错误实现(qualifier/覆盖顺序)。
- 怎么沉淀排查清单?答:团队 FAQ 记录错误形态与对应检查项。
06.8.4.1-060 多实例部署下容器状态有什么共性要求?
一句话结论
每个服务实例独立持有自己的 Koin 容器,容器内状态不跨实例共享;有状态 bean 不能依赖单实例内存语义,多实例间一致性走外部存储。
概念解释
Koin 容器是进程内组件,多副本部署时各副本独立解析与缓存。single 只在单进程内单例。需要跨副本共享的状态放数据库/缓存。会话/请求作用域天然局限在单实例内。
原理流程
- 每实例启动独立容器。
- 进程内 single 复用。
- 跨实例共享数据走外部存储。
- 会话粘性与作用域不依赖容器跨实例。
代码或图示
副本 A 容器 ←→ 共享 DB/Redis ←→ 副本 B 容器
常见误区
- 把进程内 single 当分布式缓存。
- 请求作用域数据期待路由回同一副本仍可访问。
追问
- 多副本下定时任务怎么避免重复执行?答:分布式协调/选主,不属于容器职责,见 08/09 分册。
- 实例扩容对容器有影响吗?答:每副本独立装载相同模块定义。
06.8.4.1-061 Koin 解析行为怎么接入监控指标?
一句话结论
可上报 bean 初始化耗时、解析失败计数与容器启停事件;解析频次通常无需全量埋点,重点关注启动初始化与异常。
概念解释
DI 层指标服务于启动性能与故障排查。初始化慢的 bean 进入启动耗时看板,解析失败进入错误监控。bean 数量与定义清单可作为发布校验信息。具体拦截扩展点以 4.x 能力为准(待确认)。
原理流程
- 在构造/解析阶段计时。
- 上报初始化耗时与失败计数。
- 容器启停记录事件。
- 看板关联发布与启动指标。
代码或图示
指标:bean.init.latency / bean.resolve.error / koin.startup.event
常见误区
- 每次解析都打点,指标基数与开销过大。
- 只监控 bean 不监控其外部资源初始化耗时。
追问
- 初始化失败怎么告警?答:启动阶段解析失败直接阻断启动并告警,不上线带病容器。
- 指标标签怎么避免高基数?答:按 bean 类型聚合,不携带实例 ID。
06.8.4.1-062 从手动 new 迁移到 Koin 的步骤是什么?
一句话结论
先抽接口与构造注入,再自下而上注册模块定义,启动装载后逐步替换手动构造;保持业务行为不变,分模块迁移并配合测试验证。
概念解释
手动 new 的对象往往自己获取依赖。迁移第一步让构造函数显式接收依赖,消除内部全局获取;再把对象关系搬进 Koin module。从叶子对象(repository)到上层(service/controller)逐步注册。
原理流程
- 梳理现有对象依赖图。
- 改造构造函数显式注入依赖。
- 自下而上编写 module 定义。
- 启动装载并替换手动 new,测试回归。
代码或图示
// 改造前:class UserService { val repo = UserRepository() }
// 改造后:class UserService(val repo: UserRepository)
// module:single { UserService(get()) }
常见误区
- 一次性全量迁移,问题集中爆发难定位。
- 保留内部手动 new,容器装配形同虚设。
追问
- 迁移期两种方式并存可以吗?答:可以按模块过渡,但同一对象归属要明确。
- 怎么验证迁移完整?答:检查代码中不再有业务对象手动构造,容器解析图覆盖全部服务。
06.8.4.1-063 模块依赖缺失怎么系统化定位?
一句话结论
沿构造参数链从报错类型向上游逐个核对 definition,配合模块装载清单与解析日志,找到第一个未注册节点;测试阶段用模块校验提前暴露。
概念解释
报错类型可能只是顶层服务,真正缺失的是其深层依赖。定位方法:看异常 cause 链,逐个检查构造参数类型是否注册。模块清单确认相关模块已装入。checkModules 可在不启动完整服务的情况下校验图完整。
原理流程
- 记录报错缺失类型。
- 找注册该类型的模块。
- 检查模块是否在启动模块树中。
- 递归核对其构造参数,直到找到缺失节点。
代码或图示
UserService 解析失败
→ 构造参数 UserRepository
→ UserRepository 构造参数 DataSource
→ DataSource 未注册(根因)
常见误区
- 只补报错类型的注册,不检查依赖链。
- 模块未 includes 却反复改 definition。
追问
- 校验模块能覆盖多实现歧义吗?答:按校验能力确认,歧义通常在解析或校验阶段暴露。
- 怎么减少深层缺失?答:模块按功能内聚,依赖链短而清晰。
06.8.4.1-064 qualifier 与实例持久化有什么关系?
一句话结论
qualifier 只是容器内查找键,不参与实例序列化、持久化或跨进程传输;实例状态由数据库/缓存保存,与限定符无关。
概念解释
限定符只在装配图内区分实现,落到数据库的是业务数据,不记录用了哪个 qualifier。跨进程重建实例时,由装配层根据环境重新选择实现。把实现选择状态写进业务数据是错误耦合。
原理流程
- 容器按 qualifier 选择实现。
- 实例处理业务数据落库。
- 重启后容器重新解析,环境决定实现。
- 持久化数据不携带 qualifier。
代码或图示
容器:qualifier → 实现选择
数据库:业务字段 → 数据状态
两者互不映射
常见误区
- 把实现类型存数据库当路由键,与装配层重复维护。
- 跨服务传输 qualifier 字符串,把容器概念泄漏到契约层。
追问
- 多渠道处理怎么标识?答:业务字段(渠道码)驱动,不在 DI 层做业务路由。
- 实现选择能按配置切换吗?答:可以,配置在装配层映射到 qualifier。
06.8.4.1-065 qualifier 命名有哪些团队规范?
一句话结论
限定符命名应稳定、可读、与业务概念对应;避免无意义编号,全局唯一,定义侧与解析侧共用同一命名常量,杜绝字符串散落。
概念解释
字符串 qualifier 散落在代码各处,重命名易漏。团队可把常用限定符定义为常量或枚举。命名表达实现用途(渠道、策略),不用 impl1/impl2。评审检查限定符清单。
原理流程
- 定义限定符常量/枚举。
- 注册与解析引用同一常量。
- 新增实现补充命名。
- 评审核对命名含义。
代码或图示
object Gateways { const val ALIPAY = "alipay" }
single<Gateway>(named(Gateways.ALIPAY)) { AlipayGateway() }
常见误区
- 限定符字符串硬编码两处,拼写不一致。
- 同一实现多个限定符别名,查找混乱。
追问
- 类型 qualifier 比字符串好在哪?答:编译期可重构,减少拼写错误;团队按规模选择。
- 限定符需要写进接口文档吗?答:多实现选择规则应在模块注释或接口说明中写明。
06.8.4.1-066 作用域嵌套是怎么回事?
一句话结论
部分版本支持父子作用域:子作用域查找不到时沿父作用域查找;子作用域关闭不影响父作用域实例。嵌套能力与 API 在 4.x 需对照文档确认(待确认)。
概念解释
嵌套让公共对象挂在父作用域,子作用域持有各自私有实例。典型层级:会话作用域为父,请求作用域为子。查找链方向与关闭顺序要明确。不支持嵌套时,跨层共享对象上提到 single。
原理流程
- 创建父作用域并注册共享实例。
- 子作用域挂到父作用域下创建。
- 子作用域查找先查自身再查父。
- 子作用域关闭释放自身实例。
代码或图示
SessionScope(父)
└─ RequestScope(子,按请求创建关闭)
常见误区
- 假设支持嵌套,实际版本不支持导致解析失败。
- 子作用域关闭误释放父作用域实例。
追问
- 服务端需要会话级作用域吗?答:无状态服务通常请求级足够;有会话状态需求再评估嵌套。
- 嵌套查找顺序怎么验证?答:最小用例注册父子定义,断言子作用域解析结果。
06.8.4.1-067 作用域关闭后再解析其中 bean 会怎样?
一句话结论
已关闭作用域的 scoped 实例不再可用,再次解析应报错或创建新作用域;继续持有旧实例引用属于误用。具体异常类型待确认。
概念解释
作用域关闭意味着生命周期结束,缓存与释放回调已执行。关闭后解析同作用域类型,容器找不到活动作用域。业务代码应在作用域存活期内完成解析与使用。
原理流程
- 业务使用完作用域调用 close。
- scoped 实例释放。
- 后续解析请求落到已关闭作用域 → 异常。
- 新生命周期创建新作用域。
代码或图示
scope.close()
// scope.get<RequestContext>() // 不应再调用
常见误区
- 异步任务在作用域关闭后才执行,访问 scoped bean 报错。
- 关闭时机过晚,作用域实例堆积。
追问
- 怎么避免异步回调访问已关闭作用域?答:提交任务时传不可变数据快照,不在任务内取作用域 bean。
- 作用域能复用 reopen 吗?答:按版本能力确认,通常关闭即结束,新建独立作用域。
06.8.4.1-068 scoped 与 factory 场景下有哪些内存泄漏形态?
一句话结论
泄漏来源:作用域只创不闭、single 持有大对象引用、factory 实例被长期缓存、闭包捕获外部大对象;治理靠作用域闭环、生命周期钩子与引用审查。
概念解释
scoped 实例未随作用域释放就堆积;factory 本应短生命周期却被 single 字段长期持有,等于变相单例。容器自身不主动清理使用方持有的引用。堆 dump 分析大对象引用链可定位泄漏 bean。
原理流程
- 检查作用域创建/关闭配对。
- 审查 single 字段是否缓存 factory 实例。
- 检查 definition 闭包捕获的外部引用。
- 堆分析确认残留实例链。
代码或图示
泄漏路径:作用域未 close / factory 被 long-lived 持有 / 闭包捕获大对象
常见误区
- 以为容器会自动回收所有 bean 实例。
- 只关注 single 泄漏,忽略作用域堆积。
追问
- 作用域数量怎么监控?答:统计活动作用域数与创建/关闭差值。
- 怎么测试作用域释放?答:用例创建关闭后断言实例可回收、钩子被调用。
06.8.4.1-069 Koin 是否支持按条件注册 definition?
一句话结论
是否提供声明式条件注册(按属性/平台开关)以 4.x 能力为准(待确认);通用做法是在装配层按环境选择模块,definition 本身保持无条件注册。
概念解释
条件装配在 Spring 中常见,Koin 核心更倾向模块组合表达差异。需要开关控制实现时,启动时选择装载哪个模块。definition lambda 内写 if/else 虽然可行,但把装配决策混进构造逻辑,不推荐。
原理流程
- 读取环境/属性开关。
- 装配层选择对应模块集合。
- definition 注册确定实现。
- 未装载模块不参与解析。
代码或图示
val modules = if (featureX) listOf(xModule) else emptyList()
常见误区
- 在 lambda 内读全局开关切换实现,行为难以预测。
- 期待注解式条件装配却找不到对应能力。
追问
- 条件注册能力怎么核实?答:查 4.x 文档 definition DSL 是否提供 conditional/on 一类 API。
- 开关关闭的实现留代码吗?答:保留实现与模块,不装载即可,便于回滚。
06.8.4.1-070 definition 能用工厂方法或构造引用吗?
一句话结论
definition lambda 内可调用任意工厂方法、构造引用或静态创建逻辑;容器只要求 lambda 返回实例,构造细节由代码决定。
概念解释
除直接构造函数外,第三方建造器、工厂类、依赖注入容器包装都可在 lambda 内调用。复杂构造步骤封装到工厂类,module 保持简洁。工厂方法本身的依赖通过 get() 解析。
原理流程
- definition lambda 调用工厂方法。
- 工厂内部组装对象。
- 返回实例交给容器缓存。
- 多步构造的容错与日志在工厂内处理。
代码或图示
single { HttpClientFactory.create(get()) }
常见误区
- module 内堆复杂构造逻辑,难以测试。
- 工厂方法内部又手动获取全局资源,绕过容器。
追问
- 工厂方法需要注册进容器吗?答:无状态工厂可 object;有依赖则注册为 bean。
- 构造参数在工厂内解析还是 module 解析?答:优先在 definition 层
get显式传入,工厂只做组装。
06.8.4.1-071 模块内 definition 排列顺序有约定吗?
一句话结论
建议按依赖层次排列:基础配置与客户端在上,repository/service 在下,便于阅读依赖方向;注册顺序通常不影响解析结果,但影响定义清单可读性。
概念解释
DSL 模块文件自上而下阅读,从底层组件到上层服务符合依赖方向。同层定义分组排列。顺序对解析的影响仅限重复定义覆盖场景,正常依赖按类型查找。团队在模块模板中固定排列约定。
原理流程
- 配置对象定义在前。
- 基础设施客户端定义。
- repository 定义。
- service/controller 定义在后。
代码或图示
module {
single { config }
single { HttpClient(get()) }
single { UserRepository(get()) }
single { UserService(get()) }
}
常见误区
- 上层服务定义写在依赖之前,阅读时反复跳转。
- 同模块 definition 按文件提交历史乱序,评审困难。
追问
- 顺序会影响覆盖吗?答:重复定义时后注册可能覆盖先注册,见覆盖规则题目。
- 模块很长怎么拆?答:按功能拆子模块 includes 组合。
06.8.4.1-072 多实现按配置选择策略怎么落地?
一句话结论
各实现带 qualifier 注册,装配层读取配置选择对应 qualifier 注入主服务;或按环境装载对应模块覆盖默认实现。业务代码不判断渠道字符串。
概念解释
策略选择是装配决策,不应散落在业务分支。配置值映射到 qualifier 或模块选择。新增渠道只需加实现定义与配置项。选择规则集中在装配层,便于测试覆盖各分支。
原理流程
- 注册各策略实现并标注 qualifier。
- 配置项声明渠道标识。
- 装配层把配置映射为 qualifier/模块。
- 主服务接收选定实现。
代码或图示
val gateway: PaymentGateway = when (channel) {
"alipay" -> get(named(Gateways.ALIPAY))
else -> get(named(Gateways.DEFAULT))
}
常见误区
- 业务代码内 if/else 选择实现,策略散落。
- 配置值未校验,落到未注册 qualifier 解析失败。
追问
- 策略集合需要全部加载吗?答:按场景,固定渠道选择单实现;插件式遍历全部实现。
- 配置非法怎么启动失败?答:启动校验配置映射到合法 qualifier,不合法即报错。
06.8.4.1-073 关键 bean 要不要启动预热?
一句话结论
核心链路重型 bean(客户端、连接池)可在启动后预热,缩短首请求延迟;非关键 bean 保持懒加载。预热要记录耗时并纳入启动健康检查。
概念解释
预热即启动阶段主动 get 触发构造与外部连接建立。权衡:启动时间换首请求响应。预热失败应阻断启动。预热清单按核心链路确定,避免把全部 bean 拉进来。
原理流程
- 列出核心链路必须就绪的 bean。
- 启动完成后按序主动解析。
- 记录各 bean 初始化耗时。
- 预热失败返回启动失败。
代码或图示
startKoin { modules(appModule) }
listOf(DataSource::class, HttpClient::class).forEach { get(it) }
常见误区
- 全量预热,启动时间被非关键组件拖长。
- 预热异常被吞,带病上线首请求才暴露。
追问
- 预热与懒加载矛盾吗?答:不矛盾,按 bean 分级选择。
- 怎么确定预热清单?答:从核心请求链路反向梳理依赖。
06.8.4.1-074 容器关闭时实例释放顺序怎么安排?
一句话结论
关闭先停接收新请求的入口与后台任务,再释放依赖被使用的组件,最后关闭基础资源;关闭钩子容错执行,单个失败不阻断其他释放。
概念解释
实例依赖方向反向即释放方向:上层先停,底层后释放。容器关闭回调按实现顺序执行(具体顺序保证待确认)。HTTP 服务、调度器先停止,客户端与连接池后关闭。停机流程与优雅停机整体配合,见 06.8.5.3。
原理流程
- 停止流量入口与后台调度。
- 等待在途任务完成。
- 触发 bean 关闭回调。
- 释放客户端/连接池等基础资源。
代码或图示
关闭顺序:入口/调度器 → 业务服务 → repository → 客户端/连接池
常见误区
- 基础资源先关闭,上层 bean 释放时仍引用已关闭客户端。
- 关闭回调抛异常中断后续释放。
追问
- 关闭顺序有官方保证吗?答:按容器实现的回调顺序确认(待确认);关键资源在应用层显式编排关闭。
- 释放超时怎么办?答:设置关闭超时,记录未释放资源并告警。
06.8.4.1-075 Koin 与 Ktor 怎么集成?
一句话结论
Ktor 通过 Koin 插件装载模块,路由与组件从 Koin 容器解析;集成方式与插件坐标在 4.x/Ktor 3.x 下需对照官方文档确认(待确认)。
概念解释
Ktor 应用装配 Koin module,路由处理器通过容器获取 service。插件负责把容器接入应用生命周期。服务端模块定义与 Ktor 路由解耦:路由只编排,业务在 service。Ktor 基础管道见 06.8.1。
原理流程
- 安装 Koin 插件并装载模块。
- 容器随应用启动。
- 路由处理函数解析 service。
- 应用关闭时容器释放。
代码或图示
// 集成插件 API 名称以官方文档为准(待确认)
fun Application.module() {
install(Koin) { modules(appModule) }
routing { /* get<OrderService>() */ }
}
常见误区
- 在路由内直接 new service,绕过容器。
- 模块在插件外重复启动,双容器。
追问
- Ktor 测试怎么替换 bean?答:测试应用装载覆盖模块,见 06.8.4.2。
- 插件版本与 Koin 版本兼容?答:对照兼容矩阵确认(待确认)。
06.8.4.1-076 Koin 解析与协程上下文有什么关系?
一句话结论
Koin 容器解析本身不绑定协程上下文,bean 实例在哪个线程解析就使用哪个线程;请求作用域数据要随协程上下文显式传递,容器不自动复制协程局部状态。
概念解释
DI 容器是线程安全的注册表,解析动作可在任意线程发起。协程切换线程后,容器仍可解析 single;但请求级上下文(MDC、用户信息)不在容器内,需要随上下文传递。scoped 实例的获取要在持有作用域引用的代码路径上。
原理流程
- 协程在某线程发起解析。
- 容器线程安全查找 definition。
- 实例返回协程继续使用。
- 请求上下文通过参数/上下文元素传递。
代码或图示
suspend fun handler(): Unit = withContext(Dispatchers.IO) {
val service: OrderService = get() // 容器解析与调度器无关
}
常见误区
- 以为容器自动跟随协程上下文传播请求作用域。
- 跨线程持有作用域引用却在错误上下文解析。
追问
- 请求作用域怎么在协程间传递?答:作用域引用作为参数或放入协程上下文元素显式传递。
- MDC 与协程传递见 06.8.5.2。
06.8.4.1-077 怎么断言容器提供的是预期实现?
一句话结论
测试中解析类型后断言实例类型/限定符对应实现;接口绑定与装饰链用实例类型检查验证,确保装配选择符合预期。
概念解释
装配错误(解析到错误实现)不会在编译期暴露,需要测试断言。结合模块校验与解析断言,覆盖多实现选择分支。断言检查类型、qualifier 与实例身份。
原理流程
- 装载目标模块。
- 解析类型实例。
- 断言实现类/限定符。
- 多实现分支分别用例覆盖。
代码或图示
val gateway = koin.get<PaymentGateway>(named(Gateways.ALIPAY))
assertThat(gateway).isInstanceOf(AlipayGateway::class.java)
常见误区
- 只断言接口可解析,不核对具体实现。
- 测试用生产模块未覆盖多实现分支。
追问
- 装饰器链怎么断言?答:检查外层装饰器类型并解包到内层实现。
- 断言实例身份用什么?答:
===验证 single 复用,isInstanceOf验证实现。
06.8.4.1-078 模块加载失败怎么处理?
一句话结论
模块注册阶段失败(语法/重复定义)在启动期暴露;构造失败在解析期暴露。启动失败应快速中止并记录模块与 definition 信息,不带病上线。
概念解释
加载失败分两类:注册时 definition 异常、解析时构造异常。启动阶段校验模块可提前发现注册问题。外部资源构造失败属于启动失败,应退出进程由编排层重启。
原理流程
- 启动装载模块,捕获注册异常。
- 预热/校验解析,捕获构造异常。
- 记录失败模块与类型。
- 非可恢复错误中止启动。
代码或图示
启动失败 → 记录模块/definition/异常 cause → 进程退出 → 编排层重启或告警
常见误区
- 构造外部资源失败被 catch 后继续启动,后续请求连环报错。
- 异常日志缺少模块上下文,定位困难。
追问
- 哪些失败可降级继续?答:可选扩展点缺失可降级;核心依赖缺失不可降级。
- 启动重试策略?答:由部署编排控制,应用内不无限重试启动。
06.8.4.1-079 全局 Koin 实例怎么访问?
一句话结论
startKoin 后可通过全局入口解析 bean;业务组件优先构造注入,全局入口只在框架边界/桥接处使用,避免服务定位器泛滥。全局访问 API 名称在 4.x 待确认。
概念解释
全局实例是启动容器的单例引用。直接在代码各处 GlobalKoin.get() 形成服务定位器反模式,依赖不显式。框架插件需要全局入口时使用,业务类构造函数接收依赖。
原理流程
startKoin设置全局容器。- 边界处通过全局入口解析。
- 解析结果作为依赖传入业务组件。
- 业务类不持有全局容器引用。
代码或图示
// 边界:解析后注入
val service = koin.get<UserService>()
// 业务类:class UserController(val service: UserService)
常见误区
- 业务方法内随时
get(),依赖关系不可见。 - 测试中不重置全局实例,跨用例污染。
追问
- 全局实例与独立容器能共存吗?答:全局默认一个,独立容器手动持有。
- 服务定位器反模式详解见 06.8.4.2。
06.8.4.1-080 什么时候需要多容器隔离?
一句话结论
多容器用于测试隔离、插件子系统独立生命周期或多应用组合;常规服务端单容器即可。多容器间定义不共享,实例互不影响。
概念解释
独立 koinApplication 持有自己的注册表与缓存,不写入全局状态。测试用多容器避免单例串扰。子系统可拥有独立作用域容器。跨容器对象传递由业务代码显式完成。
原理流程
- 按子系统/测试边界创建独立容器。
- 各自装载模块。
- 容器间不互相解析。
- 用完关闭独立容器。
代码或图示
val testKoin = koinApplication { modules(testModule) }.koin
常见误区
- 测试用全局容器又不重置,比多容器更易串扰。
- 独立容器忘记关闭,资源泄漏。
追问
- 多容器共享公共模块吗?答:可装载同一 module 定义,但实例各自独立。
- 生产需要多容器吗?答:少见,通常单容器按模块/作用域划分足够。
06.8.4.1-081 实例化时机如何影响可测试性?
一句话结论
懒加载让构造错误延迟到解析点,测试需主动解析覆盖;显式构造注入使依赖可在单测中直接传替身。实例化时机越晚,启动校验越要补齐。
概念解释
懒加载降低启动成本,但未被测试解析到的路径问题不会暴露。单测直接 new 业务类传替身,不经过容器;集成测试启动容器解析真实图。两种测试覆盖不同时机风险。
原理流程
- 单测:构造函数直接传 mock。
- 集成测试:容器解析真实依赖图。
- 校验模块检查未解析路径的定义完整性。
- 运行期解析错误由日志与监控兜底。
代码或图示
@Test
fun `business rule`() {
val svc = UserService(FakeRepository()) // 不启动容器
}
常见误区
- 只做单测,容器装配图从未被集成测试启动。
- 懒加载 bean 构造错误上线后才爆发。
追问
- 怎么覆盖未解析路径?答:
checkModules+ 集成测试核心链路。 - 构造注入与时机关系?答:构造注入让实例化依赖显式,测试可绕开容器。
06.8.4.1-082 Koin 4.x 相对 3.x 有哪些需要关注的变化?
一句话结论
4.x 在 KMP 支持、注解集成与部分 API 上有调整,具体 breaking changes 以官方 changelog 为准(待确认);升级时按版本说明逐项核对 import 与 API 调用。
概念解释
大版本升级可能调整模块坐标、DSL 方法名与作用域 API。本项目基线 4.x,教程示例若来自 3.x 需甄别。升级前在分支升级依赖、编译并跑测试,记录 API 适配点。
原理流程
- 阅读 4.x changelog 与迁移指南。
- 升级依赖版本。
- 编译修复不兼容调用。
- 运行解析测试回归。
代码或图示
待确认:3→4 作用域 API、注解坐标、日志 API、模块组合 API 的改名清单
常见误区
- 按 3.x 记忆写 4.x 代码,签名对不上。
- 升级不跑全量测试,运行期 API 错误残留。
追问
- 怎么查官方迁移说明?答:Koin 官方仓库 release notes 与文档目录,对照当前依赖版本。
- 不确定行为标什么?答:标「待确认」并写明最小验证用例。
06.8.4.1-083 Koin Annotations 方案有哪些限制?
一句话结论
注解方案依赖 KSP 编译期处理,模块组合与生成规则受注解库能力约束;复杂条件装配、动态作用域表达可能仍需 DSL 补充。具体限制以 4.x 注解模块文档为准(待确认)。
概念解释
注解把装配信息放在类上,跨模块组合通过 @Module/includes 声明。编译期生成在构建期可见错误有限,运行时解析行为与 DSL 一致。KMP 下各平台 KSP 生成需验证。
原理流程
- 类标注定义类型注解。
- KSP 扫描生成 module。
- 启动装载生成模块。
- 复杂场景回退 DSL 补充。
代码或图示
@Single
class OrderService @Inject constructor(val repo: OrderRepository)
常见误区
- 注解覆盖不了的装配需求硬写注解,生成结果不符合预期。
- KSP 未正确配置,类标注了但生成模块缺失。
追问
- 注解与 DSL 能在同一项目共存吗?答:可共存,但定义来源要清晰,避免重复注册。
- 生成代码难调试怎么办?答:查看 KSP 生成目录,必要时回 DSL 表达。
06.8.4.1-084 definition lambda 内做重计算有什么性能误区?
一句话结论
构造 lambda 只做对象组装,重计算、IO、循环解析应移出;构造慢会放大到首次解析线程与预热阶段。
概念解释
definition lambda 执行一次(single)或每次执行(factory)。lambda 内做复杂解析、批量加载、网络等待,直接拖慢解析。重型资源在构造时建立连接属可接受范围,但数据计算应延迟到使用时。
原理流程
- 检查构造 lambda 内容。
- 纯组装留 lambda,计算/IO 移出。
- 重资源连接按需建立。
- 构造耗时纳入启动监控。
代码或图示
// 推荐:lambda 只组装
single { OrderService(get(), config) }
常见误区
- factory lambda 内做重初始化,每次新建重复付出成本。
- 构造内启动线程未登记关闭。
追问
- 构造时必须加载配置怎么办?答:启动时组装配置对象,构造只接收值。
- 怎么测构造耗时?答:解析阶段计时上报,定位慢 bean。
06.8.4.1-085 作用域参数怎么传递?
一句话结论
创建作用域或解析 scoped bean 时可传入参数,供作用域内 definition 使用;参数随作用域生命周期,具体传参 API 形式在 4.x 待确认。
概念解释
作用域参数携带该生命周期共享的数据(请求 ID、租户标识)。scoped definition 读取参数构造上下文对象。参数不同于 factory 每次调用参数,它在作用域内稳定。
原理流程
- 创建作用域时附带参数。
- scoped definition 声明参数读取。
- 作用域内解析使用同一参数。
- 作用域关闭参数释放。
代码或图示
val scope = koin.getOrCreateScope(id, qualifier<RequestMarker>(), /* params 待确认 */)
常见误区
- 把可变请求状态放进作用域参数,跨请求污染。
- 参数类型未声明,解析时取不到。
追问
- 作用域参数与 single 配置区别?答:参数按生命周期实例独立,single 配置全局共享。
- 参数校验在哪做?答:创建作用域前校验,非法请求直接拒绝。
06.8.4.1-086 作用域内实例释放顺序要注意什么?
一句话结论
作用域关闭时先释放持有业务状态的 scoped bean,再释放其引用的资源;释放回调内不要再解析其他 bean。具体顺序保证按容器实现确认(待确认)。
概念解释
同作用域 bean 间有依赖时,释放方向与构造方向相反。回调内重新 get 可能拿到已关闭状态。跨作用域依赖(single)不在作用域关闭时释放。
原理流程
- 作用域关闭触发回调。
- 上层 bean 先释放。
- 资源 bean 后释放。
- 回调内不做跨 bean 解析。
代码或图示
构造:Context → Client
释放:Context 先关 → Client 后关
常见误区
- 回调内访问其他 scoped bean,状态已释放。
- 释放回调抛异常中断同作用域其他 bean 清理。
追问
- 释放顺序不确定怎么兜底?答:资源在应用级 single 统一管理,作用域只持短生命周期状态。
- 回调怎么测?答:用例关闭作用域后断言钩子调用与资源释放。
06.8.4.1-087 bean 类型命名如何体现业务语义?
一句话结论
类型名表达职责与业务概念,避免 Manager/Helper/Util 泛称;接口名描述能力,实现名描述技术手段,评审可读装配图。
概念解释
DI 图中类型名即组件身份。PaymentGateway 比 PayManager 清晰,SqlUserRepository 表达实现方式。命名与包结构对齐业务模块。新增实现沿用接口命名体系。
原理流程
- 接口按能力命名。
- 实现按技术/渠道后缀命名。
- 类型名进入模块注释。
- 评审检查命名泛化。
代码或图示
interface PaymentGateway
class AlipayGateway : PaymentGateway
class JdbcOrderRepository : OrderRepository
常见误区
- 名称泛化,装配图看不出职责。
- 实现名与接口名混淆,解析定位困难。
追问
- DTO/配置类命名冲突?答:按模块包隔离,类型名带业务前缀。
- 改名影响 DI 吗?答:类型重命名同步更新 definition 与解析点。
06.8.4.1-088 配置对象怎么注入并做启动校验?
一句话结论
启动时把环境变量/属性组装为类型安全配置 data class,校验必填与范围后注册 single;bean 依赖配置对象而不是散装属性。
概念解释
散装 getProperty 散落在各 definition,类型转换与校验重复。统一配置对象在启动阶段组装、校验,非法配置直接失败。配置对象不可变,single 注入。配置校验细节见 06.8.5.2。
原理流程
- 读取原始属性。
- 组装配置 data class 并校验。
- 注册配置对象 single。
- 各 bean 注入配置对象。
代码或图示
data class DbConfig(val poolSize: Int, val url: String)
val config = DbConfig(...) // 启动校验后
module { single { config } }
常见误区
- bean 内各自读属性,校验口径不一致。
- 配置非法延迟到首次使用才报错。
追问
- 敏感配置进配置对象安全吗?答:对象内存持有,日志脱敏;来源走 Secret 注入。
- 配置变更要重建 bean 吗?答:不可变配置随重启生效;热更新见配置章节。
06.8.4.1-089 外部客户端组件怎么纳入容器生命周期?
一句话结论
HTTP/RPC/MQ/数据库客户端注册为 single,构造读取配置,登记关闭回调;业务代码通过接口使用,便于测试替换与统一释放。
概念解释
外部客户端持有连接、线程池等重资源,必须纳入容器关闭流程。包装自身接口隔离第三方实现。客户端配置从配置对象注入。多个同类客户端按 qualifier 区分。
原理流程
- 注册客户端 single。
- 构造建立连接/线程池。
- 登记关闭回调。
- 容器关闭时释放。
代码或图示
single {
val client = HttpClient(config)
// 关闭回调待确认 API
client
}
常见误区
- 客户端在静态块/object 中自建,容器关闭不释放。
- 每个业务类 new 一个客户端实例,连接数膨胀。
追问
- 客户端线程池怎么配?答:与并发量级和外部承载匹配,见部署与性能章节。
- 客户端健康检查放哪?答:Actuator/健康端点调用客户端状态,见 06.8.5.2。
06.8.4.1-090 插件模块的装配开关怎么管理?
一句话结论
插件模块按配置开关在启动装配层决定是否装载;未装载插件不注册实现,主流程走默认行为。开关清单集中管理并可审计。
概念解释
开关控制模块 includes,而不是在 definition 内判断。插件自身代码保留,便于回滚。开关默认值、生效条件写入配置说明。未装载插件的扩展点由主服务降级处理。
原理流程
- 配置读取插件开关。
- 装配层条件追加插件模块。
- 主服务集合注入可用扩展。
- 无插件时默认行为生效。
代码或图示
val modules = buildList {
add(commonModule)
if (plugins.exportEnabled) add(exportModule)
}
常见误区
- 开关判断写进业务代码,主流程分支膨胀。
- 插件模块默认装载,关闭开关不生效。
追问
- 插件失败影响主流程吗?答:可选插件初始化失败应隔离,不阻断核心启动。
- 开关变更需要重启吗?答:模块装载在启动期,热替换能力有限,按部署策略处理。
06.8.4.1-091 测试如何访问 internal 定义?
一句话结论
测试通过 public 接口解析与断言,不直接访问 internal 实现类;需要直接构造替身时,替身实现 public 接口。Kotlin 可见性与测试源集配置配合。
概念解释
internal 类在同模块测试源集可见,跨模块测试只能依赖 public 接口。测试替换通过接口绑定覆盖实现,不打开实现类可见性。模块封装保持,测试不破坏边界。
原理流程
- 测试装载模块解析 public 接口。
- 断言行为与类型。
- 替身实现 public 接口注册覆盖。
- 不引用 internal 实现细节。
代码或图示
class FakeExporter : Exporter // 测试替身实现接口
常见误区
- 为测试把实现类改 public,边界泄漏。
- 测试断言 internal 方法细节,实现变更导致测试脆弱。
追问
- 同模块 internal 可直接测吗?答:可以,但优先测公开行为。
- 跨模块集成测试怎么做?答:通过接口与配置驱动。
06.8.4.1-092 怎么在测试中验证 single 实例身份复用?
一句话结论
同一容器内连续解析两次,用引用相等 === 断言同一实例;不同作用域/容器解析应得到独立实例,验证缓存层级符合预期。
概念解释
身份断言区分 single/scoped/factory 语义。测试用例独立容器,避免全局单例干扰。验证 factory 每次新建、scoped 作用域内复用、跨作用域隔离。
原理流程
- 装载模块。
- 连续解析两次。
- 断言引用相等/不等。
- 覆盖各 definition 语义。
代码或图示
val a = koin.get<DataSource>(); val b = koin.get<DataSource>()
assertThat(a).isSameAs(b) // single 复用
常见误区
- 全局容器残留其他用例实例,身份断言不准。
- 混淆值相等与引用相等。
追问
- 装饰器包装后身份怎么算?答:外层装饰器同一实例,内层被包装实例按其 definition 语义判断。
- 作用域复用怎么测?答:同作用域两次解析相等,不同作用域不等。
06.8.4.1-093 同一 module 如何派生多套变体?
一句话结论
module 写成接收配置/依赖参数的工厂函数,按环境生成变体;公共 definition 复用,差异通过覆盖模块或参数注入表达。
概念解释
module 本身是代码块,可封装为函数接收配置。变体差异小用参数注入,差异大用独立模块覆盖。避免复制粘贴整份 module 造成两份维护。
原理流程
- 抽取公共 module 工厂。
- 环境参数传入配置对象。
- 差异实现由覆盖模块提供。
- 各环境装载对应组合。
代码或图示
fun dataModule(cfg: DbConfig) = module {
single { DataSource(cfg) }
}
常见误区
- 复制多份 module 文本,definition 不同步。
- 变体差异靠模块内 if 分支,组合关系不清晰。
追问
- 变体之间共享 single 吗?答:不同容器实例独立;同容器内按定义语义复用。
- 测试变体怎么组织?答:测试工厂生成对应模块,不复制生产定义。
06.8.4.1-094 启动自检要校验哪些关键 bean?
一句话结论
启动后主动解析核心链路 bean 并检查外部资源连通性;关键配置完整、客户端可连接、核心 service 可构造,作为就绪检查的一部分。
概念解释
自检覆盖容器解析图与外部依赖连通性。bean 可构造不代表外部资源可用,客户端健康检查单独执行。自检失败进入未就绪状态,不接流量。自检清单从核心链路梳理。
原理流程
- 容器启动装载模块。
- 解析核心 bean 触发构造。
- 检查客户端/数据源连通。
- 就绪端点通过后开放流量。
代码或图示
自检:核心 bean 可解析 → 数据源连通 → 客户端可达 → 就绪
常见误区
- 只检查进程存活,不检查依赖连通。
- 自检在错误作用域解析 bean,结果不代表实际链路。
追问
- 自检与健康检查关系?答:启动自检属于就绪检查前置,探针设计见 06.8.5.3。
- 自检慢怎么办?答:区分必需检查与可选检查,并行探测外部依赖。
06.8.4.1-095 Koin 使用边界与服务定位器的分界是什么?
一句话结论
构造注入是组件显式声明依赖;在组件内部主动从容器 get() 属于服务定位器。本篇使用 Koin API,架构层面反模式判定与重构在 06.8.4.2 展开。
概念解释
DI 容器本身是装配工具,组件是否感知容器决定模式性质。构造函数接收依赖,组件不持有容器引用;内部 get() 使组件与容器耦合。边界评审:组件构造参数是否列出全部依赖。
原理流程
- 组件构造函数声明依赖。
- 容器在装配点传入。
- 组件不调用容器 API。
- 内部
get()出现即评审重构。
代码或图示
// 推荐:构造注入
class OrderService(val repo: OrderRepository)
// 反模式:内部定位
class OrderService { val repo: OrderRepository get() = koin.get() }
常见误区
- 把容器传进业务组件到处取依赖。
- 认为用了 Koin 就是 DI,不管注入方式。
追问
- 框架强制需要容器引用怎么办?答:边界组件持有,向内层传递依赖。
- 反模式清单与重构见 06.8.4.2。
06.8.4.1-096 本篇版本基线与适用范围是什么?
一句话结论
本篇以 Koin 4.x、Kotlin 2.x、Ktor 3.x 服务端为基线;Android/Compose 端侧 DI 实践归 07 分册,Spring 容器对比归 06.8.4.2。
概念解释
服务端关注点:模块装配、作用域、限定符、测试与架构边界。移动端生命周期组件(ViewModel 宿主)不在本篇展开。跨方案对比、AOT 冲突与反模式在姊妹篇覆盖。
原理流程
- 核对依赖版本基线。
- 服务端场景组织题目。
- 端侧内容引用 07 分册。
- 对比内容引用 06.8.4.2。
代码或图示
基线:Koin 4.x / Kotlin 2.x / Ktor 3.x
分工:API 机制在本篇;对比与架构在 06.8.4.2;端侧在 07
常见误区
- 把移动端 ViewModel 作用域概念套到服务端。
- 跨篇复述 DI 方案对比。
追问
- 版本行为不确定怎么办?答:标「待确认」并给验证点,不编造 API。
- 基线之外的老版本要兼容吗?答:面试以当前基线回答,差异注明版本范围。
06.8.4.1-097 本篇有哪些待核实的 Koin 4.x API?
一句话结论
待核实项包括:作用域创建/关闭 API 名称、getOrNull 命名、关闭钩子 API、集合绑定注入形式、条件注册能力、注解模块坐标与 KSP 集成方式。
概念解释
这些 API 在 3.x→4.x 可能改名或调整,面试与写代码前对照官方文档与当前依赖源码验证。稳定的概念模型(single/factory/scoped 语义、查找键组成、缓存层级)不随 API 名变化。
原理流程
- 列出使用到的 API。
- 查 4.x 文档与 release notes。
- 最小用例编译运行验证。
- 未确认处保留待确认标注。
代码或图示
待确认:scope 创建/关闭 / getOrNull / onClose 钩子 / 集合绑定 / 条件注册 / 注解坐标
验证点:依赖版本、官方文档版本、最小可运行示例
常见误区
- 凭教程记忆写 API 名,编译才发现改名。
- 把未验证 API 写成确定结论。
追问
- 怎么判断文档版本是否对应 4.x?答:看文档侧边栏版本与 artifact 版本号。
- 源码行为与文档不一致?答:以实际运行源码为准,记录差异。
06.8.4.1-098 场景题:多渠道支付服务怎么用 Koin 装配?
一句话结论
定义 PaymentGateway 接口,各渠道实现带 qualifier 注册,配置选择渠道注入 PaymentService;集合注入用于全渠道对账,单体选择用于收单。
概念解释
收单按配置选单渠道实现,对账遍历全部渠道。渠道实现独立模块,新增渠道加定义与配置项。支付服务只依赖接口,渠道切换不动业务代码。作用域为应用级 single。
原理流程
- 公共模块定义接口与支付服务。
- 各渠道模块注册 qualifier 实现。
- 配置映射渠道选择。
- 收单单选、对账集合注入。
代码或图示
module {
single<PaymentGateway>(named("alipay")) { AlipayGateway() }
single<PaymentGateway>(named("wechat")) { WechatGateway() }
single { PaymentService(get(named(config.channel))) }
}
常见误区
- 支付服务内 if/else new 各渠道,新增渠道改业务代码。
- 渠道实现持有请求级状态却注册 single。
追问
- 渠道配置非法怎么处理?答:启动校验渠道值对应已注册实现,否则启动失败。
- 渠道客户端配置隔离?答:每渠道独立配置对象注入对应实现。
06.8.4.1-099 场景题:服务端请求级上下文怎么用作用域落地?
一句话结论
每请求创建标记类型作用域,scoped 注册请求上下文与依赖请求数据的组件,请求结束关闭作用域;请求数据快照传入,异步任务不持有作用域。
概念解释
请求级对象(上下文、用户信息、链路 ID)需要每请求独立。作用域在请求开始创建、结束关闭,避免 single 串扰。框架管道负责作用域生命周期挂钩。具体作用域 API 待确认。
原理流程
- 请求到达,创建请求作用域。
- 作用域内解析上下文与组件。
- 业务处理完成。
- 响应返回后关闭作用域。
代码或图示
// 意图示例;作用域 API 名称待确认
val scope = koin.getOrCreateScope(requestId, qualifier<RequestMarker>())
try { handle(scope.get<RequestContext>()) } finally { scope.close() }
常见误区
- 请求对象注册 single,跨请求状态串扰。
- 异步任务持有已关闭作用域引用。
追问
- 作用域创建挂在框架哪一层?答:请求管道拦截器,与认证/日志同层。
- 没有显式作用域能力的版本怎么替代?答:请求上下文随参数/协程上下文传递,组件不存请求状态。
06.8.4.1-100 场景题:评审一份 Koin 模块定义,检查清单有哪些?
一句话结论
清单覆盖:构造注入优先、类型绑定完整、qualifier 一致、definition 语义正确、作用域闭环、无循环依赖、资源有释放回调、模块方向合理、测试可替换。
概念解释
评审 DI 装配图与评审代码同等重要。逐项核对依赖方向、生命周期选择、多实现区分与资源释放。发现服务定位器、循环依赖、泄漏风险记录整改。清单纳入团队模板。
原理流程
- 检查 definition 类型与绑定。
- 核对 qualifier 与解析点一致。
- 审查生命周期选择与作用域闭环。
- 检查资源回调、模块方向与可测试性。
代码或图示
评审清单:注入方式 / 绑定 / qualifier / 语义 / 作用域 / 循环 / 释放 / 方向 / 测试替换
常见误区
- 只看能否解析通过,不审查生命周期与方向。
- 评审记录不沉淀,同类问题反复出现。
追问
- 工具能自动检查吗?答:模块校验 + 架构守护测试覆盖部分项,人工评审补充方向与语义判断。
- 评审发现的问题怎么分级?答:阻塞项(循环、泄漏)合并前修,建议项(命名、拆分)排期优化。
参考来源
- Koin 官方文档:DSL 与模块定义 — single/factory/scoped、module 与 qualifier 用法说明。
- Koin 官方文档:作用域(Scopes) — 作用域创建、复用与关闭机制。
- Koin 官方文档:启动与模块组装 — startKoin/koinApplication 与模块加载。
- Koin Annotations 官方说明 — 注解定义与 KSP 集成(以当前版本目录为准)。
- Koin GitHub 仓库与 Release Notes — 版本变更、模块坐标与待确认 API 核对来源。
待整理清单
- [ ] 核对 Koin 4.x 作用域创建/关闭、
getOrNull、关闭钩子、集合绑定注入的准确 API 名称 - [ ] 核实 4.x 是否提供条件注册 definition 与父子作用域嵌套能力
- [ ] 确认 4.x 核心、注解/KSP、KMP 各模块 Gradle 坐标与包名前缀
- [ ] 整理 3.x 到 4.x 的 breaking changes 与迁移 API 清单
- [ ] 验证 Koin 与 Ktor 3.x 集成插件的当前 artifact 与安装方式
- [ ] 待确认:Koin 内部注册表与初始化同步机制的源码级实现细节