184 lines
5.1 KiB
Markdown
184 lines
5.1 KiB
Markdown
# ApiMixin 使用指南
|
||
|
||
## 概述
|
||
`ApiMixin` 是一个 Vue mixin，用于统一管理和简化应用中的 API 调用。它提供了两个主要方法：
|
||
- `callApi()` - 基础的 API 调用方法
|
||
- `callApiWithErrorMsg()` - 带自动错误处理的 API 调用方法
|
||
|
||
## 安装步骤
|
||
|
||
### 1. 引入 ApiMixin
|
||
在您的 HTML 页面中添加脚本引用（在 Vue 和其他依赖之后）：
|
||
```html
|
||
<script src="Scripts/ApiMixin.js"></script>
|
||
```
|
||
|
||
### 2. 在 Vue 组件中使用
|
||
在您的 Vue 组件中，在 mixins 数组中添加 `ApiMixin`：
|
||
```javascript
|
||
receiptEditApp = new Vue({
|
||
el: '#receiptEditApp',
|
||
mixins: [DateMixin, ToastMixin, ApiMixin], // 添加 ApiMixin
|
||
data: { ... },
|
||
// 其他选项
|
||
});
|
||
```
|
||
|
||
## API 方法
|
||
|
||
### callApi(endpoint, functionName, data)
|
||
**用途**: 调用 API 并返回原始结果
|
||
|
||
**参数**:
|
||
- `endpoint` (string): API 端点名称（.asmx 文件名）
|
||
- 示例: `'領據處理'`, `'付款設定'`
|
||
- `functionName` (string): 方法名称
|
||
- 示例: `'Save'`, `'GetOne'`, `'SearchRecipient'`
|
||
- `data` (object, 可选): 要传送的数据对象，默认为 `{}`
|
||
|
||
**返回值**: Promise，resolve 时返回 API 响应对象，reject 时返回错误对象
|
||
|
||
**示例**:
|
||
```javascript
|
||
// 基础使用
|
||
try {
|
||
const result = await this.callApi('領據處理', 'GetOne', { no: '001' });
|
||
console.log(result.Data);
|
||
} catch (error) {
|
||
console.error('API 调用失败:', error);
|
||
}
|
||
|
||
// 不等待结果
|
||
this.callApi('領據處理', 'Save', data)
|
||
.then(result => {
|
||
this.ShowSuccess(result.Message);
|
||
})
|
||
.catch(error => {
|
||
this.ShowError(error.message);
|
||
});
|
||
```
|
||
|
||
### callApiWithErrorMsg(endpoint, functionName, data, errorPrefix)
|
||
**用途**: 调用 API 并自动显示错误消息
|
||
|
||
**参数**:
|
||
- `endpoint` (string): API 端点名称
|
||
- `functionName` (string): 方法名称
|
||
- `data` (object, 可选): 要传送的数据对象
|
||
- `errorPrefix` (string, 可选): 错误消息前缀，默认为 `'操作'`
|
||
|
||
**返回值**: Promise，reject 时自动调用 `this.ShowError()`
|
||
|
||
**示例**:
|
||
```javascript
|
||
// 使用自动错误处理
|
||
try {
|
||
const result = await this.callApiWithErrorMsg('領據處理', 'Save', data, '儲存');
|
||
this.ShowSuccess(result.Message);
|
||
} catch (error) {
|
||
// 错误已自动显示
|
||
console.error('操作失败:', error);
|
||
}
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
### 原始代码（冗长）
|
||
```javascript
|
||
loadData(no) {
|
||
this.loading = true;
|
||
|
||
axios({
|
||
method: 'post',
|
||
url: `${API_BASE}/GetOne`,
|
||
headers: {
|
||
'Content-Type': 'application/json; charset=utf-8'
|
||
},
|
||
data: JSON.stringify({ no })
|
||
})
|
||
.then(response => {
|
||
const result = response.data.d || response.data;
|
||
if (result.Success) {
|
||
this.mainData = result.Data.main;
|
||
this.laborData = result.Data.labor;
|
||
this.travelData = result.Data.travel;
|
||
this.backupData();
|
||
} else {
|
||
this.ShowError('載入失敗: ' + result.Message);
|
||
}
|
||
})
|
||
.catch(error => {
|
||
console.error('LoadData error:', error);
|
||
this.ShowError('載入發生錯誤: ' + (error.message || '請檢查網路連線'));
|
||
})
|
||
.finally(() => {
|
||
this.loading = false;
|
||
});
|
||
}
|
||
```
|
||
|
||
### 使用 ApiMixin 的简化代码
|
||
```javascript
|
||
async loadData(no) {
|
||
this.loading = true;
|
||
|
||
try {
|
||
const result = await this.callApiWithErrorMsg('領據處理', 'GetOne', { no }, '載入');
|
||
|
||
this.mainData = result.Data.main;
|
||
this.laborData = result.Data.labor;
|
||
this.travelData = result.Data.travel;
|
||
this.backupData();
|
||
} catch (error) {
|
||
console.error('LoadData error:', error);
|
||
} finally {
|
||
this.loading = false;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 重构建议
|
||
|
||
使用 ApiMixin 后，您可以将 `領據處理.js` 中的多个方法简化：
|
||
|
||
1. **save()** - 减少 ~15 行代码
|
||
2. **loadDropdownList()** - 减少 ~10 行代码
|
||
3. **searchRecipient()** - 减少 ~10 行代码
|
||
4. **searchPlan()** - 减少 ~10 行代码
|
||
5. **searchOriginStation()** - 减少 ~10 行代码
|
||
6. **searchDestStation()** - 减少 ~10 行代码
|
||
7. **calculateTax()** - 减少 ~5 行代码
|
||
8. **calculateFare()** - 减少 ~5 行代码
|
||
|
||
**总计**: 可减少 ~65+ 行代码，提高代码可读性和可维护性
|
||
|
||
## 错误处理
|
||
|
||
ApiMixin 会自动处理以下情况：
|
||
- ✅ API 响应格式 (`data.d` 或 `data`)
|
||
- ✅ Success 字段检查
|
||
- ✅ 错误消息提取
|
||
- ✅ 网络错误捕获
|
||
- ✅ 自动显示错误（使用 `callApiWithErrorMsg`）
|
||
|
||
## 注意事项
|
||
|
||
1. **ToastMixin 依赖**: `callApiWithErrorMsg` 需要 `this.ShowError()` 方法，确保您的 Vue 组件已混入 `ToastMixin`
|
||
|
||
2. **API_BASE 变量**: 确保 `API_BASE` 全局变量已定义
|
||
|
||
3. **异步/等待**: 建议在 async/await 的 try-catch 块中使用，更易读
|
||
|
||
4. **错误消息格式**: 错误消息会自动格式化为 `"{errorPrefix}失敗: {具体错误信息}"`
|
||
|
||
## 性能优化
|
||
|
||
由于所有 API 调用都走同一个方法，未来可以在 `callApi` 中添加：
|
||
- ✅ API 请求/响应日志
|
||
- ✅ 请求超时管理
|
||
- ✅ 重试机制
|
||
- ✅ 请求缓存
|
||
- ✅ 性能监测
|
||
|
||
无需修改调用代码！
|