079076a70e
- 从 main 获取 single_uniapp22miao 子项目 - dart-sass: /deep/ -> ::v-deep，calc 运算符加空格 - DEPLOY.md 采用 shccd159 版本（4 子项目架构说明） Made-with: Cursor
747 lines
16 KiB
Markdown
747 lines
16 KiB
Markdown
# API接口使用指南
|
||
|
||
> **文件**: `api/miao.js`
|
||
> **创建时间**: 2025-11-08
|
||
> **接口总数**: 50+ 个
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [快速开始](#快速开始)
|
||
2. [模块说明](#模块说明)
|
||
3. [使用示例](#使用示例)
|
||
4. [错误处理](#错误处理)
|
||
5. [最佳实践](#最佳实践)
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 导入API
|
||
|
||
```javascript
|
||
// 方式一：按需导入（推荐）
|
||
import { userLogin, getGoodsList, buyGoods } from '@/api/miao.js';
|
||
|
||
// 方式二：全部导入
|
||
import * as miaoApi from '@/api/miao.js';
|
||
|
||
// 方式三：默认导入
|
||
import miaoApi from '@/api/miao.js';
|
||
```
|
||
|
||
### 2. 基本使用
|
||
|
||
```javascript
|
||
// 在Vue组件中使用
|
||
export default {
|
||
methods: {
|
||
async login() {
|
||
try {
|
||
const res = await userLogin({
|
||
account: '18379637515',
|
||
password: '123456'
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
// 登录成功
|
||
uni.setStorageSync('token', res.data.token);
|
||
}
|
||
} catch (error) {
|
||
console.error('登录失败:', error);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 模块说明
|
||
|
||
### 一、用户认证模块（7个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `userLogin` | 用户登录 | {account, password} | ❌ |
|
||
| `userRegister` | 用户注册 | {mobile, code, password, invite_code} | ❌ |
|
||
| `userInfo` | 获取用户信息 | - | ✅ |
|
||
| `updateNickname` | 修改昵称 | {nickname} | ✅ |
|
||
| `changePassword` | 修改密码 | {old_password, new_password, code} | ✅ |
|
||
| `resetPassword` | 重置密码 | {mobile, code, password} | ❌ |
|
||
| `uploadAvatar` | 上传头像 | {file} | ✅ |
|
||
|
||
---
|
||
|
||
### 二、商品模块（3个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getGoodsCategory` | 商品分类 | - | ❌ |
|
||
| `getGoodsList` | 商品列表 | {page, limit, category_id, keyword} | ❌ |
|
||
| `getGoodsDetail` | 商品详情 | id | ❌ |
|
||
|
||
---
|
||
|
||
### 三、订单模块（10个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getOrderIndex` | 订单首页 | - | ✅ |
|
||
| `getOrderGoods` | 可购买商品 | {page, limit, type} | ✅ |
|
||
| `buyGoods` | 购买商品 | {goods_id, address_id} | ✅ |
|
||
| `getOrderList` | 订单列表 | {page, limit, type, status} | ✅ |
|
||
| `getOrderDetail` | 订单详情 | id | ✅ |
|
||
| `payOrder` | 支付订单 | {id} | ✅ |
|
||
| `confirmOrder` | 确认订单 | {id} | ✅ |
|
||
| `cancelOrder` | 取消订单 | {id} | ✅ |
|
||
| `resellOrder` | 转卖订单 | {id} | ✅ |
|
||
| `getOrderCount` | 订单统计 | - | ✅ |
|
||
|
||
---
|
||
|
||
### 四、地址管理模块（6个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getAddressList` | 地址列表 | - | ✅ |
|
||
| `getDefaultAddress` | 默认地址 | - | ✅ |
|
||
| `addAddress` | 新增地址 | {name, mobile, province, city, district, detail, is_default} | ✅ |
|
||
| `updateAddress` | 更新地址 | {id, name, mobile, ...} | ✅ |
|
||
| `deleteAddress` | 删除地址 | {id} | ✅ |
|
||
| `getAddressDetail` | 地址详情 | id | ✅ |
|
||
|
||
---
|
||
|
||
### 五、财务模块（3个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getMoneyList` | 财务记录 | {page, limit, cate, type} | ✅ |
|
||
| `getWithdrawLog` | 提现记录 | {page, limit} | ✅ |
|
||
| `applyWithdraw` | 申请提现 | {amount, type} | ✅ |
|
||
|
||
---
|
||
|
||
### 六、支付方式模块（4个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getAlipayInfo` | 支付宝信息 | - | ✅ |
|
||
| `bindAlipay` | 绑定支付宝 | {account, real_name} | ✅ |
|
||
| `getBankInfo` | 银行卡信息 | - | ✅ |
|
||
| `bindBank` | 绑定银行卡 | {bank_name, card_no, real_name, bank_branch} | ✅ |
|
||
|
||
---
|
||
|
||
### 七、分享推广模块（2个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getShareIndex` | 分享首页 | - | ✅ |
|
||
| `getFansList` | 粉丝列表 | {page, limit, level} | ✅ |
|
||
|
||
---
|
||
|
||
### 八、首页模块（2个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `getBannerList` | 轮播图 | - | ❌ |
|
||
| `getIndexConfig` | 首页配置 | - | ❌ |
|
||
|
||
---
|
||
|
||
### 九、其他模块（5个接口）
|
||
|
||
| 函数名 | 说明 | 参数 | 需要登录 |
|
||
|--------|------|------|---------|
|
||
| `sendSms` | 发送验证码 | {mobile, event} | ❌ |
|
||
| `getAgreement` | 协议内容 | {type} | ❌ |
|
||
| `getSetting` | 系统配置 | - | ❌ |
|
||
| `getContractList` | 合同列表 | - | ✅ |
|
||
| `getPrizeList` | 奖品列表 | {page, limit} | ✅ |
|
||
|
||
---
|
||
|
||
## 💡 使用示例
|
||
|
||
### 1. 用户登录流程
|
||
|
||
```javascript
|
||
import { userLogin, sendSms, userRegister } from '@/api/miao.js';
|
||
|
||
export default {
|
||
data() {
|
||
return {
|
||
formData: {
|
||
mobile: '',
|
||
code: '',
|
||
password: ''
|
||
}
|
||
}
|
||
},
|
||
|
||
methods: {
|
||
// 发送验证码
|
||
async sendCode() {
|
||
try {
|
||
await sendSms({
|
||
mobile: this.formData.mobile,
|
||
event: 'register'
|
||
});
|
||
|
||
uni.showToast({
|
||
title: '验证码已发送',
|
||
icon: 'success'
|
||
});
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '发送失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
},
|
||
|
||
// 注册
|
||
async register() {
|
||
try {
|
||
const res = await userRegister({
|
||
mobile: this.formData.mobile,
|
||
code: this.formData.code,
|
||
password: this.formData.password
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
// 保存token
|
||
uni.setStorageSync('token', res.data.token);
|
||
|
||
// 跳转首页
|
||
uni.switchTab({
|
||
url: '/pages/index/index'
|
||
});
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '注册失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
},
|
||
|
||
// 登录
|
||
async login() {
|
||
try {
|
||
const res = await userLogin({
|
||
account: this.formData.mobile,
|
||
password: this.formData.password
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
uni.setStorageSync('token', res.data.token);
|
||
uni.setStorageSync('userInfo', res.data.user_info);
|
||
|
||
uni.showToast({
|
||
title: '登录成功',
|
||
icon: 'success'
|
||
});
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '登录失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 商品列表加载
|
||
|
||
```javascript
|
||
import { getGoodsList } from '@/api/miao.js';
|
||
|
||
export default {
|
||
data() {
|
||
return {
|
||
goodsList: [],
|
||
page: 1,
|
||
limit: 10,
|
||
loading: false,
|
||
noMore: false
|
||
}
|
||
},
|
||
|
||
onLoad() {
|
||
this.loadGoodsList();
|
||
},
|
||
|
||
methods: {
|
||
async loadGoodsList() {
|
||
if (this.loading || this.noMore) return;
|
||
|
||
this.loading = true;
|
||
|
||
try {
|
||
const res = await getGoodsList({
|
||
page: this.page,
|
||
limit: this.limit,
|
||
category_id: 1 // 可选
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
const list = res.data.list || [];
|
||
|
||
if (list.length < this.limit) {
|
||
this.noMore = true;
|
||
}
|
||
|
||
this.goodsList = this.page === 1
|
||
? list
|
||
: [...this.goodsList, ...list];
|
||
}
|
||
} catch (error) {
|
||
console.error('加载失败:', error);
|
||
} finally {
|
||
this.loading = false;
|
||
}
|
||
},
|
||
|
||
// 加载更多
|
||
loadMore() {
|
||
if (!this.loading && !this.noMore) {
|
||
this.page++;
|
||
this.loadGoodsList();
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 抢购下单流程
|
||
|
||
```javascript
|
||
import { getOrderGoods, buyGoods, payOrder } from '@/api/miao.js';
|
||
|
||
export default {
|
||
data() {
|
||
return {
|
||
goodsId: null,
|
||
addressId: null,
|
||
orderId: null
|
||
}
|
||
},
|
||
|
||
methods: {
|
||
// 1. 加载可购买商品
|
||
async loadGoods() {
|
||
try {
|
||
const res = await getOrderGoods({
|
||
page: 1,
|
||
limit: 20,
|
||
type: 1 // 1:可购买
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
this.goodsList = res.data.list;
|
||
}
|
||
} catch (error) {
|
||
console.error('加载失败:', error);
|
||
}
|
||
},
|
||
|
||
// 2. 抢单
|
||
async handleBuy() {
|
||
try {
|
||
const res = await buyGoods({
|
||
goods_id: this.goodsId,
|
||
address_id: this.addressId
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
this.orderId = res.data.order_id;
|
||
|
||
uni.showToast({
|
||
title: '抢购成功',
|
||
icon: 'success'
|
||
});
|
||
|
||
// 继续支付
|
||
await this.handlePay();
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '抢购失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
},
|
||
|
||
// 3. 支付
|
||
async handlePay() {
|
||
try {
|
||
const res = await payOrder({
|
||
id: this.orderId
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
uni.showToast({
|
||
title: '支付成功',
|
||
icon: 'success'
|
||
});
|
||
|
||
// 跳转订单详情
|
||
uni.navigateTo({
|
||
url: `/pages/sub-pages/rushing-order/detail?id=${this.orderId}`
|
||
});
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '支付失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 地址管理
|
||
|
||
```javascript
|
||
import { getAddressList, addAddress, updateAddress, deleteAddress } from '@/api/miao.js';
|
||
|
||
export default {
|
||
data() {
|
||
return {
|
||
addressList: []
|
||
}
|
||
},
|
||
|
||
methods: {
|
||
// 加载地址列表
|
||
async loadAddressList() {
|
||
try {
|
||
const res = await getAddressList();
|
||
if (res.code === 0) {
|
||
this.addressList = res.data.list;
|
||
}
|
||
} catch (error) {
|
||
console.error('加载失败:', error);
|
||
}
|
||
},
|
||
|
||
// 新增地址
|
||
async addNewAddress() {
|
||
try {
|
||
const res = await addAddress({
|
||
name: '张三',
|
||
mobile: '13800138000',
|
||
province: '江苏省',
|
||
city: '苏州市',
|
||
district: '工业园区',
|
||
detail: '星湖街328号',
|
||
is_default: 1
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
uni.showToast({
|
||
title: '添加成功',
|
||
icon: 'success'
|
||
});
|
||
|
||
this.loadAddressList();
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '添加失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
},
|
||
|
||
// 删除地址
|
||
async deleteAddr(id) {
|
||
try {
|
||
const res = await deleteAddress({ id });
|
||
if (res.code === 0) {
|
||
uni.showToast({
|
||
title: '删除成功',
|
||
icon: 'success'
|
||
});
|
||
|
||
this.loadAddressList();
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: error.msg || '删除失败',
|
||
icon: 'none'
|
||
});
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 文件上传
|
||
|
||
```javascript
|
||
import { uploadFile } from '@/api/miao.js';
|
||
|
||
export default {
|
||
methods: {
|
||
// 选择并上传图片
|
||
chooseAndUpload() {
|
||
uni.chooseImage({
|
||
count: 1,
|
||
success: async (res) => {
|
||
const filePath = res.tempFilePaths[0];
|
||
|
||
uni.showLoading({ title: '上传中...' });
|
||
|
||
try {
|
||
const uploadRes = await uploadFile(filePath, 'user/avatar');
|
||
|
||
if (uploadRes.code === 0) {
|
||
uni.showToast({
|
||
title: '上传成功',
|
||
icon: 'success'
|
||
});
|
||
|
||
// 使用上传后的图片URL
|
||
const imageUrl = uploadRes.data.url;
|
||
console.log('图片URL:', imageUrl);
|
||
}
|
||
} catch (error) {
|
||
uni.showToast({
|
||
title: '上传失败',
|
||
icon: 'none'
|
||
});
|
||
} finally {
|
||
uni.hideLoading();
|
||
}
|
||
}
|
||
});
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ❌ 错误处理
|
||
|
||
### 1. 统一错误处理
|
||
|
||
```javascript
|
||
import { userLogin } from '@/api/miao.js';
|
||
|
||
async function login(data) {
|
||
try {
|
||
const res = await userLogin(data);
|
||
|
||
// 成功处理
|
||
if (res.code === 0) {
|
||
return res.data;
|
||
} else {
|
||
// 业务错误
|
||
throw new Error(res.msg || '操作失败');
|
||
}
|
||
} catch (error) {
|
||
// 网络错误或其他错误
|
||
console.error('请求失败:', error);
|
||
|
||
uni.showToast({
|
||
title: error.message || '网络错误',
|
||
icon: 'none'
|
||
});
|
||
|
||
throw error;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 登录过期处理
|
||
|
||
```javascript
|
||
// 在 utils/request.js 中统一处理
|
||
request.interceptors.response.use(
|
||
response => {
|
||
const res = response.data;
|
||
|
||
// Token过期
|
||
if (res.code === 401 || res.code === 403) {
|
||
uni.removeStorageSync('token');
|
||
uni.removeStorageSync('userInfo');
|
||
|
||
uni.showToast({
|
||
title: '登录已过期',
|
||
icon: 'none'
|
||
});
|
||
|
||
setTimeout(() => {
|
||
uni.navigateTo({
|
||
url: '/pages/sub-pages/login/index'
|
||
});
|
||
}, 1500);
|
||
|
||
return Promise.reject(res);
|
||
}
|
||
|
||
return res;
|
||
},
|
||
error => {
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## ✨ 最佳实践
|
||
|
||
### 1. 封装成Mixin
|
||
|
||
```javascript
|
||
// mixins/apiMixin.js
|
||
import * as miaoApi from '@/api/miao.js';
|
||
|
||
export default {
|
||
data() {
|
||
return {
|
||
$api: miaoApi
|
||
}
|
||
}
|
||
}
|
||
|
||
// 在页面中使用
|
||
export default {
|
||
mixins: [apiMixin],
|
||
|
||
methods: {
|
||
async loadData() {
|
||
const res = await this.$api.getGoodsList({ page: 1 });
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 全局挂载
|
||
|
||
```javascript
|
||
// main.js
|
||
import * as miaoApi from '@/api/miao.js';
|
||
|
||
// 方式一：挂载到Vue原型
|
||
Vue.prototype.$miaoApi = miaoApi;
|
||
|
||
// 方式二：挂载到全局
|
||
uni.$miaoApi = miaoApi;
|
||
|
||
// 使用
|
||
export default {
|
||
methods: {
|
||
async loadData() {
|
||
// 方式一
|
||
const res1 = await this.$miaoApi.getGoodsList({ page: 1 });
|
||
|
||
// 方式二
|
||
const res2 = await uni.$miaoApi.getGoodsList({ page: 1 });
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. TypeScript支持
|
||
|
||
```typescript
|
||
// api/miao.d.ts
|
||
declare module '@/api/miao' {
|
||
export function userLogin(data: {
|
||
account: string;
|
||
password: string;
|
||
}): Promise<any>;
|
||
|
||
export function getGoodsList(params: {
|
||
page: number;
|
||
limit: number;
|
||
category_id?: number;
|
||
keyword?: string;
|
||
}): Promise<any>;
|
||
|
||
// ... 其他接口定义
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 1. 认证头名称
|
||
|
||
⚠️ **重要**: 本项目使用的认证头是 `Authori-zation`（不是标准的 `Authorization`）
|
||
|
||
```javascript
|
||
// 在 request.js 中配置
|
||
header: {
|
||
'Authori-zation': 'Bearer ' + token
|
||
}
|
||
```
|
||
|
||
### 2. POST方法查询
|
||
|
||
以下接口虽然是查询操作，但使用POST方法：
|
||
- `userInfo()` - 获取用户信息
|
||
- `getIndexConfig()` - 获取首页配置
|
||
- `getOrderIndex()` - 获取订单首页
|
||
- `getDefaultAddress()` - 获取默认地址
|
||
|
||
### 3. 分页参数
|
||
|
||
统一使用以下分页参数：
|
||
```javascript
|
||
{
|
||
page: 1, // 页码，从1开始
|
||
limit: 20 // 每页数量
|
||
}
|
||
```
|
||
|
||
### 4. 响应格式
|
||
|
||
统一响应格式：
|
||
```javascript
|
||
{
|
||
code: 0, // 0表示成功
|
||
msg: 'success', // 提示信息
|
||
data: {} // 返回数据
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [后端API接口文档](./后端API接口文档.md) - 详细接口文档
|
||
- [API接口速查表](./API接口速查表.md) - 快速查询表
|
||
- [API分析总结](./API分析总结-2025-11-08.md) - 分析报告
|
||
|
||
---
|
||
|
||
**最后更新**: 2025-11-08
|
||
**文档版本**: v1.0
|
||
|