前阵子给一个移动端小项目配商城功能翻了一圈市面上的开源商城系统要么体积大、后台模块一箩筐数据库表几十张部署起来都够喝一壶的要么压根不带支付通道接支付还得自己从头折腾。最后我干脆自己整理了一套“H5迷你商城系统源码”并把易支付接口接了进来核心诉求就两条页面在手机上打开够轻、够快用户下单后能完完整整走完支付闭环。这篇文章就把这套系统的设计与实现逻辑摊开讲一遍包括数据表怎么建、接口怎么划分、易支付这类聚合支付网关怎么对接、前端有哪些移动端兼容坑以及部署上线时容易被忽略的细节。适合想快速搭一个移动商城的人也适合想搞懂聚合支付流程、准备自己写一套支付模块的开发者。全程没有大厂全家桶那种复杂度但该有的环节一个不少。1. 从一个实际需求说起为什么是 H5 迷你商城1.1 为什么被“全家桶”方案劝退我的原始需求不复杂某个移动端小产品需要上架少量商品用户浏览、下单、付款然后收到订单通知。听起来很简单但我去翻开源商城系统的时候发现几乎每个主流项目都在做“大而全”多商户入驻、分销提成、优惠券体系、积分商城、营销拼团、后台权限角色……光是安装后台插件就能折腾一个下午。这些功能对一个只用得上三五个商品卡片的小项目来说全是负担。数据库表多意味着接口多、页面多、出 Bug 的地方也多后台复杂意味着每次部署都要处理各种依赖和初始化步骤。最尴尬的是很多项目默认对接的是企业级支付商户渠道个人开发者或小团队根本申请不下来绕一圈最后还是得自己动手接支付。1.2 迷你商城的边界留什么、砍什么所以我给这套 H5 迷你商城系统定了一条边界只保留“浏览商品 - 下单 - 支付 - 查订单”这个最小交易闭环其他一律不碰。保留的功能和砍掉的功能我列过一张对照表这里也直接放出来供你参考保留砍掉商品列表 / 商品详情多商户入驻购物车轻量版分销推广、佣金结算订单创建与状态查询积分、优惠券、满减促销易支付聚合接口扫码/H5 收银台多 SKU 规格可后续扩展支付回调、补单、关单逻辑复杂后台权限体系简易订单管理接口库存预警、数据报表砍完之后整套系统的代码量立刻下来了。对于个人开发者来说少一个模块就少一份维护压力这不是技术退步而是把有限的精力集中在交易闭环的核心点上。1.3 选 H5 而不是小程序或原生 App 的考量为什么是 H5首先是跨平台。H5 页面只要放到服务器上所有带浏览器的设备都能直接访问不需要走应用商店审核也不受小程序平台的各种类目限制。其次开发调试链路最短后端接口返回 JSON前端页面拿到数据渲染就行一人能同时搞定前后端。小程序和原生 App 的体验当然更好尤其是唤起支付的能力更强但代价也很明显小程序要注册账号、配置服务器域名、走审核原生 App 要上架、要处理版本兼容、还要维护两个端。放在“迷你商城”这个场景里体验上的差距可以接受但开发成本上的差距却很大。另外一个实际原因是易支付这类聚合网关本身提供的就是网页收银台跳转和扫码支付方案跟 H5 的天然契合度非常高。与其在小程序里绕一圈限制不如直接用网页方案把支付链路打通后续如果业务量上来了再扩展小程序端也来得及。2. 数据层与接口设计最小闭环到底有多小2.1 三张核心表与金额单位从 SQL 设计说起“迷你”不代表数据表可以乱来。我把整个商城的数据量压到了三张核心表商品表、订单表、用户表。除此之外再加一张支付日志表用于排错其余都不需要。商品表很简单字段基本就是标题、封面图、价格、库存、状态CREATE TABLE goods ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, title VARCHAR(128) NOT NULL COMMENT 商品标题, cover VARCHAR(255) NOT NULL DEFAULT COMMENT 封面图, price INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 价格单位分, stock INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 库存, status TINYINT NOT NULL DEFAULT 1 COMMENT 1上架 0下架, created_at INT UNSIGNED NOT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;订单表是最核心的一张表字段设计上我会特别注意三个点订单号唯一索引、金额存分、状态用整数枚举CREATE TABLE orders ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, order_no VARCHAR(32) NOT NULL COMMENT 业务订单号, goods_id INT UNSIGNED NOT NULL, user_id INT UNSIGNED NOT NULL, amount INT UNSIGNED NOT NULL COMMENT 实付金额单位分, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待支付 1已支付 2已关闭, pay_trade_no VARCHAR(64) NOT NULL DEFAULT COMMENT 支付通道流水号, pay_time INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 支付成功时间, created_at INT UNSIGNED NOT NULL, PRIMARY KEY (id), UNIQUE KEY uk_order_no (order_no), KEY idx_user_id (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里最关键的一个小决策是金额一律用整数分存储。很多第一次写交易系统的同学习惯用 DECIMAL(10,2) 存元看起来方便但一旦涉及浮点运算就会出现 0.1 0.2 不等于 0.3 这种经典问题。用分存储所有计算都在整数层面完成展示时再除以 100逻辑清晰也不容易出错。2.2 接口清单从商品浏览到支付查询整套后端接口我只分了六个前端调用路径非常明确接口方法作用/api/goods/listGET获取商品列表/api/goods/detailGET获取商品详情/api/order/createPOST创建订单返回订单号/api/pay/unifiedPOST请求易支付下单返回收银台跳转地址/api/pay/queryGET查询订单支付状态/api/pay/notifyPOST接收支付通道的异步回调接口少了服务端代码自然就短。每个接口做完参数校验、业务校验、返回统一 JSON 结构就算完事。这里想提醒一下做小系统不代表不做状态码约定建议返回结构一开始就固定成{code, msg, data}三件套前后端联调时能省掉大量解释成本。2.3 登录态的轻量实现与会话安全迷你商城不需要做复杂的账号体系。我的实现方式很简单首次进入时前端生成一个访客标识通过localStorage存起来后续请求头里带上这个标识后端根据它关联用户记录。但支付链路里有个安全原则要守住支付动作必须关联一个可唯一识别的订单号而不是仅仅关联一个本地标识。也就是说用户即使没注册账号也能正常走完“下单 - 支付”流程因为订单表里有独立的order_no支付通道只认这个业务订单号。用户身份只是用来做订单归属展示比如“我的订单”列表。会话安全上不搞花活但至少要做到三点接口做基础限流、下单接口校验商品状态和库存、支付回调必须验签。后面章节我会展开讲支付验签这是整个系统安全性的核心。3. 易支付接口接入的完整链路3.1 走一遍易支付聚合网关的交易流程易支付这类聚合支付网关本质上是一个“中转站”开发者只需要在网关侧注册一个商户号拿到商户 ID 和密钥 Key就能通过统一下单接口把用户引导到收银台用户支付成功后网关再通过异步回调把结果通知到你的服务器。整个流程串起来是这样的用户在前端选择商品前端调用/api/order/create创建本地订单服务端拿到订单号后带着订单金额、商品名、回调地址等参数请求易支付下单接口易支付返回一个收银台跳转地址扫码支付则返回二维码内容前端跳转到收银台用户完成支付易支付服务器异步请求你的/api/pay/notify回调地址回调验签通过后服务端更新本地订单状态为“已支付”前端轮询/api/pay/query发现订单已支付跳到支付成功页。需要注意的是第 5 步的异步回调并不保证“及时”极端情况下可能延迟几分钟。所以前端不能只等回调必须配轮询兜底这块我放在后面踩坑章节详细讲。3.2 签名算法与下单请求的代码实现易支付接口的签名逻辑很通用把所有请求参数按参数名字典序升序排列拼成kvk2v2形式的字符串尾部拼接key商户密钥再做一次 MD5得到 32 位小写签名字符串。核心签名函数用 PHP 写出来大概长这样function buildSign(array $params, string $key): string { // 过滤掉空值和 sign 本身 $params array_filter($params, function ($v) { return $v ! $v ! null; }); unset($params[sign]); ksort($params); $str ; foreach ($params as $k $v) { $str . $k . . $v . ; } // 拼接商户密钥 $str . key . $key; return md5($str); }这里有一个很多人容易踩的细节拼参数字符串的结尾不能把留进去再拼接 key而是要先拼所有kv最后再加keyxxx。否则签名对不上网关第一关就会把你拦下来。统一下单的请求参数里我每次都会带上out_trade_no业务订单号、money金额元带两位小数、notify_url回调地址、return_url支付完成后的跳转页面。注意money这里要转成“元”的字符串格式比如分存储的整数要除以 100 再格式化避免传递100被网关理解成 100 元。3.3 异步回调解密验签与订单状态流转回调是整个支付链路里最不能出错的一环。我写回调处理代码时第一件事永远是先验签再改库顺序反了就会给攻击者留下刷单的窗口。一个完整的回调处理逻辑大概是function handleNotify(array $params, string $key) { // 1. 验签 $sign $params[sign] ?? ; unset($params[sign]); if (buildSign($params, $key) ! $sign) { // 返回错误让网关重试或记录异常 return sign error; } // 2. 取业务订单号并加载订单 $orderNo $params[out_trade_no]; $order findOrderByNo($orderNo); if (!$order) { return order not found; } // 3. 校验金额防止订单金额被篡改 $paidAmount (int) round(floatval($params[money]) * 100); if ($paidAmount ! $order[amount]) { return amount mismatch; } // 4. 幂等更新当前状态必须是待支付才能更新为已支付 $affected updateOrderToPaid($orderNo, $params[trade_no]); if ($affected 0) { // 已经处理过直接返回成功 return success; } // 5. 业务侧动作扣库存、通知等 afterPaid($order); return success; }第 4 步的幂等更新非常关键。我用的是带条件更新的 SQL比如UPDATE orders SET status1, pay_time... WHERE order_no? AND status0。这样一来重复回调进来时第二次更新的影响行数必然是 0不会重复触发扣库存和业务通知。这是交易系统防重复的标准手法比“先查再更”要稳妥得多。提示回调地址必须是公网可以访问的 HTTPS 地址并且不要带查询参数。有些网关对回调地址格式有严格要求地址带?会导致验签串里的notify_url和你实际配置的不一致最终回调永远验签失败。3.4 补单、关单与退款那些被遗漏的边界只看主流程的话支付闭环已经通了。但真实跑起来你会发现三个边界情况必须提前处理第一个是补单。回调可能延迟也可能因为网络问题丢失。我的方案是写一个定时脚本每分钟扫描一次状态为“待支付”且创建时间超过 10 分钟、但本地没有收到回调的订单主动去易支付网关查询这笔订单在通道侧的真实状态。如果通道侧显示已支付就以通道侧结果为准直接执行回调里同样的更新逻辑。第二个是关单。订单创建后用户一直不支付库存就会一直被占用。我设定 30 分钟超时超时未支付就自动把订单状态改成“已关闭”同时释放库存。关闭之后的订单即使用户再拿这个订单号去发起支付服务端也要拒绝。第三个是退款。虽然迷你商城的退款频次不高但售后会出现。我的做法是干脆提供一个/api/pay/refund管理接口人工确认后调用易支付的退款接口退款结果同样走异步回调更新订单状态。这里给一句忠告退款接口千万别做成前端可随意调用的公开接口权限校验必须放在服务端或后台操作中。4. H5 前端与交互实现让页面在手机上真正好用4.1 移动端适配viewport、rem 与安全区域H5 商城的第一道门槛就是移动端适配。我在页面head里固定使用meta nameviewport contentwidthdevice-width, initial-scale1, maximum-scale1, user-scalableno布局上不引入重量级 UI 框架用 Flex 布局加简单的 CSS 变量就能搞定。商品卡片做成两列瀑布流图片统一aspect-ratio: 1 / 1避免不同尺寸图片把布局撑乱。底部购物车栏有个细节容易被忽略iPhone 等全面屏设备底部有安全区域固定定位的底部栏如果不管安全区域就会和 Home 条重叠。解决办法是给底部栏加一个padding-bottom: env(safe-area-inset-bottom, 0px);这个属性平时看不出差别一旦在真机上测试观感差距是立竿见影的。4.2 商品列表与购物车的轻量方案商品列表直接请求/api/goods/list渲染数据量小的时候不需要做分页。首屏加载我会做一层最简单的骨架屏先用灰色占位块铺满接口返回后替换成真实内容体验上比转圈好不少。购物车我采用了最轻的方案——存前端localStorage。用户加购的商品列表放在本地结算时把商品 ID 和数量提交给后端后端重新从数据库里取价格并计算总价而不是信任前端传过来的价格。这一点很重要前端展示的价格可以本地缓存但实付金额必须以服务端重新计算为准否则改一下 localStorage 里的价格就能低价下单。4.3 支付收银台的唤起与跳转兼容支付唤起这块是 H5 商城兼容性的重灾区。我的做法是后端/api/pay/unified接口返回两种响应一种直接返回收银台跳转 URL另一种返回二维码内容字符串。前端拿到跳转 URL 后最简单可靠的方法是window.location.href payUrl;不要用window.open(payUrl)去打开新窗口原因很简单很多主流社交 App 的内置浏览器会拦截 window.open 的弹窗最后用户什么都看不到。直接用当前页面跳转支付完成后再通过return_url回到商城页面。如果返回的是二维码内容我会在前端引入一个轻量的二维码生成库把字符串渲染成二维码图片展示到页面上用户长按识别或扫码支付。这种方案对于用户在电脑端预览、手机扫码付款的场景特别实用。支付跳转后还有一个状态同步问题用户支付完可能直接关掉收银台页面根本不走return_url回来。所以我从前端跳转开始就启动了一个轮询定时器每 3 秒请求一次/api/pay/query一旦发现订单状态变成“已支付”立即清理定时器并跳转到成功页。这个兜底逻辑必须写不然就会出现“用户钱付了页面还傻等”的尴尬情况。5. 部署与上线源码跑起来以后的事5.1 服务器环境与站点配置清单这套系统我这边以 PHP 版本为例部署环境只需要 Nginx PHP 7.4 MySQL 5.7一台轻量云服务器就能跑。Node 版本的原理完全一致只是语言不同。Nginx 站点配置里有两个点需要特别注意一是必须配置 HTTPS不要用明文 HTTP 承载支付相关请求二是回调地址对应的路径不能做重定向跳转否则网关回调时会因为跳转而失败。一个基础配置片段如下server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; root /var/www/h5-mall; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass 127.0.0.1:9000; } # 支付回调不打日志可以但建议单独开 access 日志记录结果 access_log /var/log/nginx/pay_access.log; }5.2 参数配置商户号、密钥、回调地址上线前要核对三处配置商户号或应用 ID、商户密钥 Key、回调地址。我习惯把这些参数放在独立的配置文件中不走代码仓库避免密钥泄露。一个很容易踩的坑是回调地址的最终形态一定要填线上真实域名不要填http://localhost或127.0.0.1。网关侧的回调请求必须能穿透到你公网服务器本地地址永远调不通。调试阶段可以用内网穿透工具辅助但上线前必须换成正式地址。另外回调地址的路径要与代码里的路由一致。如果接口路径是/api/pay/notify那么网关联调的地址就应该是https://your-domain.com/api/pay/notify不要带额外参数。5.3 日志与异常告警支付流程的可观测性支付流程一旦出问题用户最先骂的不是网关是你的商城。所以我上线前一定会把日志体系搭起来核心是三块第一块是支付回调日志。每一次回调请求进来不管验签成功还是失败都记录一行订单号、来源 IP、原始参数、验签结果。这样如果哪天出现“用户付了款但订单没更新”翻日志能立刻定位是没收到回调还是验签失败。第二块是订单状态变更日志。订单从待支付变成已支付、已关闭每次变更都带上前后状态、触发来源回调、定时补单、人工操作、操作时间。这套日志是排查“订单状态错乱”类问题的唯一可信依据。第三块是异常告警。我用了最简单的方案支付回调验签失败、订单支付后数据库更新失败这类严重异常直接发出告警通知给自己。定时补单脚本如果发现某笔订单通道侧已支付但本地一直没更新也要人工介入确认。宁可比平时多收几条告警也不能让用户付了钱还拿不到货。6. 实测踩坑记录与优化建议6.1 回调延迟的补单机制一次线上踩坑记录这套系统第一次上线的时候我以为支付链路已经够稳了结果第三天就遇到一笔订单卡在“待支付”状态用户那边明明已经扣款成功。排查过程是这样的先查回调日志发现这笔订单的异步回调压根没到。再看网关侧订单查到通道流水号状态是“已支付”。也就是说回调确实丢了或者延迟超出预期。当时我手动补了单但马上意识到这不是个例而是系统缺陷。从那以后我加了一个常驻补单任务逻辑很简单每分钟拉出所有“待支付”且创建超过 5 分钟的订单逐笔调用网关查询接口只要通道侧状态是已支付就执行与回调完全相同的“验资、验单、幂等更新”流程。这个补单任务上线后再没出现过用户付款但订单不变的情况。6.2 内置浏览器兼容页面跳转与自动打开拦截H5 商城免不了要在各类社交 App 的内置浏览器里打开。实测下来有两个典型问题一个是window.open被拦截。本来想用新窗口打开收银台结果很多内置浏览器直接把弹窗拦掉。解决方式前面已经说了用当前页面location.href跳转最省心。另一个问题是内置浏览器里跳转外部收银台时有的场景会提示“该页面包含支付内容已拦截”或者跳出去之后就没有返回按钮。我的处理方式是在收银台跳转前弹一个中间提示页提醒用户“即将跳转到收银台页面支付完成后请点击左上角返回商城”并把return_url写成商城的支付结果页。用户看到明确指引就不会在支付完成后一脸迷茫地原地卡住。6.3 金额、幂等与限流不该省的都别省安全上的硬性要求我在写代码时全部写进了流程这里集中提醒一次金额校验回调必须校验支付金额和订单金额完全一致不一致的一律拒绝更新并告警。幂等更新用带状态条件的 UPDATE 保证重复请求只生效一次不要用“先查再更”的朴素逻辑。接口限流下单、支付查询这类接口要做基础限流防止有人用脚本批量刷接口。我用的最朴素方案是 IP 用户维度每分钟 N 次超过直接拒绝。敏感日志脱敏日志里不要记录完整密钥和用户手机号能打后四位就只打后四位。6.4 后续扩展方向与二次开发建议这套 H5 迷你商城源码最大的优点是可以按需生长。如果你跑通之后想扩展优先级建议按这个顺序来先加一个简易后台管理页面商品上下架、订单发货、退款操作全都放到后台去点再加多规格 SKU订单表里加一个sku_id字段商品表拆出规格表和 SKU 表然后加物流信息录入用户能查到快递状态等基础体验稳定后再考虑优惠码、会员价这类营销功能。每一步都是增量改动不会伤筋动骨。如果你也准备把这套源码接到自己的小项目里我只有一个发自肺腑的建议先把支付回调日志和补单脚本写好再去联调支付。支付网关本身一般很稳最容易出问题的反而是本地订单状态和通道侧状态不一致。日志打全了补单兜住了这个迷你商城即使量不大也能让用户安安稳稳地完成整个付费流程。