第一部分 简介

JHttp是用java 编写的用来提供高效的、最新的、功能丰富的支持HTTP协议的客户端编程工具包，基于原生的HttpUrlConnection实现，支持：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、TRACE请求，可以适应绝大部分业务场景，并提供了丰富的请求操作的API，使开发者更加方便快捷的完成HTTP的请求工作。

第二部分 开始使用

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

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

最新的版本可以从Maven仓库或者码云获取。

2.1 一个例子

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

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中还提供了一些常用的操作方法，比如超时时间、字符编码等。

2.2 设置请求参数

通常情况，我们在网络请求的时候会传递一些请求参数，我们可以使用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);

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

2.3 设置请求体

有些时候，我们可能不仅仅是传递普通参数或者上传文件，我们可能希望直接发送一段文本，比如Restful接口提交JSON格式数据，使用JHttp也可以很方便的处理这种需求，在JRequest中有requestBody(Object body)方法可以设置要提交的请求体，默认的请求体的处理支持：CharSequence、Map、byte[]和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文件中添加需要的实现即可。

2.4 请求响应处理

在JRequest中提供了response(JResponse response)方法用于设置响应处理对象，JHttp提供了如下几种响应实现：

• JByteBufferResponse - 将响应解析为ByteBuffer

• JByteResponse - 字节数组响应

• JFileResponse - 文件响应

• JJsonResponse - JSON响应

• JNoBodyResponse - 无响应体的响应

• JTextResponse - 文本响应

• JXMLDomResponse - XML响应，DOM方式解析

• JXmlResponse - XML响应

• JXMLSaxResponse - XML响应,SAX方式解析

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

如果默认提供的响应处理不满足实际需求，我们也可以实现JResponse接口，或者直接继承JAbstractResponse，按照实际需求处理响应。

2.5 设置代理

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

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

2.6 SSL

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

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

2.8 请求回调

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

第三部分 扩展

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

@JBaseUrl("http://ws.webxml.com.cn")
public static interface Weather {
    @JApiRequest(value = "/WebServices/WeatherWS.asmx/getWeather", method = JMethod.POST)
    String weather(@JRequestParam("theCityCode") String theCityCode, @JRequestParam("theUserID") String theUserID);
}

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

JApiStore.getApi(Weather.class).weather("2009", "");

接口方法中如果含有JResponse、Proxy、JSSLContextFactory、JRequestBodyResolver、JMethod、JKeyVal类型的参数，会直接将其设置在请求对象中。

3.1 JApiRequest

设置API请求信息，用于设置请求路径、方法等信息，可以用在方法上面。与JBaseUrl搭配使用，会将域名与路径进行拼接。

3.2 JApiRequestBodyResolver

请求体解析器，用于指定当前请求使用的请求体解析器

3.3 JApiResponseCreator

响应对象创建器，用于自定义创建接口方法的响应对象

3.4 JBaseUrl

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

3.5 JCookie

Cookie

• 当注解为类注解，则required()无效， 会根据itemDelimiter()与kvDelimiter()的配置对value()进行拆分

• 当注解为方法注解，则required()无效， 会根据itemDelimiter()与kvDelimiter()的配置对value()进行拆分

• 当注解为方法参数注解，则itemDelimiter()与kvDelimiter()的配置无效， 如果方法参数类型为String，则value()必须配置，对应值为Cookie名称，方法参数为Cookie值； 如果方法参数类型为Map，则所有参数无效，方法参数即为Cookie数据

• 注解解析顺序为类注解 -> 方法注解 -> 方法参数注解。同名参数会覆盖

3.6 JHeader

请求头

• 当注解为类注解，则required()无效， 会根据itemDelimiter()与kvDelimiter()的配置对value()进行拆分

• 当注解为方法注解，则required()无效， 会根据itemDelimiter()与kvDelimiter()的配置对value()进行拆分

• 当注解为方法参数注解，则itemDelimiter()与kvDelimiter()的配置无效， 如果方法参数类型为String，则value()必须配置，对应值为请求头名称，方法参数为请求头值； 如果方法参数类型为Map，则所有参数无效，方法参数即为请求头

• 注解解析顺序为类注解 -> 方法注解 -> 方法参数注解。同名参数会覆盖

3.7 JPathParam

路径参数，路径参数形如{name}

• 如果方法参数类型为String，则value()必须配置，对应值为路径参数名称，方法参数为路径参数值； 如果方法参数类型为Map，则所有参数无效，方法参数即为路径参数数据

3.8 JRequestParam

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

• 如果参数为String，首先会判断value是否为空串，是则注解参数用法相同，不是则value为请求参数名称，参数值为对应请求参数的值
• 如果参数为Collection或数组，则仅有kvDelimiter参数有效
• 如果参数为Map则所有参数无效

3.9 JRequestBody

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

3.10 默认处理

为了方便对响应数据的处理，JHttp提供了一些默认的操作，在没有主动设置响应对象或响应对象创建器的情况下，则会根据方法返回值创建响应对象。

如果没有触发上述主动设置，JHttp会首先通过JReturnTypeResponseFactory创建需要的响应对象，想要让这部分生效，首先我们需要为JApiInvocationHandler设置合适的JReturnTypeResponseFactory实现。如果未设置JReturnTypeResponseFactory或者该接口实现最终返回的响应对象为null，那么，JHttp会依据接口方法的返回数据类型设置对应的响应对象，支持的返回类型以及对应的相应处理类如下：

需要注意的是响应对象的getData()方法的返回值必须与接口方法返回值类型匹配，如果不匹配且返回类型为JResponse，则会返回响应对象，否则会永远返回null