BaseOkHttp V3

<a href="https://github.com/kongzue/BaseOkHttp/"> <img src="https://img.shields.io/badge/BaseOkHttp-3.2.1-green.svg" alt="BaseOkHttp"> </a> <a href="https://bintray.com/myzchh/maven/BaseOkHttp_v3/3.1.9/link"> <img src="https://img.shields.io/badge/Maven-3.2.1-blue.svg" alt="Maven"> </a> <a href="http://www.apache.org/licenses/LICENSE-2.0"> <img src="https://img.shields.io/badge/License-Apache%202.0-red.svg" alt="License"> </a> <a href="http://www.kongzue.com"> <img src="https://img.shields.io/badge/Homepage-Kongzue.com-brightgreen.svg" alt="Homepage"> </a>

简介

• 无需操心线程问题，请求在异步线程执行，回调会自动回到主线程；
• 提供统一返回监听器 ResponseListener 处理一切返回数据，无论是错误还是成功，都可以一起处理，对于相同操作代码不再需要重复，避免代码反复臃肿。
• 提供基于 Map 对象和 List 对象的 Json 解析库及数据类型，直接与适配器配合，抛弃编写 JavaBean 的麻烦；
• 强大的全局方法和事件让您的请求得心应手。
• BaseOkHttp V3是基于BaseOkHttp V2( https://github.com/kongzue/BaseOkHttp )的升级版本，基于能够快速创建常用请求链接而封装的库。

[!TIP] BaseOkHttpX 现已发布，不妨试试看全新重构更好用的 BaseOkHttpX？https://github.com/kongzue/BaseOkHttpX

Maven仓库或Gradle的引用方式

jitPack 方式

请先在 'build.gradle(project)' 中添加如下代码：

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

在 'build.gradle(app)' 中引入：

dependencies {
    //BaseOkHttp V3 网络请求库
    implementation 'com.github.kongzue:BaseOkHttpV3:3.2.4.2'
    //BaseJson 解析库
    implementation 'com.github.kongzue:BaseJson:1.0.7.2'
}

额外的，如果您的项目未引入 okHttp，还需要添加 okHttp 最新版本依赖：

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.9.1" 
}

jCenter 方式

因 jCenter 停止维护，不再推荐使用。

Maven仓库：

<dependency>
  <groupId>com.kongzue.baseokhttp_v3</groupId>
  <artifactId>baseokhttp_v3</artifactId>
  <version>3.2.2</version>
  <type>pom</type>
</dependency>

Gradle：

在dependencies{}中添加引用：

//BaseOkHttp V3 网络请求库
implementation 'com.kongzue.baseokhttp_v3:baseokhttp_v3:3.2.2'
//BaseJson 解析库
implementation 'com.kongzue.basejson:basejson:1.0.7'

新版本系统（API>=27）中，使用非 HTTPS 请求地址可能出现 java.net.UnknownServiceException 错误，解决方案请参考：https://www.jianshu.com/p/528a3def1cf4

试用版可以前往 http://beta.kongzue.com/BaseOkHttp3 下载

目录

· <a href="#一般请求">一般请求</a>

· <a href="#json请求">JSON请求</a>

· <a href="#文件上传">文件上传</a>

· <a href="#文件下载">文件下载</a>

· <a href="#putdelete">PUT&DELETE</a>

· <a href="#websocket">WebSocket</a>

· <a href="#json解析">JSON解析</a>

· <a href="#javabean解析">JavaBean解析</a>

· <a href="#额外功能">额外功能</a>

···· <a href="#全局日志">全局日志</a>

···· <a href="#全局请求地址">全局请求地址</a>

···· <a href="#全局-Header-请求头">全局 Header 请求头</a>

···· <a href="#全局请求返回拦截器">全局请求返回拦截器</a>

···· <a href="#HTTPS-支持">HTTPS 支持</a>

···· <a href="#全局参数拦截器">全局参数拦截器</a>

···· <a href="#请求超时">请求超时</a>

···· <a href="#停止请求">停止请求</a>

···· <a href="#容灾地址">容灾地址</a>

···· <a href="#Cookie">Cookie</a>

· <a href="#开源协议">开源协议</a>

· <a href="#更新日志">更新日志</a>

一般请求

BaseOkHttp V3 提供两种请求写法，范例如下：

以参数形式创建请求：

progressDialog = ProgressDialog.show(context, "请稍候", "请求中...");
HttpRequest.POST(context, "http://你的接口地址", new Parameter().add("page", "1"), new ResponseListener() {
    @Override
    public void onResponse(String response, Exception error) {
        progressDialog.dismiss();
        if (error == null) {
            resultHttp.setText(response);
        } else {
            resultHttp.setText("请求失败");
            Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
        }
    }
});

Parameter 对象是一个 Map 的封装对象，可以通过 .toParameterString() 方法获得按 key 首字母排序、以“&”符号连接的文本串，或者使用 .toParameterJson() 方法将其转为 JSONObject。

一般请求中，使用 HttpRequest.POST(...) 方法可直接创建 POST 请求，相应的，HttpRequest.GET(...) 可创建 GET 请求，另外可选额外的方法增加 header 请求头：

HttpRequest.POST(Context context, String url, Parameter headers, Parameter parameter, ResponseListener listener);
HttpRequest.GET(Context context, String url, Parameter headers, Parameter parameter, ResponseListener listener);

以流式代码创建请求：

progressDialog = ProgressDialog.show(context, "请稍候", "请求中...");
HttpRequest.build(context,"http://你的接口地址")
        .addHeaders("Charset", "UTF-8")
        .addParameter("page", "1")
        .addParameter("token", "A128")
        .setResponseListener(new ResponseListener() {
            @Override
            public void onResponse(String response, Exception error) {
                progressDialog.dismiss();
                if (error == null) {
                    resultHttp.setText(response);
                } else {
                    resultHttp.setText("请求失败");
                    Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
                }
            }
        })
        .doPost();

返回回调监听器只有一个，请在其中对 error 参数判空，若 error 不为空，则为请求失败，反之则为请求成功，请求成功后的数据存放在 response 参数中。

之所以将请求成功与失败放在一个回调中主要目的是方便无论请求成功或失败都需要执行的代码，例如上述代码中的 progressDialog 等待对话框都需要关闭（dismiss掉），这样的写法更为方便。

3.1.0 版本起提供直接解析返回值为 jsonMap 对象，可使用 JsonResponseListener 监听器返回：

HttpRequest.POST(context, "/femaleNameApi", new Parameter().add("page", "1"), new JsonResponseListener() {
    @Override
    public void onResponse(JsonMap main, Exception error) {
        if (error == null) {
            resultHttp.setText(main.getString("msg"));
        } else {
            resultHttp.setText("请求失败");
            Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
        }
    }
});

关于返回线程的说明

BaseOkHttpV3 会智能的判断需要返回线程的场景，一般而言，您无需为此而操心，您可以直接在请求回调中进行 UI 的操作。

BaseOkHttpV3 的请求过程是异步进行的（多线程），而在返回数据后，是根据 context 进行判断的是要在异步线程执行还是在 UI 线程执行，当 context 传入的是 Activity 时，默认会在 UI 线程返回，无需额外处理线程问题，而当 context 为非 Activity，例如 ApplicationContext 或者 Service 时，则会在异步线程返回数据，若需要修改界面上的元素显示，您需要手动切换到主线程刷新 UI 组件。

这是在我们经过大量的使用场景调研后得出的最优设计方案，但如若您的请求返回数据流非常大，可能造成 UI 线程卡顿，建议在传入 context 时，使用 context.getApplicationContext() 方法来强制异步线程返回，待数据得到妥善处理后，需要返回 UI 线程刷新界面显示时，使用 activity.runOnUiThread(...)切换到主线程进行刷新。

特殊情况下需要同步请求可以使用全局参数BaseOkHttp.async=(boolean) 控制全局是否同步请求，也可以在单次请求局部设置setAsync(boolean)；

JSON请求

有时候我们需要使用已经处理好的json文本作为请求参数，此时可以使用 HttpRequest.JSONPOST(...) 方法创建 json 请求。

json 请求中，参数为文本类型，创建请求方式如下：

progressDialog = ProgressDialog.show(context, "请稍候", "请求中...");
HttpRequest.JSONPOST(context, "http://你的接口地址", "{\"key\":\"DFG1H56EH5JN3DFA\",\"token\":\"124ASFD53SDF65aSF47fgT211\"}", new ResponseListener() {
    @Override
    public void onResponse(String response, Exception error) {
        progressDialog.dismiss();
        if (error == null) {
            resultHttp.setText(response);
        } else {
            resultHttp.setText("请求失败");
            Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
        }
    }
});

也可以使用 JsonMap 构建请求参数：

progressDialog = ProgressDialog.show(context, "请稍候", "请求中...");

JsonMap jsonMap = new JsonMap();
jsonMap.set("key", "DFG1H56EH5JN3DFA");
jsonMap.set("token", "124ASFD53SDF65aSF47fgT211");

HttpRequest.JSONPOST(context, "http://你的接口地址", jsonMap, new ResponseListener() {
    @Override
    public void onResponse(String response, Exception error) {
        progressDialog.dismiss();
        if (error == null) {
            resultHttp.setText(response);
        } else {
            resultHttp.setText("请求失败");
            Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
        }
    }
});

另外参数也可以是 JSONObject 类型（来自 org.json 框架）。

Json请求中，可使用 HttpRequest.JSONPOST(...) 快速创建 Json 请求，另外可选额外的方法增加 header 请求头：

HttpRequest.JSONPOST(Context context, String url, Parameter headers, String jsonParameter, ResponseListener listener)

也可以使用流式代码创建请求：

progressDialog = ProgressDialog.show(context, "请稍候", "请求中...");
HttpRequest.build(context,"http://你的接口地址")
        .setJsonParameter("{\"key\":\"DFG1H56EH5JN3DFA\",\"token\":\"124ASFD53SDF65aSF47fgT211\"}")
        .setResponseListener(new ResponseListener() {
            @Override
            public void onResponse(String response, Exception error) {
                progressDialog.dismiss();
                if (error == null) {
                    resultHttp.setText(response);
                } else {
                    resultHttp.setText("请求失败");
                    Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
                }
            }
        })
        .doPost();

因需要封装请求体，Json请求只能以非 GET 请求的方式进行。

默认情况下，Json 请求的 Mime 类型是自动设置的，要自定义，可以通过以下方法进行：

.setCustomMimeInterceptor(new CustomMimeInterceptor() {
    @Override
    public String onRequestMimeInterceptor(RequestInfo requestInfo, Call call) {
        if (requestInfo.getUrl().endsWith("/mimeUrlTest")){
            return "application/json; charset=utf-8";	//根据网址返回自定义 MimeType
        }
        return super.onRequestMimeInterceptor(requestInfo, call);
    }
})

文件上传

要使用文件上传就需要将 File 类型的文件作为参数传入 Parameter，此时参数中亦可以传入其他文本类型的参数。

因需要封装请求体，文件上传只能以非 GET 请求的形式发送。

范例代码如下：

progressDialog = ProgressDialog.show(context, "请稍候", "请求中...");
HttpRequest.POST(context, "http://你的接口地址", new Parameter()
                         .add("key", "DFG1H56EH5JN3DFA")
                         .add("imageFile1", file1)
                         .add("imageFile2", file2)
        , new ResponseListener() {
            @Override
            public void onResponse(String response, Exception error) {
                progressDialog.dismiss();
                if (error == null) {
                    resultHttp.setText(response);
                } else {
                    resultHttp.setText("请求失败");
                    Toast.makeText(context, "请求失败", Toast.LENGTH_SHORT).show();
                }
            }
        });

也可以使用流式代码创建请求：

HttpRequest.build(context,"http://你的接口地址")
        .addHeaders("Charset", "UTF-8")
        .addParameter("page", "1")
        .addParameter("imageFile1", file1)
        .addParameter("imageFile2", file2)
        .setResponseListener(new ResponseListener() {
            @Override
            public void onResponse(String response, Exception error) {
                progressDialog.dismiss();