# easy-okhttp **Repository Path**: java10000/easy-okhttp ## Basic Information - **Project Name**: easy-okhttp - **Description**: 这是一个对oktthp3进行封装的工具，提供了更为便捷的方法调用。目的是为了替换难用的apache HttpClient. - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 205 - **Created**: 2016-07-19 - **Last Updated**: 2021-11-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # easy-okhttp ## 简介 项目`easy-okhttp`是对okhttp网络框架(https://github.com/square/okhttp)上层封装， 支持文件上传和下载，表单(含文件)提交，链式调用，支持HTTPS和自定义签名证书等特性。 okhttp网络框架的流行始于Android，但是在Java后端仍然是`Apache HttpClient`网络框架，这个框架的缺点在于设计非常的复杂，而且Jar的大小也很大。故此我封装okhttp主要目的希望弃用`Apache HttpClient`；其次也是为了帮助okhttp的推广^_^ ## 参考与依赖 + 参考项目说明 * [https://github.com/hongyangAndroid/okhttp-utils](mailto:https://github.com/hongyangAndroid/okhttp-utils) + 依赖关系说明 * `okhttp`，本项目核心所在，底层依赖了`okio`框架，框架的大小在500Kb之内 * `mzlion-core`，项目依赖的工具类，底层依赖了`slf4j-api`和`gson`两个框架，框架的大小在400Kb之内 ## 联系方式 * Gmail [and.mz.yq@gmail.com](and.mz.yq@gmail.com) * QQ群 目前暂未建立，如果大家有所需要共同讨论，可以在留言，然后我新建QQ群 ## 用法 ### 框架引入 项目基于Maven管理，并且项目要已经上传到JCenter，所以只要在您的项目添加如下依赖。 ```xml jcenter bintray jcenter http://jcenter.bintray.com/ true ``` ```xml com.mzlion easy-okhttp 1.0.0-beta ``` ### 支持功能说明 * GET和POST请求 * 基于POST的大文本数据、二进制文件上传，即通过Http Body提交 * 普通的表单提交 * 带有文件表单提交 * 表单提交支持参数名重复，在后台接收到的是数组或集合 * 支持session保持 * 支持链式调用 * 支持可信任证书和自定义签名证书的https访问 * 更多特性增加中 ### 全局配置（可选） * 框架会自动读取classpath下的`easy-okhttp.properties`配置文件，该配置文件包含如下配置信息 + okhttp.connectionTimeout 连接超时时间，默认设置10秒 + okhttp.readTimeout 内容读取超时时间，默认是30秒 * 如果需要更改这些默认配置，有两种方式 + 覆盖框架提供的配置`easy-okhttp.properties`，框架优先加载项目中的配置文件 + 通过代码设置全局配置，下面会讲解到 * 通过代码也可以设置全局参数，该配置操作只需要操作一次，因而可以放在项目启动时配置。 + 设置连接超时时间 `HttpClient.INSTANCE.setConnectionTimeout(int)` + 设置读取超时时间 `HttpClient.INSTANCE.setReadTimeout(int)` + 设置自定义签名证书 `HttpClient.INSTANCE.setCertificates(?)` + 设置默认Header `HttpClient.INSTANCE.setDefaultHeader(String,String)` ### 示例 #### 1.普通的GET请求无参数 ```java DefaultResponseConverter responseConverter = new DefaultResponseConverter(); HttpResponse httpResponse = HttpClient .get("http://localhost:8080/okhttp-server-test/userInfo/pageSelect") // 请求方式和请求url .execute(responseConverter); ``` #### 2.普通的GET请求带参数 ```java String responseData = HttpClient .get("http://localhost:8080/okhttp-server-test/userInfo/pageSelect") // 请求方式和请求url .queryString("username","mzlion") //设置请求参数 .execute() .asString(); ``` #### 3.POST普通表单提交 ```java String responseData = HttpClient .post("http://localhost:8080/okhttp-server-test/userInfo/create") // 请求方式和请求url .formParam("username","mzlion") // 表单参数 .formParam("userPwd", "123") // 表单参数 //queryString("queryTime","20160530") //url参数 .execute() .asString(); ``` #### 4.POST提交String ```java String responseData = HttpClient .stringBody("http://localhost:8080/okhttp-server-test/userInfo/create") // 请求方式和请求url .json("{\"username\":\"mzlion\",\"userPwd\":\"123\"}") // post提交json //.xml("") //post提交xml //.html("function fun(){}") //post提交html //.charset("utf-8") //设置编码 .execute() .asString(); ``` #### 5.POST提交二进制文件 ```java String responseData = HttpClient .binaryBody("http://localhost:8080/okhttp-server-test/userInfo/avatar") // 请求方式和请求url .stream(this.getClass().getClassLoader().getResourceAsStream("andy-bao.jpg")) // post提交流 //.file(new File("d:/andy-bao.jpg")) //post提交文件 .contentType(ContentType.IMAGE_JPG) //设置请求内容类型 .execute() .asString(); ``` #### 6.POST表单提交含文件上传 ```java String responseData = HttpClient .formDataPost("http://localhost:8080/okhttp-server-test/userInfo/createWithFile") // 请求方式和请求url .formParam("userName", "test") .formParam("userPwd", "123456") .formParam("nickName", "Test") .formParam("realName", "测试") .formParam("hobby", "测试，就爱测试") .formParam("avatarFile", this.getClass().getClassLoader().getResourceAsStream("andy-bao.jpg"), "andy-bao.jpg") //.formParam("avatarFile", this.getClass().getClassLoader().getResourceAsStream("andy-bao.jpg"), "andy-bao.jpg") .execute() .asString(); ``` #### 7.HttpResponse对象介绍 1. `HttpResponse`类是对请求服务端的结果封装，包含了3个属性 * `isSuccess` 表示请求是否成功 * `errorMessage` 请求失败时错误消息 * `rawResponse` 原始的`Response`，当框架提供的功能无法满足时候，可以调用该属性处理。 **当请求执行完成之后一定需要判断请求成功还是失败**。** 2. `HttpResponse`类提供对请求服务端的结果转换方法 默认的请求响应结果并不能直接参与编程，一般都需要经过一些转换，所以`HttpResponse`对象提供了几种常见的转换，下面直接通过示例解释各个方法的作用和应用。 **注意：当使用转换方法之前，最好调用方法`isSuccess()`判断请求响应是否成功，否则直接调用转换方法的话，如果响应失败，则会抛出'HttpClientException'异常** ```java //将响应结果转为字符串输出 String responseData = httpResponse.asString(); //将响应结果转为文件保存 File frc = new File("d:\\web\\save.txt"); httpResponse.asFile(frc); //json转换器 List personList = httpResponse.asBean(new TypeToken>(){}); //重载方法 //Person person = httpResponse.asBean(Person.class); //将响应结果转为输出流中 ByteArrayOutputStream baos = new ByteArrayOutputStream(); httpResponse.asStream(baos); ``` ### 高级配置 #### 为单个请求设置超时 当我们需要对单个请求设置连接超时时间、读取超时时间等属性时，可以在执行`execute`方法之前调用。主要有如下几个方法可以进行调用。 + `connectionTimeout(int)` 连接超时时间 + `readTimeout(int)` 读取超时时间 + `certificates([])` 自定义签名证书设置 以上这些方法的调用会使得框架创建一个新的`OkHttpClient`对象。下面给出一个snippet加以说明。 ```java //字符串转换器 String responseData = HttpClient.get() //设置请求方式 .url("http://localhost:8080/okhttp-server-test/userInfo/avatar2") //设置请求地址 .queryString("id","2") //设置请求参数 .readTimeout(30000) //覆盖设置，读取超时时间 .execute() //执行 .asString(); ``` #### 自定义签名网站https访问 1. 信任指定的自签名证书网站 自签名网站htts访问处理方式非常简单，首先拿到客户端的签名证书，一般通过浏览器就可以导出xxx.cer证书了。然后将拿到的证书文件拷贝到自己的项目中，然后按照如下方式调用或设置。 ```java //字符串转换器 String responseData = HttpClient.get() //设置请求方式 .url("http://localhost:8080/okhttp-server-test/userInfo/avatar2") //设置请求地址 .queryString("id","2") //设置请求参数 .readTimeout(30000) //覆盖设置，读取超时时间 .certificates(this.getClass().getClassLoader().getResourceAsStream("SRCA.cer")) .execute() //执行 .asString(); ``` 2. 信任所有网站 该方法不推荐在生产环境使用，否则https的作用意义就失效了。信任所有网站的https访问设置非常简单，`HttpClient.INSTANCE.setCertificates()`即可。 ## 关于demo 目前Demo还没完成，完成之后也会上传，方便大家直接把项目clone下来即可运行。