API 集成日志

更新时间: 2026-02-05

本文档记录项目 API 集成的历史和经验教训。

---

📡 API 概述

API 基础信息

项目	值
Base URL	（待配置）
认证方式	sessionid（存储在 wx.storage）
响应格式	{ code, data, msg }
成功标识	code === 1

API 模块结构

src/api/
├── common.js        # 短信验证码、上传凭证
├── user.js          # 用户认证和个人信息
├── family.js        # 家庭管理
├── points.js        # 积分/奖励系统
├── photo.js         # 照片/媒体处理
├── organization.js  # 组织管理
├── coupon.js        # 优惠券
├── feedback.js      # 用户反馈
├── map.js           # 地图相关
└── fn.js            # 通用函数

---

🔑 认证机制

SessionID 管理

获取 SessionID

// src/utils/request.js
const getSessionId = () => {
  try {
    return wx.getStorageSync('sessionid') || ''
  } catch (e) {
    console.error('获取 sessionid 失败', e)
    return ''
  }
}

设置 SessionID

// 登录成功后设置
const loginSuccess = (sessionid) => {
  wx.setStorageSync('sessionid', sessionid)
}

// 小程序授权成功后设置
const authSuccess = (sessionid) => {
  wx.setStorageSync('sessionid', sessionid)
}

清除 SessionID

// 401 响应时清除
const clearSessionId = () => {
  wx.removeStorageSync('sessionid')
}

// 用户登出时清除
const logout = () => {
  wx.removeStorageSync('sessionid')
  Taro.reLaunch({ url: '/pages/login/index' })
}

请求拦截器

// src/utils/request.js
service.interceptors.request.use(config => {
  // 动态获取 sessionid 并设置到请求头
  const sessionid = getSessionId()
  if (sessionid) {
    config.headers.cookie = sessionid
  }
  return config
})

---

📋 API 列表

用户相关 (user.js)

API	说明	方法
miniProgramAuthAPI	小程序静默授权	POST
loginAPI	用户登录	POST
getUserInfoAPI	获取用户信息	GET
updateUserInfoAPI	更新用户信息	POST

家庭相关 (family.js)

API	说明	方法
createFamilyAPI	创建家庭	POST
joinFamilyAPI	加入家庭	POST
getFamilyInfoAPI	获取家庭信息	GET
updateFamilyAPI	更新家庭信息	POST

积分相关 (points.js)

API	说明	方法
getPointsListAPI	获取积分列表	GET
addPointsAPI	添加积分	POST
deductPointsAPI	扣除积分	POST

照片相关 (photo.js)

API	说明	方法
uploadPhotoAPI	上传照片	POST
getPhotoListAPI	获取照片列表	GET
deletePhotoAPI	删除照片	POST

---

🔌 API 集成最佳实践

1. 统一错误处理

// ✅ 正确 - 完整的错误处理
const fetchData = async () => {
  loading.value = true
  try {
    const res = await yourAPI()
    if (res.code === 1) {
      dataList.value = res.data
    } else {
      Taro.showToast({
        title: res.msg || '请求失败',
        icon: 'none'
      })
    }
  } catch (err) {
    console.error('请求失败:', err)
    Taro.showToast({
      title: '网络异常',
      icon: 'none'
    })
  } finally {
    loading.value = false
  }
}

2. 检查响应格式

// ✅ 正确 - 检查 res.code === 1
if (res.code === 1) {
  // 处理成功
}

// ❌ 错误 - 不检查或错误检查
if (res.code) {  // 错误：应该检查 === 1
  // ...
}

3. 加载状态管理

const loading = ref(false)
const error = ref(null)

const fetchData = async () => {
  loading.value = true
  error.value = null
  try {
    const res = await yourAPI()
    if (res.code === 1) {
      dataList.value = res.data
    } else {
      error.value = res.msg
    }
  } catch (err) {
    error.value = err.message
  } finally {
    loading.value = false
  }
}

---

⚠️ 常见问题

问题 1: 401 未授权

原因: sessionid 过期或无效

解决方案:

// 响应拦截器自动处理（已实现）
service.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      // 清除 sessionid
      wx.removeStorageSync('sessionid')
      // 跳转登录页
      Taro.reLaunch({ url: '/pages/login/index' })
    }
    return Promise.reject(error)
  }
)

问题 2: 跨域问题

原因: 域名未在微信小程序后台配置

解决方案:

1. 登录微信小程序后台
2. 开发 → 开发管理 → 开发设置
3. 配置服务器域名白名单

问题 3: 请求超时

原因: 网络慢或服务器响应慢

解决方案:

// 设置合理的超时时间
const request = axios.create({
  timeout: 10000 // 10 秒
})

---

📝 API 变更日志

2026-02-05

• ✅ 创建 API 集成日志文档
• ✅ 整理现有 API 模块
• ✅ 记录认证机制

---

🔗 相关文档

• CLAUDE.md - 项目指南
• CODING-STANDARDS.md - 代码规范
• DEVELOPMENT-GUIDE.md - 开发指南

---

维护者: 开发团队 最后更新: 2026-02-05