FAQ

这个包只服务 H5 吗？

当前边界是 browser 和 WebView 中的 H5 应用。web-runtime 这个名字给更广义的 Web 客户端留了空间，但包本身仍应聚焦运行时编排，不应该变成通用工具集合。

为什么推荐从根入口导入？

根入口用于承载稳定 API，普通业务接入优先从 @freenotes/web-runtime 导入。模块化 public subpath 会保留给兼容和高级场景，但文档默认不推荐业务方感知这些路径。

Storage 会替代业务 repository 吗？

不会。Storage 模块只提供安全值存储能力。业务 repository 仍然负责主键设计、业务校验、合并规则、串行写入、失败重试和运行时快照。

Storage 会改写业务 key 吗？

不会。业务传入什么 key，Storage 默认就读写什么 key。业务如果需要前缀隔离或批量清理边界，应把前缀作为业务 key 的一部分，并自行负责历史 key 兼容和批量过滤。

Storage 会封装 IndexedDB 吗？

不会。IndexedDB 是异步数据库，涉及 database、object store、keyPath、版本升级、索引、事务和 migration，和 localStorage / sessionStorage 的同步 key-value 模型不一样。当前 IndexedDB 通过独立的 DB 模块封装，入口是 createDb()。

DB 是 ORM 吗？

不是。DB 只提供 IndexedDB 的 Promise facade，不提供属性式 ORM。业务应该先创建 database handle，再通过 db.store('books') 操作 store。业务 repository 仍然负责业务查询、合并和迁移策略。

Clipboard 会处理粘贴和剪切吗？

不会。当前 Clipboard 实例只提供 writeText() 和 isAvailable()。粘贴通常依赖输入框 paste 事件、selection 和业务格式规则；剪切通常由浏览器原生输入控件处理。runtime 不接管这些用户编辑行为。

HTTP 会替代业务 API client 吗？

会收敛通用请求能力，但不会替代业务 repository。HTTP 负责 baseURL、header、timeout、retry、拦截器、错误归一化、响应解包和配置式创建 API 方法；业务 repository 仍然负责业务聚合、缓存策略、字段映射、权限分支和页面状态。

为什么 HTTP 没有公开 request？

公开 http.request() 会让页面和业务模块绕过 API 定义直接发散点请求，长期会削弱统一接口声明、类型约束和迁移能力。需要特殊请求形态时，使用 endpoint 的 transformRequest / transformResponse；通用逻辑通过 createHttp({ interceptors }) 配置。

业务还需要直接依赖 axios 吗？

普通业务不需要。HTTP 通过内部默认 adapter 使用 axios 作为请求基座，但公开类型和配置不使用 axios 类型。业务迁移到 createHttp().createApi() 后，可以逐步移除自身 API client 中直接依赖 axios 的部分。

它会替代 logger 包吗？

Logger 已提供统一记录格式、限流、大小保护和结果状态，发送通道由业务显式配置 LoggerTransport。现有日志 SDK 或上报服务可以包装为 transport 继续使用；需要 App 的 writeClientLog 协议时使用 createBridgeLogTransport()。它不替代日志服务的存储、检索或告警能力，具体接入见 Logger 指南。