JHttp使用文档

/ JHttp / 没有评论 / 57浏览

简介

JHttp是用java 编写的用来提供高效的、最新的、功能丰富的支持HTTP协议的客户端编程工具包,基于原生的HttpUrlConnection实现,支持:GETPOSTPUTDELETEPATCHHEADOPTIONSTRACE请求,可以适应绝大部分业务场景,并提供了丰富的请求操作的API,使开发者更加方便快捷的完成HTTP的请求工作。可以从码云获取代码。

开始使用

使用JHttp可以直接下载源代码编译或者下载已经编译的jar文件,如果您是使用maven来构建项目,也可以直接在pom.xml中添加JHttp的坐标:

<!-- https://mvnrepository.com/artifact/com.jianggujin/JHttp -->
<dependency>
    <groupId>com.jianggujin</groupId>
    <artifactId>JHttp</artifactId>
    <version>最新版本</version>
</dependency>

最新的版本可以从这里获取。

一个例子

请求文本是最基本的用法,比如下载一个网页的源码或者普通的接口调用,以访问百度为例,我们可以这样写:

JResponse response = new JTextResponse();
JRequest.create("http://www.baidu.com").response(response).execute();
System.out.println(response.getData());

JRequest是所有请求的入口,我们可以直接使用该类提供的静态方法create创建一个请求对象,也可以使用该类的构造方法实例化请求对象。在JRequest中,提供了链式调用的方法,上面的例子中的请求,我们可以用一行代码完成。

JRequest.create("http://www.baidu.com").response(response).execute()
      .response().getData();

每个请求都应该有响应,我们可以通过JRequest.response(JResponse response)设置响应的处理对象,上面的例子中使用的是JTextResponse,该类是文本响应的处理对象。除此之外,JHttp还提供了字节数组、文件等响应的处理。

默认情况下,JRequest使用GET请求方式,我们可以通过JRequest.method(JMethod method)设置请求方法,JRequest中还提供了一些常用的操作方法,比如超时时间、字符编码等。

设置请求参数

通常情况,我们在网络请求的时候会传递一些请求参数,我们可以使用JRequest提供的data方法设置请求参数,该方法有几个重载方法,我们可以按照实际情况选择。

String url = "https://www.sojson.com/open/api/weather/json.shtml";
Object obj = JRequest.create(url).data("city", "南京")
      .response(new JTextResponse()).execute()
      .response().getData();
System.out.println(obj);

JRequest不仅支持普通的文本参数,还支持上传文件。

File uploadFile = new File("test.txt");
Object obj = JRequest.create("http://127.0.0.1/test/upload")
      .method(JMethod.POST)
      .data("uploadFile", uploadFile.getName(),
      new FileInputStream(uploadFile)).response(new JTextResponse())
      .execute().response().getData();
System.out.println(obj);

这样就可以上传文件,是不是很简单,不过需要注意的是,上传文件的时候需要使用POSTPUT这样允许请求体的请求方法。

设置请求体

有些时候,我们可能不仅仅是传递普通参数或者上传文件,我们可能希望直接发送一段文本,比如Restful接口提交JSON格式数据,使用JHttp也可以很方便的处理这种需求,在JRequest中有requestBody(Object body)方法可以设置要提交的请求体,默认的请求体的处理支持:CharSequenceMapbyte[]char[]

我们可以这样使用:

Object obj = JRequest.create("http://127.0.0.1/test/user")
      .method(JMethod.POST)
      .header("Content-Type", "application/json")
      .requestBody("{\"name\":\"jianggujin\"}")
      .response(new JTextResponse()).execute()
      .response().getData();
System.out.println(obj);

如果默认的实现不满足我们的需求,我们可以自定义自己的解析器,编写解析器我们只需要实现com.jianggujin.http.core.JRequestBodyResolver接口,该接口需要实现两个方法,write方法用于向输出流中写入数据,support方法用于判断解析器是否支持该类型数据解析(通过JRequest设置的解析器该方法无效,不会做判断)。

我们可以通过JRequest.requestBodyResolver(JRequestBodyResolver requestBodyResolver)设置请求指定解析器,这种方式级别最高,如果不设置请求的解析器,则会查找全局解析器。全局解析器支持代码注册和ServiceLoader形式加载,代码注册需要调用JRequestBodyResolverFactory.register(JRequestBodyResolver resolver)方法,ServiceLoader形式只需要在META-INF/services/com.jianggujin.http.core.JRequestBodyResolver文件中添加需要的实现即可。

JJsonResponse和JXmlResponse

这两个响应用于将响应的数据转换为指定的Java Bean,但是并未提供相关实现,如果我们需要这部分功能,可以实现相对应的JJsonResolverJXmlResolver接口,并调用对应的setResolver方法设置解析实现,这样可以完成对默认响应的扩展。

如果默认提供的响应处理不满足实际需求,我们也可以实现JResponse接口,按照实际需求处理响应。

设置代理

如果程序运行环境存在网络限制,需要代理访问,我们只需要为请求设置代理对象,方法为proxy(Proxy proxy)

Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(host, port));
JRequest.create(url).proxy(proxy );

SSL

在处理https请求的时候,我们可能需要做SSL的设置,JHttp提供了JSSLContextFactory接口用于初始化SSLContextHostnameVerifier,为了使用方便,JHttp提供了一个JDefaultSSLContextFactory,我们只需要传递协议算法即可,该类默认忽略证书的验证,并且信任所有主机,为了安全考虑,还是建议实现规范的处理。

Cookie

如果我们需要做请求的会话保持,使用JHttp可以很方便的添加Cookie信息,在JRequest中,我们提供了几个cookie的重载方法,方便我们在请求之前添加cookie信息。 因为JHttp是基于HttpUrlConnection的,所以全局的CookieManager对于JHttp同样有效。

CookieManager manager = new CookieManager();
CookieHandler.setDefault(manager);

JRequest.create("https://www.baidu.com").execute();

for (HttpCookie cookie : manager.getCookieStore().getCookies()) {
   System.out.printf("%s=%s,domain=%s,path=%s\n",
      cookie.getName(),
      cookie.getValue(),
      cookie.getDomain(),
      cookie.getPath());
}

请求回调

如果我们需要对请求添加日志等处理,我们可以实现com.jianggujin.http.core.JRequestExecuterListener接口,该接口会在请求执行前与请求之行结束进行相关方法的回调,方便我们做日志记录等处理,在JHttp中也提供了一个默认的日志实现类com.jianggujin.http.util.JRequestExecuterLog,当然了,这个类仅仅是做了最简单的打印输出,我们只需要调用JRequestExecuter.setRequestExecuterListener(JRequestExecuterListener listener)方法进行设置。

扩展

JHttp除了上面的基本使用之外,还支持动态代理方式,通过定义API接口配合提供的注解,可以更加方便快捷的完成请求处理。使用接口形式,我们首先需要定义请求的接口,举个例子:

@JBaseUrl("https://www.sojson.com")
public static interface Weather {
   @JApiRequest("/open/api/weather/json.shtml")
   @JApiTextResponse
   String weather(@JRequestParam("city") String city);
}

定义完接口,我们需要使用JApiStore获得接口的代理实现:

String rs = JApiStore.getApi(Weather.class).weather("南京");
System.out.println(rs);

接口方法中如果含有JResponseProxyJSSLContextFactoryJRequestBodyResolver类型的参数,会直接将其设置在请求对象中。

下面就来看一下相关注解的含义

JBaseUrl

请求地址,通常为域名,例如:http://www.baidu.com,可以用在方法上面。

JCharset

设置请求编码,可以用在方法上面。

JHeader

请求头,可以用在方法方法参数上面。当注解用在方法参数上面的时候

JTimeout

设置请求超时时间,可以用在方法上面。

JApiRequest

设置API请求信息,用于设置请求路径方法是否忽略响应错误,可以用在方法上面。与JBaseUrl搭配之用,会将域名与路径进行拼接。

JRequestParam

请求参数,可以用在方法方法参数上面。当注解用在方法参数上面的时候

JRequestBody

设置请求体,可以用在方法参数上。

JPathParam

设置请求路径参数,与JApiRequest搭配使用,如果路径中存在可变部分,可以使用{path}形式,例如:/user/{id}。使用该注解,可以将指定参数替换路径中的参数。

为了方便响应处理,不需要为每一个接口添加响应参数,有如下注解可以方便处理请求响应

JApiTextResponse

使用该注解会为请求对象设置JTextResponse响应,接口方法返回值应为String

JApiJsonResponse

使用该注解会为请求对象设置JJsonResponse响应,接口方法返回值应为Object

JApiByteResponse

使用该注解会为请求对象设置JByteResponse响应,接口方法返回值应为byte[]

JApiFileResponse

使用该注解会为请求对象设置JFileResponse响应,接口方法返回值应为File

JApiXmlResponse

使用该注解会为请求对象设置JXmlResponse响应,接口方法返回值应为Object