一张活动卡片加载失败,页面却同时出现空白、转圈和“请稍后再试”。真正的问题未必是网络,而是页面直接调用请求接口,失去了对错误的解释权。

先看用户的一次具体操作,通常比从 API 名称出发更容易找到真正的工程约束。 我们围绕“城市场馆预约”的“活动发现”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

本篇跨平台技术封面

把失败现象还原成工程边界

将网络能力下沉为带有响应校验的 transport,将业务地址和接口数据形状放在 service,最后由页面负责展示状态。请求层不应该认识“活动名称”或“门票余量”,否则它会在第二个业务模块出现时迅速膨胀。

如果只把“活动发现”当作一个可见页面,开发时很容易忽略操作背后的状态流。实际应用有用户重复点击、进程被回收、页面重新进入、系统权限被拒绝等情况;这些变化并不会自动遵守 Vue 组件的生命周期。建议先把 uni.request 的调用条件写成可阅读的规则,再决定在哪个页面事件里触发。

对“城市场馆预约”而言,页面组件需要能够回答三个问题:当前展示的数据是否已确认、用户现在还能执行什么动作、失败后哪些数据应继续保留。若这三个问题的答案依赖一个模糊的布尔值,后续出现空态、加载态和待确认态时就会不断补丁式增加判断。

从工程划分来看,services/http.ts 是本篇关键实现位置。页面与公共服务不应互相猜测对方的数据形状:应明确参数类型、正常返回和需要处理的失败分类;读取与写入的规则在代码审查时分别核对。在票务链路中,读取活动和创建预约虽然共用网络能力,却必须采用不同的重试规则。只读查询可以按策略重试,影响库存的写入则必须具备服务端幂等保证。将二者混成“请求失败自动发一次”,在弱网里反而更危险。

最小分层:职责不越界

传输层只返回状态码、数据与明确错误;活动服务负责将后端字段归一化为 id、title、remaining;页面维护 idle、loading、success、empty、error 五种视图状态。把契约拆开后,运营临时增加筛选条件不会波及基础请求功能。

这套网络分层的关键并不在于封装多少行代码,而是如何让业务页面不依赖服务端字段的偶然形状。比如接口字段 remaining 的确属于数字,但后端迁移期间可能返回 null。把这个问题放在列表组件里就会产生三份不一致的兜底,放在活动服务里才可以统一拒绝或归一化。还需要给失败路径建立稳定错误类型:网络无法到达、HTTP 拒绝和数据结构不合约必须被区分。调试请求时建议记录接口别名、HTTP 状态与必要的追踪标识,不把 token、手机号、完整响应体写到日志。

落地时先声明最小业务模型,再决定它的持有者。由页面驱动的暂态数据可以用 ref 或 computed;需要在刷新后恢复的结果必须明确读写入口;属于服务端最终决定的字段则不能因为按钮点击而直接写成成功。对“活动发现”的每一种可见状态,都建议找到对应的数据依据。

落到代码后再看多端约束

下面保留了与“活动发现”直接相关的核心实现。示例以标准 uni-app Vue3 工程为目标,服务端地址、业务表结构和平台授权按照项目实际环境配置。连载文章与前文按相同文件职责衔接:前面建立的类型与仓库不在后篇随意改名;独立文章则可以单独复制相应页面或服务进行验证。

// services/http.ts
export type ApiErrorKind = 'network' | 'http' | 'invalid';
export class ApiError extends Error {
  constructor(public kind: ApiErrorKind, public status = 0) {
    super(`API ${kind}: ${status}`);
  }
}
const BASE = import.meta.env.VITE_API_BASE_URL as string;
export function getJson<T>(path: string): Promise<T> {
  return new Promise((resolve, reject) => {
    uni.request({
      url: `${BASE}${path}`,
      method: 'GET', timeout: 12000,
      success: (res) => {
        if (res.statusCode < 200 || res.statusCode >= 300) {
          reject(new ApiError('http', res.statusCode)); return;
        }
        if (!res.data || typeof res.data !== 'object') {
          reject(new ApiError('invalid')); return;
        }
        resolve(res.data as T);
      },
      fail: () => reject(new ApiError('network'))
    });
  });
}
export interface EventDTO { id: string; title: string; remaining: number }
export async function fetchEvents(city: string): Promise<EventDTO[]> {
  const data = await getJson<{items: unknown}>(`/events?city=${encodeURIComponent(city)}`);
  if (!Array.isArray(data.items)) throw new ApiError('invalid');
  return data.items.filter((item): item is EventDTO =>
    typeof item?.id === 'string' &&
    typeof item?.title === 'string' &&
    typeof item?.remaining === 'number');
}

从源码阅读顺序看,先定位 services/http.ts 中的输入,再找到 uni.request 相关调用,最后确认界面状态或存储写回点。第一件事是确定调用的输入从哪里来:它可能来自路由参数、响应式状态,也可能来自本地持久化。第二件事是确定输出由谁消费:不应让 UI 组件直接承担重试协议或数据迁移。第三件事是检查失败路径是否有出口,不能永远停在加载中。

代码里最值得注意的是边界上的显式判断。它比向页面堆一个万能 catch 更有价值,因为不完整的数据、权限拒绝和无法联网,分别决定了用户接下来能做什么。业务组件只接收已经整理好的返回结果,才能独立处理加载、取消与重进页面。 这正是把逻辑拆成可测试片段的原因:当业务规则改变时,可以只替换数据整形或平台适配逻辑,而不用让每个点击处理函数再次复制错误分支。

开发环境或应用界面:本篇核心交互

错误语义与定位成本

H5 请求受浏览器同源和 CORS 约束;微信小程序需要合法 request 域名与 HTTPS 配置;Android/iOS App 则要考虑证书链、网络权限和首次启动联网授权。uni.request 是共同入口,但运行容器的失败形态不同。

Web / H5:H5 先在正式部署域名下确认 CORS 响应头,开发代理成功不能证明上线后浏览器会放行跨域请求;还要检查同一条错误在刷新页面后能否被正常恢复。 在“活动发现”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。

微信小程序:微信小程序要把业务 API 域名放入合法域名列表,开发工具忽略校验的开关不能带进发布验收;应检查真机请求的 HTTPS 证书。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。

App:App 需要检验首次安装时的联网授权、证书链兼容性和断网恢复。将请求失败归类后,才可以让页面提供有意义的重试动作。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。

三端一致的部分应尽量体现在数据契约与业务语义中,三端不同的部分则应被清楚标识。比如“活动发现”对用户呈现的保存、取消、重试这些动作应同义,但它们内部调用的权限检查、资源路径或系统接口可以不同。只有这样,平台迁移才不会变成整页复制。

跨端边界或应用运行状态

把设计变成可验证的契约

后端返回 HTTP 200 但业务 code 非成功、JSON 字段缺失、用户快速切换筛选导致旧请求覆盖新列表,是三类必须分别处理的异常。不能把它们都归入“网络错误”,也不能让页面靠判断 message 文本决定是否重试。

针对“城市场馆预约”,排查时不要把所有可见异常归入同一个“操作失败”。先问失败发生在输入校验、页面状态转换、平台 API 调用、后台返回还是存储恢复;这五个位置至少要能在日志或可见状态中区分。对用户而言,保留已填写内容通常比重复弹窗更重要;对开发者而言,保留最小触发路径比截取一张成功页更有价值。

建议采用有限的日志字段:模块、动作、错误类别、必要的状态编号和构建版本。对于 uni.request 所涉及的调用,敏感值、文件内容及完整用户资料不应输出。将错误按是否可重试划分之后,页面才能选择展示“重试”“继续编辑”或“前往授权”,而不是遇到任何问题都自动再执行一次。

回归时建议按下面五项逐条操作,不依赖“看起来正常”的主观判断:

1)当接口返回空数组时,页面显示明确空状态,不显示网络失败。 把该项拆成操作、预期和失败证据三部分:操作必须能由另一个开发者重做;预期尽量描述可见的 UI 或稳定字段;失败证据只记录必要的错误分类和接口状态,不携带隐私信息。 对“活动发现”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

2)当返回 401 时只转为鉴权错误,不自动无限重新请求。 不要只测正常网络和一台设备。若涉及异步步骤,至少安排一次连续快速触发以及一次人为中断;若涉及本地数据,则重新打开页面确认恢复结果。这样比盯着开发者工具里的成功提示可靠。 对“活动发现”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

3)连续切换城市筛选,只接纳最后一次查询对应的结果。 先对照本文定义的数据契约确认结果是否可解释,再检查不同运行容器是否走了相同的业务路径。出现差异时应保存最小输入和相应的代码版本,避免凭印象改动多个模块。 对“活动发现”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

4)关闭小程序合法域名配置,检查失败回调和提示是否一致。 验收的目标不是证明代码没有任何风险,而是把最容易造成用户损失的边界提前显露。记录触发动作、预期状态、实际状态与修复位置,并在下一次构建时用同一用例回归。 对“活动发现”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

5)将返回项 remaining 设为字符串,检验数据归一化边界。 复现时要保留输入条件与触发顺序,先判断页面是否给出确定状态,再核对存储或后台是否真正变化。尤其注意不要把一次偶然成功当作稳定结论;重复执行并检查边界值,能发现只在第二次出现的状态残留。 对“活动发现”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

不宜在第一个页面就引入庞大的通用状态机;两个明确的接口类型和一个纯函数 normalizer 往往更可靠。传输层只解决项目共同的横向问题,权限、票务规则和空状态文案留给具体业务服务。

如果本次只维护一条流程,优先把数据契约、失败状态和用户可执行的下一步做扎实。新增功能前再审视公共服务与平台分支是否仍然清晰;对于需要真实联网、后端配置或设备权限的步骤,应在目标环境执行相应测试,不宜直接把源码静态检查描述成实际编译或真机验证。

收尾与适用范围

这篇围绕“活动发现”建立了一条从数据边界、调用实现到多端验收的路径。它并不依赖于某种固定配色或 UI 库,重要的是业务动作在正常、取消、中断和重新进入时保持可解释。后续迭代可以更换组件和数据源,但输入、失败状态以及用户操作的语义应当持续稳定。

票务接口治理系列下一篇将沿着同一服务层继续扩展,不另造一套请求协议,重点处理本篇尚未覆盖的交叉状态与恢复路径。

本文所用平台 API 与工程约束可对照 uni-app 官方参考、Vue3 组合式 API 以及 条件编译文档。若使用新版 HBuilderX 或开发 HarmonyOS Next 应以目标版本的文档与设备支持表为准。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐