xuqmGroup/XuqmGroup-RNSDK
0
0
派生 0
代码 工单 合并请求 版本发布 百科 动态
78721ee2f0
XuqmGroup-RNSDK/packages/common/README.md

5.0 KiB
原始文件 Blame 文件历史

@xuqm/rn-common

所有 @xuqm React Native SDK 的唯一基础包，也可以零初始化、零登录单独使用。文件、时间、加密、设备、UI、API hooks，以及使用绝对 URL 或 configureHttp 配置地址的网络请求，都不依赖 SDK 上下文。

安装

pnpm add @xuqm/rn-common axios \
  @react-native-async-storage/async-storage

独立使用

只使用 common 的通用能力时，不放配置文件、不调用 initialize，也不调用 login：

import { apiRequest, configureHttp, expirationStatus } from '@xuqm/rn-common'

configureHttp({ baseUrl: 'https://api.example.com' })
const result = await apiRequest('/health', { skipAuth: true })
const state = expirationStatus('2027-01-01T00:00:00Z')

没有 SDK 配置时，apiRequest 不添加 appKey、用户和签名请求头。

扩展包自动初始化

把平台生成的加密配置原名放到 src/assets/config/（目录内只能有一个 .xuqmconfig），并只包装一次 Metro 配置：

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { withXuqmConfig } = require('@xuqm/rn-common/metro')

module.exports = withXuqmConfig(
  mergeConfig(getDefaultConfig(__dirname), {
    // 宿主自己的 Metro 配置
  }),
)

使用 update、bugcollect、xwebview 等扩展包时，withXuqmConfig() 会在 Node/Metro 构建进程中解密配置，生成只读的虚拟配置模块，并把 common 的初始化入口注册为 Metro pre-main module，确保初始化早于业务入口且不受 inlineRequires 影响。Metro 插件还会把同一份加密配置同步到 Android assets；宿主不需要在多个位置维护副本。PBKDF2 与 AES-GCM 解密不在 Hermes 启动线程执行，应用启动时只消费构建已经解析的配置并发起共享初始化。

common-only 项目不要放置 .xuqmconfig，也不要使用 withXuqmConfig()，即可保持零初始化。是否初始化只由这一条规则决定，不提供手动初始化、额外 alias 或多套配置约定。

Metro 预加载发起的自动初始化如果因临时网络或 DNS 问题失败，common 会终止该 Promise，避免形成未处理异常。随后第一个真正需要配置的扩展调用共享 awaitInitialization() 时，会使用同一份已解析配置重新尝试；配置、appKey 和平台地址不需要由页面或子 SDK 再次传入。持续失败由宿主入口统一记录一次，SDK 不重复打印同一错误。构建期配置损坏、密钥不匹配或 Schema 非法会直接阻断构建，禁止打出运行时才失败的安装包。

平台远程配置中的 features.update 是 Update 服务开关；兼容字段 updateEnabled 只在前者缺失时读取。两者都缺失时安全默认关闭，最后成功配置缓存会 原样保存开关值。关闭 Update 不影响 common、宿主业务或其它扩展 SDK。

扩展包的唯一登录入口

应用登录成功后只调用一次：

import { XuqmSDK } from '@xuqm/rn-common'

await XuqmSDK.login({
  userId: 'user-id',
  accessToken: 'http-access-token',
  userSig: 'optional-im-user-sig',
  name: '姓名',
  phone: '手机号',
})

await XuqmSDK.logout()

accessToken 仅用于公共 HTTP 鉴权，userSig 仅用于 IM。所有已安装的官方子 SDK 订阅这一次会话变更，不得各自初始化或登录。未使用 IM 的应用无需传 userSig。

通用能力

  • apiRequest：common-only 模式可直接使用；存在 SDK 配置时使用当前会话的 userId、access token 和请求签名。需要配置的扩展包会先调用共享 awaitInitialization()，common 不会擅自要求初始化。
  • downloadBytes、downloadText、downloadFileToPath：统一小文件流式读取与大文件落盘、进度和取消能力。
  • compareVersions、satisfiesVersion、compatibleMajorRange：统一 SemVer 与插件兼容范围判断。
  • expirationStatus、toTimestamp、millisecondsUntil、formatDateTime：统一时间解析与过期判断。
  • formatNumericDateTime：为 API 参数和固定数字布局提供不受 locale 标点/顺序影响的本地时间格式，调用方通过选项控制日期、时间、秒和分隔符。
  • fileExists、ensureDirectory、readFileAsBase64、writeBase64File、openLocalFile、registerAndroidDownloadedFile：统一文件与 Android 下载登记操作。
  • hmacSha256Base64Url、sha256Hex：签名与文件摘要使用的统一实现。平台签发的 .xuqmconfig 只允许由 Metro 构建插件验签和解析，不向运行时暴露通用解密 API。
  • getDeviceInfo、getDeviceId、useApi、usePageApi、showToast 等项目通用能力。

业务代码不得导入 @xuqm/rn-common/internal。该子路径仅供官方 @xuqm 扩展包接入公共生命周期。 internal-security 同样只供官方扩展使用：配置 V2 和插件不可变 manifest 复用一份 canonical JSON（键排序、无空白、null/undefined 字段省略）与可信 Ed25519 keyId 集合，不是宿主可替换的通用验签入口。