将大量私有的方法标记为 deprecated & 更新文档

Author: yinxulai

README.md

@@ -80,24 +80,12 @@ Qiniu-JavaScript-SDK 的示例 [Demo](http://jssdk-v2.demo.qiniu.io) 中的服
 
 支持以下几种安装方式
 
-* 直接使用静态文件地址：
-
-  ```
-  https://cdnjs.cloudflare.com/ajax/libs/qiniu-js/<version>/qiniu.min.js
-  
-  // 当上方资源链接访问不稳定时，可选使用下方资源链接
-  https://cdn.staticfile.org/qiniu-js/<version>/qiniu.min.js
-  ```
-
-  通过 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
+  $ npm install qiniu-js
   ```
 
   ```Javascript
@@ -106,9 +94,22 @@ Qiniu-JavaScript-SDK 的示例 [Demo](http://jssdk-v2.demo.qiniu.io) 中的服
   import * as qiniu from 'qiniu-js'
   ```
 
-* 通过源码编译
+* 直接通过 `script` 标签引入，通过这种方式将会在全局生成名为 `qiniu` 的对象
+
+  ```html
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/qiniu-js/<version>/qiniu.min.js"></script>
+  // 当上方资源链接访问不稳定时，可选用下方资源链接
+  <script src="https://cdn.staticfile.org/qiniu-js/<version>/qiniu.min.js"></script>
+  ```
 
-`git clone [email protected]:qiniu/js-sdk.git`，进入项目根目录执行 `npm install` ，执行 `npm run build`，即可在dist 目录生成 `qiniu.min.js`。
+* 通过源码编译，依次执行以下命令即可在本地构建
+
+  ``` bash
+  $ git clone [email protected]:qiniu/js-sdk.git
+  $ cd js-sdk
+  $ npm install
+  $ npm run build
+  ```
 
 <a id="usage"></a>
 

packages/qiniu-js/src/api/index.ts

@@ -120,7 +120,7 @@ export function uploadComplete(
  * @param token 上传鉴权凭证
  * @param key 目标文件名
  * @param uploadInfo 上传信息
- * @deprecated 请勿使用内部接口，下一个大版本将会取消导出
+ * @deprecated 请直接通过官网文档使用该接口，而不是使用当前 SDK 包装版本。
  */
 export function deleteUploadedChunks(
   token: string,
@@ -164,7 +164,7 @@ export type UploadUrlConfig = Partial<Pick<Config, 'upprotocol' | 'uphost' | 're
  * @param  {string} token
  * @returns Promise
  * @description 获取上传 url
- * @deprecated 请勿使用内部接口，下一个大版本将会取消导出
+ * @deprecated 请直接通过官网文档使用该接口，而不是使用当前 SDK 包装版本。
  */
 export async function getUploadUrl(_config: UploadUrlConfig, token: string): Promise<string> {
   const config = utils.normalizeUploadConfig(_config)

packages/qiniu-js/src/index.ts

@@ -1,10 +1,3 @@
-export type { QiniuErrorName, QiniuError, QiniuRequestError, QiniuNetworkError } from './errors'
-export { imageMogr2, watermark, imageInfo, exif, pipeline } from './image'
-export { deleteUploadedChunks, getUploadUrl } from './api'
-
-export {
-  upload
-} from './upload'
 export type {
   UploadKey,
   UploadError,
@@ -13,8 +6,21 @@ export type {
   UploadObservable
 } from './upload'
 
+export type {
+  QiniuError,
+  QiniuErrorName,
+  QiniuRequestError,
+  QiniuNetworkError
+} from './errors'
+
+export { upload } from './upload'
 export { region } from './config'
 
+export {
+  getUploadUrl,
+  deleteUploadedChunks
+} from './api'
+
 export {
   compressImage,
   urlSafeBase64Encode,
@@ -24,3 +30,5 @@ export {
 } from './utils'
 
 export type { CompressResult } from './utils'
+
+export { imageMogr2, watermark, imageInfo, exif, pipeline } from './image'

packages/qiniu-js/src/utils/base64.ts

@@ -137,7 +137,7 @@ function utf8Decode(strData: string) {
   return tmpArr.join('')
 }
 
-function base64Encode(data: any) {
+function base64Encode(data: string) {
   // http://kevin.vanzonneveld.net
   // +   original by: Tyler Akins (http://rumkin.com)
   // +   improved by: Bayron Guevara
@@ -261,14 +261,22 @@ function base64Decode(data: string) {
   return utf8Decode(dec)
 }
 
-export function urlSafeBase64Encode(v: any) {
+/**
+ * @param  {string} v
+ * @deprecated 内部实现接口，请勿使用，下个版本将会移除导出
+ */
+export function urlSafeBase64Encode(v: string) {
   v = base64Encode(v)
 
   // 参考 https://tools.ietf.org/html/rfc4648#section-5
   return v.replace(/\//g, '_').replace(/\+/g, '-')
 }
 
-export function urlSafeBase64Decode(v: any) {
+/**
+ * @param  {string} v
+ * @deprecated 内部实现接口，请勿使用，下个版本将会移除导出
+ */
+export function urlSafeBase64Decode(v: string) {
   v = v.replace(/_/g, '/').replace(/-/g, '+')
   return base64Decode(v)
 }

packages/qiniu-js/src/utils/compress.ts

@@ -209,7 +209,11 @@ class Compress {
     return blob
   }
 }
-
+/**
+ * @param  {File} file
+ * @param  {CompressOptions} options
+ * @deprecated 不推荐使用，建议使用其他更专业包替代
+ */
 const compressImage = (file: File, options: CompressOptions) => new Compress(file, options).process()
 
 export default compressImage

packages/qiniu-js/src/utils/helper.ts

@@ -109,6 +109,10 @@ export function getAuthHeaders(token: string) {
   return { Authorization: auth }
 }
 
+/**
+ * @param  {string} token
+ * @deprecated 内部实现接口，请勿使用，下个版本将会移除导出
+ */
 export function getHeadersForChunkUpload(token: string) {
   const header = getAuthHeaders(token)
   return {
@@ -117,6 +121,10 @@ export function getHeadersForChunkUpload(token: string) {
   }
 }
 
+/**
+ * @param  {string} token
+ * @deprecated 内部实现接口，请勿使用，下个版本将会移除导出
+ */
 export function getHeadersForMkFile(token: string) {
   const header = getAuthHeaders(token)
   return {