append

Author: yinxulai

README.md

@@ -6,7 +6,7 @@
 
 基于七牛 API 开发的前端 JavaScript SDK
 
-### 当前版本为 3.x，旧版本文档：[2.x](https://github.com/qiniu/js-sdk/tree/2.x)、[1.x](https://github.com/qiniu/js-sdk/tree/1.x)
+## 当前版本为 3.x，旧版本文档：[2.x](https://github.com/qiniu/js-sdk/tree/2.x)、[1.x](https://github.com/qiniu/js-sdk/tree/1.x)
 
 ### 2.x 升级到 3.x 的注意事项请参考 [文档](https://github.com/qiniu/js-sdk/wiki/2.x-%E5%8D%87%E7%BA%A7%E5%88%B0-3.x-%E6%96%87%E6%A1%A3%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)
 
@@ -81,17 +81,15 @@ Qiniu-JavaScript-SDK 的示例 [Demo](http://jssdk-v2.demo.qiniu.io) 中的服
 
 * 直接使用静态文件地址：
 
-  ```
-  https://cdnjs.cloudflare.com/ajax/libs/qiniu-js/<version>/qiniu.min.js
-  ```
+  `https://cdnjs.cloudflare.com/ajax/libs/qiniu-js/<version>/qiniu.min.js`
 
-  通过sctipt标签引入该文件，会在全局生成名为 `qiniu` 的对象
+  通过 script 标签引入该文件，会在全局生成名为 `qiniu` 的对象
 
 * 使用 NPM 安装
 
   NPM 的全称是 Node Package Manager，是一个 [NodeJS](https://nodejs.org) 包管理和分发工具，已经成为了非官方的发布 Node 模块（包）的标准。如果需要更详细的关于 NPM 的使用说明，您可以访问 [NPM 官方网站](https://www.npmjs.com)，或对应的 [中文网站](http://www.npmjs.com.cn/)
 
-  ```
+  ```shell
   npm install qiniu-js
   ```
 
@@ -164,6 +162,7 @@ qiniu.compressImage(file, options).then(data => {
           }
         }
         ```
+
       * next: 接收上传进度信息的回调函数，回调函数参数值为 `object`，包含字段信息如下：
         * uploadInfo: `object`，只有分片上传时才返回该字段
           * uploadInfo.id: 上传任务的唯一标识。
@@ -174,16 +173,15 @@ qiniu.compressImage(file, options).then(data => {
           * total.percent: `number`，当前上传进度，范围：0～100。
 
       * error: 上传错误后触发；自动重试本身并不会触发该错误，而当重试次数到达上限后则可以触发。当不是 xhr 请求错误时，会把当前错误产生原因直接抛出，诸如 JSON 解析异常等；当产生 xhr 请求错误时，参数 err 的类型为 `QiniuError`, 对于请求错误，err 的类型为 `QiniuRequestError`(继承自`QiniuError`)，如果是由于非服务端原因发生错误时（例如断网、跨域等等），错误的类型为 `QiniuNetworkError`(继承自`QiniuRequestError`)。
-        * `QiniuError`
+        * `QiniuError` (实现了 `Error`)
           * name: `QiniuErrorName` 错误的类型。
           * message `string` 错误的信息。
-        * `QiniuRequestError`
+        * `QiniuRequestError` (继承自 `QiniuError`)
           * reqId: `string` xhr 请求错误的 `X-Reqid`。
           * code: `number` 请求错误状态码，可查阅码值对应 [说明](https://developer.qiniu.com/kodo/api/3928/error-responses)。
           * isRequestError: 用于区分是否为 xhr 请求错误；当 xhr 请求出现错误并且后端通过 HTTP 状态码返回了错误信息时，该参数为 `true`；否则为 `undefined`。
-        * `QiniuNetworkError`
-          * code: `number` 固定为 `0`。
-          * reqId: 由于请求还未真正发出、无法收集到 `reqId`，所以该字段固定为 `''`。
+        * `QiniuNetworkError` (继承自 `QiniuRequestError`)
+          * reqId：由于请求可能还未真正发出、所以可能无法收集到 `reqId`，该字段可能为 `''`。
 
       * complete: 接收上传完成后的后端返回信息，具体返回结构取决于后端sdk的配置，可参考 [上传策略](https://developer.qiniu.com/kodo/manual/1206/put-policy)。
 

src/api/index.mock.ts

@@ -2,7 +2,7 @@ import { QiniuNetworkError, QiniuRequestError } from '../errors'
 import * as api from '.'
 
 export const errorMap = {
-  networkError: new QiniuNetworkError('message'), // 网络错误
+  networkError: new QiniuNetworkError('mock', 'message'), // 网络错误
 
   invalidParams: new QiniuRequestError(400, 'mock', 'message'), // 无效的参数
   expiredToken: new QiniuRequestError(401, 'mock', 'message'), // token 过期

src/errors/index.ts

@@ -47,8 +47,11 @@ export class QiniuRequestError extends QiniuError {
   }
 }
 
+/**
+ * @description 由于跨域、证书错误、断网、host 解析失败、系统拦截等原因导致的错误
+ */
 export class QiniuNetworkError extends QiniuRequestError {
-  constructor(message: string) {
-    super(0, '', message)
+  constructor(reqId: string, message: string) {
+    super(0, reqId, message)
   }
 }

src/index.ts

@@ -1,5 +1,5 @@
+export { QiniuErrorName, QiniuError, QiniuRequestError, QiniuNetworkError } from './errors'
 export { imageMogr2, watermark, imageInfo, exif, pipeline } from './image'
-export { QiniuErrorName, QiniuError, QiniuRequestError } from './errors'
 export { deleteUploadedChunks, getUploadUrl } from './api'
 export { default as upload } from './upload'
 export { region } from './config'

src/upload/hosts.ts

@@ -55,11 +55,10 @@ export class HostPool {
   private cachedHostsMap = new Map<string, Host[]>()
 
   /**
-   * @param  {string[]} hosts
-   * @description 如果在构造时传入 hosts，则该 host 池始终使用传入的 host 做为可用的数据
+   * @param  {string[]} initHosts
+   * @description 如果在构造时传入 initHosts，则该 host 池始终使用传入的 initHosts 做为可用的数据
    */
-  constructor(private hosts?: string[]) {
-  }
+  constructor(private initHosts: string[] = []) { }
 
   /**
    * @param  {string} accessKey
@@ -84,20 +83,22 @@ export class HostPool {
    * @description 从接口刷新最新的 host 数据，如果用户在构造时该类时传入了 host、则不会发起请求、而是固定使用传入的数据。
    */
   private async refresh(accessKey: string, bucketName: string, protocol: InternalConfig['upprotocol']): Promise<void> {
-    const hosts: string[] = []
-    if (this.hosts != null && this.hosts.length > 0) {
-      hosts.push(...this.hosts)
-    } else {
-      const response = await getUpHosts(accessKey, bucketName, protocol)
-      if (response?.data != null) {
-        hosts.push(
-          ...(response.data.up?.acc?.main || []),
-          ...(response.data.up?.acc?.backup || [])
-        )
-      }
+    const cachedHostList = this.cachedHostsMap.get(`${accessKey}@${bucketName}`) || []
+    if (cachedHostList.length > 0) return
+
+    if (this.initHosts.length > 0) {
+      this.register(accessKey, bucketName, this.initHosts, protocol)
+      return
     }
 
-    this.register(accessKey, bucketName, hosts, protocol)
+    const response = await getUpHosts(accessKey, bucketName, protocol)
+    if (response?.data != null) {
+      const stashHosts: string[] = [
+        ...(response.data.up?.acc?.main || []),
+        ...(response.data.up?.acc?.backup || [])
+      ]
+      this.register(accessKey, bucketName, stashHosts, protocol)
+    }
   }
 
   /**
@@ -108,13 +109,9 @@ export class HostPool {
    * @returns  {Promise<Host | null>}
    * @description 获取一个可用的上传 Host，排除已冻结的
    */
-  public async getUp(accessKey: string, bucketName: string, protocol: InternalConfig['upprotocol'], isRefresh = false): Promise<Host | null> {
-    if (isRefresh) await this.refresh(accessKey, bucketName, protocol)
-
+  public async getUp(accessKey: string, bucketName: string, protocol: InternalConfig['upprotocol']): Promise<Host | null> {
+    await this.refresh(accessKey, bucketName, protocol)
     const cachedHostList = this.cachedHostsMap.get(`${accessKey}@${bucketName}`) || []
-    if (cachedHostList.length === 0 && !isRefresh) {
-      return this.getUp(accessKey, bucketName, protocol, true)
-    }
 
     if (cachedHostList.length === 0) return null
     const availableHostList = cachedHostList.filter(host => !host.isFrozen())

src/upload/index.ts

@@ -58,7 +58,7 @@ export default function upload(
   }
 
   // 创建 host 池
-  const hostPool = new HostPool(options.config?.uphost)
+  const hostPool = new HostPool(options.config.uphost)
 
   return new Observable((observer: IObserver<UploadProgress, QiniuError, UploadCompleteData>) => {
     const manager = createUploadManager(options, {

src/upload/resume.ts

@@ -83,22 +83,14 @@ export default class Resume extends Base {
     } catch (error) {
       // uploadId 无效，上传参数有误（多由于本地存储信息的 uploadId 失效
       if (error instanceof QiniuRequestError && (error.code === 612 || error.code === 400)) {
-        try {
-          utils.removeLocalFileInfo(localKey)
-        } catch (removeError) {
-          this.logger.warn(removeError)
-        }
+        utils.removeLocalFileInfo(localKey, this.logger)
       }
 
       throw error
     }
 
     // 上传成功，清理本地缓存数据
-    try {
-      utils.removeLocalFileInfo(localKey)
-    } catch (error) {
-      this.logger.warn(error)
-    }
+    utils.removeLocalFileInfo(localKey, this.logger)
     return mkFileResponse
   }
 
@@ -157,14 +149,10 @@ export default class Resume extends Base {
       size: chunk.size
     }
 
-    try {
-      utils.setLocalFileInfo(this.getLocalKey(), {
-        id: this.uploadId,
-        data: this.uploadedList
-      })
-    } catch (error) {
-      this.logger.info(`set part ${index} cache failed.`, error)
-    }
+    utils.setLocalFileInfo(this.getLocalKey(), {
+      id: this.uploadId,
+      data: this.uploadedList
+    }, this.logger)
   }
 
   private async mkFileReq() {
@@ -196,12 +184,7 @@ export default class Resume extends Base {
   }
 
   private async initBeforeUploadChunks() {
-    let localInfo: LocalInfo | null = null
-    try {
-      localInfo = utils.getLocalFileInfo(this.getLocalKey())
-    } catch (error) {
-      this.logger.warn(error)
-    }
+    const localInfo = utils.getLocalFileInfo(this.getLocalKey(), this.logger)
 
     // 分片必须和当时使用的 uploadId 配套，所以断点续传需要把本地存储的 uploadId 拿出来
     // 假如没有 localInfo 本地信息并重新获取 uploadId

src/utils/helper.ts

@@ -1,7 +1,10 @@
 import SparkMD5 from 'spark-md5'
-import { urlSafeBase64Decode } from './base64'
-import { Progress, LocalInfo } from '../upload'
+
 import { QiniuErrorName, QiniuError, QiniuRequestError, QiniuNetworkError } from '../errors'
+import { Progress, LocalInfo } from '../upload'
+import Logger from '../logger'
+
+import { urlSafeBase64Decode } from './base64'
 
 export const MB = 1024 ** 2
 
@@ -43,14 +46,14 @@ export function sum(list: number[]) {
   return list.reduce((data, loaded) => data + loaded, 0)
 }
 
-export function setLocalFileInfo(localKey: string, info: LocalInfo) {
+export function setLocalFileInfo(localKey: string, info: LocalInfo, logger: Logger) {
   try {
     localStorage.setItem(localKey, JSON.stringify(info))
   } catch (err) {
-    throw new QiniuError(
+    logger.warn(new QiniuError(
       QiniuErrorName.WriteCacheFailed,
       `setLocalFileInfo failed: ${localKey}`
-    )
+    ))
   }
 }
 
@@ -59,26 +62,26 @@ export function createLocalKey(name: string, key: string | null | undefined, siz
   return `qiniu_js_sdk_upload_file_name_${name}${localKey}size_${size}`
 }
 
-export function removeLocalFileInfo(localKey: string) {
+export function removeLocalFileInfo(localKey: string, logger: Logger) {
   try {
     localStorage.removeItem(localKey)
   } catch (err) {
-    throw new QiniuError(
+    logger.warn(new QiniuError(
       QiniuErrorName.RemoveCacheFailed,
       `removeLocalFileInfo failed. key: ${localKey}`
-    )
+    ))
   }
 }
 
-export function getLocalFileInfo(localKey: string): LocalInfo | null {
+export function getLocalFileInfo(localKey: string, logger: Logger): LocalInfo | null {
   let localInfoString: string | null = null
   try {
     localInfoString = localStorage.getItem(localKey)
   } catch {
-    throw new QiniuError(
+    logger.warn(new QiniuError(
       QiniuErrorName.ReadCacheFailed,
       `getLocalFileInfo failed. key: ${localKey}`
-    )
+    ))
   }
 
   if (localInfoString == null) {
@@ -90,11 +93,11 @@ export function getLocalFileInfo(localKey: string): LocalInfo | null {
     localInfo = JSON.parse(localInfoString)
   } catch {
     // 本地信息已被破坏，直接删除
-    removeLocalFileInfo(localKey)
-    throw new QiniuError(
+    removeLocalFileInfo(localKey, logger)
+    logger.warn(new QiniuError(
       QiniuErrorName.InvalidCacheData,
       `getLocalFileInfo failed to parse. key: ${localKey}`
-    )
+    ))
   }
 
   return localInfo
@@ -218,13 +221,14 @@ export function request<T>(url: string, options: RequestOptions): Response<T> {
         return
       }
 
+      const reqId = xhr.getResponseHeader('x-reqId') || ''
+
       if (xhr.status === 0) {
         // 发生 0 基本都是网络错误，常见的比如跨域、断网、host 解析失败、系统拦截等等
-        reject(new QiniuNetworkError('network error.'))
+        reject(new QiniuNetworkError(reqId, 'network error.'))
         return
       }
 
-      const reqId = xhr.getResponseHeader('x-reqId') || ''
       if (xhr.status !== 200) {
         let message = `xhr request failed, code: ${xhr.status}`
         if (responseText) {