淘宝超市卡 TopAPI 接入实战：基于 Spring Boot 与 Lombok 的完整实现

三、项目架构设计

3.1 分层架构

采用标准的分层模式，确保职责清晰：

• Controller：接收 HTTP 请求，参数校验
• Service：业务逻辑处理，事务控制
• Config：配置类，如客户端初始化
• DTO：数据传输对象
• Exception：自定义异常处理

3.2 核心类设计

首先定义配置类来初始化淘宝客户端，这里利用 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);
    }
}

服务接口定义业务契约：

public interface SupermarketCardService {
    TradeInfoResponse getTradeInfo(TradeInfoRequest request);
    void buyCard(BuyCardRequest request);
    FetchCardResponse fetchCard(FetchCardRequest request);
    void bindCard(BindCardRequest request);
}

四、核心功能实现

4.1 获取虚拟用户 ID

获取虚拟用户 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();
            // 假设虚拟 ID 映射为买家昵称，实际需根据文档确认字段
            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);
    }
}

4.2 购买超市卡

购买接口需要校验入参，例如面值必须大于 0。

@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();
}

4.3 查询卡密信息

查询后通常需要对加密密码进行解密，这里涉及 RSA 处理。

@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());
            
            // 使用 RSA 私钥解密
            if (StringUtils.isNotBlank(response.getEncryptedPwd())) {
                result.setDecryptPwd(rsaDecrypt(response.getEncryptedPwd()));
            }
            return result;
        } else {
            throw new ApiException(response.getSubCode(), response.getSubMsg());
        }
    } catch (Exception e) {
        throw new RuntimeException("获取卡密失败", e);
    }
}

4.4 绑定超市卡到用户

将卡片关联到特定用户，注意异常捕获。

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

// 实现类
@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);
    }
}

五、安全与加密处理

5.1 RSA 加密配置

根据淘宝规范，敏感数据（如卡密）传输需经过 RSA 加密。配置类负责加载私钥并处理解密逻辑。

@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);
        }
    }
}

5.2 异常统一处理

全局异常处理器能避免前端收到堆栈信息，提升安全性。

@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;
    }
}

六、完整业务流程测试

6.1 测试类实现

集成测试覆盖核心链路，确保各步骤衔接正常。

@SpringBootTest
@Slf4j
class SupermarketCardIntegrationTest {
    @Autowired
    private SupermarketCardService service;

    @Test
    @Order(1)
    void testGetTradeInfo() {
        TradeInfoRequest request = new TradeInfoRequest();
        request.setTid(123456789L);
        TradeInfoResponse response = service.getTradeInfo(request);
        assertNotNull(response.getVirtualUserId());
        log.info("获取虚拟用户 ID 成功：{}", response.getVirtualUserId());
    }

    @Test
    @Order(2)
    void testBuyCard() {
        BuyCardRequest request = new BuyCardRequest();
        request.setVirtualUserId("test_user_001");
        request.setParValue(2L);
        assertDoesNotThrow(() -> service.buyCard(request));
        log.info("购买超市卡成功");
    }

    @Test
    @Order(3)
    void testFetchCard() {
        FetchCardRequest request = new FetchCardRequest();
        request.setPurchaseOrderId(987654321L);
        FetchCardResponse response = service.fetchCard(request);
        assertNotNull(response.getCardNo());
        log.info("获取卡密成功，卡号：{}", response.getCardNo());
    }

    @Test
    @Order(4)
    void testBindCard() {
        BindCardRequest request = new BindCardRequest();
        request.setVirtualUserId("test_user_001");
        request.setCardNo("1234567890");
        assertDoesNotThrow(() -> service.bindCard(request));
        log.info("绑定超市卡成功");
    }
}

6.2 测试数据准备

在 application-test.properties 中隔离配置测试环境数据：

# 测试商品
test.card.par-value=2
# 测试用户
test.user.virtual-id=test_user_001

七、部署与上线注意事项

1. 权限申请：提前在开放平台申请好 API 调用权限。
2. 监控报警：对 API 调用失败率建立监控机制，及时告警。
3. 性能优化：考虑加入缓存机制减少重复 API 调用。
4. 环境切换：确保测试环境和生产环境使用不同的配置，避免误操作。

# 测试环境
top.api.url=http://pre-gw.api.taobao.com/top/router/rest
# 生产环境
top.api.url=http://gw.api.taobao.com/router/rest

八、常见问题解决方案

8.1 虚拟用户 ID 获取失败

现象：调用 taobao.trade.fullinfo.get 接口返回空值。

排查：

1. 检查交易 ID 是否正确且有效。
2. 确认 API 权限是否已开通。
3. 验证 AppKey 和 AppSecret 是否与当前应用匹配。

8.2 卡密解密失败

现象：RSA 解密返回乱码或报错。

排查：

1. 确认使用的私钥与提供给淘宝的公钥是否匹配。
2. 检查加密算法是否为 RSA256。
3. 验证 Base64 解码过程是否正确。

8.3 API 调用频率限制

现象：返回 "API 调用频率超限" 错误。

对策：

1. 实现请求限流控制，避免突发流量。
2. 加入适当的重试机制（注意幂等性）。
3. 考虑使用异步处理非实时请求。

结语

通过上述步骤，我们完成了淘宝超市卡 TopAPI 的完整接入实现。从环境准备到核心功能开发，再到安全处理和测试验证，涵盖了 API 接入的全流程。这种实现方式不仅适用于超市卡业务，也可以作为其他淘宝 API 接入的参考模板。

在实际项目中，还需要根据具体业务需求进行调整和优化，例如加入分布式锁防止重复操作、实现更完善的日志监控等。希望本文能为开发者接入淘宝生态 API 提供有价值的参考。