三方服务API接口响应说明

我司通道服务里调用的一个三方服务商，其响应结构如下：

这个标准化响应格式，大家都比较熟悉。正常响应时，code=200，并将数据结果放到data里。非正常响应时，code是非200的错误码，data为空。

• 示例：

错误响应示例：

{"code": 400, "message": "手机号格式不正确"}

{"code":404,"data":null,"message":"订单不存在"}

正确响应示例：

{
 "code": 200,
 "data": {
 "orderId": "ORD20250720001",
 "status": "已支付",
 "amount": 299.00
 },
 "message": "订单查询成功"
}

{"code":200,"message":"用户签约成功"}

与之对应，我们程序里定义了相应的模型类：

@Data
public class SanHeCommonResponse<T> implements Serializable {
 /** 业务响应的code 码（非HTTP 状态码） */
 private Integer code;
 /** 返回值的状态描述 */
 private String message;
 
 /** 业务数据，具体的字段内容参考各个API 接口的返回值 */
 private T data;
 // 判断响应是否成功（code为200时表示成功）
 public boolean isSuccess(){
 return code == 200;
 }
}

三方服务底层调用封装——execute方法及实现

三方服务API对接层中，我们将数据加密/签名、http通信、验签/数据解密等通用性功能封装在底层，见下面的execute方法如下。注意，后面我们重点要谈针对这个方法的重构。

/**
 * 安**宇服务商接口通信（含请求及响应）封装
 */
public static SanHeCommonResponse execute(NewSanHeApiEnum apiEnum, String token) {
 SanHeCommonRequest requestBody = new SanHeCommonRequest();
 requestBody.setNonceStr(RandomUtil.randomString(10));
 requestBody.setData...
 JSONObject requestParams = JSON.parseObject(JSON.toJSONString(requestBody));
 HttpEntity<Object> requestEntity;
 HttpHeaders headers = new HttpHeaders();
 headers.add("x-access-token", token);
 requestEntity = new HttpEntity<>(requestParams, headers);
 RestTemplate restTemplate = new RestTemplate();
 String body;
 try {
 url = url.concat(apiEnum.getUrl());
 ResponseEntity<String> response = restTemplate.exchange(API_URL, HttpMethod.POST, requestEntity, String.class);
 body = response.getBody();
 } catch (Exception ex) {
 log.error("安**宇接口调用异常：", ex);
 throw BizException.build("接口调用异常");
 }
 SanHeCommonResponse sanHeCommonResponse = JSON.parseObject(body, SanHeCommonResponse.class);
 if (!sanHeCommonResponse.isSuccess()) {
 throw BizException.build(sanHeCommonResponse.getCode(), sanHeCommonResponse.getMessage());
 }
 return sanHeCommonResponse;
}

execute方法返回值重构

OOP程序设计的一个重要思想是明确对象的职责。

针对这种三方服务对接的需求场景，我们需要把握好一个设计理念：将三方服务调用涉及的数据加密/签名、http通信、验签/数据解密等通用性功能封装在底层，使上层的接口处理方法专注于接口数据的逻辑处理。

这个execute方法在返回值方面存在的问题是：调用方需要通过SanHeCommonResponse.data获取并转换为实际业务数据，这增加了编码成本。

SanHeCommonResponse response = execute(API_ORDER, token);
if (!response.isSuccess()) {
 throw new BizException("查询失败");
}
OrderResponse data = JSON.parseObject(response.getData().toString(), OrderResponse.class);

针对返回值方面的这个问题，重构结果如下：

/**
 * 安**宇服务商接口通信（含请求及响应）封装
 */
public static <T> T SanHeCommonResponse execute(NewSanHeApiEnum apiEnum, String token, Class<T> clazz) {
 ...
 
 SanHeCommonResponse<JSONObject> sanHeCommonResponse = JSON.parseObject(body, new TypeReference<SanHeCommonResponse<JSONObject>>(){});//用`new TypeReference<SanHeCommonResponse<JSONObject>>(){}`来解析带有泛型的响应, 避免IDE类型转换警告。
 if (!sanHeCommonResponse.isSuccess()) {
 throw BizException.build(sanHeCommonResponse.getCode(), sanHeCommonResponse.getMessage());
 }
 return Optional.ofNullable(sanHeCommonResponse.getData())
 .orElse(new JSONObject())
 .toJavaObject(clazz);
}

这时，上层调用直接一行代码搞定：

OrderResponse data = execute(API_ORDER, token, OrderResponse.class);

重构的目的是使方法更通用，能够直接返回业务数据对象，而不是整个SanHeCommonResponse对象。通过使用泛型，让调用者可以指定期望返回的业务数据类型，将类型安全性提前至编译期，有效增强程序健壮性。