手把手搭建koa2后端服務器-API文檔生成（番外）

為我們之前的框架沒有接入 API 文檔，而大多數 API 文檔均采用編寫注釋來生成，我不是特別喜歡這種方式，所以暫時沒有添加，后來發現一個庫—koa-swagger-decorator，它對 koa-router 進行了封裝，可以自動生成 API 文檔，而且自帶驗證，這種方式比較好，但是項目結構上會有一些細微的差異，因此我決定單開一個分支來使用這種方式初始化一個新的項目，大家可以選擇自己喜歡的項目結構來使用，這篇文檔我只介紹與之前不同的地方，如果一模一樣，我就不單獨寫了。

創建項目目錄

mkdir koa2-demo

yarn init

安裝依賴庫

yarn add koa koa-body koa-swagger-decorator dotenv log4js typeorm reflect-metadata mysql2 koa2-cors bcryptjs jsonwebtoken

yarn add -D ts-node typescript nodemon @types/dotenv @types/koa @types/log4js @types/reflect-metadata @types/koa2-cors @types/bcryptjs @types/jsonwebtoken

這里我們一次性把常用的庫全部安裝上，下面我大概介紹以下庫的用途：

koa-body：解析 post 參數的庫，koa 默認會解析查詢參數和路徑參數，但是對于請求體沒有解析，所以需要這個庫，我們就能使用 ctx.request.body 來處理請求體了。
koa-swagger-decorator：這個庫當中集成了路由（koa-router）、認證（validator）庫，這個就不需要我們單獨安裝了。
dotenv：環境變量讀取庫。
log4js：日志處理庫。
typeorm、reflect-metadata、mysql2：數據庫操作庫。
bcryptjs：加密庫。
jsonwebtoken：jwt 加解密庫。
ts-node：支持ts直接運行的庫。
nodemon：監控文件改變熱加載的庫。
其他：@types開頭的庫都是為了支持 ts 提示的，在安裝庫的時候使用@type/庫名，如果可以安裝就安裝，如果沒有就不需要安裝。

接下來除了請求參數校驗和路由動態加載以外，其他的均可參考之前的教程。

路由處理修改

// src/router/index.ts
import path from 'path';
import { SwaggerRouter } from 'koa-swagger-decorator';

const router=new SwaggerRouter();

// 定義 schema 的初始信息
router.swagger({
  title: 'koa2 基礎 API',
  description: 'API',
  version: '1.0.0',
});

// 這里會動態的檢索 controller 目錄下的所有 .js、.ts 文件，并獲取默認導出類，生成路由和API
// 因此就不需要我們再收到注冊路由和自己實現動態加載路由的功能了，具體的路由格式請參考 controller
// 目錄下的實現
router.mapDir(path.resolve(__dirname, '../controller'));

// 重定向/路由到/swagger-html路由，這是默認的API文檔路由地址
router.redirect('/', '/swagger-html');

export default router;

業務邏輯修改

之前我們通過在 controller 下創建子目錄及指定名稱的文件來區分業務邏輯，例如

- controller
  - common
    - view.ts
    - router.ts
    - rules.ts
    - types.ts

現在我們可以簡化這個目錄，結構如下：

- controller
  - common
    - view.ts
    - schema.ts

其中 view.ts 中實現我們的業務邏輯，schema.ts 中定義我們的參數信息，用來進行參數驗證和API文檔生成。

修改登錄邏輯

// src/controller/common/view.ts
import { Context } from 'koa';
import bcryptjs from 'bcryptjs';
import { request, summary, body, tags } from 'koa-swagger-decorator';
import response from '../../utils/response';
import { loginRules } from './schema';
import User from '../../entity/User';
import { generateToken } from '../../utils/auth';

export default class IndexController {
  @request('post', '/login')
  @summary('登錄')
  @tags(['基礎接口'])
  @body(loginRules)
  static async login(ctx: Context) {
    const data=ctx.request.body;
    // 校驗用戶是否存在
    let user: User | undefined=await User.getUserInfo(data.username);
    if (!user) {
      response.error(ctx, '用戶不存在');
      return;
    }

    // 校驗密碼是否正確
    if (!bcryptjs.compareSync(data.password, user.password)) {
      response.error(ctx, '密碼錯誤');
      return;
    }

    const { password, ...rest }=user;
    const token=generateToken(rest);
    response.success(ctx, { token }, '登錄成功');
  }
}

主體邏輯基本沒有變化，有幾個需要注意的點

類必須使用 export default 導出，路由掃描時會通過這個進行驗證（必須）
使用@request裝飾器修飾函數，參數為方法類型和地址，路由注冊是就會根據這些生成，而不是根據我們的函數名（必須）
函數應該定義成靜態的，因為在使用的時候并不會創建類對象，使用靜態方法更符合狀況（可選）

我們訪問：http://localhost:3100/ 就可以看到API文檔

路由修飾參數的意義

路由裝飾器分為兩種：函數裝飾器和類裝飾器

函數裝飾器

request：定義路由方法和地址，用于注冊路由和API接口文檔
summary：API 文檔中的路由解釋，參考上圖
tags：路由分類，API 文檔中用來對多個路由進行分組顯示。
query：查詢參數：url?name=xxx&age=12
path：路徑參數：/getuserinfo/{id}
body：請求體參數
formData：表單數據。
middlewares：koa中間件，eg：[md1, md2]
security：
description：接口描述
responses：接口返回值，可以設定不同的狀態返回不同的數據
deprecated：

類裝飾器

orderAll：參數為數字，表示在文檔中的位置。
tagsAll：此類下的所有路由都屬于這個tag。
responsesAll：此類下的所有路由都返回這種類型。
middlewaresAll：此類下的所有路由都擁有的中間件。
securityAll：
deprecatedAll：
queryAll：此類下的所有路由都擁有的查詢參數，與函數的查詢參數會合并。

參數驗證

參數校驗支持：string, number, boolean, object, array。在object和array里面的參數也支持校驗，對于integer類型是不支持校驗的，會直接返回其值。默認是開啟校驗的，可以通過配置關閉校驗。

router.mapDir(__dirname, { doValidation: true})

經過校驗的數據可以通過ctx.validatedBody等方式獲取經過校驗的數據了，對應關系如下：

ctx.query ≤==> ctx.validatedQuery
ctx.params ≤==> ctx.validatedParams
ctx.request.body ≤==> ctx.validatedBody

校驗對象配置

基礎校驗字段

字段	值類型	備注
required	boolean	必須參數
example	any	參數類型，API 文檔中使用的示例
description	string	接口描述
readOnly	boolean	只讀參數
writeOnly	boolean	只寫參數
nullable	boolean	是否可以為空

字符串類型

字段	值類型	備注
type	'string'
minLength	number

在前面

今年國慶假期終于可以憋在家里了不用出門了，不用出去看后腦了，真的是一種享受。這么好的光陰怎么浪費，睡覺、吃飯、打豆豆這怎么可能（耍多了也煩），完全不符合我們程序員的作風，趕緊起來把文章寫完。

這篇文章比較基礎，在國慶期間的業余時間寫的，這幾天又完善了下，力求把更多的前端所涉及到的關于文件上傳的各種場景和應用都涵蓋了,若有疏漏和問題還請留言斧正和補充。

自測讀不讀

以下是本文所涉及到的知識點，break or continue ?

文件上傳原理
最原始的文件上傳
使用 koa2 作為服務端寫一個文件上傳接口
單文件上傳和上傳進度
多文件上傳和上傳進度
拖拽上傳
剪貼板上傳
大文件上傳之分片上傳
大文件上傳之斷點續傳
node 端文件上傳

原理概述

原理很簡單，就是根據 http 協議的規范和定義，完成請求消息體的封裝和消息體的解析，然后將二進制內容保存到文件。

我們都知道如果要上傳一個文件，需要把 form 標簽的enctype設置為multipart/form-data,同時method必須為post方法。

那么multipart/form-data表示什么呢？

multipart互聯網上的混合資源，就是資源由多種元素組成，form-data表示可以使用HTML Forms 和 POST 方法上傳文件，具體的定義可以參考RFC 7578。

multipart/form-data 結構

看下 http 請求的消息體

請求頭：

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryDCntfiXcSkPhS4PN 表示本次請求要上傳文件，其中boundary表示分隔符，如果要上傳多個表單項，就要使用boundary分割，每個表單項由———XXX開始，以———XXX結尾。

消息體- Form Data 部分

每一個表單項又由Content-Type和Content-Disposition組成。

Content-Disposition: form-data 為固定值，表示一個表單元素，name 表示表單元素的名稱，回車換行后面就是name的值，如果是上傳文件就是文件的二進制內容。

Content-Type：表示當前的內容的 MIME 類型，是圖片還是文本還是二進制數據。

解析

客戶端發送請求到服務器后，服務器會收到請求的消息體，然后對消息體進行解析，解析出哪是普通表單哪些是附件。

可能大家馬上能想到通過正則或者字符串處理分割出內容，不過這樣是行不通的，二進制buffer轉化為string,對字符串進行截取后，其索引和字符串是不一致的，所以結果就不會正確，除非上傳的就是字符串。

不過一般情況下不需要自行解析，目前已經有很成熟的三方庫可以使用。

至于如何解析，這個也會占用很大篇幅，后面的文章在詳細說。

最原始的文件上傳

使用 form 表單上傳文件

在 ie時代，如果實現一個無刷新的文件上傳那可是費老勁了，大部分都是用 iframe 來實現局部刷新或者使用 flash 插件來搞定，在那個時代 ie 就是最好用的瀏覽器（別無選擇）。

DEMO

這種方式上傳文件，不需要 js ，而且沒有兼容問題，所有瀏覽器都支持，就是體驗很差，導致頁面刷新，頁面其他數據丟失。

HTML

 <form method="post" action="http://localhost:8100" enctype="multipart/form-data">

        選擇文件:
            <input type="file" name="f1"/> input 必須設置 name 屬性，否則數據無法發送<br/>
<br/>
            標題：<input type="text" name="title"/><br/><br/><br/>

        <button type="submit" id="btn-0">上 傳</button>

</form>

復制代碼

文件上傳接口

服務端文件的保存基于現有的庫koa-body結合 koa2實現服務端文件的保存和數據的返回。

在項目開發中，文件上傳本身和業務無關，代碼基本上都可通用。

在這里我們使用koa-body庫來實現解析和文件的保存。

koa-body 會自動保存文件到系統臨時目錄下，也可以指定保存的文件路徑。

然后在后續中間件內得到已保存的文件的信息，再做二次處理。

ctx.request.files.f1 得到文件信息，f1為input file 標簽的 name
獲得文件的擴展名，重命名文件

NODE

/**
 * 服務入口
 */
var http=require('http');
var koaStatic=require('koa-static');
var path=require('path');
var koaBody=require('koa-body');//文件保存庫
var fs=require('fs');
var Koa=require('koa2');

var app=new Koa();
var port=process.env.PORT || '8100';

var uploadHost=`http://localhost:${port}/uploads/`;

app.use(koaBody({
    formidable: {
        //設置文件的默認保存目錄，不設置則保存在系統臨時目錄下  os
        uploadDir: path.resolve(__dirname, '../static/uploads')
    },
    multipart: true // 開啟文件上傳，默認是關閉
}));

//開啟靜態文件訪問
app.use(koaStatic(
    path.resolve(__dirname, '../static') 
));

//文件二次處理，修改名稱
app.use((ctx)=> {
    var file=ctx.request.files.f1;//得道文件對象
    var path=file.path;
    var fname=file.name;//原文件名稱
    var nextPath=path+fname;
    if(file.size>0 && path){
        //得到擴展名
        var extArr=fname.split('.');
        var ext=extArr[extArr.length-1];
        var nextPath=path+'.'+ext;
        //重命名文件
        fs.renameSync(path, nextPath);
    }
    //以 json 形式輸出上傳文件地址
    ctx.body=`{
        "fileUrl":"${uploadHost}${nextPath.slice(nextPath.lastIndexOf('/')+1)}"
    }`;
});

/**
 * http server
 */
var server=http.createServer(app.callback());
server.listen(port);
console.log('demo1 server start ......   ');
復制代碼

CODE

https://github.com/Bigerfe/fe-learn-code/

言

Koa 是基于 Node.js 平臺的下一代 web 開發框架，參考了不少資料都是介紹 Koa 和 Express 之間的異同以及簡單的對比。

由于之前學習 Express 主要是因為需要通過 Express 進行服務端的編碼，所以本期小編也嘗試用 Koa 進行服務端編碼，看看 Koa 是如何運行的。

koa地址：https://koa.bootcss.com/

一、引入koa

const Koa=require("koa");
const app=new Koa();

二、引入路由koa-router

編寫服務端一般都需要路由名稱，koa-router 可以幫助你定義的路由一次性進行映射。

const router=require("koa-router")();
app.use(router.routes())         // 啟動路由

三、引入cors

cors 是 koa 處理跨域請求的一個包，只需要引用一下即可處理跨域。

const cors=require("@koa/cors");
app.use(cors())

四、編寫請求

1. get 請求

// http://localhost:8080/news
router.get("/news", async ctx=> {
    console.log(ctx.query);       // 請求參數
});
// http://localhost:8080/news2/aaa
router.get("/news2/:id", async ctx=> {
    console.log(ctx.params);   // {id:'aaa'}
});

2. post 請求

post 請求獲取請求參數需要通過 koa-bodyparser 模塊來進行獲取。

const bodyparser=require(“koa-bodyparser”)
app.use(bodyparser());
// http://localhost:8080/news3
router.post("/news3", async ctx=> {
    let data=await ctx.request.body
});

五、ctx參數

ctx.body：為回調參數
ctx.type：回調類型
ctx.success：成功回調，需要自己定義成函數并執行
ctx.fail：失敗回調，需要自己定義成函數并執行
ctx.status：狀態碼

以上就是本期關于 Koa 框架學習的小分享，希望能給大家帶來幫助。

下期給大家分享更多實戰中的點滴，如果大家對此感興趣，歡迎各位關注、留言，大家的支持就是我的動力！

在線咨詢

上一篇：網頁游戲如何開發網頁游戲類型有哪些？
下一篇：「筆記」零基礎學前端筆記，什么是CSS們到底發揮怎樣

您的項目需求

*請認真填寫需求信息，我們會在24小時內與您取得聯系。

整合營銷服務商