优化和补充框架使用文档

优化框架部分 API 命名优化延迟异步请求代码的写法新增支持自定义 Content-Type 新增全局下载开始和成功回调方法
getActivity · Dec 11, 2022 · ead06c8 · ead06c8
1 parent 4d6d78a
commit ead06c8
Show file tree

Hide file tree

Showing 26 changed files with 492 additions and 197 deletions.
diff --git a/.github/ISSUE_TEMPLATE/issue_template_bug.md b/.github/ISSUE_TEMPLATE/issue_template_bug.md
@@ -22,6 +22,8 @@ assignees: getActivity
 
 * 出现问题的安卓版本【必填】：请填写出现问题的 Android 版本
 
+* 问题信息的来源渠道【必填】：请填写问题的来源（例如：自己遇到的/Bugly 看到的/用户反馈等等）
+
 #### 请回答
 
 * 是部分机型还是所有机型都会出现【必答】：部分/全部（例如：某为，某 Android 版本会出现）
@@ -34,7 +36,7 @@ assignees: getActivity
 
 * 是否可以通过 Demo 来复现该问题【必答】：是/否（排查一下是不是自己的项目代码写得有问题导致的）
 
-* 这个问题是不是后台自己的问题导致的【必答】：是/否（如果无法确定问题的原因，请先和后台开发人员协商联调，确认了问题是框架的再反馈给作者，如果是后台的问题作者也没用，最后还是要自己找后台处理才有用的）
+* 这个问题是不是后台自己的问题导致的【必答】：是/否（如果无法确定问题的原因，请先和后台开发人员协商联调，确认了问题是框架的再反馈给作者，如果是后台的问题找框架作者也没用，最后还是要自己找后台处理才有用的）
 
 #### 其他
 

diff --git a/HelpDoc.md b/HelpDoc.md
@@ -22,13 +22,13 @@
 
     * [下载文件](#下载文件)
 
-    * [同步请求](#同步请求)
+    * [分区存储适配](#分区存储适配)
 
-    * [请求缓存](#请求缓存)
+    * [发起同步请求](#发起同步请求)
 
-    * [搭配协程使用](#搭配协程使用)
+    * [设置请求缓存](#设置请求缓存)
 
-    * [分区存储适配](#分区存储适配)
+    * [搭配协程使用](#搭配协程使用)
 
 * [疑难解答](#疑难解答)
 
@@ -94,6 +94,10 @@
 
     * [我想自定义一个 RequestBody 进行请求该怎么办](#我想自定义一个-requestbody-进行请求该怎么办)
 
+    * [我想自定义请求头中的 ContentType 该怎么做](#我想自定义请求头中的-contenttype-该怎么做)
+
+    * [我想自定义 Get 请求参数中的 key 和 value 该怎么做](#我想自定义-get-请求参数中的-key-和-value-该怎么做)
+
 * [搭配 RxJava](#搭配-rxjava)
 
     * [准备工作](#准备工作)
@@ -169,9 +173,9 @@ OkHttpClient okHttpClient = new OkHttpClient.Builder()
 EasyConfig.with(okHttpClient)
         // 是否打印日志
         .setLogEnabled(BuildConfig.DEBUG)
-        // 设置服务器配置
+        // 设置服务器配置（必须设置）
         .setServer(server)
-        // 设置请求处理策略
+        // 设置请求处理策略（必须设置）
         .setHandler(new RequestHandler())
         // 设置请求重试次数
         .setRetryCount(3)
@@ -413,7 +417,38 @@ EasyHttp.download(this)
         }).start();
 ```
 
-#### 同步请求
+#### 分区存储适配
+
+* 在 Android 10 之前，我们在读写外部存储的时候，可以直接使用 File 对象来上传或者下载文件，但是在 Android 10 之后，如果你的项目需要 Android 10 分区存储的特性，那么在读写外部存储文件的时候，就不能直接使用 File 对象，因为 `ContentResolver.insert` 返回是一个 `Uri` 对象，这个时候就需要使用到框架提供的 `FileContentResolver` 对象了（这个对象是 File 的子类），具体使用案例如下：
+
+```java
+File outputFile;
+if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+    ContentValues values = new ContentValues();
+    .........
+    // 生成一个新的 uri 路径
+    Uri outputUri = getContentResolver().insert(MediaStore.Xxx.Media.EXTERNAL_CONTENT_URI, values);
+    // 适配 Android 10 分区存储特性
+    outputFile = new FileContentResolver(context, outputUri);
+} else {
+    outputFile = new File(xxxx);
+}
+
+EasyHttp.post(this)
+        .api(new XxxApi()
+                .setImage(outputFile))
+        .request(new HttpCallback<Xxx <Xxx>>(this) {
+
+            @Override
+            public void onSucceed(Xxx<Xxx> data) {
+
+            }
+        });
+```
+
+* 这是上传的案例，下载也同理，这里不再赘述。
+
+#### 发起同步请求
 
 * 需要注意的是：同步请求是耗时操作，不能在主线程中执行，请务必保证此操作在子线程中执行
 
@@ -430,7 +465,7 @@ try {
 }
 ```
 
-#### 请求缓存
+#### 设置请求缓存
 
 * 需要先实现读取和写入缓存的接口，如果已配置则可以跳过，这里以 MMKV 为例
 
@@ -615,37 +650,6 @@ lifecycleScope.launch(Dispatchers.IO) {
 
 * 如果你对协程的使用不太熟悉，推荐你看一下[这篇文章](https://www.jianshu.com/p/2e0746c7d4f3)
 
-#### 分区存储适配
-
-* 在 Android 10 之前，我们在读写外部存储的时候，可以直接使用 File 对象来上传或者下载文件，但是在 Android 10 之后，如果你的项目需要 Android 10 分区存储的特性，那么在读写外部存储文件的时候，就不能直接使用 File 对象，因为 `ContentResolver.insert` 返回是一个 `Uri` 对象，这个时候就需要使用到框架提供的 `FileContentResolver` 对象了（这个对象是 File 的子类），具体使用案例如下：
-
-```java
-File outputFile;
-if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
-    ContentValues values = new ContentValues();
-    .........
-    // 生成一个新的 uri 路径
-    Uri outputUri = getContentResolver().insert(MediaStore.Xxx.Media.EXTERNAL_CONTENT_URI, values);
-    // 适配 Android 10 分区存储特性
-    outputFile = new FileContentResolver(context, outputUri);
-} else {
-    outputFile = new File(xxxx);
-}
-
-EasyHttp.post(this)
-        .api(new XxxApi()
-                .setImage(outputFile))
-        .request(new HttpCallback<Xxx <Xxx>>(this) {
-
-            @Override
-            public void onSucceed(Xxx<Xxx> data) {
-
-            }
-        });
-```
-
-* 这是上传的案例，下载也同理，这里不再赘述。
-
 # 疑难解答
 
 #### 如何设置 Cookie
@@ -1423,10 +1427,11 @@ parameter.put("key1", value1);
 parameter.put("key2", value2);
 
 String json = gson.toJson(parameter);
+JsonBody jsonBody = new JsonBody(json)
 
 EasyHttp.post(this)
         .api(new XxxApi())
-        .body(new JsonBody(json))
+        .body(jsonBody)
         .request(new HttpCallback<HttpData<Xxx>>(this) {
 
             @Override
@@ -1438,7 +1443,7 @@ EasyHttp.post(this)
 
 #### 如何设置自定义的 UA 标识
 
-* 首先 UA 是 User Agent 的简称，当我们没有设置自定义 UA 标识的时候，那么 OkHttp 会在 BridgeInterceptor 拦截器添加一个默认的 UA 标识，那么如何在 EasyHttp 设置自定义 UA 标识呢？其实很简单，UA 标识本质上其实就是一个请求头，在 EasyHttp 中添加一个请求头为 `"User-Agent` 的参数即可，至于怎么添加请求头，前面的文档已经有介绍了，这里不再赘述。
+* 首先 UA 是 User Agent 的简称，当我们没有设置自定义 UA 标识的时候，那么 OkHttp 会在 BridgeInterceptor 拦截器添加一个默认的 UA 标识，那么如何在 EasyHttp 设置自定义 UA 标识呢？其实很简单，UA 标识本质上其实就是一个请求头，在 EasyHttp 中添加一个请求头为 `User-Agent` 的参数即可，至于怎么添加请求头，前面的文档已经有介绍了，这里不再赘述。
 
 #### 我想修改请求回调所在的线程该怎么办
 
@@ -1475,6 +1480,103 @@ EasyHttp.post(this)
 
 * 需要注意的是：由于 Post 请求是将参数放置到 `RequestBody` 上面，而一个请求只能设置一个 `RequestBody`，如果你设置了自定义 `body(RequestBody body)`，那么框架将不会去将 `XxxApi` 类中的字段解析成参数。另外除了 Post 请求，Put 请求和 Patch 请求也可以使用这种方式进行设置，这里不再赘述。
 
+#### 我想自定义请求头中的 ContentType 该怎么做
+
+* 具体的写法示例如下：
+
+```java
+public final class SearchBlogsApi implements IRequestApi {
+
+    @NonNull
+    @Override
+    public String getApi() {
+        return "xxx/xxx";
+    }
+
+    @HttpHeader
+    @HttpRename("Content-Type")
+    private String contentType = "application/x-www-form-urlencoded;charset=utf-8";
+}
+```
+
+* 需要注意的是：此功能仅是在框架 **11.5** 版本的时候加上的，之前的版本没有这一功能
+
+#### 我想自定义 Get 请求参数中的 key 和 value 该怎么做
+
+* 先自定义一个 Api 类，然后通过 `getApi` 方法将参数动态拼接上去
+
+```java
+public final class CustomParameterApi implements IRequestApi {
+
+   @HttpIgnore
+   @NonNull
+   private final Map<String, String> parameters;
+
+   public CustomParameterApi() {
+      this(new HashMap<>());
+   }
+
+   public CustomParameterApi(@NonNull Map<String, String> parameters) {
+      this.parameters = parameters;
+   }
+
+   @NonNull
+   @Override
+   public String getApi() {
+      Set<String> keys = parameters.keySet();
+
+      StringBuilder builder = new StringBuilder();
+      int index = 0;
+      for (String key : keys) {
+         String value = parameters.get(key);
+
+         if (index == 0) {
+            builder.append("?");
+         }
+         builder.append(key)
+                 .append("=")
+                 .append(value);
+         if (index < keys.size() - 1) {
+            builder.append("&");
+         }
+         index++;
+      }
+
+      return "xxx/xxx" + builder;
+   }
+
+   public CustomParameterApi putParameter(String key, String value) {
+      parameters.put(key, value);
+      return this;
+   }
+
+   public CustomParameterApi removeParameter(String key) {
+      parameters.remove(key);
+      return this;
+   }
+}
+```
+
+* 外层可以通过以下方式进行调用
+
+```java
+CustomParameterApi api = new CustomParameterApi();
+api.putParameter("key1", "value1");
+api.putParameter("key2", "value2");
+
+EasyHttp.get(this)
+        .api(api)
+        .request(new HttpCallback<Xxx>(this) {
+
+            @Override
+            public void onSucceed(Xxx result) {
+
+            }
+        });
+```
+
+* 需要注意的是：这种实现方式仅适用于在框架设计无法满足需求的情况下，其他情况下作者并不提倡用这种方式，因为这样不方便管理请求参数的 key，还是推荐大家使用在类上面定义字段的方式来实现。
+
 # 搭配 RxJava
 
 #### 准备工作

diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
 # 简单易用的网络框架
 
-* 项目地址：[Github](https://github.com/getActivity/EasyHttp)、[码云](https://gitee.com/getActivity/EasyHttp)
+* 项目地址：[Github](https://github.com/getActivity/EasyHttp)
 
 * 博客地址：[网络请求，如斯优雅](https://www.jianshu.com/p/93cd59dec002)
 
-* 可以扫码下载 Demo 进行演示或者测试，如果扫码下载不了的，[点击此处下载Demo](https://github.com/getActivity/EasyHttp/releases/download/11.2/EasyHttp.apk)
+* 可以扫码下载 Demo 进行演示或者测试，如果扫码下载不了的，[点击此处下载Demo](https://github.com/getActivity/EasyHttp/releases/download/11.5/EasyHttp.apk)
 
 ![](picture/demo_code.png)
 
@@ -61,7 +61,7 @@ android {
 
 dependencies {
     // 网络请求框架：https://github.com/getActivity/EasyHttp
-    implementation 'com.github.getActivity:EasyHttp:11.2'
+    implementation 'com.github.getActivity:EasyHttp:11.5'
     // OkHttp 框架：https://github.com/square/okhttp
     // noinspection GradleDependency
     implementation 'com.squareup.okhttp3:okhttp:3.12.13'
@@ -76,7 +76,7 @@ dependencies {
 
 |  功能或细节  | [EasyHttp](https://github.com/getActivity/EasyHttp) | [Retrofit](https://github.com/square/retrofit)  | [OkGo](https://github.com/jeasonlzy/okhttp-OkGo) |
 | :----: | :------: |  :-----: |  :-----: |
-|    对应版本  |  11.2 |  2.9.0  |  3.0.4    |
+|    对应版本  |  11.5 |  2.9.0  |  3.0.4    |
 |    issues 数   |  [![](https://img.shields.io/github/issues/getActivity/EasyHttp.svg)](https://github.com/getActivity/EasyHttp/issues)  |  [![](https://img.shields.io/github/issues/square/retrofit.svg)](https://github.com/square/retrofit/issues)  |  [![](https://img.shields.io/github/issues/jeasonlzy/okhttp-OkGo.svg)](https://github.com/jeasonlzy/okhttp-OkGo/issues)  |
 |    **aar 包大小**  |  86 KB  | 123 KB  |  131 KB  |
 |    minSdk 要求  |  API 14+ |  API 21+  |  API 14+   |
@@ -241,6 +241,8 @@ EasyHttp.post(this)
 
 * Android 代码规范：[AndroidCodeStandard](https://github.com/getActivity/AndroidCodeStandard) ![](https://img.shields.io/github/stars/getActivity/AndroidCodeStandard.svg) ![](https://img.shields.io/github/forks/getActivity/AndroidCodeStandard.svg)
 
+* Android 资源大汇总：[AndroidIndex](https://github.com/getActivity/AndroidIndex) ![](https://img.shields.io/github/stars/getActivity/AndroidIndex.svg) ![](https://img.shields.io/github/forks/getActivity/AndroidIndex.svg)
+
 * Android 开源排行榜：[AndroidGithubBoss](https://github.com/getActivity/AndroidGithubBoss) ![](https://img.shields.io/github/stars/getActivity/AndroidGithubBoss.svg) ![](https://img.shields.io/github/forks/getActivity/AndroidGithubBoss.svg)
 
 * Studio 精品插件：[StudioPlugins](https://github.com/getActivity/StudioPlugins) ![](https://img.shields.io/github/stars/getActivity/StudioPlugins.svg) ![](https://img.shields.io/github/forks/getActivity/StudioPlugins.svg)

diff --git a/app/build.gradle b/app/build.gradle
@@ -1,6 +1,7 @@
 apply plugin: 'com.android.application'
 apply plugin: 'kotlin-android'
 apply plugin: 'kotlin-android-extensions'
+apply plugin: 'monitor-plugin'
 
 android {
     compileSdkVersion 31
@@ -11,10 +12,10 @@ android {
 
     defaultConfig {
         applicationId 'com.hjq.easy.demo'
-        minSdkVersion 16
+        minSdkVersion 21
         targetSdkVersion 31
-        versionCode 1120
-        versionName '11.2'
+        versionCode 1150
+        versionName '11.5'
     }
 
     // 支持 JDK 1.8
@@ -72,25 +73,28 @@ dependencies {
     implementation 'com.squareup.okhttp3:okhttp:3.12.13'
 
     // 吐司框架：https://github.com/getActivity/ToastUtils
-    implementation 'com.github.getActivity:ToastUtils:10.5'
+    implementation 'com.github.getActivity:ToastUtils:11.2'
 
     // 权限请求框架：https://github.com/getActivity/XXPermissions
-    implementation 'com.github.getActivity:XXPermissions:15.0'
+    implementation 'com.github.getActivity:XXPermissions:16.5'
 
     // 标题栏框架：https://github.com/getActivity/TitleBar
-    implementation 'com.github.getActivity:TitleBar:9.5'
+    implementation 'com.github.getActivity:TitleBar:9.6'
 
     // Json 解析框架：https://github.com/google/gson
-    implementation 'com.google.code.gson:gson:2.9.0'
+    implementation 'com.google.code.gson:gson:2.9.1'
     // Gson 解析容错：https://github.com/getActivity/GsonFactory
-    implementation 'com.github.getActivity:GsonFactory:6.2'
+    implementation 'com.github.getActivity:GsonFactory:6.3'
 
     // 腾讯 MMKV：https://github.com/Tencent/MMKV
-    implementation 'com.tencent:mmkv-static:1.2.12'
+    implementation 'com.tencent:mmkv-static:1.2.14'
 
     // 日志调试框架：https://github.com/getActivity/Logcat
-    debugImplementation 'com.github.getActivity:Logcat:10.6'
+    debugImplementation 'com.github.getActivity:Logcat:11.0'
+
+    // OkHttp 抓包框架：https://github.com/lygttpod/AndroidMonitor
+    debugImplementation 'io.github.lygttpod:monitor:0.0.7'
 
     // 内存泄漏监测框架：https://github.com/square/leakcanary
-    debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.8.1'
+    debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.10'
 }
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
@@ -42,6 +42,11 @@
             android:name="LogcatNotifyEntrance"
             android:value="true" />
 
+        <!-- 默认搜索关键字 -->
+        <meta-data
+            android:name="LogcatDefaultSearchKey"
+            android:value="EasyHttp" />
+
         <!-- 适配 Android 7.0 文件意图 -->
         <provider
             android:name="androidx.core.content.FileProvider"

diff --git a/app/src/main/java/com/hjq/easy/demo/AppApplication.java b/app/src/main/java/com/hjq/easy/demo/AppApplication.java
@@ -46,9 +46,9 @@ public void onCreate() {
         EasyConfig.with(okHttpClient)
                 // 是否打印日志
                 //.setLogEnabled(BuildConfig.DEBUG)
-                // 设置服务器配置
+                // 设置服务器配置（必须设置）
                 .setServer(server)
-                // 设置请求处理策略
+                // 设置请求处理策略（必须设置）
                 .setHandler(new RequestHandler(this))
                 // 设置请求参数拦截器
                 .setInterceptor(new IRequestInterceptor() {