Vue3 + UniApp 多端多环境请求封装落地方案

大象的鼻子那么长
VIP.4 融会贯通
0 阅读8分钟

1. 背景与目标

项目运行在 H5、小程序与 App 多端，并需在 dev/sit/uat 等多环境间切换。请求链路存在平台差异（H5 cookies、App 证书、小程序方法限制）与环境差异（域名、前缀、超时、Header 标记），需要一套统一、可落地的请求封装方案：

  • 统一请求入口，减少业务层差异处理
  • 环境驱动配置，避免手工切换造成漂移
  • 平台差异收敛，仅在请求层处理一次
  • 保持高内聚低耦合，提升可维护性

2. 需求画像与边界

必须满足

  • 多端一致的调用方式与返回结构
  • 多环境可配置切换
  • 统一 token、语言、时区等 header
  • 统一错误处理与全局 loading

明确边界

  • 业务层不处理 code 与 error
  • 接口层仅负责数据请求，不掺杂业务跳转
  • 平台差异仅出现在请求层

3. 现状问题与风险

  • 环境读取逻辑与 Vite/Uni 模式不完全一致，切换环境时存在误判风险
  • 请求超时固定值，无法适应不同环境的网络条件
  • 多端差异未被系统化处理，开发与测试重复踩坑
  • App 端脚本缺失，不利于多端一致的构建流程

4. 总体架构设计

分层结构

  1. 环境层：读取 .env 与 mode，输出可用配置
  2. 请求层：统一拦截、header、平台适配、错误处理
  3. API 层：按业务域封装请求函数
  4. 页面层：只调用 API，不处理请求细节

数据流

  • 页面触发 → API 调用 → 请求层拦截 → 平台适配 → 网络响应 → 统一处理 → API 返回

5. 环境层设计

使用 Vite 的 import.meta.env 读取运行模式与变量，统一管理：

const mode = import.meta.env.MODE || 'dev'
const uniPlatform = import.meta.env.UNI_PLATFORM || ''

核心环境变量：

  • VITE_BASE_URL：域名
  • VITE_API_URL：接口前缀
  • VITE_REQUEST_TIMEOUT：超时
  • VITE_API_HEADER_TAG：环境标记

环境映射建议

  • dev → 本地开发
  • sit → 测试环境
  • uat → 预发环境
  • prod/production → 正式环境

落地策略

  • 仅通过 .env.* 控制差异
  • 所有环境的变量命名完全一致

6. 请求层设计

核心职责

  • 统一请求入口
  • 注入 header（token、语言、时区、tag）
  • 平台差异适配
  • 统一 loading 与错误处理

平台差异适配

  • H5：withCredentials = true，保持会话一致
  • App：生产环境 sslVerify = true，开发环境放宽
  • 小程序：PUT/DELETE 转 POST + _method 兼容

接口地址拼接策略

  • 若 url 为绝对地址：直接使用
  • 否则：拼接 baseUrl + apiUrl + url

请求拦截通用能力

  • token 自动注入（Pinia 优先）
  • Accept-Language 与时区统一
  • 环境 tag 统一透传

响应处理原则

  • HTTP 非 2xx 统一错误处理
  • code === 0 视为成功
  • 登录失效统一跳转或清理

7. API 层规范

API 层保持“纯函数、无副作用”：

import { http } from '@/request'

export async function getApplyPage(data: PageParams) {
  return http.post('/system/container/charge/apply/page', data)
}

API 规范要点：

  • 只使用统一 http 实例
  • 不处理 code 与错误提示
  • 只返回业务数据

8. 脚本与环境支持

脚本维度按平台补齐，形成统一入口：

开发

  • dev:h5
  • dev:wx
  • dev:app

构建

  • build:h5-dev | build:h5-sit | build:h5-uat
  • build:wx-dev | build:wx-sit | build:wx-uat
  • build:app-dev | build:app-sit | build:app-uat

新增环境时，仅需补充 .env.* 文件即可生效。

9. 安全与稳定性策略

安全

  • 仅在请求层统一注入 token，避免泄漏
  • header 中避免输出敏感信息

稳定性

  • 超时按环境配置，不固定写死
  • 网络异常统一提示，避免多处重复 toast

10. 落地清单

环境变量

  • VITE_BASE_URL
  • VITE_API_URL
  • VITE_REQUEST_TIMEOUT
  • VITE_API_HEADER_TAG

请求层行为

  • H5：withCredentials = true
  • App：sslVerify = 生产环境
  • 小程序：PUT/DELETE → POST + _method

工程脚本

  • H5/微信/App 全覆盖

11. 效果与收益

  • 多端差异从业务层消失
  • 环境切换零侵入，环境一致性提升
  • 构建流程标准化，便于 CI/CD
  • 请求层可扩展性提升，后续接入更快

12. 常见问题

Q：为什么不在业务层判断 code？
A：统一处理可保证一致性与可维护性，避免重复判断造成逻辑分叉。

Q：小程序为何要转 _method？
A：部分小程序端限制方法类型，统一转换可提高兼容性。

Q：环境切换为何使用 MODE？
A：Vite/Uni 原生支持 mode，统一入口避免额外依赖。

13. 后续优化建议

  • Token、语言等状态统一由 Pinia 管理
  • 接口返回统一类型，对外只返回业务数据
  • 加入刷新 Token 流程与白名单管理
  • 将请求日志上报统一封装，支持调试追踪

14. 关键配置详表

变量含义示例生效位置
VITE_BASE_URL域名ibs-dev.sinolines.com.cn:24080请求层
VITE_API_URL接口前缀/admin-api请求层
VITE_REQUEST_TIMEOUT超时600000请求层
VITE_API_HEADER_TAG环境标记dev/sit请求头

15. 多端行为矩阵

平台特性处理策略影响范围
H5跨域 cookiewithCredentials=true登录态保持
App证书校验生产环境 sslVerify=true安全性
小程序方法限制PUT/DELETE → POST + _method接口兼容

16. 实施步骤

  1. 统一环境变量命名并补齐 .env.dev/.env.sit/.env.uat
  2. 使用 import.meta.env 读取 mode 与配置
  3. 在请求层集中做平台差异适配
  4. API 层全部替换为 http 实例调用
  5. 补齐 App 端脚本并建立构建规范

17. 迁移策略

阶段一：请求层接入

  • 仅调整请求封装，不改动业务接口
  • 使用灰度环境验证是否存在跨端异常

阶段二：API 层统一

  • API 文件只保留数据请求逻辑
  • 业务页面仅调用 API

阶段三：收敛与复盘

  • 统一错误与加载体验
  • 对典型接口进行稳定性评估

18. 典型场景落地示例

1）请求超时差异

  • dev/sit：适度增加超时，方便调试
  • uat/prod：设置合理超时，防止请求堆积

2）App 证书处理

  • 生产启用 sslVerify
  • 开发关闭校验，避免调试阻塞

3）小程序方法兼容

  • 后端支持 _method，保证语义一致
  • 前端无需判断平台，保证调用统一

19. 质量保障

自检清单

  • .env.* 命名是否统一
  • baseUrl/apiUrl 是否完整拼接
  • 请求层是否仅有一处 error 处理
  • 小程序端是否出现 PUT/DELETE 失败

回归验证

  • H5 登录态是否稳定
  • App 端证书校验是否仅生产生效
  • 小程序请求是否被正确转换

20. 风险与应对

风险触发条件应对方案
环境识别错误mode 不一致统一脚本参数
证书校验失败App 证书配置不一致生产与测试区分
小程序请求失败PUT/DELETE 直发请求层强制转换

21. 价值总结

  • 统一请求入口，降低维护成本
  • 环境与平台差异可控，交付更稳定
  • API 层更清晰，便于团队协作

22. 时序流程图描述

请求链路

  1. 页面触发 API 调用
  2. API 调用统一 http 实例
  3. 请求层注入 header 与平台适配
  4. 发起网络请求
  5. 统一响应处理与错误分发
  6. 返回业务数据到页面

异常链路

  1. HTTP 非 2xx 或 code 非 0
  2. 统一错误处理
  3. 业务层只处理已统一的异常结果

23. 错误码规范建议

分层错误

  • HTTP 层：2xx 为可解析响应，其余为网络异常
  • 业务层：code === 0 表示成功

统一返回结构

{
  "code": 0,
  "msg": "ok",
  "data": {}
}

约定示例

  • 401：登录失效
  • 403：无权限
  • 500：服务异常

24. 灰度发布策略

环境灰度

  • 在 uat 环境先验证多端一致性
  • 通过 VITE_API_HEADER_TAG 区分环境

用户灰度

  • 通过后端配置灰度名单
  • 请求层透传灰度标记 header

回滚策略

  • 仅切换 .env 配置即可快速回退

25. 监控指标定义

请求稳定性

  • 成功率（按接口与端）
  • 5xx 比例（按环境）

性能指标

  • 平均响应时间
  • 超时率

异常指标

  • 401/403 触发次数
  • 小程序 method 转换占比

26. API 接口规范模板

命名规范

  • 按业务域拆分文件，文件名使用 kebab-case
  • 方法名以 get/create/update/delete/query 开头

模板示例

import type { PageParams, PageRes } from '@/types/xxx'
import { http } from '@/request'

/**
 * 获取列表
 * @param data 查询参数
 * @returns 列表响应
 */
export async function getList(data: PageParams): Promise<PageRes> {
  return http.post('/path/list', data)
}

统一要求

  • 只使用 http 实例
  • 不处理 code 与 error
  • 参数与返回类型必须在 types 中定义

27. 监控埋点结构建议

埋点维度

  • 环境、平台、接口名、耗时、状态码、业务码

字段示例

{
  "env": "sit",
  "platform": "h5",
  "path": "/system/container/charge/apply/page",
  "duration": 320,
  "statusCode": 200,
  "code": 0
}

28. QA 用例清单

环境切换

  • dev/sit/uat 三环境请求是否切换成功
  • header tag 是否随环境变化

多端一致性

  • H5 登录态是否保持
  • App 端 sslVerify 仅生产生效
  • 小程序 PUT/DELETE 是否被正确转换

异常场景

  • 断网时是否统一提示
  • code 非 0 时是否统一处理
avatar
文章
阅读
粉丝