企业官网建设流程全解析

做电商开发的同学肯定都懂，拿一份标准的商品详情数据有多折腾。官方没开放接口的时候，只能靠爬虫硬啃，页面结构一改，正则表达式就要跟着重写一遍；反爬策略一升级，整个采集任务直接趴窝。后来平台开放了API，状态才好了不少。我最近在做一个跨平台比价系统，需要稳定拉取多个平台的实时商品信息，其中就对接了Letian开放平台的商品详情API。这篇文章把整个调用流程、签名计算、代码实现和线上排障经验一次性讲透，代码可以直接抄进项目里改改用。文章里的Letian是笔者对接过的某个电商开放平台的API代号，下文统一这么称呼，方便叙述。

文章适合这几类人：正在对接电商开放平台的开发者、做商品同步和价格监控的工程师、准备把爬虫采集换成正规API的同学。读完你会知道这个接口的设计逻辑是什么、调用前要准备哪些东西、四种主流语言的代码怎么写、以及那些文档里绝对查不到的坑。

1. 别急着写代码，先看懂这个接口的门道

1.1 这个接口到底解决什么问题

商品详情API的核心价值就一句话：用标准化的方式，把平台侧的商品数据稳定地搬到你的系统里。听起来很简单，但实际落地会面对三个具体问题。

第一是数据一致性问题。自建商城或者ERP系统需要展示商品标题、主图、价格、库存、SKU信息，这些数据源头在平台那边。接口拉下来之后，你才能在自己的数据库里建一条记录，后续再通过增量更新保持同步。如果没有接口，靠手工导入Excel或者爬虫抓HTML页面，数据要么过时，要么解析出错，商品下架了你还不知道。

第二是实时性问题。价格监控类业务对实时性要求很高，别人改价了，你的比价系统最好在几分钟内感知到。接口的访问频率能做到秒级，而爬虫受限于反爬策略，采集一轮可能要几十分钟，根本没法比。

第三是稳定性和合规性。平台开放API，意味着你是以开发者身份在调用，数据获取方式是被平台认可和支持的。相比爬虫，接口不用担心页面改版、账号被封、验证码拦截这类问题，长期维护成本低很多。

我在项目中遇到的实际场景是这样的：每天需要同步全量商品信息和价格变动，如果全部走爬虫，单是IP的调度和反爬识别就够喝一壶。切换到接口之后，逻辑就变成了一个简单的轮询任务：查本地数据库，找出更新时间超过阈值的商品，调用详情接口拉取最新数据，更新落库。整个系统的复杂度一下子降下来了。

1.2 一次完整的API调用要经过哪几步

Letian商品详情API的调用链路并不复杂，但每一步都有讲究。完整流程如下：

1. 在开放平台注册开发者账号，创建应用，拿到AppKey和AppSecret。
2. 用AppKey和AppSecret换取access_token，这个token有有效期，通常两个小时。
3. 构造商品详情请求参数，包括app_key、access_token、timestamp、nonce、item_id、fields。
4. 对所有请求参数按ASCII码升序排序，拼接成字符串，用AppSecret做HMAC-SHA256签名。
5. 带上签名发起HTTP请求。
6. 服务端校验签名和时间戳，返回JSON格式的商品详情数据。
7. 客户端解析JSON，做数据标准化，落库或更新缓存。

这里的核心是两步：一是token的获取和管理，二是签名计算。签名算不对，其他什么都不用谈。我在后面会专门讲这两块。

你可能会问，既然已经有AppKey和AppSecret，为什么还要多一层access_token？因为AppSecret是长期有效的密钥，一旦泄露，后果不堪设想。access_token有效期短，服务端可以随时吊销，即使被截获，影响范围也可控。这是一种常见的授权模式，相当于你拿护照（AppKey+AppSecret）去柜台换一张临时通行证（access_token），然后凭通行证进出各个业务房间。

1.3 为什么是REST + JSON + HMAC这套组合

我在对接过程中观察了一下Letian的技术选型，说实话这套方案是业内最主流、综合成本最低的组合。

REST风格接口的优点是资源语义清晰。要获取商品详情，就是GET一个/item/detail资源，传唯一的item_id参数。相比SOAP那套动辄几百行的XML报文，REST的调试成本几乎为零，你在浏览器地址栏里都能直接发起请求。

JSON作为数据格式的好处更不用多说，解析方便、体积可控、结构化强。商品信息天然是层级结构，JSON能直接表达sku_list、images这类嵌套字段。响应里的价格、库存这些字段类型很清晰，不会像字符串数组那样需要人工判断。

HMAC-SHA256签名则是为了保证请求参数不被篡改。简单说，客户端和服务端共享一把密钥（AppSecret），客户端把所有参数按规则拼成一个字符串，用密钥做哈希运算，得到的摘要就是签名。服务端收到请求后，用同样的规则自己算一遍，比对结果。不一致，就说明参数在传输过程中被动过手脚。

这套组合相比私钥加密证书的方案简单，比裸的AppId方式安全得多。对大部分电商业务场景来说，安全等级已经足够，开发成本还很可控。

2. 调用前准备：密钥、令牌与签名计算

2.1 创建开发者应用，把密钥当密码管

对接Letian平台的第一步，是在开放平台后台注册账号，创建一个应用。应用创建成功后，你会拿到两个关键凭证：AppKey和AppSecret。

AppKey是应用的公开标识，相当于你的用户名，每次请求都要带上，服务端靠它识别是哪个应用在调用。AppSecret是私有密钥，只在签名和获取token时使用，永远不应该出现在客户端代码、日志或者前端页面里。

这里有几个我踩过的坑，提前提醒：

第一，AppSecret别硬编码在代码仓库里。哪怕是私有仓库，历史提交里也可能泄露。正确做法是放到环境变量、配置中心或者密钥管理服务里，部署时再注入。

第二，密钥泄露后要立即重置。曾经有同学把AppSecret提交到了公开仓库，几分钟内就被人刷了大量接口，账户直接被限流。重置密钥很快，但一条一条排查是谁泄露的就很痛苦。

第三，区分测试环境和生产环境的应用。最好创建两个应用，一个用测试环境的AppKey，一个用生产环境的，避免测试请求污染线上数据指标。

2.2 用AppKey/AppSecret换取并缓存access_token

获取access_token的接口路径是POST /router/v1/token，参数里除了app_key、timestamp、nonce之外，还有grant_type=client_credential，sign的计算规则和业务接口一样。

token的过期时间一般是7200秒。最省事的做法是每次请求前都重新获取token，但这样会把一半以上的请求浪费在换token上，既慢又容易被限流。更合理的做法是把token缓存起来，在内存或Redis里存储，带一个过期时间，在过期之前复用。

我通常建议用Redis缓存，原因很简单：如果服务是多实例部署的，内存缓存会导致每个实例各自持有一个token，而平台侧对token的并发刷新是有限制的，搞不好会触发限流。Redis是共享存储，所有实例拿同一个token，刷新频率可控得多。

获取token的示例代码用Python写大概是这个风格：

import hashlib import hmac import json import secrets import time import requests APP_KEY = "your_app_key" APP_SECRET = "your_app_secret" BASE_URL = "https://openapi.letian.example.com/router/v1" def sign(params: dict) -> str: query = "&".join(f"{k}={v}" for k, v in sorted(params.items())) return hmac.new( APP_SECRET.encode("utf-8"), query.encode("utf-8"), hashlib.sha256 ).hexdigest() def get_access_token(): params = { "app_key": APP_KEY, "grant_type": "client_credential", "timestamp": str(int(time.time())), "nonce": secrets.token_hex(8), } params["sign"] = sign(params) resp = requests.post(f"{BASE_URL}/token", json=params, timeout=5) result = resp.json() if result.get("code") != 0: raise Exception(f"获取token失败: {result}") return result["data"]["access_token"], result["data"]["expires_in"]

拿到token后，你在Redis里设置过期时间，建议设置为实际有效期的80%，比如7200秒就设5760秒，预留时间余量，避免在token刚好过期的那一秒并发刷新。

2.3 商品详情接口的关键参数对照表

Letian商品详情接口的路径是GET /router/v1/item/detail。参数分两部分：公共参数和业务参数。公共参数每个接口都有，业务参数是商品详情特有的。

这里有两个容易忽略的细节。

一个是item_id的类型。平台返回的item_id可能是纯数字，长度超过了JavaScript的Number安全范围，前端一用JSON.parse就变成了科学计数法，再传给后端就对不上了。我的建议是全程用字符串传递，接收端也用字符串存储，避免精度问题。

另一个是fields参数。如果只需要标题、价格、库存三个字段，就传fields=title,price,stock。这个参数能显著减少响应体大小，在批量拉取场景下能省不少流量。我后续测试过，只拉核心字段的响应体比全量字段小了将近60%。

2.4 签名是怎么算出来的，这里最容易错

签名算法是Letian这套接口的核心，也是实际对接中出现问题最多的地方。算法本身不复杂，就四步，但每一步都有细节。

第一步，把所有请求参数（sign本身除外）放进一个字典。注意是全部参数，包括app_key、access_token、timestamp、nonce、item_id、fields这些。

第二步，按参数名的ASCII码升序排序，不是按你业务逻辑的顺序。

第三步，把所有参数拼接成key=value&key=value的字符串。拼接时直接用原始值，不要做URL编码，不要转义空格。

第四步，以AppSecret为密钥，对拼接好的字符串做HMAC-SHA256计算，输出hex格式的小写字符串，作为sign的值。

我专门画一下参数排序的例子。假设请求参数是app_key=abc、nonce=xyz、timestamp=1730000000、item_id=123，排序之后就是app_key、item_id、nonce、timestamp，拼接结果是app_key=abc&item_id=123&nonce=xyz&timestamp=1730000000。

很多同学在这里犯的一个错误是，拼接前把参数值做了URL编码。比如某个商品标题里可能含有特殊符号，但你注意，签名用的字段原则上不会包含中文和特殊字符，item_id是数字，timestamp是数字，nonce是十六进制串，字段本身都是安全的。但如果你的业务参数引入了特殊字符，务必以服务端收到时的原始值为准来签名，而不是以请求发送前的编码值为准。

另一个高频错误是timestamp格式不统一。有的同学用毫秒级时间戳，有的用秒级，服务端校验失败就直接签名错误。Letian要求的是10位秒级时间戳，get_token的时候也是这个格式。

3. 完整代码实现：四种语言任你抄

3.1 Python版：十分钟跑通第一个详情接口

Python是我最常用的对接语言，requests库用起来顺手，签名逻辑也比较简洁。下面是一份可以直接拿来改造的完整代码。

import hashlib import hmac import secrets import time import requests APP_KEY = "your_app_key" APP_SECRET = "your_app_secret" BASE_URL = "https://openapi.letian.example.com/router/v1" def sign(params: dict) -> str: """生成请求签名，参数必须为字符串键值对""" encoded = {k: str(v) for k, v in params.items()} query = "&".join(f"{k}={encoded[k]}" for k in sorted(encoded)) return hmac.new( APP_SECRET.encode("utf-8"), query.encode("utf-8"), hashlib.sha256 ).hexdigest() def build_params(access_token: str, item_id: str, fields: str = "") -> dict: params = { "app_key": APP_KEY, "access_token": access_token, "timestamp": str(int(time.time())), "nonce": secrets.token_hex(8), "item_id": str(item_id), } if fields: params["fields"] = fields params["sign"] = sign(params) return params def get_item_detail(access_token: str, item_id: str, fields: str = "") -> dict: params = build_params(access_token, item_id, fields) resp = requests.get(f"{BASE_URL}/item/detail", params=params, timeout=10) result = resp.json() if result.get("code") != 0: raise Exception(f"API调用失败: code={result['code']}, msg={result.get('msg')}") return result["data"] # 使用示例 # token, expires = get_access_token() # data = get_item_detail(token, "123456789", "title,price,stock,sku_list")

需要注意，requests库在GET请求传参时会对参数值自动做URL编码，这个没问题，因为签名是基于原始值算的，编码发生在签名之后。你不需要自己手动构造query string。

我在生产环境里还会加一层超时控制。requests的timeout参数一定要设置，否则某个接口异常时连接挂起，线程池直接被拖垮。设成10秒已经足够，超时后根据业务情况决定重试还是跳过。

3.2 Java版：适合接进Spring Cloud服务

Java对接的代码稍微多一点，但逻辑完全一致。核心是签名方法，用javax.crypto.Mac实现HMAC-SHA256。下面的代码我已经把关键部分写完整了。

import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.util.Map; import java.util.TreeMap; public class LetianSigner { private final String appSecret; public LetianSigner(String appSecret) { this.appSecret = appSecret; } public String sign(Map<String, String> params) throws Exception { TreeMap<String, String> sorted = new TreeMap<>(params); StringBuilder sb = new StringBuilder(); for (Map.Entry<String, String> entry : sorted.entrySet()) { if (sb.length() > 0) { sb.append("&"); } sb.append(entry.getKey()).append("=").append(entry.getValue()); } Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec keySpec = new SecretKeySpec( appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(keySpec); byte[] raw = mac.doFinal(sb.toString().getBytes(StandardCharsets.UTF_8)); StringBuilder hex = new StringBuilder(); for (byte b : raw) { String h = Integer.toHexString(b & 0xff); if (h.length() == 1) { hex.append("0"); } hex.append(h); } return hex.toString(); } }

TreeMap会自动按key升序排序，相当于替代了Python里的sorted函数。后续用Spring的RestTemplate或者OkHttp发起GET请求时，把签名后的参数放到query里就行。注意token的管理最好交给Spring Cache或者RedisTemplate，不要放在实例变量里。

3.3 PHP版：在业务项目里用cURL直连

PHP项目对接接口通常直接用cURL扩展，一把梭。签名部分用ksort排序，配合hash_hmac函数，代码非常短。

function letian_sign(array $params, string $appSecret): string { ksort($params); $query = http_build_query($params); return hash_hmac('sha256', $query, $appSecret); } function letian_get_item_detail(string $accessToken, string $itemId, string $appKey, string $appSecret): array { $params = [ 'app_key' => $appKey, 'access_token' => $accessToken, 'timestamp' => (string) time(), 'nonce' => bin2hex(random_bytes(8)), 'item_id' => $itemId, ]; $params['sign'] = letian_sign($params, $appSecret); $ch = curl_init('https://openapi.letian.example.com/router/v1/item/detail?' . http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); if ($result['code'] !== 0) { throw new RuntimeException('API调用失败: ' . $result['msg']); } return $result['data']; }

这里要注意http_build_query默认会做URL编码，而签名时用的字符串必须是原始值。在这个例子中，各参数都是纯数字或字母，不涉及编码差异，所以没问题。如果你的业务参数中包含中文，就需要先按原始值拼接签名，再用http_build_query构造请求串。

3.4 Go版：并发拉取商品数据小工具

Go语言的优势在并发，适合写批量商品数据同步工具。签名的逻辑和前面一样，我直接给出完整的函数。

import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "sort" "strings" "time" "math/rand" "net/http" "net/url" "encoding/json" "io" "strconv" ) func Sign(params map[string]string, secret string) string { keys := make([]string, 0, len(params)) for k := range params { keys = append(keys, k) } sort.Strings(keys) var sb strings.Builder for i, k := range keys { if i > 0 { sb.WriteString("&") } sb.WriteString(k) sb.WriteString("=") sb.WriteString(params[k]) } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(sb.String())) return hex.EncodeToString(mac.Sum(nil)) } func GetItemDetail(accessToken string, itemId string, appKey string, appSecret string) (map[string]interface{}, error) { params := map[string]string{ "app_key": appKey, "access_token": accessToken, "timestamp": strconv.FormatInt(time.Now().Unix(), 10), "nonce": strconv.FormatInt(rand.Int63(), 16), "item_id": itemId, } params["sign"] = Sign(params, appSecret) query := url.Values{} for k, v := range params { query.Set(k, v) } req, _ := http.NewRequest("GET", "https://openapi.letian.example.com/router/v1/item/detail?"+query.Encode(), nil) client := &http.Client{Timeout: 10 * time.Second} resp, err := client.Do(req) if err != nil { return nil, err } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result map[string]interface{} if err := json.Unmarshal(body, &result); err != nil { return nil, err } if result["code"].(float64) != 0 { return nil, fmt.Errorf("API调用失败: %v", result) } return result["data"].(map[string]interface{}), nil }

用Go写并发拉取时，要特别关注token的刷新时机。把所有协程共享一个token，在一个地方维护token缓存，刷新时加锁，避免同一时间多个协程去换token。这个话题后面在坑点部分还会展开。

4. 响应解析、数据清洗与缓存落地

4.1 返回字段长什么样，怎么读

一次成功的详情接口调用，返回的JSON结构大致是这样的：

{ "code": 0, "msg": "ok", "data": { "item_id": "123456789", "title": "示例商品标题", "price": 9900, "original_price": 12900, "stock": 88, "sales": 10086, "category_id": "23-45", "images": [ "https://img.example.com/1.jpg", "https://img.example.com/2.jpg" ], "sku_list": [ { "sku_id": "1001", "spec": "黑色/加大", "price": 9900, "stock": 5 }, { "sku_id": "1002", "spec": "白色/加大", "price": 9900, "stock": 12 } ], "detail_url": "https://item.example.com/123456789.html", "created_at": "2025-05-01 12:00:00", "updated_at": "2025-06-01 18:30:00" } }

首先注意price字段，它是以分为单位的整数。9900表示99元，12900表示129元。这是电商API的标准做法，用整数避免浮点数在传输和存储过程中的精度问题。你自己在数据库里也建议用BIGINT存分，展示层再除以100转成元。

sku_list是数组，每个SKU有自己的价格和库存。如果一个商品有多个SKU，总库存并不一定等于各SKU库存之和，有的商品会有共享库存的设计，所以读取库存字段时要分清语义。我一般是信任接口返回的总库存字段，SKU库存只在需要展示规格时使用。

stock字段直接返回实时库存。但要注意，这个值在波动快的场景下可能有分钟级延迟，如果你做的是精确库存管理，还需要结合平台侧的发货回调或消息推送来及时扣减。如果只是做展示，这个值完全够用。

images数组按封面图到详情图的顺序排列，第一个通常是主图。如果你的前端只展示一张主图，取数组第一个元素即可。detail_url是商品在平台上的原始落地页链接，用于跳转或比价核对。

4.2 把平台数据变成自己的数据结构

接口返回的数据是JSON，你的业务数据结构不一定和它一致。我建议在落库之前做一层标准化转换，而不是直接把JSON整包塞进数据库。

下面是我在比价系统里用过的表结构，可以作为参考：

CREATE TABLE product_detail ( item_id VARCHAR(64) PRIMARY KEY, title VARCHAR(255) NOT NULL, price BIGINT NOT NULL, original_price BIGINT DEFAULT 0, stock INT DEFAULT 0, sales BIGINT DEFAULT 0, category_path VARCHAR(128), images JSON, sku_json JSON, detail_url VARCHAR(512), platform_updated_at DATETIME, local_updated_at DATETIME, KEY idx_updated_at (local_updated_at) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

几个设计思路说明一下。

item_id用VARCHAR而不是BIGINT，就是前面提到的精度问题。字符串类型在传输和展示时都不会变形，而且万一哪天平台切换了ID生成规则，字符串依然兼容。

images和sku_json直接存JSON类型，因为展示端基本是原样消费这两个字段，拆成单独的表反而增加联表复杂度。但如果你的业务需要对SKU做复杂的库存合并计算，那就需要拆一张sku子表。

local_updated_at用于标识本地数据的同步时间。做增量轮询时，你只需要找出local_updated_at距离当前时间超过N分钟的商品，逐个调用接口刷新即可。platform_updated_at则用于判断平台侧的数据是否变化，如果平台侧的值小于本地，说明数据没有更新，可以直接跳过写库，节省开销。

标准化映射的逻辑看起来是体力活，但我不建议省掉这一步。直接消费平台JSON的最大问题是，一旦平台调整字段名，你的所有下游逻辑都要跟着改。中间加一层自己的数据模型，平台侧的变动就被挡住了，改映射逻辑一处就好。

4.3 读多写少的场景，缓存策略怎么定

商品详情数据是典型的读多写少类型。同一个商品可能在短时间内被多个用户查看，每次都打到平台接口，一是慢，二是浪费配额。我一般建议加两层缓存。

第一层是本地内存缓存，适用于单机高并发场景。用Google Guava Cache或者Caffeine，配置过期时间5分钟，最大条目数控制在几万。请求进来时先查Caffeine，命中就直接返回，不触达平台。

第二层是Redis分布式缓存，适用于多实例部署场景。缓存的key可以设计成letian:item:{item_id}，value存JSON字符串，过期时间300秒。多个实例共享这份缓存，减少平台侧的压力。

def get_item_with_cache(item_id: str, fields: str = "title,price,stock,sku_list") -> dict: cache_key = f"letian:item:{item_id}" cached = redis.get(cache_key) if cached: return json.loads(cached) data = get_item_detail(access_token, item_id, fields) redis.set(cache_key, json.dumps(data, ensure_ascii=False), ex=300) return data

缓存的过期策略要看业务实时性要求。做纯展示，5分钟TTL没有问题。做价格监控，5分钟就太慢了，建议降到60秒，同时要接受平台侧配额消耗的上升。大促期间价格变动频繁，可以进一步缩短到30秒，但也要评估一下被限流的风险。

还需要考虑缓存击穿的问题。如果某个热点商品突然被大量访问，缓存里没有，所有请求都穿透到平台接口，平台侧的限流策略会立刻生效。解决办法是加一个分布式锁，让同一个item_id的请求只有一个去平台拉取数据，其他请求短暂阻塞后读取缓存。

5. 线上踩坑实录与排查清单

5.1 签名不一致：先查这三件事

签名错误是接入期最高频的问题，我接到过好几个同学的求助，最后定位到的原因千奇百怪。这里我根据经验整理了一个排查顺序。

第一，先确认为你签名拼接的字符串到底是什么。把拼好的字符串打出来，人工比对你发送的请求参数。很多时候问题出在漏了某个参数，比如fields为空时你把它省略了，但服务端要求空字段也要参与签名。

第二，检查参数值是否有类型变形。比如item_id在Python里是int，转字符串之前可能已经是123456789，但如果数据源本身是科学计数法，转出来就是一个奇怪的字符串。所有参数必须原样传递，中间不要做任何类型转换。

第三，确认是否做了URL编码后再签名。有一个经典的案例：商品标题中的某个字符被json序列化时转义成了unicode形式，结果签名用的字符串和服务端拿到的字符串不一样。我后来的习惯是，所有参与签名的参数值都直接用原始值，URL编码交给HTTP库处理。

5.2 token过期与并发刷新：一个隐蔽的坑

token过期这个问题本身很简单，但如果你的服务是多实例部署，就会遇到一个隐蔽的并发问题。

假设两个实例同时检查到token快过期了，各自发起一次刷新请求，结果后刷新的那个token把先刷新的顶掉了。此时第一个实例手里的token已经失效，但它不知道，继续用失效的token去调详情接口，就会收到401错误。更麻烦的是，频繁并发刷新会触发平台侧的限流策略，然后所有实例一起失败。

我建议的解决方式是在Redis里加一把分布式锁，只允许一个实例负责刷新token，刷新成功后写入Redis，其他实例等锁释放后直接从Redis读取新token。锁的过期时间设置10秒，token刷新本身只需要几百毫秒，足够。

5.3 被限流怎么办：退避与错峰

Letian平台的限流策略是按应用维度统计的，超过一定QPS就会返回42001错误。如果你批量同步大量商品，很容易触发。

我有一次在线下压测时，用Go并发拉了500个商品，瞬间触发了限流。当时的错误表现很有意思，不是所有请求都失败，而是失败比例随机分布，看起来像服务端不稳定，实际上是应用级别的QPS被限流了。

正确的处理方式是指数退避重试。第一次失败后等1秒再试，再失败等2秒，然后是4秒、8秒，最多重试3次。同时，批量任务里要对所有商品ID做错峰处理，比如按ID哈希分片，每个分片在不同时间点启动，避免所有请求集中在同一时刻。

def call_with_retry(item_id: str, max_retries: int = 3): wait_time = 1 for attempt in range(max_retries): try: return get_item_detail_with_cache(item_id) except RateLimitError: time.sleep(wait_time) wait_time *= 2 raise Exception(f"商品 {item_id} 重试多次仍然被限流")

如果你有多个应用实例，情况又复杂一些。平台侧的限流是应用维度，不管你有多少个Pod，总QPS不能超过阈值。所以要在代码里做一个本地信号量，控制单进程内的并发请求数，再用分布式限流控制总体流量。

5.4 几类容易忽略的数据类型坑

有一个我印象很深的案例，某同学用Java的Long类型接收item_id，然后传给前端，前端用JavaScript解析后精度丢失，再用这个值去查详情，返回商品不存在。后来排查了半天，才发现是精度问题。正确的做法是全链路用字符串传递ID。

另一个坑是字段类型浮动。平台返回的stock字段大部分情况是整数，但某个商品返回了null，你的代码如果直接做大于0的判断就会抛异常。我在解析时养成习惯，把所有可空字段都做默认值处理：stock默认0，sales默认0，price默认0。宁可展示时兜底，也不要让异常穿透到业务层。

还有一类踩得比较多的是时间字段。平台返回的created_at是"2025-06-01 18:30:00"这种格式，如果你存的字段是DATETIME，可以直接写入。但有些接口平台同时返回毫秒时间戳，你做比较前一定要统一单位。建议统一格式化为字符串存储，避免类型混用。

5.5 常见错误码速查表

最后把Letian商品详情API的常见错误码整理成一个速查表，方便你排查问题时快速定位。

40001和40003是最容易混淆的两个错误。40001说明签名校验通过了，但是token本身有问题；40003说明token没问题，但是签名内容不对。定位思路完全不同，先分清楚是哪个阶段的问题，再去查对应的环节。

在对接Letian商品详情API的过程中，我个人的体会是：这个接口本身不算复杂，真正花时间的是把它接入到你的业务架构里，让它稳定可靠地跑起来。把token管理好、把签名算对、把缓存策略设计好、把限流退避实现好，这四点做到位，整个系统就稳了。如果后续还有其他平台的商品接口需要对接，这套代码和思路基本上可以平移到大部分开放平台上，底层逻辑都是通用的。