Resume upload default version to v2

CHANGELOG.md

@@ -1,4 +1,8 @@
 # Changelog
+## 7.19.0 (2025-06-20)
+
+* 分片上传接口版本默认调整为 V2
+
 
 ## 7.18.0 (2025-02-05)
 

README.md

@@ -16,14 +16,14 @@
 <dependency>
   <groupId>com.qiniu</groupId>
   <artifactId>qiniu-java-sdk</artifactId>
-  <version>[7.18.0, 7.18.99]</version>
+  <version>[7.19.0, 7.19.99]</version>
 </dependency>
 ```
 
 或者 Gradle:
 
 ```groovy
-implementation 'com.qiniu:qiniu-java-sdk:7.18.+'
+implementation 'com.qiniu:qiniu-java-sdk:7.19.+'
 ```
 
 ## 运行环境
@@ -44,7 +44,7 @@ import com.qiniu.http.Response;
 String accessKey = "Your AccessKey";
 String secretKey = "Your SecretKey";
 String bucketName = "upload to bucket";
-Configuration cfg = new Configuration();
+Configuration cfg = Configuration.create();
 UploadManager uploadManager = new UploadManager(cfg);
 Auth auth = Auth.create(accessKey, secretKey);
 String token = auth.uploadToken(bucketName);
@@ -60,7 +60,7 @@ import com.qiniu.http.Response;
 String accessKey = "Your AccessKey";
 String secretKey = "Your SecretKey";
 String bucketName = "upload to bucket";
-Configuration cfg = new Configuration();
+Configuration cfg = Configuration.create();
 cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;
 UploadManager uploadManager = new UploadManager(cfg);
 Auth auth = Auth.create(accessKey, secretKey);

examples/UploadBySelfDefiningParam.java

@@ -32,7 +32,7 @@ public class UploadBySelfDefiningParam {
         bucket = "设置你们自己的上传空间名称";
         //指定存储空间所在区域，华北region1，华南region2 ，华东 region0
         region = Region.region1();
-        //初始化cfg实例，可以指定上传区域，也可以创建无参实例 , cfg = new Configuration();
+        //初始化cfg实例，可以指定上传区域，也可以创建无参实例 , cfg = Configuration.create();
         cfg = new Configuration(region);
         //是否指定https上传，默认true
         //cfg.useHttpsDomains=false;

examples/upload_v1_api.java

@@ -93,7 +93,7 @@ public void upload() throws IOException {
         String fileName = "java_api_v1.zip";
         String token = getUpToken();
 
-        Configuration configuration = new Configuration();
+        Configuration configuration = Configuration.create();
         Client client = new Client(configuration);
 
         List<String> allBlockCtx = new ArrayList<>();

examples/upload_v2_api.java

@@ -84,7 +84,7 @@ public void testUpload() {
 
         String token = getUpToken();
 
-        Configuration configuration = new Configuration();
+        Configuration configuration = Configuration.create();
         Client client = new Client(configuration);
 
         // 1. init upload

src/main/java/com/qiniu/common/Constants.java

@@ -10,7 +10,7 @@ public final class Constants {
     /**
      * 版本号
      */
-    public static final String VERSION = "7.18.0";
+    public static final String VERSION = "7.19.0";
     /**
      * 块大小，不能改变
      */

src/main/java/com/qiniu/processing/OperationManager.java

@@ -51,7 +51,7 @@ public OperationManager(Auth auth, Configuration cfg) {
     public OperationManager(Auth auth, Client client) {
         this.auth = auth;
         this.client = client;
-        this.configuration = new Configuration();
+        this.configuration = Configuration.create();
     }
 
     public OperationManager(Auth auth, Configuration cfg, Client client) {

src/main/java/com/qiniu/storage/BaseUploader.java

@@ -17,7 +17,7 @@ public abstract class BaseUploader {
         this.key = key;
         this.upToken = upToken;
         if (config == null) {
-            this.config = new Configuration();
+            this.config = Configuration.create();
         } else {
             this.config = config.clone();
         }

src/main/java/com/qiniu/storage/BucketManager.java

@@ -47,7 +47,7 @@ public final class BucketManager {
      */
     public BucketManager(Auth auth, Configuration cfg) {
         this.auth = auth;
-        Configuration c2 = cfg == null ? new Configuration() : cfg.clone();
+        Configuration c2 = cfg == null ? Configuration.create() : cfg.clone();
         this.config = c2;
         this.configHelper = new ConfigHelper(c2);
         client = new Client(c2);
@@ -56,14 +56,14 @@ public BucketManager(Auth auth, Configuration cfg) {
     public BucketManager(Auth auth, Client client) {
         this.auth = auth;
         this.client = client;
-        this.config = new Configuration();
+        this.config = Configuration.create();
         this.configHelper = new ConfigHelper(this.config);
     }
 
     public BucketManager(Auth auth, Configuration cfg, Client client) {
         this.auth = auth;
         this.client = client;
-        Configuration c2 = cfg == null ? new Configuration() : cfg.clone();
+        Configuration c2 = cfg == null ? Configuration.create() : cfg.clone();
         this.config = c2;
         this.configHelper = new ConfigHelper(c2);
     }
@@ -1219,7 +1219,7 @@ private Api.Interceptor[] ucInterceptors() throws QiniuException {
      * <p>
      * 如果遇到超时比较多，可减小单次 batch 操作的数量，或者在创建 BucketManager 时尝试增加超时时间；
      * 增加超时时间的具体方式如下：
-     * Configuration cfg = new Configuration();
+     * Configuration cfg = Configuration.create();
      * cfg.readTimeout = 120;
      * BucketManager bucketManager = new BucketManager(auth, cfg);
      * <p>

src/main/java/com/qiniu/storage/Configuration.java

@@ -14,14 +14,23 @@
  */
 public final class Configuration implements Cloneable {
 
-    static final String ucBackUpHost0 = "kodo-config.qiniuapi.com";
-    static final String ucBackUpHost1 = "uc.qbox.me";
     /**
-     * 特殊默认域名
+     * 公有云 RS 域名，内部使用，不保证兼容性变更
      */
     public static String defaultRsHost = "rs.qiniu.com";
+
+    /**
+     * 公有云 API 域名，内部使用，不保证兼容性变更
+     */
     public static String defaultApiHost = "api.qiniu.com";
+
+    /**
+     * 公有云 Uc 域名，内部使用，不保证兼容性变更
+     */
     public static String defaultUcHost = "uc.qiniuapi.com";
+
+    static final String ucBackUpHost0 = "kodo-config.qiniuapi.com";
+    static final String ucBackUpHost1 = "uc.qbox.me";
     static final String[] defaultUcHosts = new String[]{defaultUcHost, ucBackUpHost0, ucBackUpHost1};
 
     /**
@@ -159,10 +168,22 @@ public final class Configuration implements Cloneable {
     public ProxyConfiguration proxy;
     private ConfigHelper configHelper;
 
+    /**
+     * 构造函数：
+     * 使用 {@link Configuration#create()} 替换
+     */
+    @Deprecated
     public Configuration() {
         configHelper = new ConfigHelper(this);
     }
 
+    /**
+     * 构造函数：
+     * 使用 {@link Configuration#create(Region)} 替换
+     *
+     * @param region
+     */
+    @Deprecated
     public Configuration(Region region) {
         if (region instanceof RegionGroup) {
             this.region = (Region) region.clone();
@@ -172,12 +193,47 @@ public Configuration(Region region) {
         configHelper = new ConfigHelper(this);
     }
 
+    /**
+     * 构造函数：
+     * 使用 {@link Configuration#create(Region)} 替换
+     *
+     * @param zone Zone
+     */
     @Deprecated
     public Configuration(Zone zone) {
         this.zone = zone;
         configHelper = new ConfigHelper(this);
     }
 
+    /**
+     * 默认配置
+     *
+     * @return Configuration
+     */
+    public static Configuration create() {
+        Configuration configuration = new Configuration();
+        configuration.resumableUploadAPIVersion = ResumableUploadAPIVersion.V2;
+        return configuration;
+    }
+
+
+    /**
+     * 构建配置
+     *
+     * @param region Region
+     * @return Configuration
+     */
+    public static Configuration create(Region region) {
+        Configuration configuration = new Configuration(region);
+        configuration.resumableUploadAPIVersion = ResumableUploadAPIVersion.V2;
+        return configuration;
+    }
+
+    /**
+     * 克隆
+     *
+     * @return Configuration
+     */
     public Configuration clone() {
         try {
             Configuration configuration = (Configuration) super.clone();
@@ -192,17 +248,38 @@ public Configuration clone() {
     }
 
 
+    /***
+     * 获取上传域名
+     *
+     * @param upToken 上传 token
+     * @return 上传域名
+     * @throws QiniuException 获取域名失败异常
+     */
     @Deprecated
     public String upHost(String upToken) throws QiniuException {
         return configHelper.upHost(upToken);
     }
 
 
+    /**
+     * 获取备用上传域名
+     *
+     * @param upToken 上传 token
+     * @return 上传域名
+     * @throws QiniuException 获取域名失败异常
+     */
     @Deprecated
     public String upHostBackup(String upToken) throws QiniuException {
         return configHelper.tryChangeUpHost(upToken, null);
     }
 
+    /**
+     * 获取 io 域名
+     *
+     * @param ak     七牛 AK
+     * @param bucket 存储空间名称
+     * @return io 域名
+     */
     @Deprecated
     public String ioHost(String ak, String bucket) {
         try {
@@ -212,6 +289,13 @@ public String ioHost(String ak, String bucket) {
         }
     }
 
+    /**
+     * 获取 api 域名
+     *
+     * @param ak     七牛 AK
+     * @param bucket 存储空间名称
+     * @return api 域名
+     */
     @Deprecated
     public String apiHost(String ak, String bucket) {
         try {
@@ -221,6 +305,13 @@ public String apiHost(String ak, String bucket) {
         }
     }
 
+    /**
+     * 获取 rs 域名
+     *
+     * @param ak     七牛 AK
+     * @param bucket 存储空间名称
+     * @return rs 域名
+     */
     @Deprecated
     public String rsHost(String ak, String bucket) {
         try {
@@ -230,6 +321,13 @@ public String rsHost(String ak, String bucket) {
         }
     }
 
+    /**
+     * 获取 rsf 域名
+     *
+     * @param ak     七牛 AK
+     * @param bucket 存储空间名称
+     * @return rsf 域名
+     */
     @Deprecated
     public String rsfHost(String ak, String bucket) {
         try {
@@ -239,24 +337,50 @@ public String rsfHost(String ak, String bucket) {
         }
     }
 
+    /**
+     * 获取 rs 域名
+     *
+     * @return rs 域名
+     */
     @Deprecated
     public String rsHost() {
         return configHelper.rsHost();
     }
 
+    /**
+     * 获取 api 域名
+     *
+     * @return api 域名
+     */
     @Deprecated
     public String apiHost() {
         return configHelper.apiHost();
     }
 
+    /**
+     * 获取 uc 域名
+     *
+     * @return uc 域名
+     */
     @Deprecated
     public String ucHost() {
         return configHelper.ucHost();
     }
 
-
+    /**
+     * 分片上传 API 版本
+     */
     public enum ResumableUploadAPIVersion {
-        V1, V2
+        /**
+         * 使用 V1 的分块上传API。
+         */
+        V1,
+
+        /**
+         * 使用 V2 的分块上传API。
+         * 推荐使用 V2 的分片上传版本，更稳定，更高效。
+         */
+        V2
     }
 
 }

src/main/java/com/qiniu/storage/FixBlockUploader.java

@@ -37,7 +37,7 @@ public class FixBlockUploader {
      */
     public FixBlockUploader(int blockSize, Configuration configuration, Client client, Recorder recorder) {
         if (configuration == null) {
-            configuration = new Configuration();
+            configuration = Configuration.create();
         }
         if (client == null) {
             client = new Client(configuration);