477 lines
10 KiB
Markdown
477 lines
10 KiB
Markdown
# HTTP工具类使用说明
|
||
|
||
本项目提供了基于Vue2和uni-app的HTTP请求工具类，用于统一管理API请求。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
utils/
|
||
├── https.js # HTTP工具类核心文件
|
||
├── config.js # 配置文件
|
||
├── api.js # API接口配置
|
||
├── api-demo.js # API调用示例
|
||
├── UserUtil.js # 用户信息管理工具类
|
||
├── UserUtil-demo.js # UserUtil使用示例
|
||
└── README.md # 使用说明
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 引入HTTP工具类
|
||
|
||
在需要使用API的组件中引入：
|
||
|
||
```javascript
|
||
// 引入具体的API模块
|
||
import { userApi, householdApi } from '../../utils/api.js'
|
||
|
||
// 或者引入所有API
|
||
import api from '../../utils/api.js'
|
||
```
|
||
|
||
### 2. 引入用户信息管理工具类
|
||
|
||
```javascript
|
||
// 引入UserUtil
|
||
import userUtil from '@/utils/UserUtil.js'
|
||
```
|
||
|
||
### 2. 基本使用
|
||
|
||
```javascript
|
||
export default {
|
||
data() {
|
||
return {
|
||
userInfo: null,
|
||
householdList: []
|
||
}
|
||
},
|
||
|
||
async mounted() {
|
||
// 获取用户信息
|
||
try {
|
||
this.userInfo = await userApi.getUserInfo()
|
||
} catch (error) {
|
||
console.error('获取用户信息失败:', error)
|
||
}
|
||
},
|
||
|
||
methods: {
|
||
// 创建家庭登记
|
||
async createHousehold() {
|
||
try {
|
||
const data = {
|
||
householdName: '张三家庭',
|
||
contactPhone: '13800138000',
|
||
address: '北京市朝阳区xxx街道'
|
||
}
|
||
|
||
const result = await householdApi.createHousehold(data)
|
||
console.log('创建成功:', result)
|
||
|
||
uni.showToast({
|
||
title: '创建成功',
|
||
icon: 'success'
|
||
})
|
||
} catch (error) {
|
||
console.error('创建失败:', error)
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 环境配置
|
||
|
||
在 `config.js` 中配置不同环境的API地址：
|
||
|
||
```javascript
|
||
const ENV = {
|
||
development: {
|
||
baseURL: 'http://localhost:8080/admin-api',
|
||
uploadURL: 'http://localhost:8080/admin-api/upload'
|
||
},
|
||
production: {
|
||
baseURL: 'https://your-production-domain.com/admin-api',
|
||
uploadURL: 'https://your-production-domain.com/admin-api/upload'
|
||
}
|
||
}
|
||
```
|
||
|
||
### 请求拦截器
|
||
|
||
HTTP工具类自动添加了以下拦截器功能：
|
||
|
||
1. **自动拼接基础URL**：非http开头的请求会自动拼接baseURL
|
||
2. **请求超时设置**：默认1000000ms
|
||
3. **请求头设置**：自动添加tenant-id和Authorization
|
||
4. **Token管理**：自动从本地存储获取token
|
||
|
||
### 响应处理
|
||
|
||
- **成功响应**：自动提取 `res.data.data` 作为返回结果
|
||
- **错误处理**：自动显示错误提示
|
||
- **401错误**：自动跳转到登录页
|
||
- **网络错误**：显示网络错误提示
|
||
|
||
## API接口说明
|
||
|
||
### 用户相关接口
|
||
|
||
```javascript
|
||
import { userApi } from '../../utils/api.js'
|
||
|
||
// 用户登录
|
||
const loginResult = await userApi.login({
|
||
username: 'admin',
|
||
password: '123456'
|
||
})
|
||
|
||
// 获取用户信息
|
||
const userInfo = await userApi.getUserInfo()
|
||
|
||
// 用户登出
|
||
await userApi.logout()
|
||
```
|
||
|
||
### 家庭登记相关接口
|
||
|
||
```javascript
|
||
import { householdApi } from '../../utils/api.js'
|
||
|
||
// 获取家庭列表
|
||
const list = await householdApi.getHouseholdList({
|
||
page: 1,
|
||
size: 10,
|
||
status: 'PENDING'
|
||
})
|
||
|
||
// 创建家庭登记
|
||
const result = await householdApi.createHousehold({
|
||
householdName: '张三家庭',
|
||
contactPhone: '13800138000',
|
||
address: '北京市朝阳区'
|
||
})
|
||
|
||
// 上传签名
|
||
const uploadResult = await householdApi.uploadSignature(
|
||
filePath,
|
||
{ signatureType: 'HOLDER' }
|
||
)
|
||
```
|
||
|
||
### 文件上传接口
|
||
|
||
```javascript
|
||
import { uploadApi } from '../../utils/api.js'
|
||
|
||
// 上传图片
|
||
const imageResult = await uploadApi.uploadImage(filePath, {
|
||
type: 'household_photo'
|
||
})
|
||
|
||
// 上传文档
|
||
const docResult = await uploadApi.uploadDocument(filePath, {
|
||
type: 'household_document'
|
||
})
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 全局错误处理
|
||
|
||
HTTP工具类已经内置了错误处理机制：
|
||
|
||
```javascript
|
||
// 自动处理常见错误
|
||
try {
|
||
const result = await userApi.getUserInfo()
|
||
} catch (error) {
|
||
// 错误已经被自动处理，这里可以添加额外逻辑
|
||
console.error('自定义错误处理:', error)
|
||
}
|
||
```
|
||
|
||
### 自定义错误处理
|
||
|
||
```javascript
|
||
// 在组件中自定义错误处理
|
||
methods: {
|
||
async handleRequest() {
|
||
try {
|
||
const result = await householdApi.createHousehold(this.formData)
|
||
// 成功处理
|
||
this.handleSuccess(result)
|
||
} catch (error) {
|
||
// 自定义错误处理
|
||
if (error.statusCode === 403) {
|
||
uni.showModal({
|
||
title: '权限不足',
|
||
content: '您没有权限执行此操作'
|
||
})
|
||
} else {
|
||
uni.showToast({
|
||
title: '操作失败',
|
||
icon: 'none'
|
||
})
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 文件上传
|
||
|
||
### 选择并上传图片
|
||
|
||
```javascript
|
||
methods: {
|
||
selectAndUploadImage() {
|
||
uni.chooseImage({
|
||
count: 1,
|
||
sizeType: ['compressed'],
|
||
sourceType: ['album', 'camera'],
|
||
success: async (res) => {
|
||
const filePath = res.tempFilePaths[0]
|
||
try {
|
||
const result = await uploadApi.uploadImage(filePath, {
|
||
type: 'household_photo'
|
||
})
|
||
console.log('上传成功:', result)
|
||
} catch (error) {
|
||
console.error('上传失败:', error)
|
||
}
|
||
}
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
### 上传签名
|
||
|
||
```javascript
|
||
methods: {
|
||
async uploadSignature(signatureBase64) {
|
||
try {
|
||
// 将base64转换为文件路径
|
||
const filePath = await this.base64ToFilePath(signatureBase64)
|
||
|
||
const result = await householdApi.uploadSignature(filePath, {
|
||
signatureType: 'HOLDER'
|
||
})
|
||
|
||
console.log('签名上传成功:', result)
|
||
} catch (error) {
|
||
console.error('签名上传失败:', error)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 组件中的使用
|
||
|
||
```javascript
|
||
export default {
|
||
data() {
|
||
return {
|
||
loading: false,
|
||
data: null
|
||
}
|
||
},
|
||
|
||
async mounted() {
|
||
await this.loadData()
|
||
},
|
||
|
||
methods: {
|
||
async loadData() {
|
||
this.loading = true
|
||
try {
|
||
this.data = await api.household.getHouseholdList()
|
||
} catch (error) {
|
||
// 错误已被自动处理
|
||
} finally {
|
||
this.loading = false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 表单提交
|
||
|
||
```javascript
|
||
methods: {
|
||
async submitForm() {
|
||
try {
|
||
// 表单验证
|
||
await this.validateForm()
|
||
|
||
// 提交数据
|
||
const result = await householdApi.createHousehold(this.formData)
|
||
|
||
// 成功处理
|
||
uni.showToast({ title: '提交成功', icon: 'success' })
|
||
uni.navigateBack()
|
||
|
||
} catch (error) {
|
||
// 错误处理
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 并行请求
|
||
|
||
```javascript
|
||
methods: {
|
||
async loadInitialData() {
|
||
try {
|
||
const [userInfo, householdList, dictData] = await Promise.all([
|
||
userApi.getUserInfo(),
|
||
householdApi.getHouseholdList(),
|
||
systemApi.getDictData('household_type')
|
||
])
|
||
|
||
this.userInfo = userInfo
|
||
this.householdList = householdList
|
||
this.dictData = dictData
|
||
|
||
} catch (error) {
|
||
console.error('加载数据失败:', error)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **Token管理**：确保登录后正确保存token到本地存储
|
||
2. **错误处理**：虽然工具类会自动处理常见错误，但建议在关键操作中添加自定义错误处理
|
||
3. **文件上传**：注意文件大小限制和格式要求
|
||
4. **网络状态**：在弱网环境下注意请求超时设置
|
||
5. **数据格式**：确保提交的数据格式符合后端API要求
|
||
|
||
## 用户信息管理 (UserUtil)
|
||
|
||
### 基本使用
|
||
|
||
```javascript
|
||
import userUtil from '@/utils/UserUtil.js'
|
||
|
||
// 保存登录信息
|
||
userUtil.setLoginInfo({
|
||
accessToken: 'token123',
|
||
refreshToken: 'refresh123',
|
||
userId: 'user123',
|
||
username: 'admin',
|
||
userInfo: { name: '张三', role: 'admin' }
|
||
})
|
||
|
||
// 检查登录状态
|
||
const isLoggedIn = userUtil.isLoggedIn()
|
||
|
||
// 获取用户信息
|
||
const userInfo = userUtil.getFullUserInfo()
|
||
const loginInfo = userUtil.getLoginInfo()
|
||
const accessToken = userUtil.getAccessToken()
|
||
|
||
// 清除用户信息
|
||
userUtil.clearAll()
|
||
```
|
||
|
||
### 登录流程示例
|
||
|
||
```javascript
|
||
export default {
|
||
methods: {
|
||
async handleLogin() {
|
||
try {
|
||
// 调用登录接口
|
||
const loginResult = await userApi.login(this.loginForm)
|
||
|
||
// 保存登录信息
|
||
userUtil.setLoginInfo({
|
||
accessToken: loginResult.accessToken,
|
||
refreshToken: loginResult.refreshToken,
|
||
userId: loginResult.userId,
|
||
username: this.loginForm.username,
|
||
userInfo: loginResult.userInfo
|
||
})
|
||
|
||
// 保存用户名密码（可选）
|
||
userUtil.setCredentials(this.loginForm.username, this.loginForm.password)
|
||
|
||
// 跳转到主页
|
||
uni.reLaunch({ url: '/pages/index/index' })
|
||
|
||
} catch (error) {
|
||
console.error('登录失败:', error)
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 用户信息管理
|
||
|
||
```javascript
|
||
// 更新用户信息
|
||
userUtil.updateUserInfo({
|
||
nickname: '新昵称',
|
||
avatar: 'new-avatar.jpg'
|
||
})
|
||
|
||
// 保存字典信息
|
||
userUtil.setDictInfo([
|
||
{ dictType: 'household_type', dictLabel: '家庭', dictValue: 'FAMILY' }
|
||
])
|
||
|
||
// 获取字典信息
|
||
const dictInfo = userUtil.getDictInfo()
|
||
```
|
||
|
||
### 自动登录
|
||
|
||
```javascript
|
||
export default {
|
||
async mounted() {
|
||
// 检查是否有保存的凭据
|
||
const credentials = userUtil.getCredentials()
|
||
|
||
if (credentials.username && credentials.password) {
|
||
try {
|
||
// 尝试自动登录
|
||
await this.autoLogin(credentials.username, credentials.password)
|
||
} catch (error) {
|
||
// 自动登录失败，清除凭据
|
||
userUtil.clearCredentials()
|
||
}
|
||
}
|
||
},
|
||
|
||
methods: {
|
||
async autoLogin(username, password) {
|
||
const loginResult = await userApi.login({ username, password })
|
||
userUtil.setLoginInfo({
|
||
accessToken: loginResult.accessToken,
|
||
userId: loginResult.userId,
|
||
username: username,
|
||
userInfo: loginResult.userInfo
|
||
})
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 更新日志
|
||
|
||
- v1.0.0: 初始版本，支持基本的HTTP请求和文件上传
|
||
- 支持Vue2语法和uni-app框架
|
||
- 内置请求拦截器和响应处理
|
||
- 统一的错误处理机制
|
||
- v1.1.0: 新增UserUtil用户信息管理工具类 |