@midwayjs/upload 3.0.0-beta.10

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [3.0.0-beta.10](https://github.com/midwayjs/midway/compare/v3.0.0-beta.9...v3.0.0-beta.10) (2021-12-20)
+
+
+### Features
+
+* 3.x upload ([#1422](https://github.com/midwayjs/midway/issues/1422)) ([cbd8e33](https://github.com/midwayjs/midway/commit/cbd8e334a918222f526552859401f0cf222737b6))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013 - Now midwayjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config/config.default.d.ts

@@ -0,0 +1,3 @@
+import { UploadOptions } from '../interface';
+export declare const upload: UploadOptions;
+//# sourceMappingURL=config.default.d.ts.map

package/dist/config/config.default.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upload = void 0;
+const interface_1 = require("../interface");
+const path_1 = require("path");
+const os_1 = require("os");
+exports.upload = {
+    mode: interface_1.UploadMode.File,
+    fileSize: '10mb',
+    whitelist: [
+        // images
+        '.jpg',
+        '.jpeg',
+        '.png',
+        '.gif',
+        '.bmp',
+        '.wbmp',
+        '.webp',
+        '.tif',
+        '.psd',
+        // text
+        '.svg',
+        '.js',
+        '.jsx',
+        '.json',
+        '.css',
+        '.less',
+        '.html',
+        '.htm',
+        '.xml',
+        '.pdf',
+        // tar
+        '.zip',
+        '.gz',
+        '.tgz',
+        '.gzip',
+        // video
+        '.mp3',
+        '.mp4',
+        '.avi',
+    ],
+    tmpdir: (0, path_1.join)((0, os_1.tmpdir)(), 'midway-upload-files'),
+};
+//# sourceMappingURL=config.default.js.map

package/dist/configuration.d.ts

@@ -0,0 +1,7 @@
+import { MidwayApplicationManager } from '@midwayjs/core';
+export declare class UploadConfiguration {
+    applicationManager: MidwayApplicationManager;
+    uploadConfig: any;
+    onReady(): Promise<void>;
+}
+//# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.js

@@ -0,0 +1,50 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadConfiguration = void 0;
+const decorator_1 = require("@midwayjs/decorator");
+const DefaultConfig = require("./config/config.default");
+const core_1 = require("@midwayjs/core");
+const middleware_1 = require("./middleware");
+const fs_extra_1 = require("fs-extra");
+let UploadConfiguration = class UploadConfiguration {
+    async onReady() {
+        const { tmpdir } = this.uploadConfig;
+        if (tmpdir) {
+            await (0, fs_extra_1.ensureDir)(tmpdir);
+        }
+        this.applicationManager
+            .getApplications(['koa', 'faas', 'express', 'egg'])
+            .forEach(app => {
+            app.useMiddleware(middleware_1.UploadMiddleware);
+        });
+    }
+};
+__decorate([
+    (0, decorator_1.Inject)(),
+    __metadata("design:type", core_1.MidwayApplicationManager)
+], UploadConfiguration.prototype, "applicationManager", void 0);
+__decorate([
+    (0, decorator_1.Config)('upload'),
+    __metadata("design:type", Object)
+], UploadConfiguration.prototype, "uploadConfig", void 0);
+UploadConfiguration = __decorate([
+    (0, decorator_1.Configuration)({
+        namespace: 'upload',
+        importConfigs: [
+            {
+                default: DefaultConfig,
+            },
+        ],
+    })
+], UploadConfiguration);
+exports.UploadConfiguration = UploadConfiguration;
+//# sourceMappingURL=configuration.js.map

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { UploadConfiguration as Configuration } from './configuration';
+export * from './interface';
+export * from './middleware';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Configuration = void 0;
+var configuration_1 = require("./configuration");
+Object.defineProperty(exports, "Configuration", { enumerable: true, get: function () { return configuration_1.UploadConfiguration; } });
+__exportStar(require("./interface"), exports);
+__exportStar(require("./middleware"), exports);
+//# sourceMappingURL=index.js.map

package/dist/interface.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import { Readable } from "stream";
+export declare enum UploadMode {
+    Stream = "stream",
+    File = "file",
+    Buffer = "buffer"
+}
+export interface UploadOptions {
+    mode?: UploadMode;
+    fileSize?: string;
+    whitelist?: string[];
+    tmpdir?: string;
+}
+export interface UploadFileInfo {
+    filename: string;
+    fieldname: string;
+    mimeType: string;
+    data: Buffer | Readable | string;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/interface.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadMode = void 0;
+var UploadMode;
+(function (UploadMode) {
+    UploadMode["Stream"] = "stream";
+    UploadMode["File"] = "file";
+    UploadMode["Buffer"] = "buffer";
+})(UploadMode = exports.UploadMode || (exports.UploadMode = {}));
+//# sourceMappingURL=interface.js.map

package/dist/middleware.d.ts

@@ -0,0 +1,12 @@
+import { IMiddleware, IMidwayLogger } from '@midwayjs/core';
+import { UploadOptions } from '.';
+export declare class UploadMiddleware implements IMiddleware<any, any> {
+    upload: UploadOptions;
+    logger: IMidwayLogger;
+    resolve(app: any): (req: any, res: any, next: any) => Promise<any>;
+    execUpload(ctx: any, req: any, res: any, next: any, isExpress: any): Promise<any>;
+    getUploadBoundary(request: any): false | string;
+    isReadableStream(req: any, isExpress: any): boolean;
+    checkExt(filename: any): boolean;
+}
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.js

@@ -0,0 +1,164 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadMiddleware = void 0;
+const decorator_1 = require("@midwayjs/decorator");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const stream_1 = require("stream");
+const _1 = require(".");
+const upload_1 = require("./upload");
+const getRawBody = require("raw-body");
+let UploadMiddleware = class UploadMiddleware {
+    resolve(app) {
+        if (app.getFrameworkType() === decorator_1.MidwayFrameworkType.WEB_EXPRESS) {
+            return async (req, res, next) => {
+                return this.execUpload(req, req, res, next, true);
+            };
+        }
+        else {
+            return async (ctx, next) => {
+                var _a;
+                const req = ((_a = ctx.request) === null || _a === void 0 ? void 0 : _a.req) || ctx.request;
+                return this.execUpload(ctx, req, ctx, next, false);
+            };
+        }
+    }
+    async execUpload(ctx, req, res, next, isExpress) {
+        const { mode, tmpdir, fileSize } = this.upload;
+        const boundary = this.getUploadBoundary(req);
+        if (!boundary) {
+            return next();
+        }
+        ctx.fields = {};
+        let body;
+        if (this.isReadableStream(req, isExpress)) {
+            if (mode === _1.UploadMode.Stream) {
+                const { fields, fileInfo } = await (0, upload_1.parseFromReadableStream)(req, boundary);
+                if (!this.checkExt(fileInfo.filename)) {
+                    res.status = 400;
+                    const errorMessage = 'Invalid filename: ' + fileInfo.filename;
+                    const err = new Error(errorMessage);
+                    this.logger.error(err);
+                    if (isExpress) {
+                        return res.sendStatus(400);
+                    }
+                    return;
+                }
+                else {
+                    ctx.fields = fields;
+                    ctx.files = [fileInfo];
+                    return next();
+                }
+            }
+            body = await getRawBody(req, {
+                limit: fileSize,
+            });
+        }
+        else {
+            body = req.body;
+        }
+        const data = await (0, upload_1.parseMultipart)(body, boundary);
+        if (!data) {
+            return next();
+        }
+        ctx.fields = data.fields;
+        const requireId = `upload_${Date.now()}.${Math.random()}`;
+        const files = data.files;
+        const notCheckFile = files.find(fileInfo => {
+            if (!this.checkExt(fileInfo.filename)) {
+                return fileInfo;
+            }
+        });
+        if (notCheckFile) {
+            res.status = 400;
+            const errorMessage = 'Invalid filename: ' + notCheckFile.filename;
+            const err = new Error(errorMessage);
+            this.logger.error(err);
+            if (isExpress) {
+                return res.sendStatus(400);
+            }
+            return;
+        }
+        ctx.files =
+            mode === 'buffer'
+                ? files
+                : files.map((file, index) => {
+                    const { data, filename } = file;
+                    if (mode === _1.UploadMode.File) {
+                        const ext = (0, path_1.extname)(filename);
+                        const tmpFileName = (0, path_1.resolve)(tmpdir, `${requireId}.${index}${ext}`);
+                        (0, fs_1.writeFileSync)(tmpFileName, data, 'binary');
+                        file.data = tmpFileName;
+                    }
+                    else if (mode === _1.UploadMode.Stream) {
+                        file.data = new stream_1.Readable({
+                            read() {
+                                this.push(data);
+                                this.push(null);
+                            },
+                        });
+                    }
+                    return file;
+                });
+        return next();
+    }
+    getUploadBoundary(request) {
+        var _a;
+        const method = (request.method || request.httpMethod || '').toUpperCase();
+        if (!((_a = request.headers) === null || _a === void 0 ? void 0 : _a['content-type']) || method !== 'POST') {
+            return false;
+        }
+        const contentType = request.headers['content-type'];
+        if (!contentType.startsWith('multipart/form-data;')) {
+            return false;
+        }
+        const boundaryMatch = /boundary=(.*)(;|\s|$)/.exec(contentType);
+        if (!(boundaryMatch === null || boundaryMatch === void 0 ? void 0 : boundaryMatch[1])) {
+            return false;
+        }
+        return boundaryMatch[1];
+    }
+    isReadableStream(req, isExpress) {
+        // ref: https://github.com/rvagg/isstream/blob/master/isstream.js#L10
+        if (req instanceof stream_1.Stream &&
+            typeof req._read === 'function' &&
+            typeof req._readableState === 'object' &&
+            (!req.body || isExpress)) {
+            return true;
+        }
+        if (req.pipe && req.on && !req.body) {
+            return true;
+        }
+        return false;
+    }
+    checkExt(filename) {
+        const ext = (0, path_1.extname)(filename).toLowerCase();
+        const { whitelist } = this.upload;
+        if (!Array.isArray(whitelist)) {
+            return true;
+        }
+        return whitelist.includes(ext);
+    }
+};
+__decorate([
+    (0, decorator_1.Config)('upload'),
+    __metadata("design:type", Object)
+], UploadMiddleware.prototype, "upload", void 0);
+__decorate([
+    (0, decorator_1.Logger)(),
+    __metadata("design:type", Object)
+], UploadMiddleware.prototype, "logger", void 0);
+UploadMiddleware = __decorate([
+    (0, decorator_1.Middleware)()
+], UploadMiddleware);
+exports.UploadMiddleware = UploadMiddleware;
+//# sourceMappingURL=middleware.js.map

package/dist/upload.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+import { Readable } from 'stream';
+import { UploadFileInfo } from './interface';
+export declare const parseMultipart: (body: any, boundary: string) => Promise<{
+    files: any[];
+    fields: {};
+}>;
+export declare const parseFromReadableStream: (readStream: Readable, boundary: any) => Promise<{
+    fields: any;
+    fileInfo: UploadFileInfo;
+}>;
+export declare const bufferIndexOf: (buffer: Buffer, search: Buffer, offset?: number) => number;
+export declare const bufferSplit: (buffer: Buffer, separator: Buffer, limit?: number) => Buffer[];
+export declare const parseHead: (headBuf: Buffer) => {};
+//# sourceMappingURL=upload.d.ts.map

package/dist/upload.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHead = exports.bufferSplit = exports.bufferIndexOf = exports.parseFromReadableStream = exports.parseMultipart = void 0;
+const stream_1 = require("stream");
+const headSeparator = Buffer.from('\r\n\r\n');
+const parseMultipart = async (body, boundary) => {
+    if (typeof body === 'string') {
+        body = Buffer.from(body);
+    }
+    const bufferSeparator = Buffer.from('\r\n--' + boundary);
+    const fields = {};
+    const files = [];
+    (0, exports.bufferSplit)(body, bufferSeparator).forEach(buf => {
+        const [headerBuf, data] = (0, exports.bufferSplit)(buf, headSeparator, 2);
+        const head = (0, exports.parseHead)(headerBuf);
+        if (!head['content-disposition']) {
+            return;
+        }
+        if (!head['content-disposition'].filename) {
+            if (head['content-disposition'].name) {
+                fields[head['content-disposition'].name] = data.toString();
+            }
+            return;
+        }
+        files.push({
+            filename: head['content-disposition'].filename,
+            data,
+            fieldname: head['content-disposition'].name,
+            mimeType: head['content-type'],
+        });
+    });
+    return {
+        files,
+        fields,
+    };
+};
+exports.parseMultipart = parseMultipart;
+const pre = Buffer.from('\r\n');
+const parseFromReadableStream = (readStream, boundary) => {
+    const bufferSeparator = Buffer.from(`\r\n--${boundary}`);
+    const fields = {};
+    const fileInfo = {
+        filename: '',
+        data: null,
+        fieldname: '',
+        mimeType: '',
+    };
+    const emptyBuf = Buffer.alloc(0);
+    // 上一次遗留的 chunk
+    let lastChunk = emptyBuf;
+    // 前一个chunk的后缀
+    let preChunk = emptyBuf;
+    let isTransformFileData = false;
+    let isTransformFileDataEnd = false;
+    // let isEnd = false;
+    let isFirst = true;
+    let allChuns = Buffer.alloc(0);
+    return new Promise(resolve => {
+        fileInfo.data = new stream_1.Transform({
+            highWaterMark: 1000,
+            transform(chunk, encoding, callback) {
+                if (isFirst) {
+                    chunk = Buffer.concat([pre, chunk]);
+                    isFirst = false;
+                }
+                // 已经结束了
+                if (isTransformFileDataEnd) {
+                    return callback(null, null);
+                }
+                // 正在传输中的话
+                if (isTransformFileData) {
+                    if (lastChunk.length) {
+                        chunk = Buffer.concat([lastChunk, chunk]);
+                        lastChunk = emptyBuf;
+                    }
+                    const newPreChunk = Buffer.concat([preChunk, chunk]);
+                    const newBlockIndex = (0, exports.bufferIndexOf)(newPreChunk, bufferSeparator);
+                    // 存在新的块则代表已经结束了
+                    if (newBlockIndex !== -1) {
+                        // 上一个块的最后一部分数据，需要追加写入
+                        const lastDataBlock = newPreChunk.slice(preChunk.length, newBlockIndex);
+                        isTransformFileDataEnd = true;
+                        callback(null, lastDataBlock);
+                        return;
+                    }
+                    // 块尚未结束，则继续写入
+                    callback(null, chunk);
+                    preChunk = newPreChunk.slice(-bufferSeparator.length);
+                    return;
+                }
+                // 未在传输过程中
+                allChuns = Buffer.concat([allChuns, chunk]);
+                const splitAllChuns = (0, exports.bufferSplit)(allChuns, bufferSeparator);
+                for (let chunkIndex = 0; chunkIndex < splitAllChuns.length; chunkIndex++) {
+                    const [headerBuf, data] = (0, exports.bufferSplit)(splitAllChuns[chunkIndex], headSeparator);
+                    const head = (0, exports.parseHead)(headerBuf);
+                    if (!head['content-disposition']) {
+                        continue;
+                    }
+                    if (!head['content-disposition'].filename) {
+                        if (head['content-disposition'].name) {
+                            fields[head['content-disposition'].name] = data.toString();
+                        }
+                        continue;
+                    }
+                    // 这里就是找到了 file 的段，如果没有数据，则需要继续等待
+                    if (!data.length) {
+                        continue;
+                    }
+                    fileInfo.filename = head['content-disposition'].filename;
+                    fileInfo.fieldname = head['content-disposition'].name;
+                    fileInfo.mimeType = head['content-type'];
+                    isTransformFileData = true;
+                    lastChunk = data;
+                    allChuns = emptyBuf;
+                    this.pause();
+                    resolve({ fileInfo, fields });
+                    break;
+                }
+                callback(null, emptyBuf);
+            },
+        });
+        readStream.pipe(fileInfo.data);
+        const empty = new stream_1.Writable();
+        empty._write = function (chunk, encoding, cb) {
+            cb();
+        };
+        fileInfo.data.pipe(empty);
+    });
+};
+exports.parseFromReadableStream = parseFromReadableStream;
+// search buffer index
+const bufferIndexOf = (buffer, search, offset) => {
+    return buffer.indexOf(search, offset);
+};
+exports.bufferIndexOf = bufferIndexOf;
+// split buffer to buffer list
+const bufferSplit = (buffer, separator, limit) => {
+    let index = 0;
+    const result = [];
+    let find = (0, exports.bufferIndexOf)(buffer, separator, index);
+    while (find !== -1) {
+        result.push(buffer.slice(index, find));
+        index = find + separator.length;
+        if (limit && result.length + 1 === limit) {
+            break;
+        }
+        find = (0, exports.bufferIndexOf)(buffer, separator, index);
+    }
+    result.push(buffer.slice(index));
+    return result;
+};
+exports.bufferSplit = bufferSplit;
+const headReg = /^([^:]+):[ \t]?(.+)?$/;
+const parseHead = (headBuf) => {
+    const head = {};
+    const headStrList = headBuf.toString().split('\r\n');
+    for (const headStr of headStrList) {
+        const matched = headReg.exec(headStr);
+        if (!matched) {
+            continue;
+        }
+        const name = matched[1].toLowerCase();
+        const value = matched[2]
+            ? matched[2].replace(/&#(\d+);/g, (origin, code) => {
+                try {
+                    return String.fromCharCode(parseInt(code));
+                }
+                catch (_a) {
+                    return origin;
+                }
+            })
+            : '';
+        if (name === 'content-disposition') {
+            const headCol = {};
+            value.split(/;\s+/).forEach((kv) => {
+                const [k, v] = kv.split('=');
+                headCol[k] = v ? v.replace(/^"/, '').replace(/"$/, '') : v !== null && v !== void 0 ? v : true;
+            });
+            head[name] = headCol;
+        }
+        else {
+            head[name] = value;
+        }
+    }
+    return head;
+};
+exports.parseHead = parseHead;
+//# sourceMappingURL=upload.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@midwayjs/upload",
+  "version": "3.0.0-beta.10",
+  "description": "Midway Component for upload",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --require=ts-node/register ../../node_modules/.bin/jest",
+    "cov": "node --require=ts-node/register ../../node_modules/.bin/jest --coverage --forceExit",
+    "ci": "npm run test"
+  },
+  "keywords": [],
+  "author": "",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "engines": {
+    "node": ">=12"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "fs-extra": "^8.0.1",
+    "raw-body": "^2.4.1"
+  },
+  "devDependencies": {
+    "@midwayjs/core": "^3.0.0-beta.10",
+    "@midwayjs/decorator": "^3.0.0-beta.10",
+    "@midwayjs/express": "^3.0.0-beta.10",
+    "@midwayjs/faas": "^3.0.0-beta.10",
+    "@midwayjs/koa": "^3.0.0-beta.10",
+    "@midwayjs/mock": "^3.0.0-beta.10",
+    "@midwayjs/serverless-app": "^3.0.0-beta.10",
+    "@midwayjs/web": "^3.0.0-beta.10"
+  },
+  "gitHead": "153870f2e2dd6b17673ec7591e49224a6bd51b36"
+}

package/readme.md

@@ -0,0 +1,82 @@
+## Upload 上传组件
+
+适用于 `@midwayjs/faas` 、`@midwayjs/web` 、`@midwayjs/koa` 和 `@midwayjs/express` 多种框架的通用上传组件，支持 `file` (服务器临时文件)、`stream` （流）多种模式。
+
+### Usage
+
+1. 安装依赖
+```shell
+tnpm i @midwayjs/upload --save
+```
+2. 在 configuration 中引入组件,
+```ts
+import * as upload from '../../../../src';
+@Configuration({
+  imports: [
+    // ...other components
+    upload
+  ],
+  importConfigs: [
+    {
+      default: {
+        upload: {                       // 上传组件的配置
+          mode: upload.UploadMode.File, // 默认为 file 模式
+        }
+      }
+    }
+  ]
+})
+export class AutoConfiguration {}
+```
+
+3. 在代码中获取上传的文件
+```ts
+@Controller('/')
+export class HomeController {
+
+  @Inject()
+  ctx;
+
+  @Post('/upload')
+  async upload() {
+    const { files, fields } = this.ctx;
+    /*
+    files = [
+      {
+        filename: 'test.pdf',        // 文件原名
+        data: '/var/tmp/xxx.pdf',    // mode 为 file 时为服务器临时文件地址
+        fieldname: 'test1',          // 表单 field 名
+        mimeType: 'application/pdf', // mime
+      },
+      {
+        filename: 'test.pdf',        // 文件原名
+        data: ReadStream,    // mode 为 stream 时为服务器临时文件地址
+        fieldname: 'test2',          // 表单 field 名
+        mimeType: 'application/pdf', // mime
+      },
+      // ...file 下支持同时上传多个文件
+    ]
+
+    */
+    return {
+      files,
+      fields
+    }
+  }
+}
+```
+
+
+### 配置
+```ts
+export const upload = {
+  // mode: UploadMode, 默认为file，即上传到服务器临时目录，可以配置为 stream
+  mode: 'file',
+  // fileSize: string, 最大上传文件大小，默认为 10mb
+  fileSize: '10mb',
+  // whitelist: string[]，文件扩展名白名单，默认为 null
+  whitelist: null,
+  // tmpdir: string，上传的文件临时存储路径
+  tmpdir: join(tmpdir(), 'midway-upload-files'),
+}
+```