淘宝超市卡 TopAPI 接入实战：Spring Boot + Lombok 实现方案

三、项目架构设计

分层架构

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

• Controller：接收 HTTP 请求，参数校验
• Service：处理核心业务逻辑
• Config：配置类，管理客户端与加密组件
• DTO：数据传输对象
• Exception：自定义异常处理

核心类设计

首先配置淘宝客户端，将密钥注入到 Bean 中：

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

四、核心功能实现

获取虚拟用户 ID

通过交易详情接口获取买家昵称作为虚拟 ID。注意处理 API 返回的异常状态：

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

购买超市卡

使用 DTO 接收前端请求，结合 Lombok 注解简化实体类：

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

查询卡密信息

获取订单后需解密卡密。这里要注意 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);
    }
}

绑定超市卡到用户

将已购买的卡绑定到指定虚拟用户，完成闭环：

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

五、安全与加密处理

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

异常统一处理

全局异常处理器能避免 Controller 层重复代码，保证返回格式一致：

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

六、完整业务流程测试

集成测试示例

使用 JUnit 5 编写集成测试，按顺序验证各个步骤：

@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("绑定超市卡成功");
    }
}

测试数据准备

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

# 测试商品配置
test.card.par-value=2
# 测试用户 ID
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

八、常见问题解决方案

虚拟用户 ID 获取失败

• 现象：调用 taobao.trade.fullinfo.get 接口返回空值。
• 排查：检查交易 ID 是否正确；确认 API 权限是否已开通；验证 AppKey 和 AppSecret 是否匹配当前应用。

卡密解密失败

• 现象：RSA 解密返回乱码或报错。
• 排查：确认使用的私钥与提供给淘宝的公钥匹配；检查加密算法是否为 RSA256；验证 Base64 解码是否正确。

API 调用频率限制

• 现象：返回 "API 调用频率超限" 错误。
• 排查：实现请求限流控制；加入适当的重试机制；对于非实时请求，考虑使用异步处理。

结语

通过上述流程，我们完成了淘宝超市卡 TopAPI 的完整接入实现。从环境搭建、核心功能开发，到安全处理和测试验证，这套方案涵盖了 API 接入的全生命周期。这种实现模式不仅适用于超市卡业务，也可作为其他淘宝 API 接入的参考模板。实际项目中，建议根据具体需求进一步调整，例如引入分布式锁防止重复扣款、完善日志监控体系等。希望这份指南能为开发者对接淘宝生态提供切实帮助。