做小程序开发这几年被问得最多的场景除了登录、支付就是“发货信息录入”。很多人觉得这功能太简单了不就是个表单填快递单号点提交吗真上手做才发现里面全是细节快递公司怎么选、单号格式怎么校验、订单重复提交怎么防、录错了能不能改、苹果手机上为什么列表滑不动……这篇文章就基于我最近给一个电商类微信小程序做的发货信息录入模块从设计思路到落地实现再到真机踩坑和上线优化完整拆一遍。不管你是刚接手小程序订单模块的新手还是想优化现有发货流程的开发者这篇文章应该都能给你一些可以直接用的东西。1. 发货信息录入模块的设计思路与需求拆解1.1 这个模块到底要解决什么问题先搞清楚业务背景。一个典型的电商小程序用户下单之后商家后台需要把物流信息回填到订单里这一步做不好后面全是客服灾难买家问“我货发了没”商家查不到单号又不敢瞎承诺一单一单对着聊天记录翻效率极低。发货信息录入这个模块本质上是订单履约链路里承上启下的一环。承上是从待发货订单池里取出订单启下是录入物流信息之后订单状态要从“待发货”变成“已发货”同时把运单号同步给买家。所以它不只是“填个单号”那么简单它需要具备几个核心能力准确记录物流公司和运单号保证订单与运单一一对应。防止重复发货同一订单不能被提交两次。支持修改和补救录错了能改漏录了能补。给后续状态流转提供依据发货后自动更新订单状态触发买家通知。对操作效率有要求仓库批量发货时不能一单一单慢慢敲。我在设计这个模块时把需求拆成了三层第一层是基础录入字段至少包括订单号、物流公司、运单号、发货备注第二层是异常处理包括重复提交拦截、单号格式校验、发货后不可随意修改第三层是效率增强比如扫码录入、批量导入、历史发货记录查询。如果你只是做个个人小项目第一层就够了但想上线给真实商家用第二层第三层绕不开。这里有个容易忽略的点录入权限。发货信息录入通常不是给普通用户用的而是给商家、客服或仓库管理员用的所以页面必须做身份区分。我在项目里是把“发货录入”入口放到管理端角色下普通用户的小程序首页根本没有这个入口前端隐藏加后端接口鉴权双重控制。这一点在后面安全部分会再展开。1.2 技术方案选型为什么用原生小程序加Java后端发货信息录入本身不挑技术栈市面上流行的方案无非三种原生微信小程序、uni-app跨端、纯H5嵌到小程序里。如果你已经有一个小程序项目最稳的做法是在现有工程里加页面而不是为了一个模块重新引一套框架。我自己这次选的是原生小程序前端加Java Spring Boot后端。原因很直接项目里订单、商品、支付模块都是Java后端发货信息录入只是其中一个接口用同一套技术栈维护成本最低。网上搜“微信小程序 java 发货信息录入 csdn”能搜到大量同类项目说明这个组合是真实业务里最常见的搭配出问题也好查资料。那什么时候用uni-app如果你的小程序后续还要出App或H5版本又不想重复写三套代码uni-app是合理的配合HBuilderX发行到微信小程序也成熟。但要注意uni-app发布小程序时微信特有的能力比如订阅消息、扫码还是需要通过条件编译或原生插件去适配不是说一套代码全搞定。单一小程序场景我建议别为了跨端而跨端原生开发调试起来更直接基础库更新也能第一时间用到新特性。数据库表结构我按发货单和订单两个概念来设计避免在订单表上堆太多物流字段。实际用到的核心表大致是这样的shipment主表id、order_id、shipping_company、tracking_no、remark、status、create_time、update_time。order表增加shipping_status字段0待发货1已发货2部分发货拆单场景。为什么单独建shipment表而不是直接在订单表加两个字段因为一个订单可能被拆成多个包裹分别发出一条订单记录对应多条物流记录一对多关系用独立表更干净以后做物流轨迹查询、售后核验都方便。2. 核心页面实现与关键代码拆解2.1 表单设计字段布局、快递公司选择和单号校验页面结构上我遵循“能少让用户输入就少输入”的原则。进入页面时如果是从订单列表跳转过来的订单号自动带入且只读如果是扫快递面单进入的物流公司和单号尽量自动识别。手输字段压缩到最少只有商家要额外备注时才需要碰键盘。物流公司选择不建议用输入框自由填写。不同人对“顺丰速运”“顺丰快递”“SF”的写法能差出十几种数据统计和物流查询全乱。我用了微信小程序单选框组把常用物流公司固定成选项用户点选即可。如果你家合作快递很多可以做成搜索式选择器但至少也要有个固定的基础选项池后台可配置这样才能保证录入数据的规范性。下面是WXML表单的核心片段字段不算复杂但每处都对应一个细节view classform-item text classlabel订单号/text input value{{orderNo}} disabled placeholder自动带入订单号 / /view view classform-item text classlabel物流公司/text radio-group bindchangeonCompanyChange label wx:for{{companyList}} wx:keyname radio value{{item.name}} checked{{item.name form.company}} / text{{item.name}}/text /label /radio-group /view view classform-item text classlabel运单号/text input value{{form.trackingNo}} bindinputonTrackingInput placeholder请输入或扫码识别 / button sizemini bindtapscanTrackingNo扫码/button /view view classform-item text classlabel备注/text input value{{form.remark}} bindinputonRemarkInput placeholder选填 / /view button typeprimary loading{{submitting}} disabled{{submitting}} bindtapsubmitShipment 确认发货 /button运单号校验是很多人忽略的坑。快递单号不是随便一串数字都合法各家快递公司都有固定的位数规则和前缀特征比如顺丰一般是12位或15位纯数字中通、圆通位数也不同。我封装了一个校验函数先判断长度区间再按物流公司匹配正则不合法就直接弹提示不让用户提交。校验逻辑大致是这样const RULES { 顺丰速运: { min: 12, max: 15, pattern: /^\d$/ }, 圆通速递: { min: 10, max: 14, pattern: /^YT\d{10,13}$/i }, 中通快递: { min: 10, max: 12, pattern: /^\d$/ }, 韵达快递: { min: 13, max: 13, pattern: /^\d{13}$/ }, 极兔速递: { min: 10, max: 14, pattern: /^JT\d{8,12}$/i }, }; function validateTrackingNo(company, trackingNo) { const rule RULES[company]; if (!rule) return trackingNo.length 6; const len trackingNo.length; return len rule.min len rule.max rule.pattern.test(trackingNo); }注意各快递公司的单号规则会调整这只是一个常见示例正式上线前建议跟实际合作的快递网点确认一下或者直接对接快递鸟、快递100这类平台的单号识别接口。校验的目的不是百分之百拦住所有错误而是拦住明显的手误比如少一位、多一位、混入了中文。2.2 提交逻辑防重复提交、接口封装与状态处理前端提交这块核心就一个问题怎么防止用户手抖点了两次造成重复发货我做了三层防护。第一层按钮级拦截。点击提交后立即把submitting置为true按钮进入loading状态并禁用接口返回前用户没办法再点。这个看着简单但很多项目只看后端前端不防实际上体验很差。第二层请求级幂等。前端生成一个唯一的请求标识requestId每次进入页面时初始化提交时随请求一起发给后端后端记录这个requestId处理过的requestId直接返回重复提交提示。第三层后端业务校验。即使前端双重点击被拦住了也保不齐有并发请求、或有人绕过页面直接调接口。后端在生成发货单前必须查一下这个订单当前状态是不是“待发货”如果已经发货过就直接拒绝。前端提交时的核心代码如下async function submitShipment() { if (submitting) return; if (!form.company) { wx.showToast({ title: 请选择物流公司, icon: none }); return; } if (!validateTrackingNo(form.company, form.trackingNo)) { wx.showToast({ title: 运单号格式不正确, icon: none }); return; } submitting true; try { const res await request({ url: /api/shipment/create, method: POST, data: { orderId: orderId, company: form.company, trackingNo: form.trackingNo.trim(), remark: form.remark, requestId: requestId }, header: { Authorization: Bearer ${getToken()} } }); if (res.code 0) { wx.showToast({ title: 发货成功, icon: success }); // 通知订单页刷新 const eventChannel getOpenerEventChannel(); eventChannel.emit(refreshOrder); setTimeout(() wx.navigateBack(), 1500); } else { wx.showToast({ title: res.msg || 提交失败, icon: none }); } } finally { submitting false; } }这里用到了登录态的token。小程序的登录流程通常是wx.login拿到code再传给后端换token后续请求header里带Authorization即可。关联上网上一堆“用code换token”的说法其实就是这个流程没什么玄乎的关键是token要存到小程序的安全存储里每次请求前检查是否过期过期就静默重新登录。2.3 后端接口实现幂等判断、状态流转与发货通知Java后端接口我用Spring Boot实现核心思路是先校验、再幂等、后写入、最后通知。存发货记录和更新订单状态必须放在同一个事务里否则会出现发货单写进去了订单状态没更新两边数据对不上。看下核心代码结构PostMapping(/api/shipment/create) public Result createShipment(RequestBody ShipmentCreateReq req, RequestHeader(Authorization) String token) { // 1. 鉴权并获取当前操作人 Long operatorId authService.getUserIdByToken(token); // 2. 校验订单是否存在且属于当前商家 Order order orderService.getById(req.getOrderId()); if (order null) { return Result.error(订单不存在); } // 3. 幂等判断同一requestId不重复处理 if (idempotentService.checkExists(req.getRequestId())) { return Result.error(请勿重复提交); } // 4. 业务校验订单状态必须是待发货 if (!OrderStatus.SHIPPING_WAIT.equals(order.getShippingStatus())) { return Result.error(该订单已发货不能重复操作); } // 5. 同一个事务里写发货单并更新订单状态 shipmentService.createShipment(order, req, operatorId); return Result.success(); } Transactional(rollbackFor Exception.class) public void createShipment(Order order, ShipmentCreateReq req, Long operatorId) { // 写入发货记录 Shipment shipment new Shipment(); shipment.setOrderId(order.getId()); shipment.setShippingCompany(req.getCompany()); shipment.setTrackingNo(req.getTrackingNo()); shipment.setRemark(req.getRemark()); shipment.setStatus(ShipmentStatus.CREATED.getCode()); shipment.setOperatorId(operatorId); shipmentMapper.insert(shipment); // 更新订单状态 order.setShippingStatus(OrderStatus.SHIPPING_FINISH.getCode()); order.setShipmentId(shipment.getId()); orderMapper.updateById(order); // 落幂等记录 idempotentService.record(req.getRequestId()); // 发送订阅消息通知买家 subscribeMessageService.sendShipmentNotify(order, req); }第4步的校验特别重要。如果漏了一个订单被重复发货用户会收到两条物流信息实际收的却只有一个包裹客服处理起来非常头痛。发货完成后通知买家我用的是微信小程序订阅消息。用户下单时提前引导订阅“发货通知”发货后后端调微信接口发送物流信息给买家内容包括快递公司和运单号。订阅消息一次订阅只能发一次通知所以下单那个环节就要设计好引导话术不然到发货时你没有发送权限只能干瞪眼。这算是我这次做得比较顺手的一环之前就吃过没引导订阅的亏后面补引导再发货就顺畅多了。3. 实操过程中遇到的坑与排查实录3.1 真机上的兼容性问题一个比一个隐蔽发货信息录入页面其实不复杂但真机测试时遇到的问题比我想象的多尤其是iOS和安卓的差异。挑几个印象深刻的讲一下。第一个是苹果手机在微信小程序不能进行滑动滚动。页面结构是弹窗里加了一个可滚动的物流公司列表安卓上一切正常iPhone上死活划不动。排查下来问题是弹窗容器设置了固定高度但内部滚动区域没有显式设置overflow属性iOS下父容器滚动事件被弹窗遮罩拦截了。解决方法是给内层滚动区域加上overflow-y: auto和-webkit-overflow-scrolling: touch并且给滚动区域设定明确的高度不能依赖内容撑开。之后在iPhone上测试滚动就顺滑了。第二个是handshake failed due to invalid upgrade header: null。这个报错出现在开发版真机调试的时候一开始以为是代码问题查了很久发现是我的本地环境用的调试代理引起的握手失败。也就是说报错不一定是代码或服务器的问题可能是网络代理干扰了请求头。排查办法是先关掉本地代理工具再用微信开发者工具的“不校验合法域名”模式跑一遍如果规规矩矩走线上域名这个错误基本不会出现。顺带提醒别一看到这报错就去服务器上改WebSocket配置先检查自己的调试链路。第三个是基础库版本问题。小程序里有些新API在低版本基础库上不支持比如wx.env.user_data_path只在2.19.0以上基础库才比较稳定。发货单需要导出附件时我用这个路径保存本地文件结果在低版本基础库上直接报错。解决方法是到微信公众平台后台设置最低基础库版本同时代码里做能力检测低版本走降级方案不强制用新API。基础库版本从哪设置两个地方一是在微信公众平台的小程序后台可以设置最低基础库版本二是在开发者工具的项目设置里可以调试不同基础库版本下的表现。建议至少把最低版本设到能覆盖95%以上用户的水平而不是只看你自己手机上的效果。第四个是wx.env.user_data_path的坑。这个路径返回的是小程序用户目录iOS和安卓上前缀不一样千万别把路径写死。我一开始图省事直接拼了个固定路径结果安卓上写文件老是失败。正确做法是先调用wx.env.user_data_path动态获取路径再拼上文件名这样两端都能正常读写。如果你只是临时保存附件记得用完清理这个目录在部分机型上不会自动释放时间久了会占空间。3.2 常见问题速查表收藏这一份就够了整理一份我在项目上线前后遇到的问题汇总按现象、原因、解决方案排列遇到同类问题可以直接对照着查。现象可能原因解决方案点击“确认发货”没反应按钮被loading状态锁死或前端校验不通过被拦截打开控制台看wx.showToast是否有提示检查submitting状态是否被意外置为true连续快速点击出现两条发货单前端未禁用按钮后端未做幂等前端button加loading和disabled后端用requestId幂等事务内校验订单状态单号输入框能输入中文没有做输入限制或只做了提交时校验input上加typetext但监听输入过滤掉非数字字母或提交前统一trim校验苹果手机能打开页面但点不了提交按钮被遮罩层挡住检查z-index层级弹窗/遮罩组件最高层级固定按钮层级不足时触摸事件被吞接口请求报url not in domain list小程序后台未配置request合法域名到微信公众平台配置服务器域名开发阶段可在开发者工具临时勾选不校验域名发货成功但买家没收到通知卖家未在下单时引导订阅或订阅次数用完下单选货流程中引导用户点击“允许”订阅按钮发货时调用前检查授权状态发货列表分页加载越来越慢一次查全量数据没有limit改用limitoffset或游标方式按create_time倒序每次只查20条发货记录被误操作删除没有权限控制或删除保护管理端加操作权限发货记录不提供彻底删除只允许取消并留存日志另外提一句现在网上能搜到不少“微信小程序反编译”之类的工具和文章风控上我不建议碰。小程序前端代码本身是在用户手机上下载执行的压缩混淆也不等于绝对安全所以任何敏感逻辑都必须放在后端而不是指望前端代码不被别人看到。发货单、订单这类数据是业务命脉后端接口权限和日志审计一定要做扎实这比前端加一百道锁都重要。4. 体验优化与上线后的运营建议4.1 扫码录入仓库发货快三倍的效率密码录入发货信息这个动作在订单量小的时候无所谓一天几十单手输也就输了。一旦到双十一那种量级一单一个单号手输不仅慢还容易看错。我的建议是把扫码功能加上。微信小程序里有现成的wx.scanCodeAPI在录入表单旁边放一个“扫码”按钮点一下直接调起摄像头扫快递面单上的条形码。扫码结果通常是一串包含单号的文本需要做一次清洗把数字部分提取出来。我最初是拿到什么存什么结果有的面单扫出来带一堆前后缀物流查询根本识别不了后来加了个解析函数去掉字母前缀和后缀只保留合法单号部分问题就解决了。如果条件允许可以更进一步把扫码和新建发货单的流程合并。扫一个面单自动创建一条发货单再扫下一个全程不用碰屏幕。配合批量发货列表仓库人员只需要把面单逐个对准扫码框系统自动关联到最近一个待发货订单上效率提升非常明显。我实测过熟练工手输一单平均30秒扫码一单5秒以内差距不是一星半点。当然扫码也分场景。如果你的商家是小卖家一天就几单扫码价值不如直接在订单列表上点“发货”方便。我最终做成了两者并行既支持从订单列表点进来录也支持扫码后自动定位订单。这样小额商家和仓库发货两种场景都能覆盖。4.2 上线前必须确认的细节导航栏、角色权限和页面规范发货信息录入页面上线前有几个细节容易漏整理如下。第一自定义顶部导航栏的高度适配。这个页面如果用了自定义导航不同机型的胶囊按钮位置不一样导航栏高度需要动态计算。不要写死44px或48px正确做法是用wx.getMenuButtonBoundingClientRect()拿到胶囊按钮的位置再结合系统状态栏高度算导航栏总高。我之前做过一个项目就是写死了高度iPhone全面屏上整个导航栏压到了状态栏下面特别丑。后来封装了一个公共方法所有页面统一调用才彻底解决。第二页面权限控制。发货录入页必须做角色判断不能谁拿到路径都能打开。前端要判断用户角色不是管理员就跳回首页后端接口同样要校验防止有人直接调用接口提交发货。这一点我在前面设计部分就强调过上线前一定要里里外外检查一遍。第三操作日志。发货单的创建、修改、取消都要留日志记录操作人、时间、变更内容。真出了问题比如用户说没收到货但系统显示已签收你得能查出是谁、在什么时间、用哪个设备录的这笔单。这个不能等到出事了再补一开始就要做进去。第四错误提示要友好。单号格式不对就明确告诉用户“运单号应为12位数字”而不是一个冷冰冰的“提交失败”。发货成功时要给足反馈最好带着物流公司和单号一起回显让操作的人亲眼确认没录错。这些细节看着小实际操作的人几乎天天在用这个页面体验好不好直接影响订单履约效率。4.3 关于模板消息和后续扩展的一点建议如果你做的是跑腿、二手交易、校园服务平台这类多角色小程序发货信息录入不一定叫“发货”可能是“配送单录入”或“完成订单”但底层逻辑一模一样一个角色填写物流凭证订单状态流转另一个角色收到通知。这种类似的O2O场景里建议把发货信息录入做成一个可复用的组件订单类型传参区分而不是为每个业务单独写一套页面。后续如果要扩展物流轨迹查询功能可以在shipment表上加一列tracking_status定时任务每天拉取快递100之类的接口更新物流状态然后在小程序里做一个物流详情页给买家看。这样发货信息录入模块就从一个“填单工具”升级成了“物流信息中枢”价值完全不一样。再有一个建议是把发货记录和售后打通。很多商家的售后问题都跟物流有关买家说没收到你这边能立刻看到物流轨迹和签收时间客服处理起来就有底气。所以别把这个模块当成孤立的表单它是订单生命周期里数据最密集、最有业务价值的节点之一。我在实际开发里的体会是发货信息录入这种模块功能本身不难但特别考验对业务细节的把握单号格式校验、重复提交拦截、订单状态一致性、真机兼容性、角色权限控制每个点都值得停下来多想一下。做完这个模块我对“简单功能不简单”这句话有了更深的理解。最后再分享一个实操小技巧开发阶段多用真机调试别只依赖开发者工具很多兼容性问题真机上才能暴露出来。尤其是iOS和安卓在滚动、弹窗、文件路径上的差异早发现早解决别等上线了让用户替你踩坑。
做小程序开发这几年被问得最多的场景除了登录、支付就是“发货信息录入”。很多人觉得这功能太简单了不就是个表单填快递单号点提交吗真上手做才发现里面全是细节快递公司怎么选、单号格式怎么校验、订单重复提交怎么防、录错了能不能改、苹果手机上为什么列表滑不动……这篇文章就基于我最近给一个电商类微信小程序做的发货信息录入模块从设计思路到落地实现再到真机踩坑和上线优化完整拆一遍。不管你是刚接手小程序订单模块的新手还是想优化现有发货流程的开发者这篇文章应该都能给你一些可以直接用的东西。1. 发货信息录入模块的设计思路与需求拆解1.1 这个模块到底要解决什么问题先搞清楚业务背景。一个典型的电商小程序用户下单之后商家后台需要把物流信息回填到订单里这一步做不好后面全是客服灾难买家问“我货发了没”商家查不到单号又不敢瞎承诺一单一单对着聊天记录翻效率极低。发货信息录入这个模块本质上是订单履约链路里承上启下的一环。承上是从待发货订单池里取出订单启下是录入物流信息之后订单状态要从“待发货”变成“已发货”同时把运单号同步给买家。所以它不只是“填个单号”那么简单它需要具备几个核心能力准确记录物流公司和运单号保证订单与运单一一对应。防止重复发货同一订单不能被提交两次。支持修改和补救录错了能改漏录了能补。给后续状态流转提供依据发货后自动更新订单状态触发买家通知。对操作效率有要求仓库批量发货时不能一单一单慢慢敲。我在设计这个模块时把需求拆成了三层第一层是基础录入字段至少包括订单号、物流公司、运单号、发货备注第二层是异常处理包括重复提交拦截、单号格式校验、发货后不可随意修改第三层是效率增强比如扫码录入、批量导入、历史发货记录查询。如果你只是做个个人小项目第一层就够了但想上线给真实商家用第二层第三层绕不开。这里有个容易忽略的点录入权限。发货信息录入通常不是给普通用户用的而是给商家、客服或仓库管理员用的所以页面必须做身份区分。我在项目里是把“发货录入”入口放到管理端角色下普通用户的小程序首页根本没有这个入口前端隐藏加后端接口鉴权双重控制。这一点在后面安全部分会再展开。1.2 技术方案选型为什么用原生小程序加Java后端发货信息录入本身不挑技术栈市面上流行的方案无非三种原生微信小程序、uni-app跨端、纯H5嵌到小程序里。如果你已经有一个小程序项目最稳的做法是在现有工程里加页面而不是为了一个模块重新引一套框架。我自己这次选的是原生小程序前端加Java Spring Boot后端。原因很直接项目里订单、商品、支付模块都是Java后端发货信息录入只是其中一个接口用同一套技术栈维护成本最低。网上搜“微信小程序 java 发货信息录入 csdn”能搜到大量同类项目说明这个组合是真实业务里最常见的搭配出问题也好查资料。那什么时候用uni-app如果你的小程序后续还要出App或H5版本又不想重复写三套代码uni-app是合理的配合HBuilderX发行到微信小程序也成熟。但要注意uni-app发布小程序时微信特有的能力比如订阅消息、扫码还是需要通过条件编译或原生插件去适配不是说一套代码全搞定。单一小程序场景我建议别为了跨端而跨端原生开发调试起来更直接基础库更新也能第一时间用到新特性。数据库表结构我按发货单和订单两个概念来设计避免在订单表上堆太多物流字段。实际用到的核心表大致是这样的shipment主表id、order_id、shipping_company、tracking_no、remark、status、create_time、update_time。order表增加shipping_status字段0待发货1已发货2部分发货拆单场景。为什么单独建shipment表而不是直接在订单表加两个字段因为一个订单可能被拆成多个包裹分别发出一条订单记录对应多条物流记录一对多关系用独立表更干净以后做物流轨迹查询、售后核验都方便。2. 核心页面实现与关键代码拆解2.1 表单设计字段布局、快递公司选择和单号校验页面结构上我遵循“能少让用户输入就少输入”的原则。进入页面时如果是从订单列表跳转过来的订单号自动带入且只读如果是扫快递面单进入的物流公司和单号尽量自动识别。手输字段压缩到最少只有商家要额外备注时才需要碰键盘。物流公司选择不建议用输入框自由填写。不同人对“顺丰速运”“顺丰快递”“SF”的写法能差出十几种数据统计和物流查询全乱。我用了微信小程序单选框组把常用物流公司固定成选项用户点选即可。如果你家合作快递很多可以做成搜索式选择器但至少也要有个固定的基础选项池后台可配置这样才能保证录入数据的规范性。下面是WXML表单的核心片段字段不算复杂但每处都对应一个细节view classform-item text classlabel订单号/text input value{{orderNo}} disabled placeholder自动带入订单号 / /view view classform-item text classlabel物流公司/text radio-group bindchangeonCompanyChange label wx:for{{companyList}} wx:keyname radio value{{item.name}} checked{{item.name form.company}} / text{{item.name}}/text /label /radio-group /view view classform-item text classlabel运单号/text input value{{form.trackingNo}} bindinputonTrackingInput placeholder请输入或扫码识别 / button sizemini bindtapscanTrackingNo扫码/button /view view classform-item text classlabel备注/text input value{{form.remark}} bindinputonRemarkInput placeholder选填 / /view button typeprimary loading{{submitting}} disabled{{submitting}} bindtapsubmitShipment 确认发货 /button运单号校验是很多人忽略的坑。快递单号不是随便一串数字都合法各家快递公司都有固定的位数规则和前缀特征比如顺丰一般是12位或15位纯数字中通、圆通位数也不同。我封装了一个校验函数先判断长度区间再按物流公司匹配正则不合法就直接弹提示不让用户提交。校验逻辑大致是这样const RULES { 顺丰速运: { min: 12, max: 15, pattern: /^\d$/ }, 圆通速递: { min: 10, max: 14, pattern: /^YT\d{10,13}$/i }, 中通快递: { min: 10, max: 12, pattern: /^\d$/ }, 韵达快递: { min: 13, max: 13, pattern: /^\d{13}$/ }, 极兔速递: { min: 10, max: 14, pattern: /^JT\d{8,12}$/i }, }; function validateTrackingNo(company, trackingNo) { const rule RULES[company]; if (!rule) return trackingNo.length 6; const len trackingNo.length; return len rule.min len rule.max rule.pattern.test(trackingNo); }注意各快递公司的单号规则会调整这只是一个常见示例正式上线前建议跟实际合作的快递网点确认一下或者直接对接快递鸟、快递100这类平台的单号识别接口。校验的目的不是百分之百拦住所有错误而是拦住明显的手误比如少一位、多一位、混入了中文。2.2 提交逻辑防重复提交、接口封装与状态处理前端提交这块核心就一个问题怎么防止用户手抖点了两次造成重复发货我做了三层防护。第一层按钮级拦截。点击提交后立即把submitting置为true按钮进入loading状态并禁用接口返回前用户没办法再点。这个看着简单但很多项目只看后端前端不防实际上体验很差。第二层请求级幂等。前端生成一个唯一的请求标识requestId每次进入页面时初始化提交时随请求一起发给后端后端记录这个requestId处理过的requestId直接返回重复提交提示。第三层后端业务校验。即使前端双重点击被拦住了也保不齐有并发请求、或有人绕过页面直接调接口。后端在生成发货单前必须查一下这个订单当前状态是不是“待发货”如果已经发货过就直接拒绝。前端提交时的核心代码如下async function submitShipment() { if (submitting) return; if (!form.company) { wx.showToast({ title: 请选择物流公司, icon: none }); return; } if (!validateTrackingNo(form.company, form.trackingNo)) { wx.showToast({ title: 运单号格式不正确, icon: none }); return; } submitting true; try { const res await request({ url: /api/shipment/create, method: POST, data: { orderId: orderId, company: form.company, trackingNo: form.trackingNo.trim(), remark: form.remark, requestId: requestId }, header: { Authorization: Bearer ${getToken()} } }); if (res.code 0) { wx.showToast({ title: 发货成功, icon: success }); // 通知订单页刷新 const eventChannel getOpenerEventChannel(); eventChannel.emit(refreshOrder); setTimeout(() wx.navigateBack(), 1500); } else { wx.showToast({ title: res.msg || 提交失败, icon: none }); } } finally { submitting false; } }这里用到了登录态的token。小程序的登录流程通常是wx.login拿到code再传给后端换token后续请求header里带Authorization即可。关联上网上一堆“用code换token”的说法其实就是这个流程没什么玄乎的关键是token要存到小程序的安全存储里每次请求前检查是否过期过期就静默重新登录。2.3 后端接口实现幂等判断、状态流转与发货通知Java后端接口我用Spring Boot实现核心思路是先校验、再幂等、后写入、最后通知。存发货记录和更新订单状态必须放在同一个事务里否则会出现发货单写进去了订单状态没更新两边数据对不上。看下核心代码结构PostMapping(/api/shipment/create) public Result createShipment(RequestBody ShipmentCreateReq req, RequestHeader(Authorization) String token) { // 1. 鉴权并获取当前操作人 Long operatorId authService.getUserIdByToken(token); // 2. 校验订单是否存在且属于当前商家 Order order orderService.getById(req.getOrderId()); if (order null) { return Result.error(订单不存在); } // 3. 幂等判断同一requestId不重复处理 if (idempotentService.checkExists(req.getRequestId())) { return Result.error(请勿重复提交); } // 4. 业务校验订单状态必须是待发货 if (!OrderStatus.SHIPPING_WAIT.equals(order.getShippingStatus())) { return Result.error(该订单已发货不能重复操作); } // 5. 同一个事务里写发货单并更新订单状态 shipmentService.createShipment(order, req, operatorId); return Result.success(); } Transactional(rollbackFor Exception.class) public void createShipment(Order order, ShipmentCreateReq req, Long operatorId) { // 写入发货记录 Shipment shipment new Shipment(); shipment.setOrderId(order.getId()); shipment.setShippingCompany(req.getCompany()); shipment.setTrackingNo(req.getTrackingNo()); shipment.setRemark(req.getRemark()); shipment.setStatus(ShipmentStatus.CREATED.getCode()); shipment.setOperatorId(operatorId); shipmentMapper.insert(shipment); // 更新订单状态 order.setShippingStatus(OrderStatus.SHIPPING_FINISH.getCode()); order.setShipmentId(shipment.getId()); orderMapper.updateById(order); // 落幂等记录 idempotentService.record(req.getRequestId()); // 发送订阅消息通知买家 subscribeMessageService.sendShipmentNotify(order, req); }第4步的校验特别重要。如果漏了一个订单被重复发货用户会收到两条物流信息实际收的却只有一个包裹客服处理起来非常头痛。发货完成后通知买家我用的是微信小程序订阅消息。用户下单时提前引导订阅“发货通知”发货后后端调微信接口发送物流信息给买家内容包括快递公司和运单号。订阅消息一次订阅只能发一次通知所以下单那个环节就要设计好引导话术不然到发货时你没有发送权限只能干瞪眼。这算是我这次做得比较顺手的一环之前就吃过没引导订阅的亏后面补引导再发货就顺畅多了。3. 实操过程中遇到的坑与排查实录3.1 真机上的兼容性问题一个比一个隐蔽发货信息录入页面其实不复杂但真机测试时遇到的问题比我想象的多尤其是iOS和安卓的差异。挑几个印象深刻的讲一下。第一个是苹果手机在微信小程序不能进行滑动滚动。页面结构是弹窗里加了一个可滚动的物流公司列表安卓上一切正常iPhone上死活划不动。排查下来问题是弹窗容器设置了固定高度但内部滚动区域没有显式设置overflow属性iOS下父容器滚动事件被弹窗遮罩拦截了。解决方法是给内层滚动区域加上overflow-y: auto和-webkit-overflow-scrolling: touch并且给滚动区域设定明确的高度不能依赖内容撑开。之后在iPhone上测试滚动就顺滑了。第二个是handshake failed due to invalid upgrade header: null。这个报错出现在开发版真机调试的时候一开始以为是代码问题查了很久发现是我的本地环境用的调试代理引起的握手失败。也就是说报错不一定是代码或服务器的问题可能是网络代理干扰了请求头。排查办法是先关掉本地代理工具再用微信开发者工具的“不校验合法域名”模式跑一遍如果规规矩矩走线上域名这个错误基本不会出现。顺带提醒别一看到这报错就去服务器上改WebSocket配置先检查自己的调试链路。第三个是基础库版本问题。小程序里有些新API在低版本基础库上不支持比如wx.env.user_data_path只在2.19.0以上基础库才比较稳定。发货单需要导出附件时我用这个路径保存本地文件结果在低版本基础库上直接报错。解决方法是到微信公众平台后台设置最低基础库版本同时代码里做能力检测低版本走降级方案不强制用新API。基础库版本从哪设置两个地方一是在微信公众平台的小程序后台可以设置最低基础库版本二是在开发者工具的项目设置里可以调试不同基础库版本下的表现。建议至少把最低版本设到能覆盖95%以上用户的水平而不是只看你自己手机上的效果。第四个是wx.env.user_data_path的坑。这个路径返回的是小程序用户目录iOS和安卓上前缀不一样千万别把路径写死。我一开始图省事直接拼了个固定路径结果安卓上写文件老是失败。正确做法是先调用wx.env.user_data_path动态获取路径再拼上文件名这样两端都能正常读写。如果你只是临时保存附件记得用完清理这个目录在部分机型上不会自动释放时间久了会占空间。3.2 常见问题速查表收藏这一份就够了整理一份我在项目上线前后遇到的问题汇总按现象、原因、解决方案排列遇到同类问题可以直接对照着查。现象可能原因解决方案点击“确认发货”没反应按钮被loading状态锁死或前端校验不通过被拦截打开控制台看wx.showToast是否有提示检查submitting状态是否被意外置为true连续快速点击出现两条发货单前端未禁用按钮后端未做幂等前端button加loading和disabled后端用requestId幂等事务内校验订单状态单号输入框能输入中文没有做输入限制或只做了提交时校验input上加typetext但监听输入过滤掉非数字字母或提交前统一trim校验苹果手机能打开页面但点不了提交按钮被遮罩层挡住检查z-index层级弹窗/遮罩组件最高层级固定按钮层级不足时触摸事件被吞接口请求报url not in domain list小程序后台未配置request合法域名到微信公众平台配置服务器域名开发阶段可在开发者工具临时勾选不校验域名发货成功但买家没收到通知卖家未在下单时引导订阅或订阅次数用完下单选货流程中引导用户点击“允许”订阅按钮发货时调用前检查授权状态发货列表分页加载越来越慢一次查全量数据没有limit改用limitoffset或游标方式按create_time倒序每次只查20条发货记录被误操作删除没有权限控制或删除保护管理端加操作权限发货记录不提供彻底删除只允许取消并留存日志另外提一句现在网上能搜到不少“微信小程序反编译”之类的工具和文章风控上我不建议碰。小程序前端代码本身是在用户手机上下载执行的压缩混淆也不等于绝对安全所以任何敏感逻辑都必须放在后端而不是指望前端代码不被别人看到。发货单、订单这类数据是业务命脉后端接口权限和日志审计一定要做扎实这比前端加一百道锁都重要。4. 体验优化与上线后的运营建议4.1 扫码录入仓库发货快三倍的效率密码录入发货信息这个动作在订单量小的时候无所谓一天几十单手输也就输了。一旦到双十一那种量级一单一个单号手输不仅慢还容易看错。我的建议是把扫码功能加上。微信小程序里有现成的wx.scanCodeAPI在录入表单旁边放一个“扫码”按钮点一下直接调起摄像头扫快递面单上的条形码。扫码结果通常是一串包含单号的文本需要做一次清洗把数字部分提取出来。我最初是拿到什么存什么结果有的面单扫出来带一堆前后缀物流查询根本识别不了后来加了个解析函数去掉字母前缀和后缀只保留合法单号部分问题就解决了。如果条件允许可以更进一步把扫码和新建发货单的流程合并。扫一个面单自动创建一条发货单再扫下一个全程不用碰屏幕。配合批量发货列表仓库人员只需要把面单逐个对准扫码框系统自动关联到最近一个待发货订单上效率提升非常明显。我实测过熟练工手输一单平均30秒扫码一单5秒以内差距不是一星半点。当然扫码也分场景。如果你的商家是小卖家一天就几单扫码价值不如直接在订单列表上点“发货”方便。我最终做成了两者并行既支持从订单列表点进来录也支持扫码后自动定位订单。这样小额商家和仓库发货两种场景都能覆盖。4.2 上线前必须确认的细节导航栏、角色权限和页面规范发货信息录入页面上线前有几个细节容易漏整理如下。第一自定义顶部导航栏的高度适配。这个页面如果用了自定义导航不同机型的胶囊按钮位置不一样导航栏高度需要动态计算。不要写死44px或48px正确做法是用wx.getMenuButtonBoundingClientRect()拿到胶囊按钮的位置再结合系统状态栏高度算导航栏总高。我之前做过一个项目就是写死了高度iPhone全面屏上整个导航栏压到了状态栏下面特别丑。后来封装了一个公共方法所有页面统一调用才彻底解决。第二页面权限控制。发货录入页必须做角色判断不能谁拿到路径都能打开。前端要判断用户角色不是管理员就跳回首页后端接口同样要校验防止有人直接调用接口提交发货。这一点我在前面设计部分就强调过上线前一定要里里外外检查一遍。第三操作日志。发货单的创建、修改、取消都要留日志记录操作人、时间、变更内容。真出了问题比如用户说没收到货但系统显示已签收你得能查出是谁、在什么时间、用哪个设备录的这笔单。这个不能等到出事了再补一开始就要做进去。第四错误提示要友好。单号格式不对就明确告诉用户“运单号应为12位数字”而不是一个冷冰冰的“提交失败”。发货成功时要给足反馈最好带着物流公司和单号一起回显让操作的人亲眼确认没录错。这些细节看着小实际操作的人几乎天天在用这个页面体验好不好直接影响订单履约效率。4.3 关于模板消息和后续扩展的一点建议如果你做的是跑腿、二手交易、校园服务平台这类多角色小程序发货信息录入不一定叫“发货”可能是“配送单录入”或“完成订单”但底层逻辑一模一样一个角色填写物流凭证订单状态流转另一个角色收到通知。这种类似的O2O场景里建议把发货信息录入做成一个可复用的组件订单类型传参区分而不是为每个业务单独写一套页面。后续如果要扩展物流轨迹查询功能可以在shipment表上加一列tracking_status定时任务每天拉取快递100之类的接口更新物流状态然后在小程序里做一个物流详情页给买家看。这样发货信息录入模块就从一个“填单工具”升级成了“物流信息中枢”价值完全不一样。再有一个建议是把发货记录和售后打通。很多商家的售后问题都跟物流有关买家说没收到你这边能立刻看到物流轨迹和签收时间客服处理起来就有底气。所以别把这个模块当成孤立的表单它是订单生命周期里数据最密集、最有业务价值的节点之一。我在实际开发里的体会是发货信息录入这种模块功能本身不难但特别考验对业务细节的把握单号格式校验、重复提交拦截、订单状态一致性、真机兼容性、角色权限控制每个点都值得停下来多想一下。做完这个模块我对“简单功能不简单”这句话有了更深的理解。最后再分享一个实操小技巧开发阶段多用真机调试别只依赖开发者工具很多兼容性问题真机上才能暴露出来。尤其是iOS和安卓在滚动、弹窗、文件路径上的差异早发现早解决别等上线了让用户替你踩坑。
