# public-client-sdk

**Repository Path**: m-sdk/public-client-sdk

## Basic Information

- **Project Name**: public-client-sdk
- **Description**: public-sdk配套前端插件
- **Primary Language**: Unknown
- **License**: ISC
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# public-client-sdk

[![npm version](https://img.shields.io/npm/v/public-client-sdk.svg)](https://www.npmjs.com/package/public-client-sdk)
[![license](https://img.shields.io/npm/l/public-client-sdk.svg)](https://gitee.com/m-sdk/public-client-sdk/blob/master/LICENSE)

面向 Uni-app（Web / App / 小程序）、微信小程序、抖音小程序、Web SPA 等前端环境的通用客户端 SDK。
无 Node.js 内置模块依赖，全量打包体积小于 3KB，配合后端 [`public-sdk`](https://www.npmjs.com/package/public-sdk) 提供接口签名校验、路由并发拦截、多端缓存与长连接封装能力。

---

## 前后端协同架构

`public-client-sdk` 与后端 `public-sdk` 协同工作，提供端到端的基础通信与安全能力支持：

```
  ┌─────────────────────────────────────────────────────────────┐
  │                 前端应用集群 (Frontends)                     │
  │   - B端工厂小程序 (factory-mp)   - C端商城小程序 (market-mp)    │
  │   - 平台管理后台 (pc-admin)       - 移动端混合 App (App-Plus)    │
  └──────────────────────────────┬──────────────────────────────┘
                                 │
                    驱动层: public-client-sdk
      (DEDSSigner / UniRequest / UniversalRouter / Storage / Socket)
                                 │
                                 ▼ [DEDS 动态加签 / Send 数据规范]
                                 │
                    后端服务: public-sdk
      (SignatureGuard / Http / Send / TokenService / WX)
                                 │
  ┌──────────────────────────────┴──────────────────────────────┐
  │                 后端微服务集群 (ts-server)                  │
  │   - factory-service  - market-service  - admin-service      │
  │   - pay-service      - ws-service      - cron-service       │
  └─────────────────────────────────────────────────────────────┘
```

| 功能模块 | 前端 SDK ([`public-client-sdk`](https://www.npmjs.com/package/public-client-sdk)) | 后端 SDK ([`public-sdk`](https://www.npmjs.com/package/public-sdk)) | 说明 |
| :--- | :--- | :--- | :--- |
| **接口防篡改与防重放** | `DEDSSigner` (动态签名发生器) | `SignatureGuard` (Express 守卫中间件) | 客户端计算动态时间戳与摘要签名，服务端基于时间片窗口及防重放机制完成校验 |
| **统一数据响应与解包** | `UniRequestClient` / `Fetch` / `Axios` | `Send.success` / `Send.fail` | 前端自动解包 `body.data`，统一错误状态码与 401 登录态防抖拦截 |
| **跨端路由并发锁** | `UniversalRouter` (多端通用 Router) | - | 跳转未完成前拦截后续并发跳转，防止快速连点造成重复打开或页面栈溢出 |
| **多端持久化缓存** | `UniversalStorage` (多端统一 Storage) | - | 统一多端本地存储接口，支持指定秒级/毫秒级过期时间（TTL） |
| **长连接消息推送** | `SocketClient` (WebSocket 客户端) | `ws-service` / Redis PubSub | 内置心跳检测、指数退避重连、页面生命周期事件解绑与离线消息缓冲 |
| **时间漂移校准** | `setServerTimeOffset` | `/common/timestamp` | 校准客户端与服务端时间差，保证签名校验时间片对齐与业务倒计时准确 |

---

## 安装

```bash
npm install public-client-sdk --save
```

---

## 核心功能

### 1. 路由并发拦截 (`Router` / `UniversalRouter`)

针对小程序与单页应用在快速连点时可能出现的页面重复打开、页面栈溢出或跳转动画异常问题，Router 在单次跳转完成或报错前，自动拦截并发发起的后续跳转请求。

#### 全局拦截（推荐）
```typescript
import { Router } from 'public-client-sdk'

// 应用初始化入口 (如 main.js / init.js) 中执行一次
Router.install()

// 拦截全局 uni.navigateTo、uni.redirectTo、uni.switchTab 等路由跳转并发
```

#### API 显式调用
```typescript
import { Router } from 'public-client-sdk'

// 1. 保留当前页面跳转 (支持自动格式化 query 对象参数)
await Router.navigateTo('/pages/order/detail', { id: 10086, role: 'cutter' })

// 2. 重定向关闭当前页
await Router.redirectTo('/pages/login/index')

// 3. TabBar 切换
await Router.switchTab('/pages/index/index')

// 4. 关闭所有页面并打开
await Router.reLaunch('/pages/index/index')

// 5. 页面返回
await Router.navigateBack(1)
```

#### Vue Router 适配
```typescript
import { Router } from 'public-client-sdk'
import router from './router'

// 绑定 Vue Router 实例
Router.setWebRouter(router)

// 页面内调用同样支持并发拦截与参数序列化
await Router.navigateTo('/user/list', { page: 1, pageSize: 10 })
```

---

### 2. 网络请求客户端 (`UniRequestClient`)

适配 Uni-app、微信小程序 (`wx`)、抖音小程序 (`tt`) 与原生 App 环境。
自动注入 DEDS 动态签名与 Token，内置 401 防抖拦截、自动解包与统一错误处理。

```typescript
import { UniRequestClient } from 'public-client-sdk'

export const request = new UniRequestClient({
  baseUrl: 'https://api.yourdomain.com/api',
  kernelSeed: 0x5f3759df,
  clientFp: 'factory_mp',
  unwrapData: true, // 默认 true: 自动解包返回 body.data
  getToken: () => uni.getStorageSync('token'),
  getFactoryId: () => uni.getStorageSync('activeFactoryId'),
  onUnauthorized: (err) => {
    uni.removeStorageSync('token')
    Router.navigateTo('/pages/login/index')
  }
})

// 1. 发起 GET 请求 (自动拼接并清理 undefined 参数)
const list = await request.get('/recruitment/list', { jobType: '车位工' })

// 2. 发起 POST 请求
const res = await request.post('/factory/ticket/accept', { ticketId: 10086 })

// 3. 原样获取完整结构（包含 code, message, timestamp）
const rawRes = await request.raw('/factory/ticket/accept', 'POST', { ticketId: 10086 })
console.log(rawRes.code, rawRes.message, rawRes.data)

// 4. 统一文件上传 (多端兼容)
const uploadRes = await request.upload('/tmp/image.png', '/common/upload')
```

---

### 3. Axios 拦截器 (`setupPublicSdkAxios`)

适用于基于 Axios 的 Web 管理端项目：

```typescript
import axios from 'axios'
import { setupPublicSdkAxios } from 'public-client-sdk'

const request = axios.create({ baseURL: '/api', timeout: 10000 })

// 挂载 DEDS 签名请求拦截器及响应统一处理
setupPublicSdkAxios(request, {
  kernelSeed: 0x5f3759df,
  clientFp: 'pc_admin',
  getToken: () => localStorage.getItem('admin_token') || '',
  onUnauthorized: () => {
    localStorage.removeItem('admin_token')
    window.location.href = '/login'
  }
})

export default request
```

---

### 4. 本地缓存 (`Storage` / `UniversalStorage`)

统一 Uni-app、微信小程序、抖音小程序与 Web 的本地存储接口，支持指定过期时间（TTL）：

```typescript
import { Storage } from 'public-client-sdk'

// 1. 写入缓存（支持过期时间，单位：秒）
Storage.set('user_profile', { id: 1001, name: '张三' }, { expireSeconds: 3600 })

// 2. 读取缓存（自动反序列化，若已过期则自动清除并返回 null）
const profile = Storage.get('user_profile')

// 3. 删除与清空
Storage.remove('user_profile')
Storage.clear()
```

---

### 5. 动态签名 (`DEDSSigner`)

与后端 `public-sdk` 的 `SignatureGuard` 签名算法一致。纯 TypeScript/JavaScript 实现，无 Node.js 内置依赖，支持在小程序与浏览器环境中生成请求头签名：

```typescript
import { DEDSSigner, setServerTimeOffset } from 'public-client-sdk'

// 1. 校准服务端时间差
setServerTimeOffset(1787279799862)

// 2. 初始化签名器
const signer = new DEDSSigner({
  kernelSeed: 0x5f3759df,
  clientFp: 'factory_mp'
})

// 3. 计算签名 Headers
const signHeaders = signer.sign({
  method: 'GET',
  url: '/recruitment/list?jobType=全部',
  data: { jobType: '全部' },
  token: 'JWT_TOKEN_STRING'
})

console.log(signHeaders)
// {
//   'X-Timestamp': '1787279799862',
//   'X-Nonce': 'assl9x4456asmta6',
//   'X-Client-Fp': 'factory_mp',
//   'X-Signature': '90ca106aee1600af075570c0bd8bfa673e5666e407f66be2e6b6a5812f991cf8bc5a'
// }
```

---

### 6. WebSocket 客户端 (`SocketClient`)

提供支持断线重连与页面生命周期绑定的 WebSocket 封装：

```typescript
import { SocketClient } from 'public-client-sdk'

export const socket = new SocketClient({
  url: 'wss://api.yourdomain.com/ws',
  getToken: () => uni.getStorageSync('token')
})

socket.connect()

// 页面生命周期绑定（页面卸载时自动注销监听，防止内存泄漏）
export default {
  onLoad() {
    socket.bindPage('ticketPage', 'TICKET_UPDATED', (data) => {
      console.log('收到工单状态实时推送:', data)
    })
  },
  onUnload() {
    socket.unbindPage('ticketPage')
  }
}
```

---

### 7. 数据格式化与脱敏工具 (`format`)

```typescript
import {
  fenToYuan,
  yuanToFen,
  formatDate,
  timeAgo,
  maskPhone,
  maskName
} from 'public-client-sdk'

fenToYuan(1250)              // '12.50' (货币分转元)
yuanToFen(12.5)              // 1250    (货币元转分)
maskPhone('13812345678')       // '138****5678' (手机号脱敏)
maskName('诸葛孔明')          // '诸**明'     (姓名脱敏)
timeAgo(Date.now() - 60000)  // '1分钟前'
```

---

## 许可证

ISC License © 2026 yajun.xu