Spring Boot 接入淘宝猫超卡 TopAPI 经验记录

另外 application.yml 要配好 top.api.url、top.api.appkey、top.api.appsecret，以及 RSA 私钥。

客户端初始化

把 DefaultTaobaoClient 交给 Spring 容器管理：

@Configuration
public class TopApiConfig {
    @Bean
    public TaobaoClient taobaoClient(
            @Value("${top.api.url}") String url,
            @Value("${top.api.appkey}") String appKey,
            @Value("${top.api.appsecret}") String appSecret) {
        return new DefaultTaobaoClient(url, appKey, appSecret);
    }
}

足够简单，后面 service 直接注入 TaobaoClient 调接口。

核心接口实现

我先建了个 service 接口，然后逐步实现。

获取虚拟用户 ID

这一步需要订单号，拿到买家信息后才能继续发卡。

@Override
public TradeInfoResponse getTradeInfo(TradeInfoRequest request) {
    TradeFullinfoGetRequest req = new TradeFullinfoGetRequest();
    req.setTid(request.getTid());
    try {
        TradeFullinfoGetResponse response = taobaoClient.execute(req);
        if (response.isSuccess()) {
            TradeInfoResponse result = new TradeInfoResponse();
            // 文档里 buyerNick 映射为虚拟用户 ID，线上实际字段可能叫 somethingElse
            result.setVirtualUserId(response.getBuyerNick());
            result.setTradeStatus(response.getStatus());
            return result;
        } else {
            log.error("获取交易信息失败：{}", response.getSubMsg());
            throw new ApiException(response.getSubCode(), response.getSubMsg());
        }
    } catch (ApiException e) {
        log.error("调用淘宝 API 异常", e);
        throw new RuntimeException("调用淘宝 API 异常", e);
    }
}

购买卡

入参校验用 @Valid 和 Bean Validation，面值必须大于 0，用户 ID 不能空。

@Data
public class BuyCardRequest {
    @NotBlank(message = "虚拟用户 ID 不能为空")
    private String virtualUserId;
    @Min(value = 1, message = "面值必须大于 0")
    private Long parValue;
    private boolean needBindUser = false;
}

@PostMapping("/buy")
public ResponseEntity<?> buyCard(@Valid @RequestBody BuyCardRequest request) {
    supermarketCardService.buyCard(request);
    return ResponseEntity.ok().build();
}

service 里直接用 TmallPurchaseCardBuyRequest 拼参数调用，成功与否就看 response。

查询卡密并解密

查回来的密码是 RSA 加密的，需要用商户私钥解密。我单独配了个 RsaConfig：

@Configuration
public class RsaConfig {
    @Value("${rsa.private-key}")
    private String privateKey;

    @Bean
    public RSA rsa() {
        return new RSA(privateKey, null);
    }

    public String rsaDecrypt(String encryptedText) {
        try {
            return new String(rsa().decrypt(encryptedText, KeyType.PrivateKey));
        } catch (Exception e) {
            throw new RuntimeException("RSA 解密失败", e);
        }
    }
}

然后在 fetchCard 里调用：

@Override
public FetchCardResponse fetchCard(FetchCardRequest request) {
    TmallPurchaseCardFetchRequest req = new TmallPurchaseCardFetchRequest();
    req.setPurchaseOrderId(request.getPurchaseOrderId());
    try {
        TmallPurchaseCardFetchResponse response = taobaoClient.execute(req);
        if (response.isSuccess()) {
            FetchCardResponse result = new FetchCardResponse();
            result.setCardNo(response.getCardNo());
            result.setEncryptedPwd(response.getEncryptedPwd());
            if (StringUtils.isNotBlank(response.getEncryptedPwd())) {
                result.setDecryptPwd(rsaConfig.rsaDecrypt(response.getEncryptedPwd()));
            }
            return result;
        } else {
            throw new ApiException(response.getSubCode(), response.getSubMsg());
        }
    } catch (Exception e) {
        throw new RuntimeException("获取卡密失败", e);
    }
}

绑定卡

最后一步，把卡号和虚拟用户 ID 传给 bind 接口：

@PostMapping("/bind")
public ResponseEntity<?> bindCard(@Valid @RequestBody BindCardRequest request) {
    supermarketCardService.bindCard(request);
    return ResponseEntity.ok().build();
}

// service 实现
@Override
public void bindCard(BindCardRequest request) {
    TmallPurchaseCardBindRequest req = new TmallPurchaseCardBindRequest();
    req.setCardNo(request.getCardNo());
    req.setVirtualUserId(request.getVirtualUserId());
    try {
        TmallPurchaseCardBindResponse response = taobaoClient.execute(req);
        if (!response.isSuccess()) {
            throw new ApiException(response.getSubCode(), response.getSubMsg());
        }
    } catch (ApiException e) {
        throw new RuntimeException("绑定超市卡失败", e);
    }
}

异常处理

用 @RestControllerAdvice 兜底，避免堆栈信息直接丢给前端：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ApiException.class)
    public ResponseEntity<ErrorResponse> handleApiException(ApiException e) {
        ErrorResponse response = new ErrorResponse("API_ERROR", "淘宝 API 调用失败：" + e.getMessage());
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
    }

    @Data
    @AllArgsConstructor
    public static class ErrorResponse {
        private String code;
        private String message;
    }
}

测试与部署注意事项

我写了个集成测试把主要流程串了一遍，确保从取 ID 到绑定都能走通。测试时记得用 application-test.properties 隔离配置，别把真钱花了。

部署上线前这几件事最好做一下：

• 在开放平台确认所有 API 权限已开通。
• 监控 API 调用失败率，尤其下单接口报错要及时告警。
• 测试环境和生产环境的网关域名得分开，防止误操作：测试用 pre-gw.api.taobao.com，线上用 gw.api.taobao.com。
• 如果并发量大，考虑加缓存和限流，避免频率超限。

踩过的几个坑

• 虚拟用户 ID 为空：很可能订单号无效或者权限没开全，先检查 taobao.trade.fullinfo.get 的返回值。
• RSA 解密报错或乱码：公钥私钥不匹配最常见，确认提供给淘宝的公钥和本地私钥是一对，算法用 RSA256，Base64 解码也要核对。
• 频率限制：碰到超限错误，除了限流，还可以在业务上做异步处理，非实时发放的卡片扔队列慢慢发。

整体来说，淘宝这套 API 还算规范，就是文档更新不太及时，有些字段名可能会变。上面的代码大多能直接复用，但实际接的时候还是以官方最新文档为准，尤其是字段映射。