如何封装第三方API

Posted 2021-03-20 小虾米的java梦

日常开发中，少不了对第三方api的封装。api封装的好坏绝定了后期维护的难度以及使用api的开发人员是否抱怨。比如：有一天第三方api的域名变了。或者自己封装的api没有参数说明，过段时间来改代码自己忘什么意思了。或者应该调用哪个URL来满足我当前的需求。考虑到这些因素，最终选择将api封装为jar包，并生成相应的文档。

首先看一个错误案例：

错误例子

url没有使用全局变量，一旦域名变更或者http变为https，你就得满项目的替换。bug的几率可以说是飙升。大家千万别存在侥幸心理说域名和http协议是不会变的。在我封装的oppo api中就出现了http协议的变更，而360点睛api出现了域名的变更（这种事情不可以不预防）。再者上面的传参是存在问题的。个人认为应该写成javaBean，并且bean中要有注释，不然可能出现开发人员过段时间不知道字段什么意思了，或者开发者块的程序员离职了，下一个开发者的人完全不知道这写的什么。

虽然说像oppo会给你一份pdf文档，告诉你传递哪些参数。360点睛是提供的html页面。但是在开发中难道还要找文档去编码吗。多影响效率而且代码会写的很乱，一个人一个样。后期一旦出现问题，有的程序员会记录调用api的日志，但是有的人没有记录，找bug时，无论是对于管理人还是开发人都是头疼的事。所以在封装api的前期就一定得把好脉。

综上所述，我选择封装成jar包，放在svn上，谁要是使用，就下载jar包，放在自己的项目里。而且这个jar包我只让一个人管理开发，其他人只管使用jar包。这样后期出问题可以直接定位到人。

现在说下如何封装（我拿今日头条的API说下）

1、首先我要有一个全局的url定义，目的就是一旦出现域名或者协议变更，更改一处代码就OK了，如图：

全局URL

2、封装HTTP请求，（GET、POST），并记录详细日志【我使用的HttpClient，也可以使用别的，如java自带的】

自己封装请求

这里详细的记录，请求数据，返回数据，消耗时间。这么写后开发人员完全就不必关心日志的问题，而且一旦http改成https在这里修改一下就可以了。

3、定义实体类（javaBean）【请求bean、返回bean】，这块是最烦人的，看着返回的json，一个一个字段的写。我教个简单的。

json示例

如图中的这个json，访问此url：http://www.bejson.com/json2javapojo/new/

直接生成javaBean

把json放在里面会自动为我们生成bean，很方便吧。

4、对外提供方法，供别人调用（通过javadoc生成文档），如图：

提供外部调用

这样如果别人想要获取代理商下的广告主ID列表，直接调用AccountService.getAdvertiserList(xx,xx)就可以了，不必关心内部的实现。生成的文档可以看到。

文档1

点击进去看详细参数

文档详细描述

在点击AccountParams看详细参数

参数描述

到此api封装就完事了。这里说下如何将json数据转为javaBean。看到我上面代码的应该知道我使用的是Gson

最简单的实现就是：

response = (AccountClientLoginResponse) gson.fromJson(result,

AccountClientLoginResponse.class);

AccountClientLoginResponse就是你想转为的bean。

复杂些的如带泛型：

response = gson.fromJson(jsonStr,

new TypeToken<BasicsResponse<ConvertInfo>>() {

}.getType());

这2个内容，我放在下一篇文章说。喜欢的可以关注下，等待我下次更新。

总结：在一些公司调用第三方api如：oppo、vivo、头条、360，这些api不知道什么时候会更新，为了为会期的维护和开发着想，一定要对api统一管理。避免牵一发而动全身