快速开始
1. 初始化 httpApi
在应用启动入口(如 main.ts)调用一次 setupHttpApi,完成请求核心的初始化:
Pinia 安装后注入 loginRefreshHandler、异步 loginParamsBuilder 的调用示例
// 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 完整字段说明:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
baseUrl | string | 是 | 后台 API 根地址 |
appId | string | 是 | 请求头 X-App-ID,用于标识业务项目 |
identityAppId | string | 否 | 请求头 X-Identity-App-ID,业务请求和登录刷新请求均会携带 |
realAppId | string | 否 | 请求头 X-Real-App-ID,业务请求和登录刷新请求均会携带;与 appId、identityAppId 独立配置 |
loginPath | string | 否 | 登录刷新接口路径,默认 /user/login |
auth | AuthBridge | 否 | 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() 异步调用示例
// 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,避免后续请求重新读取旧缓存:
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 分开配置:
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,推荐只引入用到的领域:
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) 发起请求:
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 一次并复用同一个实例来持有分页状态:
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 常用属性/方法:
| 成员 | 类型 | 说明 |
|---|---|---|
list | ItemDto[] | 当前已加载的列表数据(累加) |
hasMore | Ref<boolean> | 是否还有下一页 |
refreshing | Ref<boolean> | 是否正在刷新(下拉刷新场景可直接绑定 loading 状态) |
loadedCount | Ref<number> | 已加载的数据条数,初始为 -1 |
isEmpty | boolean | 数据是否为空(refresh 完成后可用) |
error | Ref<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 类型判断:
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 对象,有数据时继续返回或格式化数据。