Deprecate RemoteFile.upload and relevant extensions, fix #1255 (#1290)

* Deprecate `RemoteFile.upload` and relevant extensions, fix #1255

* Replace '// since 2.7-M1' with '// deprecated since 2.7-M1'

* Move deprecation notes to `RemoteFile.upload`

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

@@ -271,14 +271,26 @@ public interface ExternalResource : Closeable {
          *
          * 需要调用方手动[关闭资源][ExternalResource.close].
          *
+         * ## 已弃用
+         * 查看 [RemoteFile.upload] 获取更多信息.
+         *
          * @param path 远程路径. 起始字符为 '/'. 如 '/foo/bar.txt'
          * @since 2.5
          * @see RemoteFile.path
          * @see RemoteFile.upload
          */
+        @Suppress("DEPRECATION")
         @JvmStatic
         @JvmBlockingBridge
         @JvmOverloads
+        @Deprecated(
+            "Use sendTo instead.",
+            ReplaceWith(
+                "this.sendTo(contact, path, callback)",
+                "net.mamoe.mirai.utils.ExternalResource.Companion.sendTo"
+            ),
+            level = DeprecationLevel.WARNING
+        ) // deprecated since 2.7-M1
         public suspend fun File.uploadTo(
             contact: FileSupported,
             path: String,
@@ -292,15 +304,27 @@ public interface ExternalResource : Closeable {
          *
          * 需要调用方手动[关闭资源][ExternalResource.close].
          *
+         * ## 已弃用
+         * 查看 [RemoteFile.upload] 获取更多信息.
+         *
          * @param path 远程路径. 起始字符为 '/'. 如 '/foo/bar.txt'
          * @since 2.5
          * @see RemoteFile.path
          * @see RemoteFile.upload
          */
+        @Suppress("DEPRECATION")
         @JvmStatic
         @JvmBlockingBridge
         @JvmName("uploadAsFile")
         @JvmOverloads
+        @Deprecated(
+            "Use sendAsFileTo instead.",
+            ReplaceWith(
+                "this.sendAsFileTo(contact, path, callback)",
+                "net.mamoe.mirai.utils.ExternalResource.Companion.sendAsFileTo"
+            ),
+            level = DeprecationLevel.WARNING
+        ) // deprecated since 2.7-M1
         public suspend fun ExternalResource.uploadAsFile(
             contact: FileSupported,
             path: String,
@@ -315,7 +339,7 @@ public interface ExternalResource : Closeable {
          * @param path 远程路径. 起始字符为 '/'. 如 '/foo/bar.txt'
          * @since 2.5
          * @see RemoteFile.path
-         * @see RemoteFile.upload
+         * @see RemoteFile.uploadAndSend
          */
         @JvmStatic
         @JvmBlockingBridge
@@ -334,7 +358,7 @@ public interface ExternalResource : Closeable {
          * @param path 远程路径. 起始字符为 '/'. 如 '/foo/bar.txt'
          * @since 2.5
          * @see RemoteFile.path
-         * @see RemoteFile.upload
+         * @see RemoteFile.uploadAndSend
          */
         @JvmStatic
         @JvmBlockingBridge

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

@@ -412,14 +412,21 @@ public interface RemoteFile {
      * 上传后不会发送文件消息, 即官方客户端只能在 "群文件" 中查看文件.
      * 可通过 [toMessage] 获取到文件消息并通过 [Group.sendMessage] 发送, 或使用 [uploadAndSend].
      *
-     * 若 [RemoteFile.id] 存在且旧文件存在, 将会覆盖旧文件.
-     * 即使用 [resolve] 或 [resolveSibling] 获取到的 [RemoteFile] 的 [upload] 总是上传一个新文件,
-     * 而使用 [resolveById] 或 [listFiles] 获取到的总是覆盖旧文件, 当旧文件已在远程删除时上传一个新文件.
+     * ## 已弃用
+     *
+     * 使用 [sendFile] 代替. 本函数会上传文件但不会发送文件消息.
+     * 不发送文件消息就导致其他操作都几乎不能完成, 而且经反馈, 用户通常会忘记后续的 [RemoteFile.toMessage] 操作.
+     * 本函数造成了很大的不必要的迷惑, 故以既上传又发送消息的, 与官方客户端行为相同的 [sendFile] 代替.
+     *
+     * 相关问题: [#1250: 群文件在上传后 toRemoteFile 返回 null](https://github.com/mamoe/mirai/issues/1250)
      *
      * @param resource 需要上传的文件资源. 无论上传是否成功, 本函数都不会关闭 [resource].
      * @param callback 进度回调
      * @throws IllegalStateException 该文件上传失败或权限不足时抛出
      */
+    @Deprecated(
+        "Use uploadAndSend instead.", ReplaceWith("this.uploadAndSend(resource, callback)"), DeprecationLevel.WARNING
+    ) // deprecated since 2.7-M1
     public suspend fun upload(
         resource: ExternalResource,
         callback: ProgressionCallback? = null
@@ -427,14 +434,26 @@ public interface RemoteFile {
 
     /**
      * 上传文件到 [RemoteFile.path] 表示的路径.
+     * ## 已弃用
+     * 阅读 [upload] 获取更多信息
      * @see upload
      */
+    @Suppress("DEPRECATION")
+    @Deprecated(
+        "Use uploadAndSend instead.", ReplaceWith("this.uploadAndSend(resource)"), DeprecationLevel.WARNING
+    )  // deprecated since 2.7-M1
     public suspend fun upload(resource: ExternalResource): FileMessage = upload(resource, null)
 
     /**
      * 上传文件.
+     * ## 已弃用
+     * 阅读 [upload] 获取更多信息
      * @see upload
      */
+    @Suppress("DEPRECATION")
+    @Deprecated(
+        "Use uploadAndSend instead.", ReplaceWith("this.uploadAndSend(file, callback)"), DeprecationLevel.WARNING
+    ) // deprecated since 2.7-M1
     public suspend fun upload(
         file: File,
         callback: ProgressionCallback? = null
@@ -442,12 +461,23 @@ public interface RemoteFile {
 
     /**
      * 上传文件.
+     * ## 已弃用
+     * 阅读 [upload] 获取更多信息
      * @see upload
      */
+    @Suppress("DEPRECATION")
+    @Deprecated(
+        "Use sendFile instead.", ReplaceWith("this.uploadAndSend(file)"), DeprecationLevel.WARNING
+    ) // deprecated since 2.7-M1
     public suspend fun upload(file: File): FileMessage = file.toExternalResource().use { upload(it) }
 
     /**
      * 上传文件并发送文件消息.
+     *
+     * 若 [RemoteFile.id] 存在且旧文件存在, 将会覆盖旧文件.
+     * 即使用 [resolve] 或 [resolveSibling] 获取到的 [RemoteFile] 的 [upload] 总是上传一个新文件,
+     * 而使用 [resolveById] 或 [listFiles] 获取到的总是覆盖旧文件, 当旧文件已在远程删除时上传一个新文件.
+     *
      * @param resource 需要上传的文件资源. 无论上传是否成功, 本函数都不会关闭 [resource].
      * @see upload
      */
@@ -503,12 +533,24 @@ public interface RemoteFile {
 
         /**
          * 上传文件并获取文件消息, 但不发送.
+         *
+         * ## 已弃用
+         * 在 [upload] 获取更多信息
+         *
          * @param path 远程路径. 起始字符为 '/'. 如 '/foo/bar.txt'
          * @param resource 需要上传的文件资源. 无论上传是否成功, 本函数都不会关闭 [resource].
          * @see RemoteFile.upload
          */
         @JvmStatic
         @JvmOverloads
+        @Deprecated(
+            "Use sendFile instead.",
+            ReplaceWith(
+                "this.sendFile(path, resource, callback)",
+                "net.mamoe.mirai.utils.RemoteFile.Companion.sendFile"
+            ),
+            level = DeprecationLevel.WARNING
+        ) // deprecated since 2.7-M1
         public suspend fun FileSupported.uploadFile(
             path: String,
             resource: ExternalResource,
@@ -517,11 +559,22 @@ public interface RemoteFile {
 
         /**
          * 上传文件并获取文件消息, 但不发送.
+         * ## 已弃用
+         * 阅读 [uploadFile] 获取更多信息.
+         *
          * @param path 远程路径. 起始字符为 '/'. 如 '/foo/bar.txt'
          * @see RemoteFile.upload
          */
         @JvmStatic
         @JvmOverloads
+        @Deprecated(
+            "Use sendFile instead.",
+            ReplaceWith(
+                "this.sendFile(path, file, callback)",
+                "net.mamoe.mirai.utils.RemoteFile.Companion.sendFile"
+            ),
+            level = DeprecationLevel.WARNING
+        ) // deprecated since 2.7-M1
         public suspend fun FileSupported.uploadFile(
             path: String,
             file: File,
@@ -531,7 +584,7 @@ public interface RemoteFile {
         /**
          * 上传文件并发送文件消息到相关 [FileSupported].
          * @param resource 需要上传的文件资源. 无论上传是否成功, 本函数都不会关闭 [resource].
-         * @see RemoteFile.upload
+         * @see RemoteFile.uploadAndSend
          */
         @JvmStatic
         @JvmOverloads
@@ -543,7 +596,7 @@ public interface RemoteFile {
 
         /**
          * 上传文件并发送文件消息到相关 [FileSupported].
-         * @see RemoteFile.upload
+         * @see RemoteFile.uploadAndSend
          */
         @JvmStatic
         @JvmOverloads