OkGo 网络请求框架介绍与使用说明

前言

本文摘自 OkGo，一个专注于让网络请求更简单的框架，与 RxJava 完美结合，比 Retrofit 更简单易用。

项目地址：https://github.com/jeasonlzy

使用

Android Studio 用户

一般来说，只需要添加第一个 okgo 的核心包即可，其余的三个库根据自己的需要选择添加。

//必须使用
compile 'com.lzy.net:okgo:3.0.4'

//以下三个选择添加，okrx和okrx2不能同时使用
compile 'com.lzy.net:okrx:1.0.2'
compile 'com.lzy.net:okrx2:2.0.2'  
compile 'com.lzy.net:okserver:2.0.5'

//或者
compile 'com.lzy.net:okgo:+'        //版本号使用 + 可以自动引用最新版
compile 'com.lzy.net:okrx:+'        //版本号使用 + 可以自动引用最新版
compile 'com.lzy.net:okserver:+'    //版本号使用 + 可以自动引用最新版

注意事项

使用该网络框架时，必须要在 Application 中做初始化，详细的初始化办法点击这里
okgo使用的okhttp的版本是最新的3.8.0版本，OkGo详细文档点击这里
okrx是基于RxJava的扩展项目，OkRx详细文档点击这里
okrx2是基于RxJava2的扩展项目，OkRx2详细文档点击这里
okserver是对okgo的扩展，包含两个核心入口类：
- OkDownload是统一的下载管理，支持断点续传功能，OkDownload详细文档点击这里
- OkUpload是统一的上传管理，OkUpload详细文档点击这里

OkGo主要功能

基本的 get、post、put、delete、head、options、trace、patch 八种请求；
支持 upString，upJson，upBytes，upFile 等 up 类方法上传特定数据；
支持一个 key 上传一个文件，也可以一个 key 上传多个文件，也可以多文件和多参数一起上传；
大文件下载和下载进度回调；
大文件上传和上传进度回调；
支持 cookie 的自动管理，并可自定义 cookie 管理策略；
支持缓存模式，不仅支持 http 缓存协议，也支持自定义缓存策略；
支持重定向；
支持自定义超时自动重连次数；
支持链式调用；
支持 https 访问，支持双向认证；
支持根据 tag 取消请求，也可全部取消；
支持自定义 Callback，自动解析网络数据；

请求

1. 请求所有配置

无论做什么请求，第一行的泛型一定要加！

注意以下几点：

这里演示的是一次普通请求所有能配置的参数，真实使用时不需要配置这么多，按自己的需要，选择性的使用即可；

第一行的泛型一定要特别注意，这个表示你请求网络的数据类型是什么，必须指定，否则无法解析网络数据；

.post(url)：
这个表示当前请求是 post 请求，当然一共支持
GET，HEAD，OPTIONS，POST，PUT，DELETE，PATCH， TRACE 这 8 种请求方式，你只需要改改这个方法名就行了，很方便；

.params()：
添加参数的时候,最后一个 isReplace 为可选参数,默认为 true，即代表相同 key 的时候，后添加的会覆盖先前添加的；

.tag(this)：
请求的 tag，用于标识当前的请求，方便后续取消对应的请求，如果你不需要取消请求，也可以不用设置；

.isMultipart()：
该方法表示是否强制使用 multipart/form-data 表单上传，因为该框架在有文件的时候，无论你是否设置这个参数，默认都是
multipart/form-data 格式上传，但是如果参数中不包含文件，默认使用 application/x-www-form-urlencoded 格式上传，如果你的服务器要求无论是否有文件，都要使用表单上传，那么可以用这个参数设置为 true；

.isSpliceUrl()：
该方法表示是否强制将 params 的参数拼接到 url 后面，默认 false 不拼接。一般来说，post、put 等有请求体的方法应该把参数都放在请求体中，不应该放在 url 上，但是有的服务端可能不太规范，url 和请求体都需要传递参数，那么这时候就使用该参数，它会将你所有使用 .params() 方法传递的参数，自动拼接在 url 后面；

.retryCount()：
该方法是配置超时重连次数，也可以在全局初始化的时候设置，默认使用全局的配置，即为 3 次，你也可以在这里为你的这个请求特殊配置一个，并不会影响全局其他请求的超时重连次数；

.cacheKey() .cacheTime() .cacheMode()：
这三个是缓存相关的配置，详细请看缓存介绍；

.headers()：
该方法是传递服务端需要的请求头，如果你不知道什么是请求头，看wiki首页关于网络抓包中的http协议链接；

.params()：
该方法传递键值对参数，格式也是 http 协议中的格式，详细参考上面的 http 协议连接；

.addUrlParams() .addFileParams() .addFileWrapperParams()：
这里是支持一个 key 传递多个文本参数，也支持一个 key 传递多个文件参数，详细也看上面的 http 协议连接；

另外，每个请求都有一个 .client() 方法可以传递一个 OkHttpClient
对象，表示当前这个请求将使用外界传入的这个 OkHttpClient 对象，其他的请求还是使用全局的保持不变。那么至于这个
OkHttpClient 你想怎么配置，或者配置什么东西，那就随意了，改个超时时间，加个拦截器什么的统统都是可以的，看你心情喽。

特别注意：如果你的当前请求使用的是你传递的 OkHttpClient
对象的话，那么当你调用 OkGo.getInstance().cancelTag(tag) 的时候，是取消不了这个请求的，因为 OkGo 只能取消使用全局配置的请求，不知道你这个请求是用你自己的 OkHttpClient 的，如果一定要取消，可以是使用 OkGo 提供的重载方法，详细看下方的取消请求的部分。

2. Response对象介绍

先看Response对象内部的字段：

该对象一共有5个字段，分别表示以下意思：

body：当前返回的数据，T 即为数据的泛型。使用方法 body() 获取该值。如果请求成功，回调 onSuccess()，该字段为 convertResponse() 解析数据后返回的数据。如果发生异常，回调 onError()，该字段值为 null；
throwable：如果发生异常，回调 onError()，该字段保存了当前的异常信息。如果请求成功，回调 onSuccess()，该字段为 null。使用方法 getException() 获取该值；
isFromCache：表示当前的数据是来自哪里，true：来自缓存，false：来自网络。使用方法 isFromCache() 获取该值；
rawCall：表示当前请求的真正 okhttp3.Call 对象。使用方法 getRawCall() 获取该值；
rawResponse：表示当前请求服务端真正返回的 okhttp3.Response 对象，注意：如果数据来自缓存，该对象为 null，如果来自网络，该对象才有值。使用方法 getRawResponse() 获取该值。

另外，Response 对象还有以下几个方法：

code()：http 协议的响应状态码，如果数据来自网络，无论成功失败，该值都为真实的响应码，如果数据来自缓存，该值一直为 -1；
message()：http 协议对响应状态码的描述信息，如果数据来自网络，无论成功失败，该值都为真实的描述信息，如果数据来自缓存，该值一直为 null；
headers()：服务端返回的响应头信息，如果数据来自网络，无论成功失败，该值都为真实的头信息，如果数据来自缓存，该值一直为 null；
isSuccessful()：本次请求是否成功，判断依据是：是否发生了异常。

3. 基本请求

无论做什么请求，第一行的泛型一定要加！

那么我们不可能每次请求都写上面那么一大堆，这里可以看到，一次简单的请求，这么写就够了。

4. 请求 Bitmap

如果你知道你的请求数据是图片，可以使用这样的方法：

5. 基本文件下载

如果你要下载文件，可以这么写。

FileCallback 具有三个重载的构造方法，分别是

FileCallback()：空参构造
FileCallback(String destFileName)：可以额外指定文件下载完成后的文件名
FileCallback(String destFileDir, String destFileName)：可以额外指定文件的下载目录和下载完成后的文件名

文件目录如果不指定，默认下载的目录为 sdcard/download/，文件名如果不指定，则按照以下规则命名：

首先检查用户是否传入了文件名，如果传入，将以用户传入的文件名命名

如果没有传入,那么将会检查服务端返回的响应头是否含有
Content-Disposition=attachment;filename=FileName.txt 该种形式的响应头，如果有，则按照该响应头中指定的文件名命名文件，如 FileName.txt；

如果上述响应头不存在，则检查下载的文件url，例如：
http://image.baidu.com/abc.jpg，那么将会自动以 abc.jpg 命名文件

如果 url 也不能把文件名解析出来，那么最终将以 "unknownfile_" + System.currentTimeMillis() 命名文件

这里面有个新对象叫 Progress，关于这个对象的解释，看这里我进行了专门的讲解。

6. 上传 String 类型的文本

一般此种用法用于与服务器约定的数据格式，当使用该方法时，params 中的参数设置是无效的，所有参数均需要通过需要上传的文本中指定，此外，额外指定的 header 参数仍然保持有效。

默认会携带以下请求头：

Content-Type: text/plain;charset=utf-8

如果你对请求头有自己的要求，可以使用这个重载的形式，传入自定义的 content-type：

// 比如上传 xml 数据，就可以自己指定请求头：
upString("这是要上传的长文本数据！",MediaType.parse("application/xml"))

7. 上传 JSON 类型的文本

该方法与 upString 没有本质区别，只是数据格式是 json,一般来说，需要自己创建一个实体 bean 或者一个 map，把需要的参数设置进去，然后通过三方的 Gson 或者 fastjson 转换成 json 对象，最后直接使用该方法提交到服务器。

默认会携带以下请求头，请不要手动修改，okgo 也不支持自己修改

Content-Type: application/json;charset=utf-8

8. 上传文件

上传文件支持文件与参数一起同时上传，也支持一个 key 上传多个文件，以下方式可以任选。

特别要注意的是：

很多人会说需要在上传文件到时候，要把 Content-Type
修改掉，变成 multipart/form-data，就像下面这样的。其实在使用 OkGo 的时候，只要你添加了文件，这里的的 Content-Type 不需要你手动设置，OkGo 自动添加该请求头，同时，OkGo 也不允许你修改该请求头。