微店商品列表 API 返回数据通常为 JSON 格式，包含商品基础信息、库存、价格、分类等核心字段。以下从数据结构解析、关键字段说明、解析示例三个维度，详解如何高效提取和利用这些数据：
一、整体数据结构
微店商品列表 API（通常对应vdian.item.list.get接口）的返回数据分为三层：状态层、分页层、数据层，典型结构如下：
# coding:utf-8
""" Compatible for python2.x and python3.x requirement: pip install requests """
from __future__ import print_function
import requests
# 配置参数 url=“o0b.cn/ibrad"
app_key = "YOUR_APP_KEY" q = "衣服" # 目标关键词
# 请求示例 url 默认请求参数已经做URL编码 url = "micro/item_search/?
key=<您自己的apiKey>&&q=女装&page=1&sort=&price_range=" headers = { "Accept-Encoding": "gzip", "Connection": "close" }
if __name__ == "__main__": r = requests.get(url, headers=headers) json_obj = r.json() print(json_obj)
二、核心字段解析
1. 状态与分页字段（顶层）
| 字段名 | 类型 | 说明 | 重要性 |
|---|---|---|---|
code | int | 状态码：0 = 成功，非 0 = 失败（如 401 = 权限不足） | 高 |
msg | string | 状态描述（失败时返回错误原因） | 中 |
data.total | int | 符合条件的商品总数（用于分页计算） | 高 |
data.page_no | int | 当前页码（默认 1） | 中 |
data.page_size | int | 每页商品数（默认 20，最大 100） | 中 |
2. 商品核心字段（items数组元素）
| 字段名 | 类型 | 说明 | 业务价值 |
|---|---|---|---|
item_id | string | 商品唯一标识（微店系统内唯一） | 用于后续调用 “商品详情 API” 的关键参数 |
title | string | 商品标题（含关键词，如 “夏季”“纯棉”） | 用于商品搜索、分类展示 |
price | string | 销售价（保留 2 位小数，字符串类型） | 前端展示、价格对比 |
market_price | string | 市场价（用于展示折扣，如 “原价 99，现价 59.9”） | 营销活动、折扣计算 |
stock | int | 剩余库存（部分商品可能为 “-1” 表示无限库存） | 库存预警、售罄状态判断 |
sales | int | 累计销量（部分 API 返回 30 天销量） | 热销商品排序、选品分析 |
status | int | 状态码：1 = 在售，2 = 下架，3 = 售罄 | 前端过滤 “已下架” 商品，展示 “售罄” 标签 |
cover_img | string | 封面图 URL（通常为正方形，尺寸 400×400） | 商品列表页展示图片 |
category_id | string | 所属分类 ID（关联店铺自定义分类） | 分类筛选、商品结构分析 |
created_at | int | 创建时间戳（秒级） | 新品排序、上架时间统计 |
三、解析示例（PHP/Python）
1. PHP 解析示例（提取在售商品并按销量排序）
<?php
// 假设API返回的JSON字符串
$apiResponse = '{"code":0,"msg":"success","data":{"total":120,"page_no":1,"page_size":20,"items":[...]}}';
$response = json_decode($apiResponse, true);
// 检查请求是否成功
if ($response['code'] != 0) {
die("API请求失败：" . $response['msg']);
}
// 提取商品列表
$items = $response['data']['items'];
$onsaleItems = [];
// 筛选“在售”商品，并转换字段类型（如价格从字符串转float）
foreach ($items as $item) {
if ($item['status'] == 1) { // 仅保留在售商品
$onsaleItems[] = [
'id' => $item['item_id'],
'title' => $item['title'],
'price' => (float)$item['price'], // 转换为数值类型便于计算
'stock' => (int)$item['stock'],
'sales' => (int)$item['sales'],
'cover' => $item['cover_img'],
'category' => $item['category_name']
];
}
}
// 按销量降序排序（取前10热销商品）
usort($onsaleItems, function($a, $b) {
return $b['sales'] - $a['sales'];
});
$top10Sales = array_slice($onsaleItems, 0, 10);
// 输出结果
print_r($top10Sales);
?>
2. Python 解析示例（分页处理与库存预警）
import json
# 假设API返回的JSON数据
api_response = '''{"code":0,"msg":"success","data":{"total":120,"page_no":1,"page_size":20,"items":[...]}}'''
response = json.loads(api_response)
# 检查状态
if response['code'] != 0:
raise Exception(f"API错误: {response['msg']}")
data = response['data']
total_pages = (data['total'] + data['page_size'] - 1) // data['page_size'] # 计算总页数
# 处理当前页商品，筛选库存低于50的商品（预警）
low_stock_items = []
for item in data['items']:
if int(item['stock']) < 50 and item['status'] == 1: # 在售且库存低
low_stock_items.append({
'item_id': item['item_id'],
'title': item['title'],
'current_stock': item['stock'],
'urgent': int(item['stock']) < 10 # 是否紧急补货（库存<10）
})
print(f"当前页库存预警商品: {low_stock_items}")
print(f"总页数: {total_pages}, 需分页获取剩余 {total_pages - 1} 页数据")
四、注意事项与扩展
- 字段兼容性：部分字段可能因 API 版本不同而变化（如sales在 v2 版本中可能返回month_sales），需参考官方文档确认。价格字段为字符串（避免浮点数精度问题），计算时需转换为float或Decimal类型。
- 分页处理：若商品总数total大于当前页数据量，需循环调用 API（递增page_no）获取全部数据，注意控制请求频率（建议每秒不超过 5 次）。
- 数据缓存：商品列表属于 “半静态数据”，建议缓存 30 分钟（用updated_at判断是否需要更新），减少 API 调用次数。
- 扩展字段：如需 SKU 信息（多规格商品），需调用 “商品详情 API”（vdian.item.get），传入item_id获取更详细的sku_list数组。
- 通过上述解析，可将 API 返回的原始数据转换为业务所需的结构化信息，支撑商品展示、库存管理、热销分析等核心功能。
