用户在地铁中提交场馆预约,按钮转了一圈后网络断开。应用不能简单提示“失败请重试”,因为服务端可能已经收到了请求,客户端只是不知道结果。

看似简单的功能最容易掩盖边界条件,直到用户快速操作、离线使用或者升级版本时才暴露。 我们围绕“城市场馆预约”的“预约队列”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

本篇跨平台技术封面

为什么需要评审这条业务链

无法确认结果的写操作和确定失败的写操作必须区分。幂等键要从用户一次明确意图产生并与队列记录绑定,重试使用同一个键;如果每次重试都生成新键,就等于没有幂等保障。

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

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

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

状态和接口契约

提交时先写入 pending 记录,再调用服务端预订接口;服务端按 idempotencyKey 去重并返回稳定 bookingId。客户端保存 acknowledged 状态后清理队列,未知状态保留待用户主动或网络恢复后查询。

对预约类写操作来说,网络超时不等于订单未生成。客户端既不应该在超时后直接宣布失败,也不该自动再创建一个全新请求。幂等键是用户本次意图的身份,可以帮助后台把多次传输折叠为一次业务操作。它必须和业务参数保持绑定,不能因为重新打开页面就换一个键。服务端仍应建立唯一约束、事务边界与查询接口,否则单靠前端去重无法控制库存扣减。队列状态用 pending 和 unknown 是为了如实表达不确定性。

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

关键实现与风险控制

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

// services/booking-queue.ts
interface PendingBooking {
  intentId: string; eventId: string;
  status: 'pending' | 'unknown'; createdAt: number;
}
const KEY = 'ticket.pendingBookings';
function readQueue(): PendingBooking[] {
  return (uni.getStorageSync(KEY) || []) as PendingBooking[];
}
function writeQueue(list: PendingBooking[]) { uni.setStorageSync(KEY, list); }
export function enqueue(item: PendingBooking) {
  const queue = readQueue();
  if (queue.some(v => v.intentId === item.intentId)) return;
  writeQueue([...queue, item]);
}
export async function flushQueue(): Promise<void> {
  const queue = readQueue();
  for (const item of queue) {
    try {
      const res = await uni.request({
        url: `${import.meta.env.VITE_API_BASE_URL}/bookings`,
        method: 'POST',
        header: { 'Idempotency-Key': item.intentId },
        data: { eventId: item.eventId }
      });
      // 仅稳定确认的成功响应才移除;服务端必须按同一键去重
      if (res.statusCode === 200 || res.statusCode === 201) {
        writeQueue(readQueue().filter(v => v.intentId !== item.intentId));
      } else {
        writeQueue(readQueue().map(v => v.intentId === item.intentId
          ? {...v, status: 'unknown'} : v));
      }
    } catch { break; } // 断网时保留剩余队列
  }
}

从源码阅读顺序看,先定位 services/booking-queue.ts 中的输入,再找到 uni.getNetworkType 相关调用,最后确认界面状态或存储写回点。这里刻意不把所有规则塞进一个通用帮助函数。跨端适配、数据校验与业务决定属于不同层级;只有约定好每一层的输入和输出,未来更换 UI 或接入新平台时才不会连带修改底层逻辑。

阅读这段实现时,可以沿着“用户动作→页面状态→领域函数→平台 API→结果回写”的方向跟踪。任意一个阶段发生异常,都应知道是保留已有状态、允许重试还是明确阻止下一步,而不是让异常继续冒泡成空白页面。 这正是把逻辑拆成可测试片段的原因:当业务规则改变时,可以只替换数据整形或平台适配逻辑,而不用让每个点击处理函数再次复制错误分支。

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

不同终端怎样失效

uni.getNetworkType 只反映当前网络接入状态,不能保证后端此刻可达;App 进入后台后的任务运行时间也受系统约束。小程序退出后不能保证 JS 定时器继续运行,必须接受“下次打开再回补”。

Web / H5:H5 关闭标签页后不能保证请求队列继续重放,重开时应从本地 pending 队列恢复并先查询未知订单结果。 在“预约队列”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。

微信小程序:微信小程序退后台时网络和定时任务可能被停止,不能承诺“离开小程序仍会自动提交预约”。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。

App:App 后台运行时长由系统策略决定,重试应依据实际网络与业务状态进行,而不是依赖无限轮询。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。

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

跨端边界或应用运行状态

交付验收与后续选择

用户连续点两次、服务端返回 500 但事务实际成功、队列重放顺序被打乱,都可能产生双订。要在服务端建立幂等保证,客户端按钮防抖只是用户体验优化。

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

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

关键流程、状态或验证步骤讲解

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

1)同一意图重试三次服务端只产生一条预约。 把该项拆成操作、预期和失败证据三部分:操作必须能由另一个开发者重做;预期尽量描述可见的 UI 或稳定字段;失败证据只记录必要的错误分类和接口状态,不携带隐私信息。 对“预约队列”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

2)未知结果保留队列而不是被当作失败删除。 不要只测正常网络和一台设备。若涉及异步步骤,至少安排一次连续快速触发以及一次人为中断;若涉及本地数据,则重新打开页面确认恢复结果。这样比盯着开发者工具里的成功提示可靠。 对“预约队列”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

3)断网时新请求加入待确认区并显示状态。 先对照本文定义的数据契约确认结果是否可解释,再检查不同运行容器是否走了相同的业务路径。出现差异时应保存最小输入和相应的代码版本,避免凭印象改动多个模块。 对“预约队列”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

4)恢复网络后使用原幂等键,不修改用户意图。 验收的目标不是证明代码没有任何风险,而是把最容易造成用户损失的边界提前显露。记录触发动作、预期状态、实际状态与修复位置,并在下一次构建时用同一用例回归。 对“预约队列”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

5)订单取消与预约提交采用不同业务键。 复现时要保留输入条件与触发顺序,先判断页面是否给出确定状态,再核对存储或后台是否真正变化。尤其注意不要把一次偶然成功当作稳定结论;重复执行并检查边界值,能发现只在第二次出现的状态残留。 对“预约队列”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。

适合预约这类可恢复的请求队列,不适合凭空为支付扣款做离线自动重试。对资金、库存的强约束,必须由服务端事务和确认接口兜底,并提供用户可理解的“处理中”状态。

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

收尾与适用范围

这篇围绕“预约队列”建立了一条从数据边界、调用实现到多端验收的路径。它并不依赖于某种固定配色或 UI 库,重要的是业务动作在正常、取消、中断和重新进入时保持可解释。真正的跨端收益来自共享契约与可维护的端差异,而不是把所有平台都伪装成同一个运行环境。

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

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

Logo

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

更多推荐