Update docs about FileCacheStrategy, close #1046

docs/Bots.md

@@ -3,7 +3,19 @@
 **目录**
 
 - [1. 创建和配置 `Bot`](#1-创建和配置-bot)
+  - [配置 Bot](#配置-bot)
+  - [常用配置](#常用配置)
+    - [修改运行目录](#修改运行目录)
+    - [修改 Bot 缓存目录](#修改-bot-缓存目录)
+    - [设备信息](#设备信息)
+    - [切换登录协议](#切换登录协议)
+    - [重定向日志](#重定向日志)
+    - [覆盖登录解决器](#覆盖登录解决器)
+    - [启用列表缓存](#启用列表缓存)
+  - [获取当前所有 `Bot` 实例](#获取当前所有-bot-实例)
 - [2. 登录](#2-登录)
+  - [处理滑动验证码](#处理滑动验证码)
+  - [常见登录失败原因](#常见登录失败原因)
 
 ## 1. 创建和配置 `Bot`
 
@@ -68,7 +80,7 @@ workingDir = File("C:/mirai")
 setWorkingDir(File("C:/mirai"))
 ```
 
-#### 修改缓存目录
+#### 修改 Bot 缓存目录
 
 缓存目录会相对于 `workingDir` 解析。如 `File("cache")` 将会解析为 `workingDir` 内的 `cache` 目录。而 `File("C:/cache")` 将会解析为绝对的 `C:/cache` 目录。
 
@@ -87,6 +99,10 @@ setCacheDir(File("C:/cache")) // 最终为 C:/cache
 
 目前缓存目录会存储列表缓存、登录服务器、资源会话秘钥等。这些数据的存储方式有可能变化，请不要修改缓存目录中的文件。
 
+[FileCacheStrategy]: ../mirai-core-api/src/commonMain/kotlin/utils/FileCacheStrategy.kt#L55
+
+注意，`cacheDir` 仅存储与 Bot 相关的上述信息。其他的如 `InputStream` 的缓存由 [FileCacheStrategy] 管理，默认使用系统临时文件。
+
 #### 设备信息
 Bot 默认使用全随机的设备信息。**在更换账号地点时候使用随机设备信息可能会导致无法登录**，当然，**成功登录时使用的设备信息也可以保存后在新的设备使用**。
 

mirai-core-api/src/commonMain/kotlin/IMirai.kt

@@ -54,6 +54,8 @@ public interface IMirai : LowLevelApiAccessor {
      * Mirai 全局使用的 [FileCacheStrategy].
      *
      * 覆盖后将会立即应用到全局.
+     *
+     * 要覆盖 [FileCacheStrategy],
      */
     public var FileCacheStrategy: FileCacheStrategy
 

mirai-core-api/src/commonMain/kotlin/utils/BotConfiguration.kt

@@ -22,6 +22,7 @@ import net.mamoe.mirai.Bot
 import net.mamoe.mirai.BotFactory
 import net.mamoe.mirai.event.events.BotOfflineEvent
 import java.io.File
+import java.io.InputStream
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.coroutines.coroutineContext
@@ -386,7 +387,18 @@ public open class BotConfiguration { // open for Java
     //////////////////////////////////////////////////////////////////////////
 
     /**
-     * 缓存数据目录, 相对于 [workingDir]
+     * 缓存数据目录, 相对于 [workingDir].
+     *
+     * 缓存目录保存的内容均属于不稳定的 Mirai 内部数据, 请不要手动修改它们. 清空缓存不会影响功能. 只会导致一些操作如读取全部群列表要重新进行.
+     * 默认启用的缓存可以加快登录过程.
+     *
+     * 注意: 这个目录只存储能在 [BotConfiguration] 配置的内容, 即包含:
+     * - 联系人列表
+     * - 登录服务器列表
+     * - 资源服务秘钥
+     *
+     * 其他内容如通过 [InputStream] 发送图片时的缓存使用 [FileCacheStrategy], 默认使用系统临时文件且会在关闭时删除文件.
+     *
      * @since 2.4
      */
     public var cacheDir: File = File("cache")

mirai-core-api/src/commonMain/kotlin/utils/FileCacheStrategy.kt

@@ -12,10 +12,13 @@
 package net.mamoe.mirai.utils
 
 import kotlinx.coroutines.Dispatchers
+import net.mamoe.mirai.Bot
 import net.mamoe.mirai.IMirai
 import net.mamoe.mirai.utils.ExternalResource.Companion.sendAsImageTo
 import net.mamoe.mirai.utils.ExternalResource.Companion.toExternalResource
 import net.mamoe.mirai.utils.ExternalResource.Companion.uploadAsImage
+import net.mamoe.mirai.utils.FileCacheStrategy.MemoryCache
+import net.mamoe.mirai.utils.FileCacheStrategy.TempCache
 import java.io.File
 import java.io.IOException
 import java.io.InputStream
@@ -25,12 +28,27 @@ import java.io.InputStream
  *
  * 由于上传资源时服务器要求提前给出 MD5 和文件大小等数据, 一些资源如 [InputStream] 需要首先缓存才能使用.
  *
- * Mirai 全局都使用 [IMirai.FileCacheStrategy]. 可以覆盖.
+ * 资源的缓存都是将 [InputStream] 缓存未 [ExternalResource]. 根据 [FileCacheStrategy] 实现不同, 可以以临时文件存储, 也可以在数据库或是内存按需存储.
+ * Mirai 内置的实现有 [内存存储][MemoryCache] 和 [临时文件存储][TempCache].
+ * 操作 [ExternalResource.toExternalResource] 时将会使用 [IMirai.FileCacheStrategy]. 可以覆盖, 示例:
+ * ```
+ * // Kotlin
+ * Mirai.FileCacheStrategy = FileCacheStrategy.TempCache() // 使用系统默认缓存路径, 也是默认的行为
+ * Mirai.FileCacheStrategy = FileCacheStrategy.TempCache(File("C:/cache")) // 使用自定义缓存路径
+ *
+ * // Java
+ * Mirai.getInstance().setFileCacheStrategy(new FileCacheStrategy.TempCache()); // 使用系统默认缓存路径, 也是默认的行为
+ * Mirai.getInstance().setFileCacheStrategy(new FileCacheStrategy.TempCache(new File("C:/cache"))); // 使用自定义的缓存路径
+ * ```
+ *
+ * 此接口的实现和使用都是稳定的. 自行实现的 [FileCacheStrategy] 也可以被 Mirai 使用.
+ *
+ * 注意, 此接口目前仅缓存 [InputStream] 等一次性数据. 好友列表等数据由每个 [Bot] 的 [BotConfiguration.cacheDir] 缓存.
  *
  * ### 使用 [FileCacheStrategy] 的操作
- * [ExternalResource.toExternalResource],
+ * - [ExternalResource.toExternalResource]
- * [ExternalResource.uploadAsImage],
+ * - [ExternalResource.uploadAsImage]
- * [ExternalResource.sendAsImageTo]
+ * - [ExternalResource.sendAsImageTo]
  *
  * @see ExternalResource
  */
@@ -58,7 +76,7 @@ public interface FileCacheStrategy {
     public fun newCache(input: InputStream): ExternalResource = newCache(input, null)
 
     /**
-     * 使用内存直接存储所有图片文件.
+     * 使用内存直接存储所有图片文件. 由 JVM 执行 GC.
      */
     public object MemoryCache : FileCacheStrategy {
         @Throws(IOException::class)
@@ -68,9 +86,9 @@ public interface FileCacheStrategy {
     }
 
     /**
-     * 使用系统临时文件夹缓存图片文件. 在图片使用完毕后删除临时文件.
+     * 使用系统临时文件夹缓存图片文件. 在图片使用完毕后或 JVM 正常结束时删除临时文件.
      */
-    public class TempCache @JvmOverloads constructor(
+    public class TempCache @JvmOverloads public constructor(
         /**
          * 缓存图片存放位置. 为 `null` 时使用主机系统的临时文件夹: `File.createTempFile("tmp", null, directory)`
          */