feat: support apigw base64 encode (#46)

* feat: support apigw base64 encode

* docs: update upload.md

* test: fix

Author: yugasun

README.en.md

@@ -2,8 +2,6 @@
 
 # 腾讯云 Koa 组件
 
-简体中文 | [English](https://github.com/serverless-components/tencent-koa/tree/master/README.en.md)
-
 ## 简介
 
 使用腾讯云 Koa 组件，可快速的在腾讯云创建，配置和管理一个 [Koa 框架](https://koajs.com/) 服务。
@@ -152,9 +150,9 @@ module.exports = app
 
 这样应用部署到云函数后，在函数服务逻辑执行前，会先执行 `slsInitialize()` 函数，来初始化数据库连接。
 
-### 还支持哪些组件？
+## 文件上传
 
-可以在 [Serverless Components](https://github.com/serverless/components) repo 中查询更多组件的信息。
+[文件上传教程](https://github.com/serverless-components/tencent-koa/tree/master/docs/upload.md)
 
 ## License
 

README.md

@@ -26,7 +26,7 @@ const credentials = {
 // get serverless construct sdk
 const sdk = getServerlessSdk(instanceYaml.org)
 
-it('should successfully deploy koa app', async () => {
+it('deploy koa app by template', async () => {
   const instance = await sdk.deploy(instanceYaml, credentials)
   expect(instance).toBeDefined()
   expect(instance.instanceName).toEqual(instanceYaml.name)
@@ -39,7 +39,7 @@ it('should successfully deploy koa app', async () => {
   expect(instance.outputs.apigw.environment).toEqual(instanceYaml.inputs.apigatewayConf.environment)
 })
 
-it('should successfully update source code', async () => {
+it('deploy with src code', async () => {
   const srcPath = path.join(__dirname, '..', 'example')
   execSync('npm install', { cwd: srcPath })
   instanceYaml.inputs.src = srcPath
@@ -51,7 +51,7 @@ it('should successfully update source code', async () => {
   expect(instance.outputs.templateUrl).not.toBeDefined()
 })
 
-it('should successfully remove koa app', async () => {
+it('remove koa app', async () => {
   await sdk.remove(instanceYaml, credentials)
   result = await sdk.getInstance(instanceYaml.org, instanceYaml.stage, instanceYaml.app, instanceYaml.name)
 

__tests__/index.test.js

@@ -4,12 +4,12 @@
 >
 > 例如，如果该组件名称是 `test_name`, ·且只部署于一个地域，则可以通过 `${output:${stage}:${app}:test_name.apigw.url}` 在别的组件中获取该组件的 API 网关的 `url`。
 
-| 名称        |      类型       | 描述                                                   |
-| :---------- | :-------------: | :----------------------------------------------------- | ---------------- |
-| templateUrl |     string      | 未提供代码时的模板代码 url                             |
-| region      |     string      | 地域信息（只有一个地域时才提供）                       |
-| scf         | [`FunctionOutput | Record<string,FunctionOutput>`](#云函数输出-`FunctionOutput`) | 云函数输出信息   |
-| apigw       |  [`ApigwOutput   | Record<string:ApigwOutput>`](#API-网关输出-`ApigwOutput`)     | API 网关输出信息 |
+| 名称        |                                       类型                                       | 描述                             |
+| :---------- | :------------------------------------------------------------------------------: | :------------------------------- |
+| templateUrl |                                      string                                      | 未提供代码时的模板代码 url       |
+| region      |                                      string                                      | 地域信息（只有一个地域时才提供） |
+| scf         | [`FunctionOutput | Record<string,FunctionOutput>`](#云函数输出-`FunctionOutput`) | 云函数输出信息                   |
+| apigw       |    [`ApigwOutput | Record<string:ApigwOutput>`](#API-网关输出-`ApigwOutput`)     | API 网关输出信息                 |
 
 ## 云函数输出 `FunctionOutput`
 
@@ -25,30 +25,27 @@
 ## API 网关输出 `ApigwOutput`
 
 | 名称          |                                 类型                                 | 描述                       |
-| :------------ | :------------------------------------------------------------------: | :------------------------- | ------- | -------- |
+| :------------ | :------------------------------------------------------------------: | :------------------------- |
 | serviceId     |                                string                                | API 网关 ID                |
 | subDomain     |                                string                                | API 网关子域名             |
-| enviroment    |                              `"release"                              | "prepub"                   | "test"` | API 网关 |
+| enviroment    |                   `"release" | "prepub" | "test"`                    | API 网关                   |
 | url           |                                string                                | API 网关对外的完整 URL     |
 | traffic       |                             number (0~1)                             | 将多少流量导向该云函数     |
 | customDomains | [CustomDomain[]](#API-网关自定义域名输出-`ApigwOutput.CustomDomain`) | API 网关自定义域名输出列表 |
 
 ## API 网关自定义域名输出 `ApigwOutput.CustomDomain`
 
 | 名称             |                                类型                                | 描述                       |
-| :--------------- | :----------------------------------------------------------------: | :------------------------- | ---------- |
+| :--------------- | :----------------------------------------------------------------: | :------------------------- |
 | domain           |                               string                               | 自定义域名                 |
 | certificateId    |                               string                               | 域名证书 ID                |
 | isDefaultMapping |                              boolean                               | 该自定义域名是否为默认域名 |
 | pathMappingSet   | [PathMapping[]](#-API-网关域名映射规则-`CustomDomain.PathMapping`) | 该域名的路径映射规则列表   |
-| protocols        |                              `"http"                               | "https"`                   | 启用的协议 |
-
-
+| protocols        |                         `"http" | "https"`                         | 启用的协议                 |
 
 ## API 网关域名映射规则 `CustomDomain.PathMapping`
 
 | 名称       |  类型  | 描述             |
 | :--------- | :----: | :--------------- |
 | path       | string | 路径             |
 | enviroment | string | 路径映射到的环境 |
-

docs/output.md

@@ -0,0 +1,31 @@
+## 文件上传说明
+
+项目中如果涉及到文件上传，需要依赖 API 网关提供的 [Base64 编码能力](https://cloud.tencent.com/document/product/628/51799)，使用时只需要 `serverless.yml` 中配置 `isBase64Encoded` 为 `true`，如下：
+
+```yaml
+app: appDemo
+stage: dev
+component: koa
+name: koaDemo
+
+inputs:
+  # 省略...
+  apigatewayConf:
+    isBase64Encoded: true
+    # 省略...
+  # 省略...
+```
+
+当前 API 网关支持上传最大文件大小为 `2M`，如果文件过大，请修改为前端直传对象存储方案。
+
+## Base64 示例
+
+此 Github 项目的 `example` 目录下存在模板文件：
+
+- [sls.upload.js](../example/sls.upload.js)
+
+开发者可根据个人项目需要参考修改，使用时需要复制文件名为 `sls.js`。
+
+文件中实现了文件上传接口 `POST /upload`，如果要支持文件上传，需要安装 `@koajs/multer` 和 `multer` 包。
+
+同时需要在 `serverless.yml` 的 `apigatewayConf` 中配置 `isBase64Encoded` 为 `true`。

docs/upload.md

@@ -9,8 +9,8 @@
   "author": "yugasun",
   "license": "MIT",
   "dependencies": {
-    "koa": "^2.11.0",
-    "koa-router": "^8.0.8",
+    "@koa/router": "^10.0.0",
+    "koa": "^2.13.1",
     "koa-sendfile": "^2.0.1"
   }
 }

example/package.json

@@ -1,4 +1,3 @@
-org: orgDemo
 app: appDemo
 stage: dev
 component: koa

example/serverless.yml

@@ -1,17 +1,25 @@
 const Koa = require('koa')
-const KoaRouter = require('koa-router')
+const KoaRouter = require('@koa/router')
 const sendFile = require('koa-sendfile')
 const path = require('path')
 
 const app = new Koa()
 const router = new KoaRouter()
+const isServerless = process.env.SERVERLESS
+const PORT = 3000
 
 // Routes
-router.get(`/*`, async (ctx) => {
+router.get(`/`, async (ctx) => {
   await sendFile(ctx, path.join(__dirname, 'index.html'))
 })
 
 app.use(router.allowedMethods()).use(router.routes())
 
 // don't forget to export!
-module.exports = app
+if (isServerless) {
+  module.exports = app
+} else {
+  app.listen(PORT, () => {
+    console.log(`Server start on http://localhost:${PORT}`)
+  })
+}

example/sls.js

@@ -0,0 +1,30 @@
+const Koa = require('koa')
+const KoaRouter = require('@koa/router')
+const multer = require('@koa/multer')
+const sendFile = require('koa-sendfile')
+const path = require('path')
+
+const isServerless = process.env.SERVERLESS
+const app = new Koa()
+const router = new KoaRouter()
+const upload = multer({ dest: isServerless ? '/tmp/upload' : './upload' })
+
+router.get(`/`, async (ctx) => {
+  await sendFile(ctx, path.join(__dirname, 'index.html'))
+})
+router.post('/upload', upload.single('file'), (ctx) => {
+  ctx.body = {
+    success: true,
+    data: ctx.file
+  }
+})
+
+app.use(router.routes()).use(router.allowedMethods())
+
+if (isServerless) {
+  module.exports = app
+} else {
+  app.listen(3000, () => {
+    console.log(`Server start on http://localhost:3000`)
+  })
+}

example/sls.upload.js

@@ -1,5 +1,5 @@
 name: koa
-version: 0.3.2
+version: 0.4.0
 author: 'Tencent Cloud, Inc.'
 org: 'Tencent Cloud, Inc.'
 description: Deploy a serverless Koa.js application onto Tencent SCF and API Gateway.