Runtime SDK Implementation Recommendations

目的

本文件是非规范性的实现推荐模块，提供一组跨语言、跨平台包可复用的推荐实现形状。

实现 MAY 采用这些形状，也 MAY 使用其他 API，只要仍满足 Runtime SDK 中的能力契约和协商语义。

推荐对象

• CoreRuntime
  • 当前 runtime 实例的 core 能力入口
• SDKCapabilityDescriptor
  • SDK capability 的统一描述对象，区分 core 与 platform
• CorePolyfillPlugin
  • 一次可批量注册多个 core polyfill 的插件对象
• CoreCapabilityRegistration
  • 单项 core 能力注册记录

推荐装配形状

• register(capabilityName, impl, options?) -> void
  • 注册单项 core capability 的 polyfill
• use(plugin) -> CoreRuntime
  • 以插件方式批量注册 polyfill，并返回当前 core runtime 以便链式装配

CorePolyfillPlugin 的推荐最小形状：

• name
• register(core) -> void

推荐优先级

• polyfill registry SHOULD 以单个 CoreRuntime 实例为作用域，不做进程全局共享
• use(plugin) SHOULD 可被视为一组 register(...) 的语法糖
• 原生 core 实现 SHOULD 具有最高优先级
• register(...) SHOULD NOT 覆盖原生 core 实现
• 同一 capability 的重复注册默认 SHOULD 失败
• 只有显式 override 选项时，后注册实现才 MAY 覆盖先前的 polyfill
• 即使显式 override，也只建议覆盖已有 polyfill，不覆盖原生实现

语言绑定建议

• TypeScript、Python 或其他语言 MAY 使用不同命名风格暴露 createCore、register、use
• 平台包 SHOULD 同时导出：
  • 一个 useXxxPolyfills(core) 或等价 plugin
  • 一个独立的 platform API 命名空间

测试建议

• 推荐把 register/use/plugin 行为放在实现推荐测试中验证，而不是作为 core conformance 的必选条件
• 推荐测试项：
  • duplicate registration
  • override precedence
  • native-over-polyfilled precedence
  • language binding helper parity