设计或评审 Kotlin 公开 API 时：决定函数归属…

在 Kotlin（含 KMP）中设计或审查函数归属、成员/扩展函数、工厂、单字段领域类型、value class、data class、expect/actual 声明与平台服务边界时使用。

适用场景

解决思路

1. 把行为、类型和平台接缝放在对调用方来说含义最清晰的位置；公开抽象只选用能保留领域语言与平台独立性的最小抽象。
2. 先命名领域概念、它所属的类型或模块，以及需要依赖它的调用方，再动代码。
3. 在添加扩展函数、工厂、辅助函数或服务层之前，先决定函数的归属（成员、顶层、扩展、工厂、服务还是 receiver）。
4. 审查对 sealed 结果做映射的公开 API 时，逐一列出所有对调用方可见的结果分支；若出现隐藏子类型的 catch-all `else` 就标记出来，建议改成显式的子类型分支，使契约保持穷尽并保留 smart cast。
5. 用能同时保留其语义与互操作契约的最小类型来表示单字段领域概念。
6. 共享代码只承载语义；把原生 SDK 与平台细节放到接口之后，或放在范围有明确理由的 expect/actual 边界之后。
7. 按决策信号查阅对应的聚焦参考文档：成员 vs 顶层、扩展、工厂、服务或 receiver 的选择 → 读 references/functions.md；原始类型偏执、单字段领域类型、`@JvmInline value class`、data class、互操作或 Compose 稳定性 → 读 references/value-classes.md；source set、平台服务、原生 SDK、文件、传感器、权限、Compose Multiplatform 互操作或 expect/actual → 读 references/multiplatform-boundaries.md；分支与 guard 条件形态、sealed 结果映射或 catch-all `else` → 读 ../kotlin-control-flow/SKILL.md。
8. 当公开接口已表达出领域意图、平台细节都留在叶子节点、且调用方不再依赖没有明确归属的便利抽象时，即可结束。
9. 若最终返回的 sealed 结果映射仍存在隐藏子类型的 catch-all `else`，则视为未完成，必须改为显式子类型分支。
10. 若共享代码中仍混入原生 SDK 或平台细节、或它们没有被接口/expect-actual 边界隔离，则视为未完成。
11. 若调用方仍依赖没有清晰归属的便利抽象，则视为未完成。

适用边界 · 注意事项

• 不是 Kotlin/JVM/Kotlin Multiplatform 项目时，没有 value class、expect/actual 等对应机制，本经验不适用。
• API 只是模块内部一次性的临时实现细节、不会被其他模块依赖时，不必为此调整函数归属或引入 value class。
• 已有团队明确且稳定的 API 归属约定、且改动收益极低的简单样板代码，不必套用这套评审流程。