Skip to content

快速开始 ​

1. 初始化 httpApi ​

在应用启动入口(如 main.ts)调用一次 setupHttpApi,完成请求核心的初始化:

Pinia 安装后注入 loginRefreshHandler、异步 loginParamsBuilder 的调用示例

ts
// main.ts
import { setupHttpApi } from '@hfyidu/api/http'
import { createSSRApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import { useUserStore } from '@/store/userStore'
import { miniLoginParamsBuilder } from '@/services/loginParams'

export function createApp() {
  const app = createSSRApp(App)
  const pinia = createPinia()
  // 如需持久化,在 app.use(pinia) 前通过 pinia.use(...) 注册业务侧插件。
  app.use(pinia)
  const userStore = useUserStore(pinia)

  setupHttpApi({
    baseUrl: import.meta.env.VITE_BASE_URL, // 后台 API 根地址,必填
    appId: import.meta.env.VITE_API_ID, // X-App-ID 请求头,必填
    auth: {
      getToken: () => userStore.token,
      setToken: token => userStore.setToken(token),
      loginRefreshHandler: result => userStore.setUserInfo(result.user),
      loginParamsBuilder: miniLoginParamsBuilder,
    },
  })
  return { app }
}

示例中的 store 由业务项目提供,包含 token、setToken 和 setUserInfo; 请按实际 store 调整。先安装 Pinia,再创建 store,才能让已注册的持久化插件 恢复缓存并订阅后续状态变化。SDK 通过桥接回写状态,本身不负责写入本地缓存。

HttpApiConfig 完整字段说明:

字段类型必填说明
baseUrlstring是后台 API 根地址
appIdstring是请求头 X-App-ID,用于标识业务项目
identityAppId string否请求头 X-Identity-App-ID,业务请求和登录刷新请求均会携带
realAppIdstring否请求头 X-Real-App-ID,业务请求和登录刷新请求均会携带;与 appId、identityAppId 独立配置
loginPath string否登录刷新接口路径,默认 /user/login
authAuthBridge否Token 读写和登录刷新桥接;不配置时默认无法从业务状态读取 token,也不会回写业务状态
plateform'web' | 'miniapp'否1.1.1 新增,默认 miniapp;没有自定义登录参数 builder 时,决定使用小程序登录还是微信网页授权。字段拼写为 plateform

AuthBridge 类型定义:

字段类型说明
getToken() => string | null读取当前登录 token
setToken(token: string) => void写入 token(登录成功、续期成功时会被调用)
loginRefreshHandler (result: UserLoginDto) => void可选;SDK 调用 setToken 并更新内存 token 后,同步用户等登录信息
loginParamsBuilder (...argv: any[]) => Promise<Record<string, any>>可选;异步构造自动登录刷新的请求体,SDK 等待其完成后发送登录请求;当前调用不传参数

微信小程序登录参数 ​

下面的业务侧 builder 对应入口中的 @/services/loginParams,在每次自动登录 刷新时获取新的微信 code。它只返回参数,不再次调用登录接口。

miniLoginParamsBuilder() 异步调用示例

ts
// services/loginParams.ts
export async function miniLoginParamsBuilder(): Promise<Record<string, any>> {
  const { code } = await uni.login({ provider: 'weixin' })
  const device = uni.getDeviceInfo()
  const { query = {}, scene, referrerInfo } = uni.getLaunchOptionsSync()
  return {
    theatre_code: code,
    device_uid: device.deviceId ?? '',
    brand_type: device.brand ?? 'unknown',
    brand_name: device.model ?? 'unknown',
    spread_id: query.spread_id ?? 0,
    spread_params: JSON.stringify(query),
    launch_scene: scene,
    source_package_name: JSON.stringify(referrerInfo ?? {}),
  }
}

设备、推广及其他登录字段按后台协议补齐。不要在 builder 内通过同一个 httpApi 发起需要 token 的请求:这类请求会等待当前刷新,形成相互等待。 如需获取公开数据,请显式设置 tokenRequired: false;公开请求不会等待刷新, 认证失败时也不会触发自动登录或续期。 builder 抛出的异常会使本次刷新失败,等待该刷新的请求也会失败。

认证错误与自动续期 ​

  • 当 HTTP 状态为 200 且业务码命中 isAuthError 时,SDK 自动登录刷新,再重试原请求。
  • 多个认证错误共享正在进行的登录刷新;刷新期间新发起的需 token 请求等待同一个 Promise,tokenRequired: false 的请求直接发送。
  • 自动登录刷新成功后先调用 setToken 并更新 SDK 内存 token,再调用 loginRefreshHandler。
  • 业务码 100000 表示自动续期,从响应头 automatic-renewal-token 读取新 token,回写后重试;此流程不调用 builder 和 loginRefreshHandler。
  • 同一会话内,迟到的旧 token 响应若发现内存 token 已更新,使用当前 token 重试,不再次登录;仍受重试上限约束。
  • 每次公开的 request() 调用最多进行一次认证重试和一次续期重试;两种状态交错时最多发送三次业务请求,不含登录刷新请求。达到上限后抛出错误。
  • tokenRequired: false 的请求遇到认证或续期业务码直接抛出 HttpBusinessError,不自动重试。
  • 调用 setAccessToken() 会更新会话版本;旧版本的刷新结果不再回写,旧版本请求也不会继续认证重试。该机制不会取消已经发出的网络请求。

loginRefreshHandler 是同步回调,SDK 不等待它返回的异步任务。 主动调用 UserDomain.cases.login.run() 不会自动触发这个刷新回调,仍需业务侧保存登录结果。 HTTP 401 等非 200 响应会作为 HTTP 错误抛出,不进入上述业务码刷新流程。 其他平台的登录参数也可通过 builder 注入;H5 可使用下方内置微信网页授权流程,或自行构造 wxoa_code 等字段。

主动登录、退出与切换账号 ​

SDK 仅在内存 token 为空时通过 getToken 读取业务状态,不会持续订阅 store。 主动登录成功、退出及切换账号时,业务层应同时更新 store 和 SDK 内存 token。 退出时先清空 store,再清空 SDK token,避免后续请求重新读取旧缓存:

ts
import { httpApi } from '@hfyidu/api/http'

// 主动登录成功后,loginResult 为本次登录返回的 UserLoginDto。
userStore.setToken(loginResult.token)
httpApi.setAccessToken(loginResult.token)
userStore.setUserInfo(loginResult.user)

// 退出登录时,clear() 为业务侧清理 token、用户信息及持久化缓存的方法。
userStore.clear()
httpApi.setAccessToken(null)

自动刷新桥接中的 setToken 只负责写入业务 store,loginRefreshHandler 负责用户信息等同步; 不要在这些回调里额外调用 setAccessToken,以免将同一次自动刷新误标记为会话切换。 自定义 builder 内同样应只构造参数。

微信网页授权(1.1.1) ​

微信 H5 项目在启动时设置 plateform: 'web',并调用 setupWxAuth。服务号 AppId 与后台 API 的 appId 分开配置:

ts
import { setupHttpApi, setupWxAuth } from '@hfyidu/api/http'

setupHttpApi({
  baseUrl: import.meta.env.VITE_BASE_URL,
  appId: import.meta.env.VITE_API_ID,
  plateform: 'web',
  auth: {
    getToken: () => userStore.token,
    setToken: token => userStore.setToken(token),
  },
})
setupWxAuth({
  appId: import.meta.env.VITE_WXOA_APP_ID,
  snsapi: 'snsapi_base',
})

上述 userStore 使用前需按初始化示例创建。配置应在业务请求发起前完成。

WxAuthConfig 字段必填说明
appId是微信服务号 AppId;未配置时内置网页登录抛出初始化错误
redirectUri否自定义完整回调 URL;省略时使用 https://web.auth.ax3672.cn/callback/web,附带 scene=1 和当前页面 origin
snsapi否snsapi_base(默认)或 snsapi_userinfo

内置登录优先读取 URL 的 code,读取后删除地址栏中的 code 和 state,并向后台提交 wxoa_code。没有 code 时跳转微信授权页面,当前刷新请求等待页面跳转。自定义回调地址需自行保留业务参数,并确保回调页面完成 SDK 初始化。

配置 auth.loginParamsBuilder 时,SDK 优先调用该 builder,不使用内置授权,也不要求 setupWxAuth。小程序项目使用默认 miniapp,无需配置服务号授权。

WARNING

在调用 setupHttpApi 之前发起任何请求都会直接抛出 [@hfyidu/api] httpApi 未初始化 错误,避免因为忘记初始化而静默失败。

请求选项与响应字段 ​

成员类型说明
HttpRequestOption.ignore boolean关闭失败时的自动 Toast,仍会抛出错误
HttpRequestOption.tokenRequired boolean默认 true;false 时不使用 Bearer token,当前 Authorization 值为 not founded
HttpRequestOption.progress boolean类型中声明;当前 request 实现未据此显示进度条
ResponseData.message string(可选)登录刷新失败时优先使用后台返回的错误消息
isAutoRefresh(code) (code: number) => boolean判断业务码是否为 100000,可从 @hfyidu/api/http 导入

headerBuilder(header, tokenRequired) 新增第二个参数;通常直接使用 httpApi.request() 传入请求选项。 setDeviceId()、device、handleTokenRefresh() 已从当前公开 API 移除,迁移方式见升级说明。

2. 按需引入业务领域 ​

@hfyidu/api 按业务领域拆分了 subpath,推荐只引入用到的领域:

ts
import { UserDomain } from '@hfyidu/api/user'
import { NovelDomain } from '@hfyidu/api/novel'

H5 等不受小程序体积限制的场景,也可以用根入口 import { UserDomain } from '@hfyidu/api' 获取其导出的业务领域。通用工具领域请通过 @hfyidu/api/tool 单独导入。各领域的 subpath 见业务领域文档。

3. 发起一次性请求 ​

每个业务领域导出一个 XxxDomain 类,Domain.cases.xxx 是具体用例(UseCase),调用 .run(params) 发起请求:

ts
import { UserDomain } from '@hfyidu/api/user'

const { data } = await UserDomain.cases.login.run({
  phone: '13800000000',
  captcha: '1234',
})

console.log(data) // UserLoginDto

.run(params) 返回 { data, updatedAt },data 为该用例对应的响应 DTO(已完成字段格式化),updatedAt 为本次请求完成的时间戳(毫秒)。

4. 发起分页列表请求 ​

部分用例是分页列表(继承自 PaginatorUseCase),自带 list / hasMore / refreshing 等状态,建议只 new 一次并复用同一个实例来持有分页状态:

ts
import { UserDomain } from '@hfyidu/api/user'

// 只 new 一次,复用同一实例
const consumesCase = UserDomain.cases.consumes

// 首次加载 / 下拉刷新
await consumesCase.refresh()

// 上拉加载更多
if (consumesCase.hasMore.value) {
  await consumesCase.loadNextPage()
}

console.log(consumesCase.list) // 当前已加载的列表数据
console.log(consumesCase.hasMore.value) // 是否还有下一页
console.log(consumesCase.refreshing.value) // 是否正在刷新中

PaginatorUseCase 常用属性/方法:

成员类型说明
listItemDto[]当前已加载的列表数据(累加)
hasMoreRef<boolean>是否还有下一页
refreshingRef<boolean>是否正在刷新(下拉刷新场景可直接绑定 loading 状态)
loadedCountRef<number>已加载的数据条数,初始为 -1
isEmptyboolean数据是否为空(refresh 完成后可用)
errorRef<string>最近一次请求的错误信息
refresh()() => Promise<void>重置到第一页并重新加载(下拉刷新)
loadNextPage()() => Promise<void>加载下一页并追加到 list(上拉加载更多)
insertAt(item, index?)(item, index?: number) => void本地在指定位置插入一条数据,无需重新请求
removeAt(index)(index: number) => void本地移除指定位置的数据,无需重新请求

Vue 响应式提示

list 是普通数组属性而非 ref,通过整体重新赋值(this.list = ...)更新;hasMore、refreshing、loadedCount、error 是 shallowRef。在 Vue 组件中使用时,建议结合 reactive/自定义 composable 同步这些状态到模板可感知的响应式数据。

5. 错误处理 ​

请求失败或一般业务错误时,HTTP 层会抛出异常,每次 httpApi.request() 调用的整个重试链最多自动 Toast 一次;ignore: true 仅关闭提示,错误仍会抛出。业务错误可以通过 HttpBusinessError 类型判断:

ts
import { HttpBusinessError } from '@hfyidu/api'

try {
  await UserDomain.cases.login.run({ phone, captcha })
} catch (error) {
  if (error instanceof HttpBusinessError) {
    console.log(error.code, error.message) // 后台返回的业务错误码与错误信息
  }
}

HTTP 状态非 200 时抛出 HTTP 错误。普通响应体必须是对象且包含数字类型的 code, 否则抛出“接口响应格式异常”;续期和登录刷新返回的 token 必须是非空字符串。

配置 formatter 时,仅 null 和 undefined 被视为无数据并抛出错误, 0、false、空字符串仍会传给 formatter,由 formatter 决定如何处理。 资源未解锁或余额不足(业务码 417001、417002)沿用特殊约定: 无数据时 HTTP 层返回 HttpBusinessError 对象,有数据时继续返回或格式化数据。

下一步 ​

内部工具包 · 未开源授权,仅限公司内部授权团队使用