diff --git a/README.md b/README.md index ff6098c..2357bb2 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,15 @@ Rest Proxy组件是本人在长期的系统对接工作中提炼出的一个可 具体请查看开源仓库:https://git.flyfish.group/flyfish-group/rest-proxy.git 然后demo的话请切换到`example`分支。 +请使用maven引入依赖 +```xml + + group.flyfish + rest-proxy-core + 1.1.2 + +``` + ### 1. 定义请求源 我们提供了非常灵活的**请求源**(Base URL)定义方式。 @@ -233,6 +242,98 @@ public class RestProxyDemoApplication { ### 4. 开始愉快的对接吧! 至此,我们的快速开始教程已经完成。 +## 结果映射处理和绑定 +大家在实现接口的时候都心照不宣的都一个习惯,那就是将接口响应增加一个包装类,样子大概是这样的: + +```json +{ + "success": true, + "code": 0, + "message": "成功", + "result": { + "name": "名称", + "code": "编码" + } +} +``` +但是我们在写Java代码时却不这么写。于是乎,这里就涉及到了一个**结果解包**的逻辑。 + +默认情况下,Rest代理器不会对结果进行解包。但是你可以添加`@AutoMapping`注解来标记自动解包。 + +这里我们提供了一个默认的数据结构用于解包的缺省行为,具体的格式就是**上面的例子**所定义的那样。 +如果您要调用的系统不以该接口包装格式返回,需要您自己书写相应逻辑。您需要实现`RestResultMapping`接口并正确书写`map`和`resolve`方法。 + +`map`方法用于实现解包逻辑,也就是**如何从包装的结果中取得真实的数据**,比如上面的`result`字段。 +此外,该方法内建议自行处理异常结果`code`,并主动抛出`RestClientException`。 + +`convert`方法用于将我们在`@RestService`中定义的`method`的返回值进行包装,保证返回真实的类型。 +比如方法签名为:`User getUser()`,包装类为:`Result`,这时我们需要返回`Result`类型,可以使用我们提供的工具类`TypeResolveUtils` +中的`wrap`方法进行包装。具体可以参考下面的例子。 + +以下是系统内的默认实现逻辑,仅供参考: +```java +/** + * 默认缺省的结果映射 + * + * @author wangyu + */ +@Slf4j +public class DefaultRestResultMapping implements RestResultMapping { + + /** + * 模糊的结果映射 + * + * @param body 结果 + * @return 映射后的结果 + */ + @Override + @SuppressWarnings("unchecked") + public T map(Object body) throws RestClientException { + // 多一步类型检查,保证转换的结果类型正确 + if (body instanceof RestResult) { + RestResult result = (RestResult) body; + if (result.isSuccess()) { + return (T) result.getResult(); + } + log.error("【RestProxy】请求发生异常!状态码:{},时间:{},信息:{}", result.getCode(), + DateUtils.formatDate(new Date(result.getTimestamp()), "yyyy-MM-dd HH:mm:ss"), result.getMessage()); + throw new RestClientException(result.getMessage()); + } + return (T) body; + } + + /** + * 解析返回类型 + * + * @param resultType 返回类型 + * @return 结果 + */ + @Override + public Type resolve(Type resultType) { + return TypeResolveUtils.wrap(resultType, RestResult.class); + } +} + +``` + +完成上面的步骤后,就可以使用`@AutoMapping`注解标记解包处理了! +最后实现的效果,就是从`TestService`到`TestUnwrapService`,如下: +```java +@RestService +public interface TestService { + + RestResult getUser(); +} +``` +```java +@RestService +@AutoMapping(DefaultRestResultMapping.class) +public interface TestUnwrapService { + + User getUser(); +} +``` + ## 定制您的rest客户端 我们提供了许多丰富的定制选项来帮助您更好的使用组件。