OkHttpUtils的使用以及帶進度條的回撥StringDialogCallback
1.OkHttpUtils 目前支援
- 一般的 get,post,put,delete,head,options請求
- 基於Post的大文字資料上傳
- 多檔案和多引數統一的表單上傳
- 支援一個key上傳一個檔案,也可以一個Key上傳多個檔案
- 大檔案下載和下載進度回撥
- 大檔案上傳和上傳進度回撥
- 支援cookie的記憶體儲存和持久化儲存,支援傳遞自定義cookie
- 支援304快取協議,擴充套件四種本地快取模式,並且支援快取時間控制
- 支援301、302重定向
- 支援鏈式呼叫
- 支援可信證書和自簽名證書的https的訪問,支援雙向認證
- 支援根據Tag取消請求
- 支援自定義泛型Callback,自動根據泛型返回物件
2.OkHttpServer 擴充套件功能
2.1 統一的檔案下載管理(DownloadManager):
- 結合OkHttpUtils 的request進行網路請求,支援與OkHttpUtils 保持相同的全域性公共引數,同時支援請求傳遞引數
- 支援斷點下載,支援突然斷網,強殺程序後,斷點依然有效
- 支援 下載 暫停 等待 停止 出錯 完成 六種下載狀態
- 所有下載任務按照taskKey區分,切記不同的任務必須使用不一樣的key,否者斷點會發生覆蓋
- 相同的下載url地址如果使用不一樣的taskKey,也會認為是兩個下載任務
- 默認同時下載數量為3個,預設下載路徑
/storage/emulated/0/download
,下載路徑和下載數量都可以在程式碼中配置 - 下載檔名可以自己定義,也可以不傳,框架自動解析響應頭或者url地址獲得檔名,如果都沒獲取到,使用default作為檔名
- 下載管理使用了服務提高執行緒優先順序,避免後臺下載時被系統回收
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
:如果要做檔案下載,則必須使用該回調,內部封裝了關於檔案下載進度回撥的方法-
package com.hxzh.uniwill.lingjian.json; import android.app.Activity; import android.app.ProgressDialog; import android.support.annotation.Nullable; import android.view.Window; import com.lzy.okhttputils.callback.StringCallback; import com.lzy.okhttputils.request.BaseRequest; /** * ================================================ * 作 者:jeasonlzy(廖子堯) * 版 本:1.0 * 建立日期:2016/4/8 * 描 述:我的Github地址 https://github.com/jeasonlzy * 修訂歷史: * ================================================ */ public abstract class StringDialogCallback extends StringCallback { private ProgressDialog dialog; public StringDialogCallback(Activity activity) { dialog = new ProgressDialog(activity); dialog.requestWindowFeature(Window.FEATURE_NO_TITLE); dialog.setCanceledOnTouchOutside(false); dialog.setProgressStyle(ProgressDialog.STYLE_SPINNER); dialog.setMessage("請求網路中..."); } @Override public void onBefore(BaseRequest request) { super.onBefore(request); //網路請求前顯示對話方塊 if (dialog != null && !dialog.isShowing()) { dialog.show(); } } @Override public void onAfter(@Nullable String s, @Nullable Exception e) { super.onAfter(s, e); //網路請求結束後關閉對話方塊 if (dialog != null && dialog.isShowing()) { dialog.dismiss(); } } }
該網路框架的核心使用方法即為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
三個方法進行具體判斷。