Shopee商品数据API解析与Java实现
1. Shopee API接口概述与合规调用指南
Shopee作为东南亚领先的电商平台，其公开API为开发者提供了获取商品数据的合法途径。与直接爬取网页数据不同，API调用具有明确的权限控制和访问频率限制，更符合平台规则。在开始技术实现前，有几个关键点需要注意：
- robots协议限制：Shopee明确禁止爬虫抓取数据，其robots.txt文件显示
User-agent: * Disallow: /。这意味着任何绕过API直接抓取页面数据的行为都违反平台规则 - API调用频率：未认证的公开API通常有每分钟60次的请求限制，超过可能触发IP封禁
- 数据使用范围：获取的数据仅可用于技术研究，禁止用于商业爬虫或自动化下单等场景
实测发现，Shopee的API接口设计相对规范，返回数据为结构化JSON格式。以台湾站点为例，主要API端点包括：
- 分类树获取：
https://xiapi.xiapibuy.com/api/v4/pages/get_category_tree - 商品列表获取：
https://xiapi.xiapibuy.com/api/v4/search/search_items
重要提示：所有API调用都应当设置合理的间隔时间（建议至少1秒/次），避免对服务器造成过大压力。我在实际项目中测试发现，连续高频请求会导致HTTP 429错误。
2. 商品分类数据结构解析
Shopee采用两级分类体系，通过get_category_tree接口返回的JSON数据结构如下：
{ "data": { "category_list": [ { "catid": 11040766, "display_name": "女生衣著", "children": [ { "catid": 11042304, "display_name": "T恤" } ] } ] } }关键字段说明：
catid：分类唯一标识，商品列表查询需使用二级分类IDparent_catid：父分类ID，一级分类该值为0level：分类层级（1或2）display_name：分类显示名称
通过Java解析时，推荐使用FastJSON处理嵌套结构。这里有个实际开发中的坑点：部分分类的children字段可能为null而非空数组，需要特别处理NPE异常。
3. 商品列表接口参数详解
获取商品列表的核心接口是search_items，其请求参数需要特别注意：
String url = "https://xiapi.xiapibuy.com/api/v4/search/search_items" + "?by=relevancy" + "&fe_categoryids=" + categoryId + "&limit=60" + // 每页记录数 "&newest=" + (pageIndex * 60) + // 偏移量 "&order=desc" + "&page_type=search" + "&scenario=PAGE_OTHERS" + "&version=2";参数说明表：
| 参数名 | 必填 | 示例值 | 说明 |
|---|---|---|---|
| fe_categoryids | 是 | 11042304 | 二级分类ID |
| limit | 是 | 60 | 固定每页60条 |
| newest | 是 | 0 | 偏移量计算规则：(页码-1)*60 |
| scenario | 是 | PAGE_OTHERS | 固定值勿修改 |
| version | 是 | 2 | API版本号 |
返回数据中最有用的item_basic对象包含：
itemid：商品唯一IDname：商品标题price：价格（需除以100000）historical_sold：历史销量image：主图URL
4. 完整Java实现代码
以下是增强版的Java实现，增加了异常处理和速率控制：
import java.io.IOException; import java.util.concurrent.TimeUnit; import org.jsoup.Connection.Method; import org.jsoup.Jsoup; import com.alibaba.fastjson.JSON; import com.alibaba.fastjson.JSONArray; import com.alibaba.fastjson.JSONObject; public class ShopeeApiClient { private static final String CATEGORY_API = "https://xiapi.xiapibuy.com/api/v4/pages/get_category_tree"; private static final String ITEMS_API = "https://xiapi.xiapibuy.com/api/v4/search/search_items"; private static final int MAX_PAGES = 100; private static final int DELAY_MS = 1500; // 1.5秒间隔 public static void main(String[] args) { try { JSONArray categories = fetchCategories(); processCategories(categories); } catch (Exception e) { System.err.println("程序异常终止: " + e.getMessage()); } } private static JSONArray fetchCategories() throws IOException { String result = Jsoup.connect(CATEGORY_API) .ignoreContentType(true) .method(Method.GET) .timeout(30000) .execute() .body(); return JSON.parseObject(result) .getJSONObject("data") .getJSONArray("category_list"); } private static void processCategories(JSONArray categories) { for (int i = 0; i < categories.size(); i++) { JSONObject parentCat = categories.getJSONObject(i); System.out.printf("处理分类: %s (%s)%n", parentCat.getString("display_name"), parentCat.getString("catid")); JSONArray children = parentCat.getJSONArray("children"); if (children == null || children.isEmpty()) continue; for (int j = 0; j < children.size(); j++) { processSubCategory(children.getJSONObject(j)); } } } private static void processSubCategory(JSONObject subCat) { String catId = subCat.getString("catid"); System.out.printf(" 处理子分类: %s (%s)%n", subCat.getString("display_name"), catId); for (int page = 0; page < MAX_PAGES; page++) { try { TimeUnit.MILLISECONDS.sleep(DELAY_MS); JSONArray items = fetchItems(catId, page); if (items == null || items.isEmpty()) break; System.out.printf(" 第%d页获取到%d个商品%n", page + 1, items.size()); processItems(items); } catch (Exception e) { System.err.printf("处理页面%d出错: %s%n", page, e.getMessage()); break; } } } private static JSONArray fetchItems(String catId, int page) throws IOException { String url = String.format("%s?by=relevancy&fe_categoryids=%s&limit=60&newest=%d&order=desc&page_type=search&scenario=PAGE_OTHERS&version=2", ITEMS_API, catId, page * 60); String response = Jsoup.connect(url) .ignoreContentType(true) .timeout(30000) .execute() .body(); return JSON.parseObject(response).getJSONArray("items"); } private static void processItems(JSONArray items) { for (int i = 0; i < items.size(); i++) { JSONObject item = items.getJSONObject(i) .getJSONObject("item_basic"); System.out.printf(" [%d] %s - %.2f元%n", item.getLong("itemid"), item.getString("name"), item.getLong("price") / 100000.0); } } }代码优化点说明：
- 增加了1.5秒的请求间隔，符合API限制
- 使用更清晰的方法拆分各处理逻辑
- 添加了空数据检查和异常处理
- 价格显示格式化为两位小数
- 输出日志更友好直观
5. 常见问题与调试技巧
在实际对接过程中，可能会遇到以下典型问题：
问题1：返回数据为空
- 检查分类ID是否正确（必须使用二级分类ID）
- 确认页码计算正确（newest参数=(页码-1)*60）
- 某些分类可能确实没有商品
问题2：连接超时
- 适当增加timeout值（示例代码设置为30秒）
- 添加重试机制（建议最多3次）
问题3：HTTP 429错误
- 降低请求频率（增加DELAY_MS值）
- 使用代理IP轮询（需谨慎，避免滥用）
调试建议：
- 先用Postman测试API接口，确认参数组合有效
- 打印完整响应数据，检查错误信息字段
- 对大数据量处理时，添加进度日志输出
// 示例调试代码：打印原始响应 System.out.println("原始响应: " + response.substring(0, Math.min(200, response.length())));6. 性能优化与扩展建议
对于需要大规模采集的场景，可以考虑以下优化方案：
- 多线程优化：
ExecutorService executor = Executors.newFixedThreadPool(5); executor.submit(() -> processSubCategory(subCat));- 数据存储优化：
- 使用数据库批量插入代替逐条处理
- 考虑使用Spring Batch处理海量数据
- 断点续采：
- 将已采集的categoryId和pageIndex持久化
- 程序重启时从上次中断处继续
- 代理池管理：
- 使用Luminati等专业代理服务
- 实现自动IP切换机制
- 数据更新策略：
- 记录商品最后更新时间
- 增量更新而非全量采集
7. 法律合规与最佳实践
在开发过程中务必注意：
- 严格遵守Shopee的API使用条款
- 禁止绕过限制进行高频访问
- 数据不得用于商业爬虫或恶意竞争
- 建议添加用户代理标识：
Jsoup.connect(url) .userAgent("MyResearchApp/1.0 (contact@example.com)") ...我在实际项目中的经验是，保持透明合规的使用态度，必要时可以联系Shopee官方申请正式的API权限。曾经因为测试时忘记加延迟，导致IP被临时封禁，后来通过控制请求频率就再未出现问题。