企业官网建设流程全解析

• 后端
• 即时通讯

微信小商店是微信官方提供的电商能力，小程序开发者可以通过官方接口在小程序内完成商品管理、购物车、订单履约等电商闭环操作。EasyWeChat 在 5.x 版本的小程序模块中提供了完整的「微信小商店」封装，将微信小商店的所有 HTTP 接口收敛为$app->mall下的一组语义化客户端，本文将以 docs/src/5.x/mini-program/mall.md 为骨架，结合仓库源码深入讲解其获取实例、商品管理、购物车管理、订单管理、媒体文件管理的完整用法，并给出可直接复制的完整示例与注意事项。

一、微信小商店能力概览

微信小商店是微信官方提供的电商解决方案，小程序通过相关接口即可管理商品、订单等核心电商数据，无需自行搭建交易后台。在 EasyWeChat 中，该能力被组织为mall应用下的五个子模块：

二、获取小商店实例

在完成小程序应用初始化后，通过$app->mall即可获得小商店客户端。按照 docs/src/5.x/mini-program/index.md 的说明，$app指Factory::miniProgram($config)得到的实例：

use EasyWeChat\Factory; $config = [ 'app_id' => 'wx3cf0f39249eb0exx', 'secret' => 'f1c242f4f28f735d4687abb469072axx', // 下面为可选项 // 指定 API 调用返回结果的类型：array(default)/collection/object/raw/自定义类名 'response_type' => 'array', 'log' => [ 'level' => 'debug', 'file' => __DIR__ . '/wechat.log', ], ]; $app = Factory::miniProgram($config); $mall = $app->mall;

从源码结构看，mall下挂载的product、cart、order、media等子客户端通过应用的动态属性机制暴露，$mall->product、$mall->cart等即对应微信小商店的各业务接口分组。所有请求都经由 src/MiniApp/Application.php 中createClient()构建的AccessTokenAwareClient发出，SDK 会自动携带 access_token、按errcode与error字段判断请求是否失败，开发者无需手动拼接 URL 或处理鉴权。

三、商品管理

商品是小商店交易的核心数据，微信小商店要求商品与 SKU 分层建模，EasyWeChat 的$mall->product封装了完整的商品生命周期操作。

3.1 导入或更新商品

import方法支持批量导入或更新商品信息。相同product_id的商品会被更新，不存在的则新建。价格统一以分为单位：

$products = [ [ 'product_id' => 'product_001', 'title' => '商品标题', 'sub_title' => '商品副标题', 'head_imgs' => ['图片URL1', '图片URL2'], 'category_id' => 1234, 'brand_id' => 5678, 'model' => '型号', 'third_cat_id' => 9012, 'product_type' => 1, 'qualification_pics' => ['资质图片URL'], 'src_wxapp_path' => 'pages/product/detail?id=123', 'skus' => [ [ 'sku_id' => 'sku_001', 'price' => 9900, // 以分为单位 'original_price' => 12900, 'status' => 1, // 1:上架 0:下架 'stock_num' => 100, 'sku_attrs' => [ ['attr_key' => '颜色', 'attr_value' => '红色'], ['attr_key' => '尺寸', 'attr_value' => 'L'] ] ] ] ] ]; $result = $mall->product->import($products, false); // false表示正式环境

参数要点：

• head_imgs为商品头图 URL 数组，必须先上传到微信服务器或使用 HTTPS 图片地址；
• category_id、third_cat_id等分类 ID 需从微信官方小商店类目体系获取；
• skus中的price、original_price单位为分，status为 1 表示上架、0 表示下架；
• import的第二个布尔参数控制环境，传入false表示正式环境（按微信小商店接口约定，不同环境调用的能力有差异，请以微信官方当前规则为准）。

3.2 查询商品信息

query方法按product_id查询商品详细信息，need_edit_spu控制返回的 SPU 数据是否可用于编辑回填：

$params = [ 'product_id' => 'product_001', 'need_edit_spu' => 1 ]; $result = $mall->product->query($params);

3.3 获取商品状态

批量查询多个商品当前的上架/下架状态，入参为product_id字符串数组：

$result = $mall->product->getStatus(['product_001', 'product_002']);

3.4 更新商品状态

updateStatus接收一个元素为「商品 ID + 目标状态」的数组，可一次性批量上下架多个商品：

$result = $mall->product->updateStatus([ ['product_id' => 'product_001', 'status' => 1], // 1:上架 0:下架 ['product_id' => 'product_002', 'status' => 0] ]);

四、购物车管理

购物车能力面向已登录用户（通过user_open_id标识），围绕「商品 + SKU」粒度进行增删查操作。

4.1 添加商品到购物车

$params = [ 'user_open_id' => 'user_openid', 'sku_product_id' => 'product_001', 'sku_id' => 'sku_001', 'num' => 2 ]; $result = $mall->cart->add($params);

4.2 获取购物车商品

按用户维度拉取该用户购物车中的全部商品条目：

$params = [ 'user_open_id' => 'user_openid' ]; $result = $mall->cart->get($params);

4.3 删除购物车商品

删除时需要同时指定商品 ID 与 SKU ID，精确到具体规格：

$params = [ 'user_open_id' => 'user_openid', 'sku_product_id' => 'product_001', 'sku_id' => 'sku_001' ]; $result = $mall->cart->delete($params);

五、订单管理

订单模块覆盖「生成订单 → 更新订单状态 → 批量拉取订单」的核心履约链路。订单数据结构较为复杂，分为商品信息、支付信息、价格信息、配送信息四大部分。

5.1 生成订单

add方法一次性提交整单数据。create_time、prepay_time等时间字段建议直接使用time()生成 Unix 时间戳；order_id需要业务侧保证唯一，可通过'order_' . time()之类的策略生成：

$orderData = [ 'create_time' => time(), 'type' => 1, 'order_id' => 'order_' . time(), 'openid' => 'user_openid', 'union_id' => 'user_unionid', 'product_infos' => [ [ 'product_id' => 'product_001', 'sku_id' => 'sku_001', 'product_cnt' => 2, 'sale_price' => 9900, 'head_img' => '商品图片URL', 'title' => '商品标题', 'path' => 'pages/product/detail?id=123' ] ], 'pay_info' => [ 'pay_method' => '微信支付', 'pay_method_type' => 1, 'prepay_id' => 'prepay_id_xxx', 'prepay_time' => time() ], 'price_info' => [ 'order_price' => 19800, 'freight' => 1000, 'discounted_price' => 0, 'additional_price' => 0, 'additional_remarks' => '' ], 'delivery_info' => [ 'delivery_type' => 1, 'receiver_name' => '张三', 'detailed_address' => '详细地址', 'tel_number' => '13800138000', 'country' => '中国', 'province' => '北京市', 'city' => '北京市', 'town' => '朝阳区' ] ]; $result = $mall->order->add($orderData);

结构说明：

• product_infos：下单商品明细，sale_price为该 SKU 的成交单价（分）；
• pay_info：支付信息，prepay_method_type区分支付方式，prepay_id通常来自微信支付统一下单返回；
• price_info：整单金额拆分，order_price为订单总价、freight为运费、discounted_price为优惠金额、additional_price为加价金额（分）；
• delivery_info：收货信息，delivery_type指定配送方式，收货地址按国家/省/市/区四级填写。

5.2 更新订单状态

订单状态变更需要严格遵循微信小商店的状态机规范，action_type标识操作类型，action_remark为操作备注：

$params = [ 'order_id' => 'order_123', 'status' => 2, // 订单状态 'action_type' => 1, // 操作类型 'action_remark' => '操作备注' ]; $result = $mall->order->updateStatus($params);

5.3 批量获取订单

list方法按创建时间区间批量拉取订单，支持游标分页：首次调用last_index传空字符串，后续用上一次返回的分页标识继续翻页：

$params = [ 'start_create_time' => strtotime('-30 days'), 'end_create_time' => time(), 'last_index' => '', // 分页标识 'page_size' => 10 ]; $result = $mall->order->list($params);

六、媒体文件管理

商品头图、资质图片等素材需要先上传至微信服务器，获得media_id后才能在商品数据中引用，这也印证了「图片需要先上传到微信服务器」的注意事项。

6.1 上传图片

$result = $mall->media->uploadImg('/path/to/image.jpg');

6.2 获取图片

根据上传返回的media_id获取图片信息：

$result = $mall->media->getImg('media_id');

七、完整示例

下面把「初始化应用 → 导入商品 → 查询商品」串成一段可直接运行验证的完整流程：

use EasyWeChat\Factory; $config = [ 'app_id' => 'your-app-id', 'secret' => 'your-app-secret', // ... ]; $app = Factory::miniProgram($config); $mall = $app->mall; // 导入商品 $products = [ [ 'product_id' => 'test_product_001', 'title' => '测试商品', 'sub_title' => '这是一个测试商品', 'head_imgs' => ['https://example.com/img1.jpg'], 'category_id' => 1234, 'skus' => [ [ 'sku_id' => 'sku_001', 'price' => 9900, 'original_price' => 12900, 'status' => 1, 'stock_num' => 100 ] ] ] ]; $result = $mall->product->import($products); if ($result['errcode'] === 0) { echo "商品导入成功\n"; // 查询商品信息 $productInfo = $mall->product->query(['product_id' => 'test_product_001']); print_r($productInfo); }

关于返回值：SDK 底层由 AccessTokenAwareClient 负责在请求前注入 access_token，并在收到响应后按errcode与error字段判定成败；默认配置下返回数组（response_type => 'array'），因此可以直接用$result['errcode'] === 0判断业务是否成功。若配置了http.throw，业务失败时会抛出异常而非返回错误数组，具体可参考 src/MiniApp/Application.php 中createClient()的 failureJudge 逻辑。

八、注意事项

1. 金额单位：商品价格、订单金额等所有货币字段一律以分为单位（如9900表示 99 元），切勿直接使用元，否则会造成金额差 100 倍；
2. 图片素材：图片需要先通过mall->media->uploadImg()上传到微信服务器获取media_id，或直接使用 HTTPS URL，否则商品头图、资质图片无法生效；
3. 分类 ID：商品分类 ID（category_id等）需要从微信官方小商店类目体系获取，不同品类对应不同 ID，需要与平台方核对确认；
4. 订单状态流转：订单状态变更必须按照微信小商店的规范执行，非法状态跳转会报错，请务必在业务侧维护状态机；
5. 调用频率限制：微信小商店 API 有调用频率限制，批量操作（导入、批量拉单）时请合理控制调用频次，建议结合缓存与队列削峰。

九、小结

本文基于 docs/src/5.x/mini-program/mall.md 完整梳理了 EasyWeChat 小程序微信小商店的四个业务模块：商品（product）、购物车（cart）、订单（order）与媒体（media）。在实际项目中，建议按照「先上传媒体获取media_id→ 导入商品 → 用户加购 → 生成订单 → 按需更新订单状态」的链路组织业务代码，并始终牢记金额以分存储、分类 ID 以官方数据为准、订单状态严格按规范流转这三点核心约束。更多小程序模块（如business商户功能）可继续查阅 docs/src/5.x/mini-program 目录下的对应文档。

• 后端
• 即时通讯