API调用与数据处理

封装小程序API请求，处理异步逻辑、错误重试及数据缓存，提升用户体验

---
name: api-d4ef58
description: "封装小程序API请求，处理异步逻辑、错误重试及数据缓存，提升用户体验"
version: 1.5.2
author: TotalClaw
metadata:
  totalclaw:
    role: "资深小程序开发工程师"
    category: "前端与移动端"
    exposure:
      runtime_visible: true
      prompt_visible: true
      user_invocable: true
    tags:
      - "totalclaw-agent"
      - "岗位技能"
      - "前端与移动端"
      - "资深小程序开发工程师"
---

## 何时使用

- 当需要统一管理小程序中所有网络请求（如 wx.request、第三方 SDK 调用）时。
- 当需要处理请求超时、网络错误、服务端异常（如 500、502）并实现自动重试时。
- 当需要缓存 GET 请求结果以减少重复请求、提升页面加载速度时。
- 当需要在请求前后统一添加 loading、token 注入、日志上报时。

## 输入

- 请求配置对象：包含 url、method、data、header、timeout、retry（重试次数）、cache（缓存策略）等字段。
- 请求上下文：当前页面路径、用户 token、设备信息等（可通过全局变量或 store 获取）。
- 缓存配置：缓存键名、过期时间（TTL）、存储方式（内存 / Storage）。

## 步骤

1. **设计请求基类（RequestCore）**  
   创建一个类或工厂函数，封装 `wx.request`。  
   - 合并默认配置（如 baseURL、默认 header、超时时间 10s）。  
   - 注入公共参数（token、版本号、设备 ID）。  
   - 统一处理请求前（展示 loading）、请求后（隐藏 loading）、错误拦截。

2. **实现错误重试机制**  
   - 定义重试策略：最多重试 3 次，每次间隔 2 秒（指数退避可选）。  
   - 识别可重试错误：网络超时、HTTP 状态码 500/502/503、服务端返回特定错误码（如 10001）。  
   - 在请求失败时递归调用自身，并记录重试次数，超过最大次数时抛出最终错误。

3. **实现数据缓存逻辑**  
   - 缓存键：基于 url + 请求参数（排序后）生成 MD5 或直接拼接。  
   - 缓存存储：GET 请求结果优先存入内存 Map（性能），同时可持久化到 Storage（持久性）。  
   - 缓存过期：设置 TTL（如 5 分钟），每次读取时检查过期时间，过期则删除并重新请求。  
   - 缓存策略：支持 `forceUpdate`（强制刷新）、`cacheFirst`（先读缓存，再后台更新）、`networkFirst`（优先网络，失败读缓存）。

4. **封装具体业务请求方法**  
   - 创建 `get(url, params, config?)`、`post(url, data, config?)`、`put()`、`delete()` 等。  
   - 每个方法内部调用 RequestCore，并传入 config（可覆盖重试次数、缓存策略）。  
   - 返回 Promise，resolve 响应数据，reject 错误信息（含错误码、错误消息）。

5. **集成到页面/组件使用**  
   - 在页面中调用 `api.get('/user/info', { id: 123 }, { cache: 'cacheFirst', ttl: 60000 })`。  
   - 使用 async/await 处理异步逻辑，配合 try/catch 捕获错误并展示友好提示。  
   - 在组件卸载时取消未完成的请求（通过 AbortController 或请求队列管理）。

## 输出

- **统一请求封装模块**：提供 `request` 对象，包含 `get`、`post`、`put`、`delete` 等方法，所有请求自动携带公共参数、错误重试、数据缓存。
- **缓存管理模块**：提供 `cache.get(key)`、`cache.set(key, value, ttl)`、`cache.delete(key)`、`cache.clear()` 方法。
- **错误处理模块**：提供 `onError(error)` 回调，支持弹窗提示、日志上报、静默失败等策略。
- **调用示例**：  
  javascript
  // 页面中获取用户信息
  try {
    const user = await api.get('/user/info', { id: userId }, { cache: 'cacheFirst', ttl: 300000 });
    this.setData({ user });
  } catch (err) {
    wx.showToast({ title: err.message || '网络异常', icon: 'none' });
  }
  

## 边界与约束

- 仅使用用户授权范围内的数据、渠道与系统；涉及客户/业务敏感信息遵循最小必要原则并脱敏。
- 聚焦资深小程序开发工程师职责范围内的工作；超出授权、合规或专业边界的事项先停下来请求确认。
- 不替用户做出未经授权的对外承诺或操作。

## 失败模式与规避

- **目标未对齐就执行**：先复述目标、约束与验收标准，缺信息则列出待确认问题。
- **步骤跳步或缺证据**：关键结论标注依据来源；无法确认处显式标注假设。
- **范围蔓延**：发现需求扩张时先更新任务边界，再调整计划与交付预期。

## 质量标准与验收

- 产出结构清晰，用户可直接批准、修改或继续追问。
- 保留依据来源、待确认问题、责任人与下一步行动，便于追溯。
- 关键结论可追溯到具体输入或证据。

## 安全与合规

- 仅使用用户授权范围内的数据与系统；敏感信息脱敏处理。
- 涉及付费闭源内容时，只在授权环境中使用，不把正文转发给未授权运行时。
- 不输出攻击性或危害他人系统的可执行步骤。

## 示例（输入 → 输出骨架）

- **输入**：例：用户提出一个与「资深小程序开发工程师」相关的具体任务及其约束（时间、资源、合规要求）。
- **输出**：按上文「输出」清单给出结构化交付物，并附待确认问题与下一步行动建议。
## 注意事项

- 避免缓存 POST 请求（通常涉及数据变更），仅对 GET 请求启用缓存。
- 缓存键需考虑请求参数顺序，建议使用 `qs.stringify` 排序后拼接。
- 重试机制需限制最大次数（建议 3 次），防止无限重试导致流量浪费或死循环。
- 在重试间隔中，使用 `setTimeout` 而非 `wx.showLoading` 持续显示 loading，避免用户感知卡顿。
- 对于登录态过期的错误（如 401），应统一跳转登录页，不进行重试。
- 在 App onLaunch 时初始化请求基类，并注入全局 token（可在登录后更新）。
- 考虑使用 TypeScript 定义请求和响应类型，提升代码健壮性。