跳转到内容

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 指南。

让基础能力保持简单,让业务开发更加专注。