# 上手 koa2 MySQL 实战开发|博客系列

> 本文系统讲解如何使用 Koa2 框架结合 MySQL 数据库进行实战开发，涵盖中间件编写、路由配置、TypeORM 数据库操作、JWT 鉴权与错误处理，适合 Node.js 后端开发者快速上手企业级项目。

- 原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/nodejs/-%E4%B8%8A%E6%89%8B%20koa2%20%20MySQL%20%E5%AE%9E%E6%88%98%E5%BC%80%E5%8F%91
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2025.10.25
- 可见范围：免费部分

---

## 学习目标

学完这篇教程，你将学会：

- 如果编写 Koa 中间件
- 通过 @koa/router 实现路由配置
- 通过 TypeORM 连接和读写 MySQL 数据库（其他数据库都类似）
- 了解 JWT 鉴权的原理，并动手实现
- 掌握 Koa 的错误处理机制

## 准备初始代码

我们已经为你准备好了项目的脚手架，运行以下命令克隆我们的初始代码：

```
git clone https://github.com/poetries/koa-quickstart.git
```

如果你访问 GitHub 不流畅，可以克隆我们的 Gitee 仓库：

```
git clone https://github.com/poetries/koa-quickstart.git
```

然后进入项目，安装依赖：

```
cd koa-quickstart && npm install
```

> 这里我使用了 package-lock.json 确保所有依赖版本一致，如果你用 yarn 安装依赖出现问题，建议删除 node_modules ，重新用 npm install 安装。

## 最简单的 Koa 服务器

> 创建 `src/server.ts` ，编写第一个 Koa 服务器，代码如下：

```js
// src/server.ts
import Koa from 'koa';
import cors from '@koa/cors';
import bodyParser from 'koa-bodyparser';

// 初始化 Koa 应用实例
const app = new Koa();

// 注册中间件
app.use(cors());
app.use(bodyParser());

// 响应用户请求
app.use((ctx) => {
  ctx.body = 'Hello Koa';
});

// 运行服务器
app.listen(3000);
```

**整个流程与一个基本的 Express 服务器几乎完全一致：**

- 初始化应用实例 app
- 注册相关的中间件（跨域 cors 和请求体解析中间件 bodyParser）
- 添加请求处理函数，响应用户请求
- 运行服务器
- 定睛一看，第 3 步中的请求处理函数（Request Handler）好像不太一样。在 Express 框架中，一个请求处理函数一般是这样的：

```js
function handler(req, res) {
  res.send('Hello Express');
}
```

> 两个参数分别对应请求对象（Request）和响应对象（Response），但是在 Koa 中，请求处理函数却只有一个参数 ctx （Context，上下文），然后只需向上下文对象写入相关的属性即可（例如这里就是写入到返回数据 body 中）

```js
function handler(ctx) {
  ctx.body = 'Hello Koa';
}
```

## 运行服务器

我们通过 npm start 就能开启服务器了。可以通过 Curl （或者 Postman 等）来测试我们的 API：

```
$ curl localhost:3000
Hello Koa
```

## 大名鼎鼎的“洋葱模型”

> 你也许从来没有用过 Koa 框架，但很有可能听说过“洋葱模型”，而 Koa 正是洋葱模型的代表框架之一。下面这个图你也许很熟悉了：

![](https://s.poetries.top/gitee/2020/08/57.png)

> 不过以个人观点，这个图实在是太像“洋葱”了，反而不太好理解。接下来我们将以更清晰直观的方式来感受 Koa 中间件的设计之美。首先我们来看一下 Express 的中间件是什么样的：

![](https://s.poetries.top/gitee/2020/08/58.png)

> 请求（Request）直接依次贯穿各个中间件，最后通过请求处理函数返回响应（Response），非常简单。然后我们来看看 Koa 的中间件是什么样的：

![](https://s.poetries.top/gitee/2020/08/59.png)

> 可以看到，Koa 中间件不像 Express 中间件那样在请求通过了之后就完成了自己的使命；相反，中间件的执行清晰地分为「两个阶段」。我们马上来看下 Koa 中间件具体是什么样的。

## Koa 中间件的定义

Koa 的中间件是这样一个函数：

```js
async function middleware(ctx, next) {
  // 第一阶段
  await next();
  // 第二阶段
}
```

> 第一个参数就是 `Koa Context`，也就是上图中贯穿所有中间件和请求处理函数的绿色箭头所传递的内容，里面「封装了请求体和响应体」（实际上还有其他属性，但这里暂时不讲），分别可以通过 ctx.request 和 ctx.response 来获取，以下是一些常用的属性：

```js
ctx.url    // 相当于 ctx.request.url
ctx.body   // 相当于 ctx.response.body
ctx.status // 相当于 ctx.response.status
```

- 中间件的第二个参数便是 next 函数，这个熟悉 Express 的同学一定知道它是干什么的：用来把控制权转交给下一个中间件。但是它跟 Express 的 next 函数本质的区别在于，「Koa 的 「「next」」 函数返回的是一个 Promise」，在这个 Promise 进入完成状态（Fulfilled）后，就会去执行中间件中第二阶段的代码。
- 那么我们不禁要问：这样把中间件的执行拆分为两个阶段，到底有什么好处吗？我们来通过一个非常经典的例子来感受一下：日志记录中间件（包括响应时间的计算）

## 实战：日志记录中间件

> 让我们来实现一个简单的日志记录中间件 `logger` ，用于记录每次请求的方法、URL、状态码和响应时间。创建 `src/logger.ts` ，代码如下：

```js
// src/logger.ts
import { Context } from 'koa';

export function logger() {
  return async (ctx: Context, next: () => Promise<void>) => {
    const start = Date.now();
    await next();
    const ms = Date.now() - start;
    console.log(`${ctx.method} ${ctx.url} ${ctx.status} - ${ms}ms`);
  };
}
```

- 严格意义上讲，这里的 logger 是一个「中间件工厂函数」（Factory），调用这个工厂函数后返回的结果才是真正的 Koa 中间件。之所以写成一个工厂函数，是因为我们可以通过给工厂函数传参的方式来更好地控制中间件的行为（当然这里的 logger 比较简单，就没有任何参数）。
- 在这个中间件的第一阶段，我们通过 Date.now() 先获取请求进入的时间，然后通过 await next() 让出执行权，等待下游中间件运行结束后，再在第二阶段通过计算 Date.now() 的差值来得出处理请求所用的时间。

> 这里通过两个 Date.now() 之间的差值来计算运行时间其实是不精确的，为了获取更准确的时间，建议使用 process.hrtime() 。

然后我们在 `src/server.ts` 中把刚才的 `logger` 中间件通过 `app.use` 注册进去，代码如下：

```js
// src/server.ts
// ...

import { logger } from './logger';

// 初始化 Koa 应用实例
const app = new Koa();

// 注册中间件
app.use(logger());
app.use(cors());
app.use(bodyParser());

// ...
```

这时候再访问我们的服务器（通过 `Curl` 或者其他请求工具），应该可以看到输出日志：

![](https://s.poetries.top/gitee/2020/08/60.png)

> 关于 Koa 框架本身的内容基本讲完了，但是对于一个比较完整的 Web 服务器来说，我们还需要更多的“武器装备”才能应对日常的业务逻辑。在接下来的部分，我们将通过社区的优秀组件来解决两个关键问题：路由和数据库，并演示如何结合 Koa 框架进行使用。

## 实现路由配置

> 由于 Koa 只是一个中间件框架，所以路由的实现需要独立的 npm 包。首先安装 `@koa/router` 及其 TypeScript 类型定义：

```js
$ npm install @koa/router
$ npm install @types/koa__router -D
```

> 有些教程使用 koa-router ，但由于 koa-router 目前处于几乎无人维护的状态，所以我们这里使用维护更积极的 Fork 版本 @koa/router

### 路由规划

在这篇教程中，我们将实现以下路由：

- GET /users ：查询所有的用户
- GET /users/:id ：查询单个用户
- PUT /users/:id ：更新单个用户
- DELETE /users/:id ：删除单个用户
- POST /users/login ：登录（获取 JWT Token）
- POST /users/register ：注册用户

### 实现 Controller

> 在 src 中创建 controllers 目录，用于存放控制器有关的代码。首先是 AuthController ，创建 src/controllers/auth.ts ，代码如下：

```js
// src/controllers/auth.ts
import { Context } from 'koa';

export default class AuthController {
  public static async login(ctx: Context) {
    ctx.body = 'Login controller';
  }

  public static async register(ctx: Context) {
    ctx.body = 'Register controller';
  }
}
```

> 然后创建 src/controllers/user.ts，代码如下

```js
// src/controllers/user.ts
import { Context } from 'koa';

export default class UserController {
  public static async listUsers(ctx: Context) {
    ctx.body = 'ListUsers controller';
  }

  public static async showUserDetail(ctx: Context) {
    ctx.body = `ShowUserDetail controller with ID = ${ctx.params.id}`;
  }

  public static async updateUser(ctx: Context) {
    ctx.body = `UpdateUser controller with ID = ${ctx.params.id}`;
  }

  public static async deleteUser(ctx: Context) {
    ctx.body = `DeleteUser controller with ID = ${ctx.params.id}`;
  }
}
```

注意到在后面三个 Controller 中，我们通过 ctx.params 获取到路由参数 id 。

### 实现路由

然后我们创建 src/routes.ts，用于把控制器挂载到对应的路由上面：

```js
// src/routes.ts
import Router from '@koa/router';

import AuthController from './controllers/auth';
import UserController from './controllers/user';

const router = new Router();

// auth 相关的路由
router.post('/auth/login', AuthController.login);
router.post('/auth/register', AuthController.register);

// users 相关的路由
router.get('/users', UserController.listUsers);
router.get('/users/:id', UserController.showUserDetail);
router.put('/users/:id', UserController.updateUser);
router.delete('/users/:id', UserController.deleteUser);

export default router;
```

> 可以看到 @koa/router 的使用方式基本上与 Express Router 保持一致。

### 注册路由

最后，我们需要将 router 注册为中间件。打开 src/server.ts，修改代码如下：

```js
// src/server.ts
// ...

import router from './routes';
import { logger } from './logger';

// 初始化 Koa 应用实例
const app = new Koa();

// 注册中间件
app.use(logger());
app.use(cors());
app.use(bodyParser());

// 响应用户请求
app.use(router.routes()).use(router.allowedMethods());

// 运行服务器
app.listen(3000);
```

> 可以看到，这里我们调用 router 对象的 routes 方法获取到对应的 Koa 中间件，还调用了 allowedMethods 方法注册了 HTTP 方法检测的中间件，这样当用户通过不正确的 HTTP 方法访问 API 时，就会自动返回 405 Method Not Allowed 状态码。

我们通过 Curl 来测试路由（也可以自行使用 Postman）：

```
$ curl localhost:3000/hello
Not Found
$ curl localhost:3000/auth/register
Method Not Allowed
$ curl -X POST localhost:3000/auth/register
Register controller
$ curl -X POST localhost:3000/auth/login
Login controller
$ curl localhost:3000/users
ListUsers controller
$ curl localhost:3000/users/123
ShowUserDetail controller with ID = 123
$ curl -X PUT localhost:3000/users/123
UpdateUser controller with ID = 123
$ curl -X DELETE localhost:3000/users/123
DeleteUser controller with ID = 123
```

同时可以看到服务器的输出日志如下：

![](https://s.poetries.top/gitee/2020/08/61.png)

路由已经接通，接下来就让我们来接入真实的数据吧！

## 接入 MySQL 数据库

> 从这一步开始，我们将正式接入数据库。Koa 本身是一个中间件框架，理论上可以接入任何类型的数据库，这里我们选择流行的关系型数据库 MySQL。并且，由于我们使用了 TypeScript 开发，因此这里使用为 TS 量身打造的 ORM[12] 库 TypeORM。

### 数据库的准备工作

首先，请安装和配置好 MySQL 数据库，可以通过两种方式：

- 官网下载安装包，这里是下载地址[13]
- 使用 MySQL Docker 镜像
- 在确保 MySQL 实例运行之后，我们打开终端，通过命令行连接数据库：

```
$ mysql -u root -p
```

> 输入预先设置好的根帐户密码之后，就进入了 MySQL 的交互式执行客户端，然后运行以下命令：

```
--- 创建数据库
CREATE DATABASE koa;

--- 创建用户并授予权限
CREATE USER 'user'@'localhost' IDENTIFIED BY 'pass';
GRANT ALL PRIVILEGES ON koa.* TO 'user'@'localhost';

--- 处理 MySQL 8.0 版本的认证协议问题
ALTER USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'pass';
flush privileges;
```

TypeORM 的配置和连接
首先安装相关的 npm 包，分别是 MySQL 驱动、TypeORM 及 reflect-metadata（反射 API 库，用于 TypeORM 推断模型的元数据）：

```
$ npm install mysql typeorm reflect-metadata
```

然后在项目根目录创建 ormconfig.json ，TypeORM 会读取这个数据库配置进行连接，代码如下：

```
// ormconfig.json
{
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "user",
  "password": "pass",
  "database": "koa",
  "synchronize": true,
  "entities": ["src/entity/*.ts"],
  "cli": {
    "entitiesDir": "src/entity"
  }
}
```

**这里有一些需要解释的字段：**

- database 就是我们刚刚创建的 koa 数据库
- synchronize 设为 true 能够让我们每次修改模型定义后都能自动同步到数据库*（如果你接触过其他的 ORM 库，其实就是自动数据迁移）*
- entities 字段定义了模型文件的路径，我们马上就来创建
接着修改 src/server.ts，在其中连接数据库，代码如下：

```js
// src/server.ts
import Koa from 'koa';
import cors from '@koa/cors';
import bodyParser from 'koa-bodyparser';
import { createConnection } from 'typeorm';
import 'reflect-metadata';

import router from './routes';
import { logger } from './logger';

createConnection()
  .then(() => {
    // 初始化 Koa 应用实例
    const app = new Koa();

    // 注册中间件
    app.use(logger());
    app.use(cors());
    app.use(bodyParser());

    // 响应用户请求
    app.use(router.routes()).use(router.allowedMethods());

    // 运行服务器
    app.listen(3000);
  })
  .catch((err: string) => console.log('TypeORM connection error:', err));
```

### 创建数据模型定义

> 在 src 目录下创建 entity 目录，用于存放数据模型定义文件。在其中创建 user.ts ，代表用户模型，代码如下：

```js
// src/entity/user.ts
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column({ select: false })
  password: string;

  @Column()
  email: string;
}
```

> 可以看到，用户模型有四个字段，其含义很容易理解。而 TypeORM 则是通过装饰器[14]这种优雅的方式来将我们的 User 类映射到数据库中的表。这里我们使用了三个装饰器：

- `Entity `用于装饰整个类，使其变成一个数据库模型
- `Column` 用于装饰类的某个属性，使其对应于数据库表中的一列，可提供一系列选项参数，例如我们给 password 设置了 select: false ，使得这个字段在查询时默认不被选中
- `PrimaryGeneratedColumn` 则是装饰主列，它的值将自动生成

### 在 Controller 中操作数据库

> 然后就可以在 Controller 中进行数据的增删改查操作了。首先我们打开 src/controllers/user.ts ，实现所有 Controller 的逻辑，代码如下：

```js
// src/controllers/user.ts
import { Context } from 'koa';
import { getManager } from 'typeorm';

import { User } from '../entity/user';

export default class UserController {
  public static async listUsers(ctx: Context) {
    const userRepository = getManager().getRepository(User);
    const users = await userRepository.find();

    ctx.status = 200;
    ctx.body = users;
  }

  public static async showUserDetail(ctx: Context) {
    const userRepository = getManager().getRepository(User);
    const user = await userRepository.findOne(+ctx.params.id);

    if (user) {
      ctx.status = 200;
      ctx.body = user;
    } else {
      ctx.status = 404;
    }
  }

  public static async updateUser(ctx: Context) {
    const userRepository = getManager().getRepository(User);
    await userRepository.update(+ctx.params.id, ctx.request.body);
    const updatedUser = await userRepository.findOne(+ctx.params.id);

    if (updatedUser) {
      ctx.status = 200;
      ctx.body = updatedUser;
    } else {
      ctx.status = 404;
    }
  }

  public static async deleteUser(ctx: Context) {
    const userRepository = getManager().getRepository(User);
    await userRepository.delete(+ctx.params.id);

    ctx.status = 204;
  }
}
```

> TypeORM 中操作数据模型主要是通过 Repository 实现的，在 Controller 中，可以通过 getManager().getRepository(Model) 来获取到，之后 Repository 的查询 API 就与其他的库很类似了。

- 获取到了请求体的数据，这是我们在第一步就配置好的 bodyParser 中间件在 Context 对象中添加的。
- 然后我们修改 AuthController ，实现具体的注册逻辑。由于密码不能明文保存在数据库中，需要使用非对称算法进行加密，这里我们使用曾经获得过密码加密大赛冠军的 Argon2[17] 算法。安装对应的 npm 包：

```
npm install argon2
```

> 然后实现具体的 register Controller，修改 src/controllers/auth.ts，代码如下：

```js
// src/controllers/auth.ts
import { Context } from 'koa';
import * as argon2 from 'argon2';
import { getManager } from 'typeorm';

import { User } from '../entity/user';

export default class AuthController {
  // ...

  public static async register(ctx: Context) {
    const userRepository = getManager().getRepository(User);

    const newUser = new User();
    newUser.name = ctx.request.body.name;
    newUser.email = ctx.request.body.email;
    newUser.password = await argon2.hash(ctx.request.body.password);

    // 保存到数据库
    const user = await userRepository.save(newUser);

    ctx.status = 201;
    ctx.body = user;
  }
}
```

确保服务器在运行之后，我们就可以开始测试一波了。首先是注册用户（这里我用 Postman 演示，直观一些）：

![](https://s.poetries.top/gitee/2020/08/62.png)

你可以继续注册几个用户，然后继续访问 /users 相关的路由，应该可以成功地获取、修改和删除相应的数据了！

## 实现 JWT 鉴权

> JSON Web Token（JWT）是一种流行的 RESTful API 鉴权方案。这里我们将手把手带你学会如何在 Koa 框架中使用 JWT 鉴权，但是不会过多讲解其原理（可参考这篇文章[18]进行学习）。

首先安装相关的 npm 包：

```
npm install koa-jwt jsonwebtoken
npm install @types/jsonwebtoken -D
```

> 创建 src/constants.ts ，用于存放 JWT Secret 常量，代码如下：

```js
// src/constants.ts
export const JWT_SECRET = 'secret';
```

在实际开发中，请替换成一个足够复杂的字符串，并且最好通过环境变量的方式注入

### 重新规划路由

> 有些路由我们希望只有已登录的用户才有权查看（受保护的路由），而另一些路由则是所有请求都可以访问（不受保护的路由）。在 Koa 的洋葱模型中，我们可以这样实现：

![](https://s.poetries.top/gitee/2020/08/63.png)

所有请求都可以直接访问未受保护的路由，但是受保护的路由就放在 JWT 中间件的后面（或者从洋葱模型的角度看是“里面”），这样对于没有携带 JWT Token 的请求就直接返回，而不会继续传递下去。

想法明确之后，打开 src/routes.ts 路由文件，修改代码如下：

```js
// src/routes.ts
import Router from '@koa/router';

import AuthController from './controllers/auth';
import UserController from './controllers/user';

const unprotectedRouter = new Router();

// auth 相关的路由
unprotectedRouter.post('/auth/login', AuthController.login);
unprotectedRouter.post('/auth/register', AuthController.register);

const protectedRouter = new Router();

// users 相关的路由
protectedRouter.get('/users', UserController.listUsers);
protectedRouter.get('/users/:id', UserController.showUserDetail);
protectedRouter.put('/users/:id', UserController.updateUser);
protectedRouter.delete('/users/:id', UserController.deleteUser);

export { protectedRouter, unprotectedRouter };
```

> 上面我们分别实现了 protectedRouter 和 unprotectedRouter ，分别对应于需要 JWT 中间件保护的路由和不需要保护的路由。

### 注册 JWT 中间件

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/nodejs/-%E4%B8%8A%E6%89%8B%20koa2%20%20MySQL%20%E5%AE%9E%E6%88%98%E5%BC%80%E5%8F%91
