【初始化】前端工程项目

frontend/packages/hooks/docs/useAxios.md

@@ -0,0 +1,284 @@
+# useAxios 使用文档
+
+## 基本介绍
+
+`useAxios` 是一个基于 Vue 3 的 Axios 封装钩子函数，它提供了一种简洁的方式来管理 HTTP 请求。通过这个钩子函数，你可以轻松地处理请求状态、加载状态、错误处理、请求取消等功能。
+
+## 核心函数
+
+### useAxios
+
+```typescript
+function useAxios<T = unknown, Z = Record<string, unknown>>(instance: HttpClient): useAxiosReturn<T, Z>
+```
+
+**参数**:
+
+- `instance`: HttpClient 实例，用于发送 HTTP 请求
+
+**返回值**:
+包含以下属性和方法的对象：
+
+**状态属性**:
+
+- `loadingMask`: 加载遮罩配置，类型为 `Ref<{ status: boolean } & LoadingMaskOptions>`
+- `message`: 是否显示响应消息，类型为 `Ref<boolean>`
+- `dialog`: 确认框配置，类型为 `Ref<{ status: boolean } & CustomDialogOptions>`
+- `loading`: 是否正在加载，类型为 `Ref<boolean>`
+- `error`: 错误信息，类型为 `ShallowRef<Error | null | string>`
+- `response`: 原始响应对象，类型为 `ShallowRef<AxiosResponse<T> | null>`
+- `data`: 响应数据，类型为 `Ref<T>`
+- `defaultData`: 默认数据，类型为 `Ref<T>`
+- `statusCode`: HTTP 状态码，类型为 `ComputedRef<HttpStatusCode | null>`
+- `aborted`: 是否被中断，类型为 `Ref<boolean>`
+- `urlRef`: 请求 URL，类型为 `Ref<string>`
+- `paramsRef`: 请求参数，类型为 `Ref<Z>`
+
+**方法**:
+
+- `execute(url: string, params?: Z)`: 执行请求，返回 `Promise<T>`
+- `setParams(params: Z)`: 设置请求参数并执行请求，返回 `Promise<T>`
+- `setUrl(url: string, params?: Z)`: 设置请求 URL 和参数并执行请求，返回 `Promise<T>`
+- `cancel(url: string)`: 取消特定请求
+- `cancelAll()`: 取消所有请求
+- `start(params?: Z)`: 使用当前 URL 和参数重新发起请求，返回 `Promise<T>`
+
+## 使用示例
+
+### 基本用法
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+// 创建 HTTP 客户端实例
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+// 创建请求钩子
+const api = useAxios<UserData, UserParams>(httpClient)
+
+// 发送请求
+const fetchUser = async (userId: string) => {
+	try {
+		const result = await api.execute('/user/info', { userId })
+		console.log('用户数据:', result)
+		return result
+	} catch (error) {
+		console.error('获取用户数据失败:', error)
+	}
+}
+```
+
+### 配置加载遮罩
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios(httpClient)
+
+// 配置加载遮罩
+api.loadingMask.value = {
+	status: true, // 启用加载遮罩
+	text: '正在加载数据，请稍候...', // 自定义加载文本
+}
+
+// 发送请求时会自动显示加载遮罩
+api.execute('/data/list', { page: 1 })
+```
+
+### 配置确认对话框
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios(httpClient)
+
+// 配置确认对话框
+api.dialog.value = {
+	status: true, // 启用确认对话框
+	title: '确认操作',
+	content: '确定要执行此操作吗？',
+	positiveText: '确定',
+	negativeText: '取消',
+}
+
+// 发送请求前会先显示确认对话框
+api.execute('/user/delete', { userId: '123' })
+```
+
+### 启用响应消息提示
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios(httpClient)
+
+// 启用响应消息提示
+api.message.value = true
+
+// 发送请求后会自动显示响应中的消息
+// 假设响应格式为 { status: boolean, message: string, data: any }
+api.execute('/user/update', { userId: '123', name: '张三' })
+```
+
+### 取消请求
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios(httpClient)
+
+// 发送请求
+const fetchData = () => {
+	api.execute('/data/large-file')
+}
+
+// 取消特定请求
+const cancelFetch = () => {
+	api.cancel('/data/large-file')
+}
+
+// 取消所有请求
+const cancelAllRequests = () => {
+	api.cancelAll()
+}
+```
+
+### 重新发送请求
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios(httpClient)
+
+// 首次发送请求
+api.execute('/data/list', { page: 1 })
+
+// 更新参数并重新发送请求
+const nextPage = () => {
+	api.setParams({ page: api.paramsRef.value.page + 1 })
+}
+
+// 使用当前参数重新发送请求
+const refresh = () => {
+	api.start()
+}
+```
+
+### 监听请求状态
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+import { watch } from 'vue'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios(httpClient)
+
+// 监听加载状态
+watch(api.loading, (isLoading) => {
+	console.log('加载状态:', isLoading)
+})
+
+// 监听错误状态
+watch(api.error, (error) => {
+	if (error) {
+		console.error('请求错误:', error)
+	}
+})
+
+// 监听响应数据
+watch(api.data, (data) => {
+	console.log('响应数据:', data)
+})
+```
+
+## 高级用法
+
+### 设置默认数据
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+const api = useAxios<{ list: any[]; total: number }>(httpClient)
+
+// 设置默认数据
+api.defaultData.value = { list: [], total: 0 }
+
+// 当请求失败时，data 会被重置为默认数据
+api.execute('/data/list', { page: 1 })
+```
+
+### 类型化请求和响应
+
+```typescript
+import { useAxios, HttpClient } from '@baota/hooks/axios'
+
+// 定义响应数据类型
+interface UserData {
+	id: string
+	name: string
+	email: string
+	role: string
+}
+
+// 定义请求参数类型
+interface UserParams {
+	userId: string
+}
+
+const httpClient = new HttpClient({
+	baseURL: 'https://api.example.com',
+})
+
+// 创建类型化的请求钩子
+const api = useAxios<UserData, UserParams>(httpClient)
+
+// 发送类型化的请求
+const fetchUser = async (userId: string) => {
+	const user = await api.execute('/user/info', { userId })
+	// user 的类型为 UserData
+	console.log(`用户名: ${user.name}, 角色: ${user.role}`)
+}
+```
+
+## 注意事项
+
+1. `useAxios` 默认使用 POST 方法发送请求，如需使用其他 HTTP 方法，需要在 HttpClient 实例中配置。
+
+2. 响应消息提示功能要求响应数据格式包含 `status` 和 `message` 字段。
+
+3. 加载遮罩、确认对话框和响应消息提示功能依赖于 `@baota/naive-ui/hooks` 提供的相关组件。
+
+4. 取消请求功能基于 Axios 的 AbortController 实现，可以通过 URL 来标识和取消特定请求。
+
+5. 当请求被取消时，`aborted` 状态会被设置为 `true`，可以通过监听此状态来处理请求取消的情况。
+
+6. 错误处理会自动显示错误消息，并将错误信息存储在 `error` 状态中。