KMP项目common目录使用@JSName/@JsExport是否为合理开发实践？

一、直接在common目录添加@JSName/@JsExport的合理性 #

该方案可运行，但不属于长期最优实践

• 可行性支撑：Kotlin编译器对平台专属注解做了静默兼容处理，非JS目标平台编译时会自动忽略JS相关注解，不会产生编译错误，对于小型项目、JS导出需求极少的场景，该方案改造成本最低，可快速实现需求。
• 存在的弊端：
  • 破坏common层的平台无关性定位：common层的核心设计目标是存放三端完全通用的逻辑代码，混入平台专属注解会让通用层逻辑和单一平台的适配规则耦合。
  • 提升后续维护成本：后续调整JS导出规则时需要修改common层代码，每次修改都需要同步验证Android、iOS等其他平台的编译正确性，同时如果后续新增桌面、Wasm等其他编译目标，这些注解会成为冗余的无效代码。

二、expect/actual剥离JS注解的方案优劣 #

中大型、长期维护的KMP项目更推荐该方案，小型项目可按需选择

• 实现逻辑：不需要把完整类改造成expect/actual结构，有两种低侵入实现方式：
  1. 仅将JS专属注解声明为expect注解，common层用自定义的通用注解标记需要导出的类，JS源集的actual注解映射为真实的@JsExport/@JSName，其他平台的actual注解为空实现，编译时自动忽略。
  2. common层保留无注解的核心类，在JS源集单独实现一层导出包装层，所有对外暴露给JS的声明都收敛在该层统一添加注解。
• 方案优势：
  • 完全保留common层的纯通用属性，核心逻辑不会掺杂任何平台专属配置。
  • JS侧的导出规则完全收敛在JS源集下，修改适配逻辑不会影响其他平台的编译和运行。
  • 扩展性更强，后续如果需要适配其他平台的专属导出规则（如iOS端的@ObjCName），仅需要在对应源集添加适配逻辑即可，不需要修改common层代码。
• 注意事项：如果项目规模极小、仅需要导出3个以内的类给JS侧，直接添加注解的投入产出比更高，不需要为了架构规范强行增加冗余的适配代码。

内容的提问来源于stack exchange，提问作者suns9