integral-shop/single_uniapp22miao/docs/API接口使用指南.md

API接口使用指南

文件: api/miao.js
创建时间: 2025-11-08
接口总数: 50+ 个

---

📋 目录

1. 快速开始
2. 模块说明
3. 使用示例
4. 错误处理
5. 最佳实践

---

🚀 快速开始

1. 导入API

// 方式一：按需导入（推荐）
import { userLogin, getGoodsList, buyGoods } from '@/api/miao.js';

// 方式二：全部导入
import * as miaoApi from '@/api/miao.js';

// 方式三：默认导入
import miaoApi from '@/api/miao.js';

2. 基本使用

// 在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. 用户登录流程

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. 商品列表加载

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. 抢购下单流程

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. 地址管理

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. 文件上传

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. 统一错误处理

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. 登录过期处理

// 在 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

// 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. 全局挂载

// 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支持

// 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）

// 在 request.js 中配置
header: {
  'Authori-zation': 'Bearer ' + token
}

2. POST方法查询

以下接口虽然是查询操作，但使用POST方法：

• userInfo() - 获取用户信息
• getIndexConfig() - 获取首页配置
• getOrderIndex() - 获取订单首页
• getDefaultAddress() - 获取默认地址

3. 分页参数

统一使用以下分页参数：

{
  page: 1,     // 页码，从1开始
  limit: 20    // 每页数量
}

4. 响应格式

统一响应格式：

{
  code: 0,           // 0表示成功
  msg: 'success',    // 提示信息
  data: {}           // 返回数据
}

---

📚 相关文档

• 后端API接口文档 - 详细接口文档
• API接口速查表 - 快速查询表
• API分析总结 - 分析报告

---

最后更新: 2025-11-08
文档版本: v1.0