更新记录

0.1.0（2026-08-02） 下载此版本

• 创建符合 uni_modules 规范的 bsx-core 基础能力模块
• 新增 storage 存储能力，支持本地存储、过期时间包装与认证 token 管理
• 新增 request 请求能力，支持统一请求入口、基础配置、认证注入与错误观察器
• 新增 router 路由能力，统一 URL 拼接和页面跳转包装
• 新增 device 设备能力，统一读取设备、窗口与安全区信息
• 新增 permission 权限能力，统一读取授权状态并打开系统授权设置页
• 新增 logger 日志能力，支持日志级别、调试开关与日志观察器
• 新增请求错误集成说明和宿主应用适配模板，保持基础模块与业务错误体系解耦

平台兼容性

uni-app x(4.71)

bsx-core

bsx-core 是面向 uni-app x 的基础能力模块，当前第一阶段承载六组高频能力：

• storage：本地存储、过期时间包装、认证 token 存取
• request：统一请求入口、认证注入、统一错误模型、错误观察器
• router：统一 URL 拼接与页面跳转包装
• device：统一读取设备、窗口与安全区信息
• permission：统一读取授权状态并打开系统授权设置页
• logger：统一日志级别、调试开关与观察器

设计边界

bsx-core 不直接依赖宿主应用的业务错误模块。

原因很直接：

• bsx-core 应保持可复用
• 宿主应用可能有自己的 AppError、ServiceResult、toast/modal/full-error 体系
• 如果在 bsx-core 内部直接 import 宿主层错误模块，会形成反向依赖

因此，当前推荐模式是：

页面 / 业务 service
-> bsx-core/request
-> 返回 BsxCoreRequestResult<T>
-> 宿主应用把 BsxCoreRequestError 适配成自己的 AppError

同时，request 还提供全局错误观察器：

• setBsxRequestErrorObserver(observer)

宿主应用可以在这个观察器里：

• 把 BsxCoreRequestError 转成 AppError
• 再决定是否调用自己的 dispatchAppError

这样可以接入你现有的 infrastructure/error，但不会让 bsx-core 侵入宿主应用。

更具体的接入说明见：

• request-error-integration.md
• request-error-adapter-template.md

当前导出

storage

• createBsxStorageKey(namespace, name)
• setBsxStorageString(key, value)
• getBsxStorageString(key)
• setBsxStorageJSON(key, value)
• getBsxStorageJSON(key)
• removeBsxStorage(key)
• setBsxStorageStringWithExpires(key, value, ttlMs)
• getBsxStorageStringWithExpires(key)
• setBsxAuthToken(token)
• getBsxAuthToken()
• clearBsxAuthToken()

request

• setBsxBaseURL(baseURL)
• getBsxBaseURL()
• setBsxRequestTimeout(timeout)
• getBsxRequestTimeout()
• setBsxAuthHeaderName(name)
• setBsxAuthScheme(scheme)
• setBsxDefaultHeaderEntries(entries)
• setBsxAuthTokenGetter(getter)
• setBsxUnauthorizedHandler(handler)
• setBsxRequestErrorObserver(observer)
• request<T>(options)
• get<T>(url, query, headers, fallbackMessage, silent)
• post<T>(url, data, headers, fallbackMessage, silent)

router

• createBsxRouteLocation(path, query?)
• buildBsxRouteURL(path, query?)
• buildBsxRouteURLFromLocation(location)
• bsxNavigateTo(path, query?)
• bsxNavigateToLocation(location)
• bsxRedirectTo(path, query?)
• bsxRedirectToLocation(location)
• bsxSwitchTab(path, query?)
• bsxSwitchTabLocation(location)
• bsxNavigateBack(delta?)

device

• getBsxSafeArea()
• getBsxWindowInfo()
• getBsxDeviceInfo()
• isBsxLandscape()
• isBsxPadOrPC()

permission

• getBsxPermissionSnapshot()
• getBsxPermissionStatus(kind)
• isBsxPermissionAuthorized(kind)
• shouldBsxOpenPermissionSettings(kind)
• openBsxAppAuthorizeSetting()

logger

• setBsxDebugLogEnabled(enabled)
• isBsxDebugLogEnabled()
• setBsxLogObserver(observer)
• bsxLogDebug(tag, message)
• bsxLogInfo(tag, message)
• bsxLogWarn(tag, message)
• bsxLogError(tag, message)

推荐接入方式

1. 页面主接口

• 页面自己管理错误态：silent: true
• 页面自己把 BsxCoreRequestError 转成 AppError

2. 按钮提交

• 统一交给宿主应用全局提示：silent: false
• 在 setBsxRequestErrorObserver 中桥接到错误模块

3. 与 infrastructure/error 集成

推荐是“桥接”，不是“硬依赖”。

建议宿主应用做两件事：

1. 页面 / service 层把 result.error 映射成自己的 AppError
2. 全局注册 setBsxRequestErrorObserver，处理 silent: false 的场景