Koa

基本介绍

Koa是Node.js中非常出名的一款WEB框架，其特点是短小精悍性能强。

它由Express原版人马打造，同时也是Egg框架的设计蓝图，可以说Koa框架的学习性价比是非常高的。

官方文档

项目搭建

我们先初始化一个项目：

$ npm init

TypeScript可以让项目更加容易维护，所以安装TypeScript是不可或缺的一部分：

$ npm install typescript ts-node @types/node peer dependencies yourself --save

当安装完成后，需要在根目录中新建src目录以及server.ts文件：

$ mkdir ./src
$ touch ./src/server.ts

下一步是填入TypeScript的配置文件：

$ tsc --init

配置文件内容如下：

{
  "include": [
    "./src/**/*", // 仅编译src目录下的所有ts文件
  ],
  "exclude": [
    "./src/test/**/*", // 不编译src目录中test目录下所有的ts文件
  ],
  "compilerOptions": {
    "target": "ES6", // 编译后生成的js版本为es6
    "module": "CommonJS", // 编译后的模块使用规范为CommonJs
    "lib": [ // node环境中测试ts代码所需要使用的库
      "ES6"
    ],
    "outDir": "./dist", // 编译后生成的js文件存放路径
    "allowJs": true, // 二次编译js文件
    "checkJs": true, // 验证js文件语法
    "removeComments": false, // 编译后的js文件删除注释信息
    "noEmitOnError": true, // 如果编译时出现错误，编译将终止
    "strict": true, // 启用TypeScript的严格模式
    "alwaysStrict": true, // 启用JavaScript的严格模式
    "noFallthroughCasesInSwitch": true, // 检测switch语句块是否正确的使用了break
    "noImplicitReturns": true, // 检测函数是否具有隐式的返回值
    "noUnusedLocals": false, // 检测是否具有未使用的局部变量
    "noUnusedParameters": false, // 检测是否具有未使用的函数参数
    "allowUnreachableCode": true, // 检测是否具有永远不会运行的代码
  }
}

由于Koa是第三方框架，所以你应该先安装它：

$ npm install koa --save
$ npm install @types/koa --save

快速上手

使用Koa框架搭建一个HTTP服务器非常的简单，你只需要以下几行代码即可搞定。

import * as Koa from "koa"

const server: Koa = new Koa()

server.use(async (ctx: Koa.Context) => {
    ctx.response.body = "HELLO KOA!";
})

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

级联操作

每一个视图函数中，都具有2个参数ctx和next，而通过next你可以实现级联操作。

如下所示，它将按顺序打印1、2、3、4、5：

import * as Koa from "koa"

const server: Koa = new Koa()

server.use(async (ctx: Koa.Context, next: Koa.Next) => {
    const start: number = Date.now()
    console.log("1");
    await next()
    console.log("5");
    ctx.response.body = "HELLO KOA!"
})

server.use(async (ctx: Koa.Context, next: Koa.Next) => {
    console.log("2");
    await next();
    console.log("4");
})

server.use(async (ctx: Koa.Context, next: Koa.Next) => {
    console.log("3");
    console.log("hello middleware");
})


server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

路由系统

koa-router

默认的Koa框架路由系统不是很完善，对此你可以使用koa-router插件，官方所提供的文档非常齐全，你可以自行前往查看，包括嵌套路由、动态路由等知识在官方文档里面都有详细的示例，这里不再阐述。

首先需要进行下载：

$ npm install koa-router --save
$ npm install @types/koa-router --save

然后就可以进行使用了，注意现在Middleware View Function的编写不再是通过server.use()进行注册了而是通过router.use()进行注册，代码如下：

import * as Koa from "koa"
import * as Router from 'koa-router'

const server: Koa = new Koa()
const router: Router = new Router()

// 1. 装载插件
server.use(router.routes())

// 2.书写视图，注意后面都是编程router.use()
router.get("/api/get", async (ctx: Koa.Context, next: Koa.Next) => {
    // 3.等待之前的插件处理完成后再运行Middleware View Function
    await next()
    ctx.response.body = "HELLO KOA!"
})

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

请求方式

koa-router能够限制请求方式，如下所示，其中all()方法能支持所有的请求：

router
  .get('/', (ctx, next) => {
    ctx.body = 'Hello World!';
  })
  .post('/users', (ctx, next) => {
    // ...
  })
  .put('/users/:id', (ctx, next) => {
    // ...
  })
  .del('/users/:id', (ctx, next) => {
    // ...
  })
  .all('/users/:id', (ctx, next) => {
    // ...
  });

请求相关

ctx.request

ctx是一个上下文对象，你可以通过ctx.request获得本次HTTP服务的请求对象。

在请求对象中它提供了很多属性可供我们使用，以下只例举一些比较常见的：

结果如下：

ctx.request.href            http://localhost:3000/api/get?name=Jack
ctx.request.origin          http://localhost:3000
ctx.request.host            localhost:3000
ctx.request.hostname        localhost
ctx.request.url             /api/get?name=Jack
ctx.request.path            /api/get
ctx.request.query           { name: 'Jack' }

params

对于动态的URL params，可以使用ctx.params获取，注意！这是vue-router所提供的一个方法，它并不存在于ctx.request对象中：

import * as Koa from "koa"
import * as Router from 'koa-router'

const server: Koa = new Koa()
const router: Router = new Router()

server.use(router.routes())

router.get("/api/get/:id?", async (ctx: Koa.Context, next: Koa.Next) => {
    await next()
    // http://localhost:3000/api/get/8?k1=v1
    console.log(ctx.params.id);  // 8
    ctx.response.body = "HELLO KOA!"
})

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

get请求参数

对于URL中的query请求参数来说，你可以直接通过ctx.request.query进行获取：

import * as Koa from "koa"
import * as Router from 'koa-router'

const server: Koa = new Koa()
const router: Router = new Router()

server.use(router.routes())

router.get("/api/get/:id?", async (ctx: Koa.Context, next: Koa.Next) => {
    await next()
    // http://localhost:3000/api/get/8?k1=v1
    console.log(ctx.request.query);  // { k1: 'v1' }
    ctx.response.body = "HELLO KOA!"
})

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

post请求参数

对于请求体中的data请求参数来说，我们可以通过第三方插件koa-body来让它的获取更加的方便。

因为默认的ctx.request对象中没有获取请求体的方法，但是使用koa-body插件后它会向ctx.request中封装一个body属性，调用它你将会获得data请求参数对象。

要想使用koa-body插件，需要对其进行安装：

$ npm install koa-body --save
$ npm install @types/koa__cors --save

示例如下：

import * as Koa from "koa"
import * as Router from 'koa-router'
import * as koaBody from "koa-body"

const server: Koa = new Koa()
const router: Router = new Router()

server.use(router.routes())
server.use(koaBody({
    // 是否支持 multipart-formdata 的表单
    multipart: true,
}))

router.post('/api/post', async (ctx, next) => {
    // 等待之前的插件处理完成后再运行Middleware View Function
    // 否则你必须将server.use()的插件应用语句放在
    // Middleware View Function的下面
    await next()
    console.log(ctx.request.body);
    ctx.response.body = "HELLO KOA!"
});

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

上传文件

koa-body插件同样支持对文件自动上传，如下所示，我们在使用之前需要对其进行一些小小的配置，在获取文件后它将自动进行上传。

我们可通过ctx.request.files参数获取文件对象，与ctx.request.body一样，它也是koa-body所封装的方法：

import * as fs from "fs"
import * as path from "path"
import * as Koa from "koa"
import * as Router from 'koa-router'
import * as koaBody from "koa-body"

const server: Koa = new Koa()
const router: Router = new Router()

server.use(router.routes())
server.use(koaBody({
    // 是否支持 multipart-formdata 的表单
    multipart: true,
    formidable: {
        // 上传的目录
        uploadDir: path.join(__dirname, 'upload'),
        // 保持文件的后缀
        keepExtensions: true,
        // 最大支持上传8M的文件
        maxFieldsSize: 8 * 1024 * 1024,
        // 文件上传前的设置
        onFileBegin: (name: string, file: any): void => {
            const filePath: string = path.join(__dirname, "upload");
            // 检查是否有upload目录
            if (!fs.existsSync(filePath)) {
                fs.mkdirSync(filePath);
                console.log("mkdir success!");
            }
        }
    }
}))

router.post('/api/upload', async (ctx, next) => {
    // 等待之前的插件处理完成后再运行Middleware View Function
    // 否则你必须将server.use()的插件导入语句放在
    // Middleware View Function的下面
    await next()
    // 获取文件对象avatar
    const avatar: any | null = ctx.request.files["avatar"]
    // 自动写入...
    // 将上传后的信息自动返回
    ctx.response.set("Content-Type", "application/json")
    ctx.response.body = JSON.stringify(avatar)
});

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

文件对象中包含的属性如下：

{
    "size": 文件大小,
    "path": "上传路径",
    "name": "文件原本的名字",
    "type": "image/jpeg",
    "mtime": "文件最后修改时间"
}

koa-body配置

以下是koa-body在进行使用时的一级配置项：

以下是koa-body在进行使用时的二级（formidable）配置项：

ctx.req

ctx.request是Koa框架所封装的请求对象，而ctx.req则是原生的http库的请求对象。

我们不建议对其进行使用，具体所包含的属性可以参照http库中的req对象。

响应相关

ctx.response

ctx是一个上下文对象，你可以通过ctx.response获得本次HTTP服务的响应对象。

在响应对象中它也提供了很多属性或者方法可供我们使用，以下只例举一些比较常见的：

设置响应码

响应码一般来说不需要我们手动设置，它的默认值大多数情况下总是200或者204.

如果你想手动进行设置，可参照下面这个示例：

router.get("/api/get", async (ctx: Koa.Context, next: Koa.Next) => {
    ctx.response.status = 403;
    ctx.response.message = "Reject service";
})

设置响应头

如果你没有使用TypeScript来规范你的项目代码，则可以直接对响应头做出结构改变的操作：

router.get("/api/get", async (ctx: Koa.Context, next: Koa.Next) => {
    ctx.response.headers = { "Content-Type": "text/plain; charset=utf-8" };
    ctx.response.body = "HELLO KOA!";
})

如果你使用了TypeScript来规范你的项目代码，则必须通过ctx.response.set()方法来设置响应头：

// 设置一个 ctx.response.set(k, v)
ctx.response.set("Content-Type", "text/plain; charset=utf-8");

// 设置多个 ctx.response.set({k1 : v1, k2 : v2, ...})
ctx.response.set({
    "Content-Type": "text/plain; charset=utf-8",
    "Token" : "=fdss9d9k!-=f23"
});

重定向

对于需要跳转的路由，可以使用ctx.response.redirect()方法来进行跳转：

import * as Koa from "koa"
import * as Router from 'koa-router'

const server: Koa = new Koa()
const router: Router = new Router()

server.use(router.routes())

router.get("/", async (ctx: Koa.Context, next: Koa.Next) => {
    ctx.redirect("/index");
    ctx.response.status = 302;
})

router.get("/index", async (ctx: Koa.Context, next: Koa.Next) => {
    ctx.response.body = "HELLO KOA!";
})


server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

CORS跨域

利用第三方插件@koa/cors解决跨域问题：

$ npm install @koa/cors

它的使用非常简单，直接server.use()即可，当然你也可以对其进行详细配置，这里不再进行配置举例：

import * as Koa from "koa"
import * as cors from "@koa/cors"

const server: Koa = new Koa()
server.use(cors())

ctx.res

ctx.response是Koa框架所封装的响应对象，而ctx.res则是原生的http库的响应对象。

我们不建议对其进行使用，具体所包含的属性可以参照http库中的res对象。

jsonwebtoken

基本介绍

Koa框架中提供了Cookie相关的操作，但是Cookie在目前的项目开发中使用的比较少，故这里不再进行例举，而是推荐使用第三方插件jsonwebtoken来生成JWT进行验证。

如果你不了解JWT，我之前也有写过相关的技术文章，你可以搜索并进行参考。

现在我假设你已经了解过了JWT相关的知识，让我开始第一步，安装jsonwebtoken这个插件吧。

$ npm install jsonwebtoken --save

安装后之后我们需要在src目录中新建一个JWT目录以及一个index.js文件，用来JWT存放相关的代码：

$ mkdir ./src/jwt
$ touch ./src/jwt/index.ts

封装使用

一般的手动签发token我们需要用到下面3种类型的数据：

• header：头部信息，可定义加密类型、加密方式
• playload：荷载信息，可定义token过期时间、签发者、接受者以及私有声明信息，但不建议存放敏感信息
• secret：密钥，该密钥只能由服务端所知晓

但是jsonwebtoken对其进行封装，直接使用config来配置即可，以下是签发和验证token的案例，默认它将采用HASH256算法进行JWT格式封装：

import * as JWT from "jsonwebtoken"

// 服务端的字符串，绝对保密
const secret = "=937dce32&?f99"

function issueToken(userID: number, userName: string, expiration: number = 86400 * 14) {
    // 定义荷载信息，不要存放敏感的诸如用户密码之类的数据
    const playLoad = {
        id: String(userID),
        name: userName,
    }
    // 定义配置文件，下面有一些选项也是属于荷载信息的一部分，如过期时间、签发时间、面向谁签发的
    const config = {
        // 定义头部信息
        header: {},
        // 过期时间、按秒计算，也可以是字符串，如1day、1min等
        expiresIn: expiration,
        // 在签发后多久之前这个token是无用的，如果是数字则是按秒计算
        notBefore: `120ms`,
        // 面向谁签发的
        audience: userName,
        // 发行者是谁
        issuer: "Node.js KOA",
        // 该token的发布主题
        subject: "demo",
        // 不使用时间戳
        noTimestamp: true,
    }
    // 第一个对象中也可以添加额外的属性，它将作为荷载信息被格式化
    return JWT.sign(playLoad, secret, config)
}

function verifyToken(token: string | string[]): { verify: boolean, playLoad: { id: string, name: string, nbf: number, exp: number, aud: string, iss: string, sub: string } | null } {
    // 如果没有抛出异常，则验证成功
    try {
        return {
            playLoad: JWT.verify(token, secret),
            verify: true
        }
    }
    // 如果抛出了异常，则验证失败
    catch {
        return {
            playLoad: null,
            verify: false
        }
    }
}

export { issueToken, verifyToken }

使用案例：

// 手动传入用户ID以及用户姓名还有token过期时间
const token = issueToken(19, "Jack", 7);

// 传入token验证是否成功
console.log(verifyToken(token));

验证成功返回的结果：

{
  playLoad: {
    id: '19',
    name: 'Jack',
    nbf: 1633537512,
    exp: 1633537519,
    aud: 'Jack',
    iss: 'Node.js KOA',
    sub: 'demo'
  },
  verify: true
}

实战演示

我们以一个简单的案例来进行说明，后端有2个api接口，分别是index和login。

若用户第一次访问主页，则必须先进行登录后才能访问主页，此后的20s内用户不用再重新登录：

import * as Koa from "koa"
import * as Router from 'koa-router'
import * as koaBody from 'koa-body'
import * as cors from "@koa/cors"
import * as JWT from "./jwt/index"

// 模拟数据库
const userDataBase: { id: number, username: string, password: string, age: number }[] = [
    { id: 1, username: "Jack", password: "123456", age: 18 }
]

const server: Koa = new Koa()
const router: Router = new Router()

server.use(cors())
server.use(koaBody({
    // 是否支持 multipart-formdata 的表单
    multipart: true,
}))
server.use(router.routes())

server.use(async (ctx: any, next: any) => {
    await next()
    // 由于所有返回的数据格式都是JSON，故这里直接进行生命
    ctx.response.set("Content-Type", "application/json");
})

router.get("/api/index", async (ctx: Koa.Context, next: Koa.Next) => {
    await next()
    const token: string | string[] = ctx.request.get("JWT");
    // 如果能获取token就进行验证，判断是否是伪造请求
    if (token) {
        const { verify, playLoad } = JWT.verifyToken(token)
        if (verify) {
            // 验证通过，直接返回playLoad给前端
            ctx.response.body = JSON.stringify({
                code: 200,
                message: playLoad
            })
        }
        else {
            // 验证未通过，token无效或者已过期
            ctx.response.body = JSON.stringify({
                code: 403,
                message: "Please do not forgery information"
            })
        }
    }
    // 获取不到token，你应该先进行登录
    else {
        ctx.response.body = JSON.stringify({
            code: 401,
            message: "please log in first"
        })
    }
})

router.post("/api/login", async (ctx: Koa.Context, next: Koa.Next) => {
    await next()
    const name: string = ctx.request.body.name;
    const pwd: string = ctx.request.body.pwd;
    // 如果用户存在于数据库中，就签发token，并且设置在响应头中返回
    for (const row of userDataBase) {
        if (row.username === name && row.password === pwd) {
            const token = JWT.issueToken(row.id, row.username, 20);
            // 设置响应头JWT
            ctx.response.set("JWT", token);
            ctx.response.body = JSON.stringify({
                code: 200,
                message: "login successful"
            });
            return
        }
    }
    // 用户不存在
    ctx.response.body = JSON.stringify({
        code: 406,
        message: "Login error, username or password is incorrect"
    })
})

server.listen(3000, "localhost", 128, (): void => {
    console.log("server started at http://localhost:3000");
})

代码测试

下面我们使用postMan来测试一下这个功能过程。

首先是用户第一次到我们的网站尝试访问主页，此时会提示它应该先进行登录：

然后我们进行登录，下面是登录错误的情况，数据库没有这个用户：

下面是登录成功后的情况，它会返回给你一个JWT的响应字段：

我们需要复制这个JWT响应字段的value值，并且将它添加到访问index时的请求头里，注意请求头的字段也必须是JWT，因为我们的后端做了限制，那么接下来的20s内你对index的访问都将是正常的：

如果token过期或者被伪造，它将提示你不要伪造token，其实这里有心的朋友可以处理的更细节一点：

其他插件推荐

好了，关于Koa框架的基本使用目前就到此结束了。

下面推荐一些Koa框架中可能会被使用到的插件：

• koa-compress：用于压缩内容，以便更快的完成HTTP响应
• koa-logger：提供日志输出
• koa-static：提供静态文件服务
• koa-view：提供视图模板渲染，适用于前后端混合开发
• koa-jwt：也是一款提供JWT认证的插件，不同于jsonwebtoken，它的局限性比较清

作者：云崖先生