有赞 OSS node 客户端

有赞 OSS 下的 Node 客户端，提供 put、putStream、get、getStream、head、delete 方法

• 使用姿势
  • 安装依赖
  • Node 里使用
• API 介绍
  • OSS 实例化
  • put 方法
  • stream 流式上传
  • get 方法
  • stream 流式获取方法
  • head 方法
  • delete 方法
• 错误信息

使用姿势

安装依赖

  yarn add @youzan/youzan-oss -S

Node 里使用

在 3.x 版本中，导出方式已订正为 ESM 标准导出，使用 CommonJS 的同学注意

上传文件到 OSS

CJS

  const OSS = require('@youzan/youzan-oss').default;

  // 实例化
  const client = new OSS({
    namespace: 'xxxx', // 需要申请
    env: 'prod',       // 可选。环境
  });

  // 上传文件，xxx 可以是文件路径、Buffer 或者是可读流
  // key 是用来查找改资源文件的钥匙
  client.put('key', 'xxxxx')
    .then(url => {
      console.log('put done. The resource url is %s', url);
    })
    .catch((err) => {
      console.log(err);
    })

ESM

import OSS from '@youzan/youzan-oss'

const client = new OSS({
  namespace: 'xxxx',
  env: 'prod'
})

const url = await client.put('key', 'xxxxx')

从 OSS 上获取文件

  const OSS = require('@youzan/youzan-oss').default;

  // 实例化
  const client = new OSS({
    namespace: 'xxxx' // 需要申请
  });

  // 查找文件
  // key 是上传时定义的
  // xxxx 可传，文件地址，传入后把 OSS 上的文件写入到此
  client.get('key', 'xxxxx')
    .then(() => {
      console.log('get done');
    })
    .catch((err) => {
      console.log(err);
    })

API 介绍

OSS 实例化

目前实例化时值需要传入 namespace 即可，namespace 需要找运维申请

使用方法：

  const client = new OSS({
    namespace: 'xxxx' // 需要申请
  });

参数：

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | namespace | string | 命名空间 | 是 | 无 | 需要申请 | | env | string | 环境 | 否 | NODE_ENV | | | host | string | 请求的 host 域名 | 否 | src/constants/index | 不传时会根据环境获取

put 方法

put 方法用来将本地文件上传到 OSS

使用方法：

  client.put('object-key', file)
    .then(url => {
      console.log('put done. The resource url is %s', url);
    })
    .catch((err) => {
      console.log(err);
    })

参数

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | key | string | 文件对应的 key | 是 | 无 | 每个上传的文件对应的 key | | file | Buffer、ReadStream、string | 需要上传的文件 | 是 | 无 | 可以是文件路径、Buffer、可读流 | | options | urllib.RequestOptions | 请求参数 | 否 | 无 | 详见：https://www.npmjs.com/package/urllib |

stream 流式上传

putStream 方法用来将本地大文件上传到 OSS，可监听进度
(适合大文件)

使用方法：

  const stream = client.putStream('object-key', file);
  let total = 0;
  let count = 0;

  stream.on('progress', (contentLength, totalLength) => {
    total += contentLength;
    count += 1;
    console.log(total + '------' + count);
  });

  stream.on('finish', url => {
    console.log('put done. The resource url is %s', url);
    console.log('finish', total + '------' + count)
  });

  stream.on('error', (err) => console.log(err));

参数

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | key | string | 文件对应的 key | 是 | 无 | 每个上传的文件对应的 key | | file | ReadStream、string | 需要上传的文件 | 是 | 无 | 可以是文件路径、可读流 | | options | urllib.RequestOptions | 请求参数 | 否 | 无 | 详见：https://www.npmjs.com/package/urllib |

get 方法

get 方法用来获取 OSS 上的文件

使用方法1 - 存储到文件里

  client.get('object-key', file)
    .then(() => {
      console.log('done');
    })
    .catch((err) => {
      console.log(err);
    })

使用方法2 - 存储到内存中

  client.get('object-key')
    .then((buf) => {
      // 返回 Buffer
      console.log(buf');
    })
    .catch((err) => {
      console.log(err);
    })

参数

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | key | string | 文件对应的 key | 是 | 无 | 每个上传的文件对应的 key | | file | string | 需要写入的文件路径 | 否 | 无 | 如果传入，将 OSS 上的内容写入到该文件 | | options | urllib.RequestOptions | 请求参数 | 否 | 无 | 详见：https://www.npmjs.com/package/urllib |

stream 流式获取方法

getStream 通过流的形式获取 OSS 文件，可获取下载进度。常用来获取大文件

使用方法

  const stream = client.getStream('object-key', file);
  let total = 0;

  stream.on('progress', (contentLength, totalLength) => {
    total += contentLength;

    console.log('获取进度为：'  + total / totalLength);
  });

  stream.on('finish', () => console.log('获取完毕'));

  stream.on('error', (err) => console.log('获取出错' + err));

参数

getStream 入参和上面 get 相同。返回的实例可监听 on、finish、error。

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | key | string | 文件对应的 key | 是 | 无 | 每个上传的文件对应的 key | | file | string、WriteStream | 需要写入的文件 | 否 | 无 | 如果传入，将 OSS 上的内容写入到该文件或可写流 | | options | urllib.RequestOptions | 请求参数 | 否 | 无 | 详见：https://www.npmjs.com/package/urllib |

head 方法

head 方法用来获取 OSS 上的文件信息

使用方法：

  client.head('object-key')
    .then((info) => {
      console.log(info);
    })
    .catch((err) => {
      console.log(err);
    })

参数

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | key | string | 文件对应的 key | 是 | 无 | 每个上传的文件对应的 key |

delete 方法

delete 会删除 OSS 上的文件

使用方法：

  client.delete('object-key')
    .then(() => {
      console.log('delete done');
    })
    .catch((err) => {
      console.log(err);
    })

参数

| 参数 | 类型 | 描述 | 是否必传 | 默认值 | 备注 | |------|------|------|------|------|------| | key | string | 文件对应的 key | 是 | 无 | 每个上传的文件对应的 key |

错误信息

| code | message | 备注 | |------|------|------| | FILE_OUT_OF_SIZE | 文件超过限制 | 默认限制 1 G | | UNKNOWN_HOST | 当前 host 不是标准的环境变量 | host 必须是 qa pre prod test officeProd 中的一个 |