小程序订单后端：从登录到支付回调的完整实践-代码聚汇网

项目概述：为什么要专门做一个“小程序订单后端”

最近几年我接了不少小程序相关的兼职单子，有个现象挺有意思：很多客户手里都已经有了一套前端界面，甚至是设计稿都画好了，但问到后端时往往一脸茫然——要么是根本没人写过，要么是之前找的人只做了个数据库雏形，接口一个都对不上。

小程序开发和其他前端开发不太一样的地方在于，微信平台有自己的一套登录、支付、消息推送规则，前端调接口的方式和后端返回数据的格式要严格对齐，一旦中间层没人管，整个项目就卡在“前端造轮子、后端原地踏步”的状态。这也直接导致了一个市场需求：懂小程序后端开发的人，在兼职接单市场里非常吃香。

今天要聊的这个项目，就是我自己在多个订单类小程序项目里反复沉淀下来的一套后端基础架构。我给它取名叫“小程序订单后端”，因为它不绑定任何具体业务，凡是涉及注册登录、商品列表、下单支付、订单查询与状态流转的后端需求，基本都能拿它当底座直接改。整篇文章会按我实际开发时的思路来拆：先讲整体设计和选型理由，再逐个拆解核心模块的实操细节，然后给出一整套从下单到支付回调的完整流程，最后把我在接单过程中踩过的常见坑列出来，方便大家直接避让。

这套东西不需要你有多高深的后端功底，只要会基础的后端开发，哪怕以前只写过一些简单的 CRUD，跟着思路走一遍，也足够应付大多数小程序的订单后端需求了。对正在找兼职方向的人来说，这属于投入产出比非常高的一个切入点。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

1. 项目整体设计与技术选型

1.1 为什么选 Node.js 而不是 Java 或 PHP

每次接单我都会考虑同一个问题：客户大概率不关心你用什么语言，他们只关心上线速度、维护成本、后续能不能接着改。这决定了技术栈不能选偏，也不能选重。

我最终选择 Node.js + Express + MySQL 的理由有三条。第一，Node.js 的异步模型特别适合小程序这种大量短请求、低计算量的场景，I/O 密集的操作（查数据库、调微信接口）不需要频繁开线程，开发时心智负担也小。第二，整个项目代码量可控，一个订单后端压缩到几百行就能跑通核心流程，交付和交接都比较轻。第三，小程序前端开发者普遍对 JavaScript 更熟悉，大部分接单团队都是前端出身，后端用 JS 写，沟通成本和后期维护难度会低很多。

这不是说 Java/Spring Boot 不好，而是对于兼职接单这个场景，时间和人力都是最贵的资源。Java 光环境搭建、项目配置就要耗掉半天，对几百块钱到几千块钱的小单子来说，性价比太低了。当然，如果你本身就是 Java 出身，用 Spring Boot 完全没问题，后端逻辑是通用的，核心在于接口设计和业务建模。

提示：如果你是纯新手，不建议在这个阶段纠结框架，先用 Express 跑通，再考虑 NestJS 这类带工程化能力的框架升级。接单的第一要务是交付，不是炫技。

1.2 项目目录结构与职责划分

这套代码我按“路由 → 控制器 → 服务 → 数据模型”四层拆分，结构非常直白，新接手的人看目录就能猜到代码在哪：

text复制mini-order-backend/
├── app.js                  # 应用入口
├── config/
│   ├── index.js            # 全局配置（端口、密钥等）
│   └── db.js               # 数据库连接配置
├── routes/
│   ├── user.js             # 用户相关路由（登录、信息）
│   ├── product.js          # 商品路由
│   ├── order.js            # 订单路由（创建、查询、取消）
│   └── pay.js              # 支付相关路由（下单、回调）
├── controllers/
│   ├── userController.js
│   ├── productController.js
│   ├── orderController.js
│   └── payController.js
├── services/
│   ├── wxService.js        # 微信接口封装（登录、支付）
│   ├── orderService.js     # 订单业务逻辑
│   └── productService.js   # 商品业务逻辑
├── models/
│   ├── userModel.js
│   ├── productModel.js
│   ├── orderModel.js
│   └── orderItemModel.js
├── utils/
│   ├── response.js         # 统一响应格式
│   ├── auth.js             # token 鉴权中间件
│   └── wxpay.js            # 微信支付签名/验签工具
└── sql/
    └── init.sql            # 建表脚本

这种拆法的好处是：控制器只负责接参数、调服务、返回结果，不掺任何业务逻辑；服务层专注业务规则；模型层只做数据持久化。后期加一个“优惠券”或“物流查询”功能，基本不会影响现有代码，最多加一个模型加一个服务方法。

我见过很多新手接单，所有代码全塞在一个文件里，第一版功能能跑，但客户提需求变更时代码改起来要命。兼职接单的项目虽然小，但至少有二次开发的可能，分层清晰能帮你省下很多维护成本，也更容易让客户后续继续找你。

1.3 为什么订单表要拆成主表和明细表

一开始我也偷懒过，把订单里的商品信息直接塞到订单表的一个字段里（比如 JSON 字符串），这样查询订单列表、统计金额看起来很省事。但等客户要求“我的订单要能看到每个商品的名字和图片”“退款要支持退单个商品”的时候，就发现设计完全撑不住了。

正确做法是拆成 orders（订单主表）和 order_items（订单明细表）。orders 记录一次下单的整体信息——订单号、用户ID、总金额、状态、支付时间等；order_items 记录这个订单里包含的每个商品项——商品ID、数量、单价、小计金额。二者通过 order_no 或 order_id 关联。

这样做最大的好处是支持部分退款、部分发货等后续需求。比如一个订单里有三件商品，客户只退了一件，明细表能清楚记录哪一件退了，主表状态也能随之流转，不会把数据搞成一坨浆糊。对于兼职接单的项目，宁可前期多一张表，也不要后期重构。

2. 核心模块拆解与实操要点

2.1 数据库表设计：一次到位的关键

我直接把建表脚本贴出来，这是经过多次迭代后相对稳定的一版，大家可以按需再扩展字段：

sql复制CREATE TABLE `user` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `openid` VARCHAR(64) NOT NULL COMMENT '微信openid',
  `nickname` VARCHAR(64) DEFAULT '' COMMENT '昵称',
  `avatar` VARCHAR(255) DEFAULT '' COMMENT '头像',
  `phone` VARCHAR(20) DEFAULT '' COMMENT '手机号',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_openid` (`openid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `product` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `title` VARCHAR(128) NOT NULL COMMENT '商品标题',
  `cover` VARCHAR(255) DEFAULT '' COMMENT '封面图',
  `price` DECIMAL(10,2) NOT NULL COMMENT '单价（元）',
  `stock` INT NOT NULL DEFAULT 0 COMMENT '库存',
  `status` TINYINT NOT NULL DEFAULT 1 COMMENT '1上架 0下架',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `orders` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `order_no` VARCHAR(32) NOT NULL COMMENT '业务订单号',
  `user_id` INT NOT NULL,
  `total_amount` DECIMAL(10,2) NOT NULL COMMENT '总金额',
  `status` TINYINT NOT NULL DEFAULT 0 COMMENT '0待支付 1已支付 2已发货 3已完成 4已取消 5退款中',
  `pay_time` DATETIME DEFAULT NULL,
  `transaction_id` VARCHAR(64) DEFAULT NULL COMMENT '微信支付单号',
  `remark` VARCHAR(255) DEFAULT '' COMMENT '用户备注',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_order_no` (`order_no`),
  KEY `idx_user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `order_items` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `order_id` INT NOT NULL,
  `product_id` INT NOT NULL,
  `product_title` VARCHAR(128) NOT NULL,
  `product_cover` VARCHAR(255) DEFAULT '',
  `price` DECIMAL(10,2) NOT NULL COMMENT '下单时单价',
  `quantity` INT NOT NULL DEFAULT 1,
  `subtotal` DECIMAL(10,2) NOT NULL COMMENT '小计金额',
  PRIMARY KEY (`id`),
  KEY `idx_order_id` (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `pay_log` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `order_no` VARCHAR(32) NOT NULL,
  `transaction_id` VARCHAR(64) DEFAULT NULL,
  `pay_amount` DECIMAL(10,2) NOT NULL,
  `pay_status` TINYINT NOT NULL DEFAULT 0 COMMENT '0未回调 1已回调',
  `raw_data` TEXT COMMENT '回调原始数据',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_order_no` (`order_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

有几个设计细节值得单独说。

第一，user 表用 openid 做唯一键，而不是用自增 ID。微信登录拿到的就是 openid，这是用户的天然唯一标识，拿它直接做关联，省去一次“openid → user_id”的查询。业务上如果需要，再扩展 unionid 做多端绑定。

第二，order_items 里我冗余了 product_title 和 product_cover。字段冗余在规范设计里常被视为“坏味道”，但在订单场景里，商品名称和图片在下单后不应该跟随商品表的变化而变化——商品改名了，历史订单不能跟着改，否则客户对账会乱。冗余存储商品快照是订单系统的常见做法。

第三，金额字段统一用 DECIMAL(10,2)，不要用 FLOAT 或 DOUBLE。浮点数在比较和累加时存在精度误差，涉及钱的事情绝对不能出这种问题。很多新人在这上面踩过坑，值得提一嘴。

2.2 微信登录接入：搞定 code2Session 这一个接口

小程序登录的流程，很多文档都写了，但实际写起来还是有不少细节坑。前端调用 wx.login() 拿到一个临时 code，传给后端，后端拿着 code 去微信的 jscode2session 接口换 openid 和 session_key。

一个典型的实现如下：

javascript复制// services/wxService.js
const axios = require('axios');
const config = require('../config');

async function code2Session(code) {
  const url = 'https://api.weixin.qq.com/sns/jscode2session';
  const params = {
    appid: config.wx.appid,
    secret: config.wx.secret,
    js_code: code,
    grant_type: 'authorization_code'
  };
  const { data } = await axios.get(url, { params });
  if (data.errcode) {
    // 记录日志并抛出可读错误
    throw new Error(`微信登录失败: ${data.errcode} ${data.errmsg}`);
  }
  return data; // { openid, session_key, unionid }
}

拿到 openid 后，查用户表是否存在：

不存在则自动注册一个新用户，只存 openid，其他信息等用户主动授权后更新；
存在则直接返回登录成功。

然后后端签发一个自定义登录态 token 给前端。token 一般用 jsonwebtoken 生成，把 user_id 和过期时间放进去，后续接口通过 Authorization 头带过来，服务端中间件解析后就能拿到当前用户。

javascript复制// utils/auth.js
const jwt = require('jsonwebtoken');
const config = require('../config');

function signToken(userId) {
  return jwt.sign({ userId }, config.jwtSecret, { expiresIn: '7d' });
}

function verifyToken(token) {
  return jwt.verify(token, config.jwtSecret);
}

注意：session_key 是敏感信息，拿到后可以用来解密手机号、运动数据等，绝对不能返回给前端，也不能直接存储到数据库的普通字段中。正确做法是只在需要解密的请求里临时使用。

这里有一个非常常见的报错“获取登录后的微信用户失败”，对于新手来说，十有八九是 appid 或 secret 配置错了。还有一种情况是开发者工具里用了测试号，而后端配置的是正式小程序的 appid，两边对不上，微信接口直接报错。排查时先确认配置，再用微信开发者工具的控制台看请求返回的具体错误码，比盲猜快得多。

2.3 订单状态机：怎么流转才能不出错

订单系统最核心的部分不是增删改查，而是状态流转。我把订单状态定义成一组整型常量：

text复制0 = 待支付
1 = 已支付（待发货）
2 = 已发货（待收货）
3 = 已完成
4 = 已取消
5 = 退款中
6 = 已退款

为什么要用数字而不是字符串？因为数字在存储和比较时效率更高，而且前端展示文案和后端状态值可以解耦。前端拿到 status 后，映射到自己那套文案字典里就行。

状态流转规则我习惯在服务层写死，不暴露任意跳转的接口。比如：

待支付 → 已支付（通过支付回调触发，或用户主动取消则进入已取消）；
待支付 → 已取消（用户取消或超时系统自动取消）；
已支付 → 已发货（商家后台发货）；
已发货 → 已完成（用户确认收货）；
已支付/已发货 → 退款中 → 已退款（售后流程）。

加一个统一的 transitionOrderStatus 方法，任何入口要改状态都必须走这个方法，在里面校验前置状态是否符合预期。比如“已取消”的订单不能直接变成“已支付”，“已完成”的订单也不能变成“已发货”。用状态机的方式把规则限定住，能防止很多因为接口被恶意调用而导致的脏数据。

这个方法大概长这样：

javascript复制// services/orderService.js
const STATUS_TRANSITIONS = {
  0: [1, 4],   // 待支付可以变成已支付或已取消
  1: [2, 5],   // 已支付可以变成已发货或退款中
  2: [3, 5],   // 已发货可以变成已完成或退款中
  3: [],       // 已完成，终态
  4: [],       // 已取消，终态
  5: [6],      // 退款中可以变成已退款
  6: [],       // 已退款，终态
};

async function transitionOrderStatus(orderNo, targetStatus, extra = {}) {
  const order = await orderModel.findByOrderNo(orderNo);
  if (!order) {
    throw new Error('订单不存在');
  }
  const allowed = STATUS_TRANSITIONS[order.status] || [];
  if (!allowed.includes(targetStatus)) {
    throw new Error(`非法状态流转: ${order.status} -> ${targetStatus}`);
  }
  // 执行状态更新，并记录操作日志
  await orderModel.updateStatus(orderNo, targetStatus, extra);
}

这套规则在订单系统里非常值得花时间写好，因为订单问题一多半都出在“状态跟实际业务对不上”上。状态机逻辑清晰了，后面写支付回调、退款、售后的逻辑都会顺很多。

3. 实操过程：从用户下单到支付回调的完整实现

3.1 登录接口的完整链路

前面已经讲了 code2Session 的流程，这里把整个登录接口串一遍。

前端调用 wx.login() 后拿到 code，POST 到后端 /api/user/login，请求体格式：

json复制{
  "code": "0a3Dz..."
}

后端控制器：

javascript复制// controllers/userController.js
async function login(req, res) {
  try {
    const { code } = req.body;
    if (!code) {
      return res.json({ code: 400, msg: '缺少code' });
    }
    const wxSession = await wxService.code2Session(code);
    let user = await userModel.findByOpenid(wxSession.openid);
    if (!user) {
      user = await userModel.create({ openid: wxSession.openid });
    }
    const token = auth.signToken(user.id);
    res.json({ code: 0, data: { token, userInfo: { id: user.id, nickname: user.nickname, avatar: user.avatar } } });
  } catch (err) {
    // 统一错误处理
    res.json({ code: 500, msg: err.message });
  }
}

接口的响应格式我统一约定成：

json复制{
  "code": 0,
  "msg": "success",
  "data": {}
}

code = 0 表示成功，非 0 表示失败。前端可以封装一个 request 方法统一拦截，比如遇到 code = 401（token 过期）就自动跳转登录页。统一响应格式能减少前后端联调时因为字段名不一致出的各种问题。

3.2 创建订单接口：事务、库存、幂等

创建订单是订单系统最敏感的写操作，涉及多张表的变更，任何一个环节失败都要整体回滚，不能出现“订单创建了但库存没扣”或“库存扣了但订单没了”的情况。

核心代码：

javascript复制// services/orderService.js
async function createOrder(userId, items, remark = '') {
  const conn = await db.getConnection();
  try {
    await conn.beginTransaction();

    let totalAmount = 0;
    const orderItems = [];

    for (const item of items) {
      const product = await productModel.findByIdForUpdate(conn, item.productId);
      if (!product || product.status !== 1) {
        throw new Error(`商品不存在或已下架: ${item.productId}`);
      }
      if (product.stock < item.quantity) {
        throw new Error(`库存不足: ${product.title}`);
      }

      // 扣减库存
      await productModel.decreaseStock(conn, product.id, item.quantity);

      const subtotal = product.price * item.quantity;
      totalAmount += subtotal;
      orderItems.push({
        productId: product.id,
        title: product.title,
        cover: product.cover,
        price: product.price,
        quantity: item.quantity,
        subtotal
      });
    }

    const orderNo = generateOrderNo();
    const orderId = await orderModel.create(conn, {
      orderNo,
      userId,
      totalAmount,
      status: 0,
      remark
    });

    for (const item of orderItems) {
      await orderItemModel.create(conn, {
        orderId,
        ...item
      });
    }

    await conn.commit();

    return { orderNo, totalAmount };
  } catch (err) {
    await conn.rollback();
    throw err;
  } finally {
    conn.release();
  }
}

几个关键点需要展开。

SELECT ... FOR UPDATE 在查询商品时加上行锁，防止并发下单导致超卖。下单时先锁住商品行，其他事务必须等当前事务提交或回滚后才能继续操作这行数据。对于订单量不大的小程序项目，这种方式完全够用，不需要引入 Redis 等额外组件。

generateOrderNo() 生成订单号我建议用“时间戳 + 随机数 + 用户ID尾巴”的组合，保证唯一性。比如：

javascript复制function generateOrderNo() {
  const now = new Date();
  const ymd = formatDate(now, 'yyyymmddhhmmss');
  const random = Math.floor(Math.random() * 9000 + 1000);
  return `${ymd}${random}`;
}

如果对并发量有更高要求，可以再接入雪花算法，但小项目没必要，用数据库的唯一索引兜底就足够了。

前端重复提交问题。用户网络不稳定时可能点了两次“提交订单”，后端需要做幂等处理。简单做法：前端在发请求时带上一个请求方生成的 clientToken，后端把这个 clientToken 作为唯一键存到订单表，重复请求直接返回已有订单。没有这个设计的，至少也要在创建前检查“相同用户是否存在同一商品的待支付订单”，避免一堆重复废单。

3.3 微信支付预下单：参数、签名、幂等

支付环节是小程序订单后端里最容易出问题的一环。微信支付接口对接流程是：

后端先调用微信支付的“统一下单”接口，传入订单号、金额、用户 openid、回调地址等参数；
微信返回一个 prepay_id（预支付交易会话标识）；
后端用自己的商户密钥对 prepay_id 等信息签名，把签名结果返回给前端；
前端通过 wx.requestPayment 拉起微信支付面板；
支付成功后，微信服务器异步通知后端回调地址，后端确认并更新订单状态。

统一下单的参数较多，核心几个如下：

text复制appid         小程序 appid
mch_id        商户号
out_trade_no  业务订单号（就是咱们生成的 orderNo）
total_fee     支付金额，单位是分
body          商品描述
notify_url    支付结果回调地址
openid        用户 openid
sign_type     MD5 或 HMAC-SHA256

其中最大的坑有两个：金额单位是“分”不是“元”，签名算法必须严格按微信文档执行。

金额单位这个，很多人第一次对接都会踩。前端和后端所有的金额计算用“元”，到微信支付接口时乘以 100 转成整数“分”，回调里拿到金额再除以 100。不要在接口请求和回调里对金额做浮点运算，直接用整数比较。

签名环节，微信支付要求把所有参与签名的参数按字典序排列，拼接 key=value&...，最后加上 &key=商户密钥，再算 MD5（或按选择的 HMAC-SHA256）。一个可靠的封装：

javascript复制// utils/wxpay.js
const crypto = require('crypto');

function buildSign(params, apiKey) {
  const keys = Object.keys(params).sort();
  const str = keys
    .filter(k => params[k] !== '' && params[k] !== undefined && k !== 'sign')
    .map(k => `${k}=${params[k]}`)
    .join('&') + `&key=${apiKey}`;

  return crypto.createHash('md5').update(str).digest('hex').toUpperCase();
}

生成 paySign 返回给前端时，前端 wx.requestPayment 需要这几个字段：timeStamp、nonceStr、package（格式是 prepay_id=xx）、signType、paySign。其中 paySign 的签名参数里 appId 和 timeStamp 等字段名必须按微信小程序端的规则来，这一点很多人和统一下单的签名混淆了，要特别小心。

3.4 支付回调处理：验签、解密、更新订单的稳定三步

支付回调是“钱是否入账”的最终确认点。前端即使收到了支付成功的返回，也只能当参考，真正可信的是微信服务器异步通知的 notify_url。

回调接口第一步必须先验签。微信通知的请求体是 XML 格式，里面有 appid、mch_id、out_trade_no、result_code、return_code 等字段。验签方式和统一下单一致：把 XML 转成对象，排除 sign 字段，按字典序拼接后算签名，和通知里带的 sign 比对。验签不通过直接返回失败，不能让异常请求进入业务逻辑。

第二步是处理业务。确认 return_code 和 result_code 都是 SUCCESS 后，拿 out_trade_no 查订单，如果订单状态是“待支付”，则更新为“已支付”，记录 transaction_id 和支付时间。这里要特别注意：微信回调可能因为网络原因通知多次，接口必须幂等。同一个订单被通知十次，也应该只有第一次真正更新状态，其余直接返回成功。

第三步是回复微信。微信要求接收方在收到通知后返回：

xml复制<xml>
  <return_code><![CDATA[SUCCESS]]></return_code>
</xml>

如果不返回这个，微信会按一定频率重试通知，通常持续几天。接口处理慢或返回格式不对，就会收到一大堆重复通知，把日志刷爆。

还有一个很多人忽略的点：支付金额必须和订单金额比对，不一致要告警，绝不能直接更新。虽然概率低，但万一出现中间环节篡改或系统 bug，金额比对是最后一层防线。

javascript复制// controllers/payController.js
async function payNotify(req, res) {
  const xml = req.body.toString('utf8');
  const data = wxpay.parseXml(xml);

  const valid = wxpay.verifySign(data, config.wxpay.apiKey);
  if (!valid) {
    return res.status(401).send('sign error');
  }

  if (data.return_code === 'SUCCESS' && data.result_code === 'SUCCESS') {
    const orderNo = data.out_trade_no;
    const amount = Number(data.total_fee);

    const order = await orderModel.findByOrderNo(orderNo);
    if (!order) {
      return res.status(404).send('order not found');
    }

    if (order.status === 0) {
      const orderAmount = Math.round(order.total_amount * 100);
      if (orderAmount !== amount) {
        console.error(`金额不一致: order=${orderNo}, expect=${orderAmount}, actual=${amount}`);
      } else {
        await orderModel.updateStatus(orderNo, 1, {
          transactionId: data.transaction_id,
          payTime: new Date()
        });
        await payLogModel.create({ orderNo, transactionId: data.transaction_id, amount: orderAmount, status: 1, rawData: xml });
      }
    }
  }

  res.send(wxpay.buildSuccessReply());
}

3.5 订单超时未支付：定时任务怎么补

订单创建后，如果用户一直不支付，订单会一直占着库存。所以需要一个“超时取消”机制。

最简单实用的方案是：Node.js 进程里跑一个 setInterval 定时任务，每分钟扫描一次超过 30 分钟仍未支付的订单，把状态改成“已取消”，并回补库存。

javascript复制// utils/schedule.js
const ORDER_TIMEOUT_MINUTES = 30;

async function cancelTimeoutOrders() {
  const orderList = await orderModel.findTimeoutOrders(ORDER_TIMEOUT_MINUTES);
  for (const order of orderList) {
    // 用条件更新防止并发取消
    const ok = await orderModel.cancelIfPending(order.orderNo);
    if (ok) {
      await orderItemModel.restoreStock(order.id);
    }
  }
}

setInterval(cancelTimeoutOrders, 60 * 1000);

条件更新是关键，SQL 类似于：

sql复制UPDATE orders SET status = 4, update_time = NOW()
WHERE order_no = ? AND status = 0

affectedRows = 1 才说明是本次把状态改成了已取消，等于 0 说明订单已经被处理过了，不能再去回补库存。

这种定时轮询方案在订单量不大的小程序项目里完全够用。要是以后单量上来了，可以换延迟队列、消息队列或者 Redis 过期监听，但这些都是后话，不要一开始就为了“高并发”给自己加戏。

4. 常见问题与排查技巧实录

关键词里那个 wx1cb4398e1413dce7 是开发者工具里的请求编号，这类报错通常点开详情能看到具体的 errcode。常见情况有：

40013：appid 无效。检查后台配置的 appid 是否和实际小程序一致；
40125：secret 无效。检查小程序后台是否重置过 secret，代码里是否同步；
40029：code 无效。通常是因为 code 用过了，或者过期时间到了（5分钟有效期），而且 code 只能使用一次，不能重复请求；
45011：接口调用频率限制，短时间内调用太频繁被限流。

我的排障习惯是，先在 Node 端直接打印 jscode2session 接口返回的原始数据，再和微信文档对照，95% 的问题都能定位在“配置没对齐”或“code 被重复使用”上。

4.2 支付下单返回签名错误

签名错误的比例非常高，常见的原因有：

参与签名的参数末尾没有拼 &key=商户密钥；
参数名写错，比如统一下单里是 out_trade_no，有人写成 order_no；
大小写不对，微信支付的 MD5 结果要转大写，转小写就报错；
时间戳格式不对，统一下单里的 timeStamp 是字符串，不能传数字；
商户平台 API 密钥没有正确配置到代码中，而不是下载证书时看到的那个证书密码。

排查方法很笨但很有效：把微信文档里的签名示例参数，放到自己的签名函数里跑一遍，看生成的签名是否和文档一致。一致，说明签名工具没问题，问题在参数；不一致，赶紧查签名函数的实现。

4.3 回调收到但订单状态没更新

这种情况先看回调接口的日志。很多人在本地开发时，回调地址填的是局域网 IP 或者 localhost，微信服务器根本访问不到，自然收不到回调。正确的开发方式是内网穿透工具把自己的服务暴露到公网，再填成回调地址。

还有种情况是回调收到了，但业务逻辑抛出异常了。比如查订单时用了事务的连接但没正确释放，导致后续查询超时；或者订单表里查不到对应的 out_trade_no，回调返回了订单不存在。用户明明支付成功了，订单还停在待支付，这种 bug 一定要看日志才能定位。

我建议回调接口单独写一个日志文件，把每次收到的 XML 原样记录，同时记录处理结果。这样即使出了线上问题，也能从日志倒推问题发生的过程。

4.4 小程序真机测试连接被重置

热搜词里有一条“微信小程序真机测试(failed)net::ERR_CONNECTION_RESET”，这个我之前也遇到过。常见原因有三类：

第一类是后端服务没有部署到 HTTPS。小程序正式环境要求所有接口域名必须备案，且必须支持 HTTPS，开发者工具里可以勾选“不校验合法域名”来临时跳过，但真机预览往往没有这个选项，请求直接失败。

第二类是域名不在小程序后台的 request 合法域名列表中。需要到小程序管理后台的“开发管理 → 开发设置 → 服务器域名”里添加后端接口的域名。注意域名不能带端口，意味着后端常规跑在 3000 端口还需要通过 Nginx 做反向代理到 443。

第三类是本地服务只监听了 127.0.0.1，手机和电脑不在同一网络，或者防火墙拦截了端口。开发时可以通过局域网 IP 访问来排查，但最终一定要走到 HTTPS 这一步。

4.5 开发环境与生产环境配置隔离

很多兼职项目最后交付时，代码里还写着一堆本地的数据库密码、密钥，客户自己接手的时候根本不知道改哪里。

我习惯在 config/ 下建三个文件：dev.js、prod.js、index.js，index 根据 NODE_ENV 加载对应环境的配置。数据库、appid、secret、API 密钥全部放到环境变量或环境配置里，而不是硬编码到代码中。还可以加一个 .env.example 文件，把需要的环境变量列清楚，方便接手的人快速配置。

text复制# .env.example
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=yourpassword
DB_NAME=mini_order
WX_APPID=your_appid
WX_SECRET=your_secret
WX_MCH_ID=your_mchid
WX_API_KEY=your_api_key
JWT_SECRET=your_jwt_secret

这个习惯在接单场景里特别重要，因为客户很可能不是开发者，他们把项目交给别人维护时，如果环境配置一团糟，很容易产生信任危机，影响后续合作。

4.6 表格汇总：常见问题速查

现象	大概率原因	排查路径
code2Session 报 appid 无效	appid 配置错误或用了测试号	对比开发者工具和后台配置
code2Session 报 code 无效	code 被重复使用或过期	检查登录流程是否多次调用 wx.login
支付报签名错误	签名算法、参数名、密钥问题	用文档示例参数自测签名函数
收不到支付回调	回调地址不可公网访问	内网穿透或部署到线上后用在线工具测试
真机请求连接重置	域名未备案 / 没有 HTTPS	检查合法域名列表和网络环境
金额单位不对	元分转换出错	所有金额统一以“分”为最小单位比较
重复支付回调	未做幂等或返回格式错误	订单状态条件更新，重复通知直接返回成功
超时订单未取消	定时任务没跑或条件更新失败	检查服务是否启用调度，查看取消日志

收个尾，聊点接单实战经验

前面讲完了所有核心模块，最后从接单角度聊几句。

给客户做小程序订单后端，最重要的一条原则是：先跑通再优化。我第一次接单时总想着一口气把代码写得完美，结果耗了两周还在“设计架构”，客户那边已经有点不耐烦了。后来我调整了节奏，第一版先做成一个“能跑的最小闭环”：登录、下单、支付回调、订单查询，功能有了，客户看到了进度，心里踏实，后面再迭代也就顺了。

另一个经验是，交付时一定要附带一份简单的接口文档。不需要多正式，一个 Markdown 文件，列清楚每个接口的 URL、请求参数、响应格式就够了。很多兼职项目的矛盾都出在“前端等后端字段、后端等前端说明”上，有文档能省掉至少一半的扯皮时间。

最后一个小建议：这套后端基础架构，建议自己动手敲一遍，不要直接复制粘贴。敲的过程中你会遇到各种问题，也正是在解决这些问题的过程中，你才能真正弄懂每个环节为什么这么设计。等技术变成你自己的东西，以后接单时遇到任何订单类需求，都能很快判断出哪里要改、哪里能复用——这种能力，才是兼职接单真正的核心竞争力。

小程序订单后端：从登录到支付回调的完整实践