快速开始

1. 初始化 httpApi

在应用启动入口（如 main.ts）调用一次 setupHttpApi，完成请求核心的初始化：

// main.ts
import { setupHttpApi } from '@hfyidu/api/http'
import { useUserStore } from '@/store/userStore'

setupHttpApi({
  baseUrl: import.meta.env.VITE_BASE_URL, // 后台 API 根地址，必填
  appId: import.meta.env.VITE_API_ID, // X-App-ID 请求头，必填
  auth: {
    // 可选：接入业务项目自己的状态管理（如 pinia），不传则请求不携带 token
    getToken: () => useUserStore().getToken,
    setToken: token => useUserStore().setToken(token),
  },
})

HttpApiConfig 完整字段说明：

字段	类型	必填	说明
`baseUrl`	`string`	是	后台 API 根地址
`appId`	`string`	是	请求头 `X-App-ID`，用于标识业务项目
`auth`	`AuthBridge`	否	Token 读写桥接，不传则请求不携带 `Authorization`，且续期后的新 token 不会被持久化

AuthBridge 类型定义：

字段	类型	说明
`getToken`	`() => string \| null`	读取当前登录 token
`setToken`	`(token: string) => void`	写入 token（登录成功、续期成功时会被调用）

WARNING

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

2. 按需引入业务领域

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

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

H5 等不受小程序体积限制的场景，图方便也可以直接用根入口 import { UserDomain } from '@hfyidu/api' 一次性拿到全部领域。可选 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. 错误处理

请求失败或业务错误时，.run() 会抛出异常，同时框架已经统一处理了 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) // 后台返回的业务错误码与错误信息
  }
}

下一步

深入理解代码组织方式：DDD 架构设计
查看具体业务领域的完整接口、参数与 DTO 字段：业务领域文档

快速开始 ​

1. 初始化 httpApi ​

2. 按需引入业务领域 ​

3. 发起一次性请求 ​

4. 发起分页列表请求 ​

5. 错误处理 ​