OkGO一個專注於讓網路請求更簡單的框架

阿新 • • 發佈：2019-01-10

1.支援的常用功能

一般的 get,post,put,delete,head,options請求
基於Post的大文字資料上傳，postString(),postJson()等
多檔案和多引數統一的表單上傳（允許監聽上傳進度）
支援一個key上傳一個檔案，也可以一個Key上傳多個檔案
大檔案下載和下載進度回撥
大檔案上傳和上傳進度回撥
支援cookie的記憶體儲存和持久化儲存，支援傳遞自定義cookie
提供網路快取功能，預設支援304快取協議，並額外擴充套件了三種本地快取模式
支援301、302重定向
支援鏈式呼叫
支援可信證書和自簽名證書的https訪問
支援根據Tag取消網路請求
支援自定義泛型Callback，自動根據泛型返回物件

2.支援的擴充套件功能

統一的檔案下載管理（DownloadManager）
預設使用的是 get 請求，同時下載數量為3個，支援斷點下載，斷點資訊使用ORMLite資料庫框架儲存，預設下載路徑/storage/emulated/0/download，下載路徑和下載數量都可以在程式碼中配置，下載管理使用了服務提高執行緒優先順序，避免後臺下載時被系統回收。
當你的專案需要做大量的下載的時候，並且多個頁面需要監聽下載進度，使用該擴充套件讓你更方便。原生支援下載任務的開始、暫停、停止、出錯、完成五個狀態，當同時下載任務數量超過3個（可程式碼動態設定）時，後續任務自動等待，當有任務下載完成時，等待任務按照優先順序自動開始下載。

統一的檔案上傳管理（UploadManager）
預設使用的是 post 上傳請求，該上傳管理為簡單管理，不支援斷點續傳和分片上傳，只是簡單的將所有上傳任務使用執行緒池進行了統一管理，默認同時上傳數量為1個。由於斷點分片上傳的技術需要大量的服務端程式碼配合，同時也會極大的增加客戶端程式碼量，所以綜合考慮，該框架不做實現。如果確實有特殊需要，可以自己做擴充套件。

2.2 統一的檔案上傳管理(UploadManager)

結合OkHttpUtils 的request進行網路請求,支援與OkHttpUtils 保持相同的全域性公共引數,同時支援請求傳遞引數
上傳只能使用Post, Put, Delete

, Options 這四種請求,不支援Get, Head
該上傳管理為簡單管理，不支援斷點續傳或分片上傳，只是簡單的將所有上傳任務使用執行緒池進行了統一管理
默認同時上傳數量為1個,該數列可以在程式碼中配置修改
由於斷點分片上傳的技術需要大量的服務端程式碼配合，同時也會極大的增加客戶端程式碼量，所以綜合考慮，該框架不做實現。如果確實有特殊需要，可以自己做擴充套件。

專案的效果圖如下：

專案主頁

請求詳細資訊

下載管理列表頁

下載管理詳情頁

上傳管理和圖片選擇

3.如何選擇網路框架

說了這麼多功能，我們來看看為什麼要使用OkHttpUtils這個框架。
首先目前主流的幾個網路框架

android-async-http
xUtils
volley
retrofit
okhttp

在此引用知乎上Stay Zhang的回答：

我們來先說一個常識性的錯誤：volley, retrofit, android-async-http 幫你封裝了具體的請求，執行緒切換以及資料轉換。而OkHttp 是基於http協議封裝的一套請求客戶端，雖然它也可以開執行緒，但根本上它更偏向真正的請求，跟HttpClient, HttpUrlConnection的職責是一樣的。

所以不要混淆。

-----以下純個人主觀見解
首先，我想即使你單純使用OkHttp，還是會再包一層的，這樣就等價於Volley之流的框架，只是封裝的好與壞而已。

android-async-http內部實現是基於HttpClient, 想必你肯定知道6.0之後HttpClient是不是系統自帶的了，不過它在最近的更新中將HttpClient的所有程式碼copy了一份進來，所以還能使用。

Volley是官方出的，volley在設計的時候是將具體的請求客戶端做了下封裝：HurlStack，也就是說可以支援HttpUrlConnection, HttpClient, OkHttp，相當於模版模式吧，這樣解耦還是非常方便的，可以隨意切換，如果你之前使用過Volley，並習慣使用，那直接寫個OkHttp擴充套件就行了。

Retrofit因為也是square出的，所以大家可能對它更崇拜些。Retrofit的跟Volley是一個套路，但解耦的更徹底:比方說通過註解來配置請求引數，通過工廠來生成CallAdapter，Converter，你可以使用不同的請求介面卡(CallAdapter), 比方說RxJava，Java8, Guava。你可以使用不同的反序列化工具(Converter)，比方說json, protobuff, xml, moshi等等。關鍵是想要用好這個框架，最好是和RxJava聯用，否者和普通的網路框架也沒什麼區別，而對於RxJava，特別team人數多的情況下，總得有個完全精通的吧，萬一掉坑裡了呢。。。

4.OkHttpUtils的優勢

優勢一：效能高，專注於簡單易用的網路請求，使用主流的okhttp進行封裝，對於okhttp大家都知道，在Android4.4的原始碼中可以看到HttpURLConnection已經替換成OkHttp實現了，並且支援HTTP2/SPDY黑科技，支援socket自動選擇最好路線，並支援自動重連，擁有自動維護的socket連線池，減少握手次數，擁有佇列執行緒池，輕鬆寫併發。
優勢二：特有的網路快取模式，是大多數網路框架所不具備的，說一個應用場景，老闆說我們的app不僅需要在有網的情況下展示最新的網路資料，還要在沒網的情況下使用快取資料，這時候是不是專案中出現了大量的程式碼判斷當前網路狀況，根據不同的狀態儲存不同的資料，然後決定是否使用快取。細想一下，這是個通用的寫法，於是OkHttpUtils提供了四種快取模式，讓你不用關心快取的實現，而專注於資料的處理。（具體快取的使用方法請看最後第四章節）。
優勢三：方便易用的擴充套件介面，可以新增全域性的公共引數，全域性攔截器，全域性超時時間，更可以對單個請求定製攔截器，超時時間，請求引數修改等等，在使用上更是方便，原生支援的鏈式呼叫讓你的請求更加清晰。
優勢四：強大的Cookie保持策略，我們知道在客戶端對cookie的獲取是個不太簡單的事情，特別是還要處理cookie的過期時間，持久化策略等等，OkHttpUtils幫你徹底解決Cookie的難題，預設擁有記憶體儲存和持久化儲存兩種實現，cookie全程自動管理，並且提供了額外的addCookie方式，允許介入到自動管理的過程中，新增你想建立的任何cookie。

所以就說這麼多啦，選最適合專案的，選大多數人選擇的，選簡單易用的，就這麼個標準，而OkHttpUtils正是在這種情況下誕生啦！！

5.使用方法

對於Android Studio的使用者，可以選擇新增:

  compile 'com.lzy.net:okhttputils:1.8.1'  //可以單獨使用，不需要依賴下方的擴充套件包
  compile 'com.lzy.net:okhttpserver:1.0.3' //擴充套件了下載管理和上傳管理，根據需要新增

  compile 'com.lzy.net:okhttputils:+'  //版本號使用 + 可以自動引用最新版
  compile 'com.lzy.net:okhttpserver:+' //版本號使用 + 可以自動引用最新版

為了方便大家使用，更加通俗的理解http的網路協議，建議做網路請求的時候，對每個請求抓包後檢視請求資訊和響應資訊。
如果是 Windows 作業系統，可以使用 Fiddler 對手機的請求進行抓包檢視。
如果是 Mac OS 作業系統，可以使用 Charles 對手機的請求進行抓包檢視。
具體的下載地址和抓包配置方法，我這就不提供了，請自行百度或谷歌。

6.使用注意事項

okhttputils使用的okhttp的版本是最新的 3.4.1 版本，和以前的 2.x 的版本可能會存在衝突。
okhttpserver是對okhttputils的擴充套件，統一了下載管理和上傳管理，對專案有需要做統一下載的可以考慮使用該擴充套件，不需要的可以直接使用okhttputils即可。
對於快取模式使用，需要與返回物件相關的所有javaBean必須實現Serializable介面，否者會報NotSerializableException。
使用快取時，如果不指定cacheKey，預設是用url帶引數的全路徑名為cacheKey。
使用該網路框架時，必須要在 Application 中做初始化 OkHttpUtils.init(this);。

一、全域性配置

一般在 Aplication，或者基類中，只需要呼叫一次即可，可以配置除錯開關，全域性的超時時間，公共的請求頭和請求引數等資訊，所有的請求引數都支援中文，

    @Override
    public void onCreate() {
        super.onCreate();

        HttpHeaders headers = new HttpHeaders();
        headers.put("commonHeaderKey1", "commonHeaderValue1");    //所有的 header 都 不支援 中文
        headers.put("commonHeaderKey2", "commonHeaderValue2");
        HttpParams params = new HttpParams();
        params.put("commonParamsKey1", "commonParamsValue1");     //所有的 params 都 支援 中文
        params.put("commonParamsKey2", "這裡支援中文引數");

        //必須呼叫初始化
        OkHttpUtils.init(this);
        //以下都不是必須的，根據需要自行選擇
        OkHttpUtils.getInstance()//
                .debug("OkHttpUtils")                                              //是否開啟除錯
                .setConnectTimeout(OkHttpUtils.DEFAULT_MILLISECONDS)               //全域性的連線超時時間
                .setReadTimeOut(OkHttpUtils.DEFAULT_MILLISECONDS)                  //全域性的讀取超時時間
                .setWriteTimeOut(OkHttpUtils.DEFAULT_MILLISECONDS)                 //全域性的寫入超時時間
              //.setCookieStore(new MemoryCookieStore())                           //cookie使用記憶體快取（app退出後，cookie消失）
              //.setCookieStore(new PersistentCookieStore())                       //cookie持久化儲存，如果cookie不過期，則一直有效
                .addCommonHeaders(headers)                                         //設定全域性公共頭
                .addCommonParams(params);                                          //設定全域性公共引數
    }

二、普通請求

1.基本的網路請求

OkHttpUtils.get(Urls.URL_METHOD)     // 請求方式和請求url
    .tag(this)                       // 請求的 tag, 主要用於取消對應的請求
    .cacheKey("cacheKey")            // 設定當前請求的快取key,建議每個不同功能的請求設定一個
    .cacheMode(CacheMode.DEFAULT)    // 快取模式，詳細請看快取介紹
    .execute(new JsonCallback<RequestInfo>(RequestInfo.class) {
        @Override
        public void onResponse(boolean isFromCache, RequestInfo requestInfo, Request request, @Nullable Response response) {
            // requestInfo 物件即為所需要的結果物件
        }
    });

2.請求 Bitmap 物件

OkHttpUtils.get(Urls.URL_IMAGE)//
    .tag(this)//
    .execute(new BitmapCallback() {
        @Override
        public void onResponse(boolean isFromCache, Bitmap bitmap, Request request, @Nullable Response response) {
        // bitmap 即為返回的圖片資料
        }
    });

3.請求檔案下載

OkHttpUtils.get(Urls.URL_DOWNLOAD)//
    .tag(this)//
    .execute(new FileCallback("/sdcard/temp/", "file.jpg") {  //檔案下載時，需要指定下載的檔案目錄和檔名
        @Override
        public void onResponse(boolean isFromCache, File file, Request request, @Nullable Response response) {
        // file 即為檔案資料，檔案儲存在指定布幕
        }
    });

4.普通Post，直接上傳String型別的文字

一般此種用法用於與伺服器約定的資料格式，當使用該方法時，params中的引數設定是無效的，所有引數均需要通過需要上傳的文字中指定，此外，額外指定的header引數仍然保持有效。

OkHttpUtils.post(Urls.URL_TEXT_UPLOAD)//
    .tag(this)//
    .postString("這是要上傳的長文字資料！")//
    .execute(new StringCallback() {
        @Override
        public void onResponse(boolean isFromCache, String s, Request request, @Nullable Response response) {
            //上傳成功
        }
    });

5.普通Post，直接上傳Json型別的文字

該方法與postString沒有本質區別，只是資料格式是json,一般來說，需要自己建立一個實體bean或者一個map，把需要的引數設定進去，然後通過三方的Gson或者fastjson轉換成json字串，最後直接使用該方法提交到伺服器。

OkHttpUtils.post(Urls.URL_TEXT_UPLOAD)//
    .tag(this)//
    .postJson("{\"des\": \"這裡面要寫標準的json格式資料\"}")//
    .execute(new StringCallback() {
        @Override
        public void onResponse(boolean isFromCache, String s, Request request, @Nullable Response response) {
            //上傳成功
        }
    });

6.請求功能的所有配置講解

以下程式碼包含了以下內容：

一次普通請求所有能配置的引數，真實使用時不需要配置這麼多，按自己的需要選擇性的使用即可
多檔案和多引數的表單上傳，同時支援進度監聽
自簽名網站https的訪問，呼叫setCertificates方法即可
為單個請求設定超時，比如涉及到檔案的需要設定讀寫等待時間多一點。
Cookie一般情況下只需要在初始化的時候呼叫setCookieStore即可實現cookie的自動管理，如果特殊業務需要，需要手動額外向伺服器傳遞自定義的cookie，可以在每次請求的時候呼叫addCookie方法，該方法提供了3個過載形式，可以根據自己的需要選擇使用。

OkHttpUtils.get(Urls.URL_METHOD) // 請求方式和請求url, get請求不需要拼接引數，支援get，post，put，delete，head，options請求
    .tag(this)               // 請求的 tag, 主要用於取消對應的請求
    .connTimeOut(10000)      // 設定當前請求的連線超時時間
    .readTimeOut(10000)      // 設定當前請求的讀取超時時間
    .writeTimeOut(10000)     // 設定當前請求的寫入超時時間
    .cacheKey("cacheKey")    // 設定當前請求的快取key,建議每個不同功能的請求設定一個
    .cacheMode(CacheMode.FIRST_CACHE_THEN_REQUEST) // 快取模式，詳細請看第四部分，快取介紹
    .setCertificates(getAssets().open("srca.cer")) // 自簽名https的證書，可變引數，可以設定多個
    .addInterceptor(interceptor)            // 新增自定義攔截器
    .headers("header1", "headerValue1")     // 新增請求頭引數
    .headers("header2", "headerValue2")     // 支援多請求頭引數同時新增
    .params("param1", "paramValue1")        // 新增請求引數
    .params("param2", "paramValue2")        // 支援多請求引數同時新增
    .params("file1", new File("filepath1")) // 可以新增檔案上傳
    .params("file2", new File("filepath2")) // 支援多檔案同時新增上傳
    .addUrlParams("key", List<String> values)  //這裡支援一個key傳多個引數
    .addFileParams("key", List<File> files)    //這裡支援一個key傳多個檔案
    .addFileWrapperParams("key", List<HttpParams.FileWrapper> fileWrappers) //這裡支援一個key傳多個檔案
    .addCookie("aaa", "bbb")                // 這裡可以傳遞自己想傳的Cookie
    .addCookie(cookie)                      // 可以自己構建cookie
    .addCookies(cookies)                    // 可以一次傳遞批量的cookie
     //這裡給出的泛型為 RequestInfo，同時傳遞一個泛型的 class物件，即可自動將資料結果轉成物件返回
    .execute(new DialogCallback<RequestInfo>(this, RequestInfo.class) {
        @Override
        public void onBefore(BaseRequest request) {
            // UI執行緒 請求網路之前呼叫
            // 可以顯示對話方塊，新增/修改/移除 請求引數
        }

        @Override
        public RequestInfo parseNetworkResponse(Response response) throws Exception{
            // 子執行緒，可以做耗時操作
            // 根據傳遞進來的 response 物件，把資料解析成需要的 RequestInfo 型別並返回
            // 可以根據自己的需要，丟擲異常，在onError中處理
            return null;
        }

        @Override
        public void onResponse(boolean isFromCache, RequestInfo requestInfo, Request request, @Nullable Response response) {
            // UI 執行緒，請求成功後回撥
            // isFromCache 表示當前回撥是否來自於快取
            // requestInfo 返回泛型約定的實體型別引數
            // request     本次網路的請求資訊，如果需要檢視請求頭或請求引數可以從此物件獲取
            // response    本次網路訪問的結果物件，包含了響應頭，響應碼等，如果資料來自於快取，該物件為null
        }

        @Override
        public void onError(boolean isFromCache, Call call, @Nullable Response response, @Nullable Exception e) {
            // UI 執行緒，請求失敗後回撥
            // isFromCache 表示當前回撥是否來自於快取
            // call        本次網路的請求物件，可以根據該物件拿到 request
            // response    本次網路訪問的結果物件，包含了響應頭，響應碼等，如果網路異常 或者資料來自於快取，該物件為null
            // e           本次網路訪問的異常資訊，如果伺服器內部發生了錯誤，響應碼為 400~599之間，該異常為 null
        }

        @Override
        public void onAfter(boolean isFromCache, @Nullable RequestInfo requestInfo, Call call, @Nullable Response response, @Nullable Exception e) {
            // UI 執行緒，請求結束後回撥，無論網路請求成功還是失敗，都會呼叫，可以用於關閉顯示對話方塊
            // isFromCache 表示當前回撥是否來自於快取
            // requestInfo 返回泛型約定的實體型別引數，如果網路請求失敗，該物件為　null
            // call        本次網路的請求物件，可以根據該物件拿到 request
            // response    本次網路訪問的結果物件，包含了響應頭，響應碼等，如果網路異常 或者資料來自於快取，該物件為null
            // e           本次網路訪問的異常資訊，如果伺服器內部發生了錯誤，響應碼為 400~599之間，該異常為 null
        }

        @Override
        public void upProgress(long currentSize, long totalSize, float progress, long networkSpeed) {
            // UI 執行緒，檔案上傳過程中回撥，只有請求方式包含請求體才回調（GET,HEAD不會回撥）
            // currentSize  當前上傳的大小（單位位元組）
            // totalSize 　 需要上傳的總大小（單位位元組）
            // progress     當前上傳的進度，範圍　0.0f ~ 1.0f
            // networkSpeed 當前上傳的網速（單位秒）
        }

        @Override
        public void downloadProgress(long currentSize, long totalSize, float progress, long networkSpeed) {
            // UI 執行緒，檔案下載過程中回撥
            //引數含義同　上傳相同
        }
    });

7.取消請求

每個請求前都設定了一個引數tag，取消則通過OkHttpUtils.cancel(tag)執行。
例如：在Activity中，當Activity銷燬取消請求，可以在onDestory裡面統一取消。

    @Override
    protected void onDestroy() {
        super.onDestroy();

        //根據 Tag 取消請求
        OkHttpUtils.getInstance().cancelTag(this);
    }

8.同步的請求

execute方法不傳入callback即為同步的請求，返回Response物件，需要自己解析

    Response response = OkHttpUtils.get("http://www.baidu.com")//
                                    .tag(this)//
                                    .headers("aaa", "111")//
                                    .params("bbb", "222")
                                    .execute();

三、自定義CallBack使用

目前內部提供的包含AbsCallback, StringCallBack ,BitmapCallback ,FileCallBack ,可以根據自己的需求去自定義Callback

AbsCallback: 所有回撥的父類，抽象類
StringCallBack：如果返回值型別是純文字資料，即可使用該回調
BitmapCallback：如果請求的是圖片資料，則可以使用該回調
FileCallBack：如果要做檔案下載，則必須使用該回調，內部封裝了關於檔案下載進度回撥的方法

該網路框架的核心使用方法即為`Callback`的繼承使用，詳細請看 Demo 原始碼中`callback`包下的程式碼。

因為不同的專案需求，可能對資料格式進行了不同的封裝，於是在 Demo 中的進行了詳細的程式碼示例，以下是詳細介紹：

CommonCallback:繼承自AbsCallback,主要作用是做全域性共同請求引數的新增，同樣也可以在第一步全域性配置的時候設定，效果一樣。
EncryptCallback：繼承自CommonCallback,主要功能是做 Url 引數加密，對每個請求的引數進行編碼，防止攔截資料包，篡改資料。
JsonCallback：繼承自EncryptCallback,一般來說，伺服器返回的響應碼都包含 code，msg，data 三部分，在此根據自己的業務需要完成相應的邏輯判斷，並對資料進行解析，可以使用 Gson 或者 fastjson，將解析的物件返回。
DialogCallback：繼承自JsonCallback,對需要在網路請求的時候顯示對話方塊，使用該回調。
StringDialogCallback：繼承自EncryptCallback,如果網路返回的資料只是純文字，使用該回調
BitmapDialogCallback ：繼承自BitmapCallback,如果網路返回的是Bitmap物件，使用該回調
DownloadFileCallBack ：繼承自FileCallback,如果需要做檔案下載，使用該回調

以上基本是包含了大部分的業務邏輯，具體情況請參照demo示例，根據業務需求修改！

四、快取的使用

使用快取前，必須讓快取的資料`javaBean`物件實現`Serializable`介面，否者會報`NotSerializableException`。

因為快取的原理是將物件序列化後直接寫入資料庫中，如果不實現Serializable介面，會導致物件無法序列化，進而無法寫入到資料庫中，也就達不到快取的效果。

目前提供了四種CacheMode快取模式

DEFAULT: 按照HTTP協議的預設快取規則，例如有304響應頭時快取
REQUEST_FAILED_READ_CACHE：先請求網路，如果請求網路失敗，則讀取快取，如果讀取快取失敗，本次請求失敗。該快取模式的使用，會根據實際情況，導致onResponse,onError,onAfter三個方法呼叫不只一次，具體請在三個方法返回的引數中進行判斷。
IF_NONE_CACHE_REQUEST：如果快取不存在才請求網路，否則使用快取。
FIRST_CACHE_THEN_REQUEST：先使用快取，不管是否存在，仍然請求網路，如果網路順利，會導致onResponse方法執行兩次，第一次isFromCache為true，第二次isFromCache為false。使用時根據實際情況，對onResponse,onError,onAfter三個方法進行具體判斷。

無論對於哪種快取模式，都可以指定一個`cacheKey`，建議針對不同需要快取的頁面設定不同的`cacheKey`，如果相同，會導致資料覆蓋。

文／廖子堯（簡書作者）
原文連結：http://www.jianshu.com/p/4c17956fe3b4
著作權歸作者所有，轉載請聯絡作者獲得授權，並標註“簡書作者”。
文／廖子堯（簡書作者）
原文連結：http://www.jianshu.com/p/4c17956fe3b4
著作權歸作者所有，轉載請聯絡作者獲得授權，並標註“簡書作者”。