原文首发于我的博客，欢迎点击查看获得更好的阅读体验~

前言

一直都想接触下服务端的内容，以前看过python基础，但是因为在工作中基本上使用不到，所以基础看了几遍没有实际项目操作就忘记了，忘~记~了~

朝三暮四后最终选择了基于Nodejs的中间件Koa2完成了一个简单的RESTful风格的API项目。

项目中主要完成了以下API接口：

登录
用户的增删改查
图片上传、视频上传以及获取缩略图
图片、视频列表查询
节目新建(三表关联)
节目查询(三表关联)

项目根据molunerfinn的全栈开发实战：用Vue2+Koa1开发完整的前后端项目（更新Koa2）教程搭建，在此感谢作者分享。

项目结构

.
├── package.json 			// npm的依赖、项目信息文件
├── README.md 				// 说明文件
├── upload  				// 上传文件存储位置
├── index.js  				// Koa入口文件
├── server 					// vue-cli 生成，用于webpack监听、构建
│   ├── config  			// 配置文件夹
│   ├── controllers 		// controller-控制器
│   ├── models 				// model-模型
│   ├── routes 				// route-路由
│   ├── schema 				// schema-数据库表结构
└── └── utils 				// 实用工具

项目依赖包

以下依赖的版本都是本文所写的时候的版本：

@koa/corsv2.2.3 (跨域)
koa v2.7.0
koa-body v4.1.0 (解析post以及文件上传)
koa-json v2.0.2 (Koa中间件)
koa-jwt v3.6.0 (Koa token的中间件)
koa-logger v3.2.1 (Koa日志中间件)
koa-router v7.4.0 (Koa路由中间件)
mysql2 v1.6.5 (nodejs的mysql驱动)
sequelize v5.12.1 (操作数据库的ORM)

为什么要使用mysql2呢？因为使用mysql时启动项目sequelize会报Error: Please install mysql2 package manually，提示安装mysql2。

项目搭建

初始化项目

首先我们得新建一个项目文件夹koa-demo，然后用命令行进入该文件夹，执行npm init创建项目描述文件package.json

E:\Project\WebStorm\Node\koa-demo> npm init

命令行里会以交互的形式让你填一些项目的介绍信息，依次介绍如下：（不知道怎么填的直接回车、回车...）

name 项目名称
version 项目的版本号
description 项目的描述信息
entry point 项目的入口文件
test command 项目启动时脚本命令
git repository 如果你有 Git 地址，可以将这个项目放到你的 Git 仓库里
keywords 关键词
author 作者叫啥
license 项目要发行的时候需要的证书，平时玩玩忽略它

然后就可以打开项目文件夹，可以看到自动生成的package.json文件

入口文件

接下来我们先加入入口文件index.js，写入基本内容：

// index.js
import Koa from 'koa'
import koaRouter from 'koa-router'
import json from 'koa-json'
import logger from 'koa-logger'
import koaBody from 'koa-body'

const app = new Koa()
const router = koaRouter()

app.use(koaBody())
app.use(json())
app.use(logger())

app.use(async (ctx,next) => {
    await next()
})

app.on('error',(err,ctx) => {
    console.log('server error', err)
})

app.listen(3000,()=>{
  console.log('服务启动成功,端口：3000,地址：http://localhost:3000')
})

export default app

然后在控制台输入node index.js，发现报错，因为我们使用了es6的import/export

Babel引入

为了支持import/export我们需要引入babel转码器

npm install @babel/core @babel/node @babel/preset-env @babel/register --save-dev

然后在根目录添加.babelrc文件，写入

{
  "presets": [
    ["@babel/preset-env", {
      "targets": {
        "node": "current"
      }
    }]
  ],
  "plugins": []
}

然后在package.json中的scripts写入

"scripts": {
    "server": "npx babel-node index.js" //使用 npx 省去了输入 babel-node 完整路径的麻烦。
    // or "server": "node_modules/.bin/babel-node index.js"
  }

然后运行npm run server就可以了，能看到输出服务启动成功,端口：3000,地址：http://localhost:3000，则说明我们的Koa已经启动成功了，并在3000端口监听。

热启动

用过vue-cli的都知道前端代码修改过后，会进行热启动，就免去了手动重启项目的麻烦，那么koa2中如何进行热启动呢？nodemon可以帮助我们~

npm install nodemon

然后在package.json中的scripts加入

"scripts": {
    "server": "npx babel-node index.js",
    "start": "nodemon index.js --exec babel-node"
  }

最后运行npm run start就可以了

断点调试

在IDE中断点调试需要配置一下

首先在打开菜单栏的Run->Run Configurations
然后点击绿色+号，选择Node.js
在右侧的Configuration下面填入对应的参数
- Node interpreter：选择node的执行程序
- Node parameters：填写参数，参数如下
  
  E:\Project\WebStorm\Node\koa-demo\node_modules\nodemon\bin\nodemon --exec E:\Project\WebStorm\Node\koa-demo\node_modules\.bin\babel-node
  
  可以理解为将package.json中的scripts下的start命令加入了完整路径
- Working directory：填写项目目录
- JavaScript file：入口文件

环境搭建

项目流程图

为了方便理解项目结构，我做一张图，我们就按照这个顺序进行环境搭建。

创建数据库

去MySql官网下载一个对应系统的安装程序，安装过程还是比较简单的，这里就不详细描述了

对于初次接触MySql的我，使用命令操作实在有此难为我了，还好之前装了个可视化的工具Navicat(破解版)，当然也有一些免费版的，例如：Windows上HediSQL，macOS上Sequel Pro。

好了，现在我们先创建一个连接koa
- 连接名：koa
- 主机名或IP地址：localhost
- 端口：3306
- 用户名： root
- 密码：123456
然后新建一个数据库demo
- 数据库名：demo
- 字符集：``utf8 -- UTF-8 Unicode`
- 排序规则： utf8_general_ci
最后我们创建两个表user与resource

user表：

字段	类型	长度	主键	说明
id	int(自增)	255	1	用户ID
nickname	varchar	50		昵称
username	varchar	50		用户名
password	varchar	128		密码
creationTime	datetime	0		创建时间
updateTime	datetime	0		更新时间

resource表：

字段	类型	长度	主键	说明
id	int(自增)	125	1	资源ID
name	varchar	255		资源名称
size	double	0		资源大小
measure	varchar	255		分辨率
thumbnail	varchar	255		资源地址
operator	varchar	255		操作者
time	datetime	0		创建时间

生成数据结构

我们需要把数据库的表结构用sequelize-auto导出来。

更多关于sequelize-auto的使用可以参考官方介绍或者这篇文章

由此，我们首先全局安装sequelize-auto

npm install -g sequelize-auto

进入server的目录，执行如下语句

sequelize-auto -o "./schema" -d demo -h localhost -u root -p 3306 -x 123456 -e mysql

-o 参数后面的是输出的文件夹目录
-d 参数后面的是数据库名
-h 参数后面是数据库地址
-u 参数后面是数据库用户名
-p 参数后面是端口号
-x 参数后面是数据库密码，这个要根据自己的数据库密码来！
-e 参数后面指定数据库为mysql

然后就会在schema文件夹下自动生成两个文件：

// user.js
/* jshint indent: 2 */
module.exports = function(sequelize, DataTypes) {
return sequelize.define('user', {
  id: {
    type: DataTypes.INTEGER(255),
    allowNull: false,
    primaryKey: true,
    autoIncrement: true
  },
  nickname: {
    type: DataTypes.STRING(50),
    allowNull: true
  },
  username: {
    type: DataTypes.STRING(50),
    allowNull: true
  },
  password: {
    type: DataTypes.STRING(128),
    allowNull: true
  },
  creationTime: {
    type: DataTypes.DATE,
    allowNull: true
  },
  updateTime: {
    type: DataTypes.DATE,
    allowNull: true
  }
}, {
  tableName: 'user'
});
};

// resource.js
/* jshint indent: 2 */

module.exports = function(sequelize, DataTypes) {
  return sequelize.define('resource', {
    id: {
      type: DataTypes.INTEGER(125),
      allowNull: false,
      primaryKey: true,
      autoIncrement: true
    },
    name: {
      type: DataTypes.STRING(255),
      allowNull: true
    },
    size: {
      type: "DOUBLE",
      allowNull: true
    },
    measure: {
      type: DataTypes.STRING(255),
      allowNull: true
    },
    thumbnailProxy: {
      type: DataTypes.STRING(255),
      allowNull: true
    },
    operator: {
      type: DataTypes.STRING(255),
      allowNull: true
    },
    time: {
      type: DataTypes.DATE,
      allowNull: true
    }
  }, {
    tableName: 'resource'
  });
};

连接数据库

跟数据库打交道的时候我们都需要一个好的操作数据库的工具，能够让我们用比较简单的方法来对数据库进行增删改查。

我选用的是Sequelize，它支持多种关系型数据库（Sqlite、MySQL、Postgres等），它的操作基本都能返回一个Promise对象，这样在Koa里面我们能够很方便地进行”同步”操作。

更多关于Sequelize的用法，可以参考官方文档，以及这几篇文章——Sequelize中文API文档、Sequelize和MySQL对照、Sequelize快速入门

安装Sequelize依赖

npm install --save sequelize

然后在server目录下的config目录下我们新建一个db.js，用于初始化Sequelize和数据库的连接。

// config/db.js
import Sequelize from 'sequelize' // 引入sequelize

// 使用url连接的形式进行连接，注意将root: 后面的XXXX改成自己数据库的密码
const demo = new Sequelize('mysql://root:123456@127.0.0.1/demo',{
    define:{
        // 取消Sequelzie自动给数据表加入时间戳（createdAt以及updatedAt）
        timestamps: false
    },
    timezone: '+08:00' // 时差区，国内需要加入不然存储的时间会有时差
})

export default demo // 将demo暴露出接口方便Model调用

数据库操作

接着我们去models文件夹里将数据库和表结构文件连接起来。在这个文件夹下新建一个user.js的文件。

所谓增、删、改、查，那么我们就先来写一个新增用户的操作。

// models/user.js
import demoDB from '../config/db'

// 引入user的表结构
const userModel = '../schema/user.js'

// 用sequelize的import方法引入表结构，实例化了User。
const User = demoDB.import(userModel)

// async 异步操作
const addUser = async (userInfo) => {
 await User.create(userInfo)
}

module.exports = {
  addUser
}

业务逻辑操作

现在我们就需要写一写接收参数后的一些操作以及返回信息。

// controllers/user.js
import user from '../models/login'

const postUserInfo = async ctx => {
  const data = ctx.request.body
  const userAuth = await login.getUserByName(data.username)

  if(userAuth === null){
    let userInfo = {
      username: data.username,
      password: data.password,
      nickname: data.nickname,
      creationTime: dataTime(),
      updateTime: dataTime()
    }
    user.addUser(userInfo)
    ctx.body = {
      code: '0000',
      info: '新建成功!'
    }
  }else {
    ctx.body = {
      code: '9999',
      info: '用户已存在!'
    }
  }
}

export default {
  postUserInfo
}

写完这个还不能直接请求，因为我们还没有定义路由，请求经过Koa找不到这个路径是没有反应的。

创建路由

在routes文件夹下写一个api.js的文件。

// routes/api.js
import user from '../controllers/user'
import koaRouter from 'koa-router'

const router = koaRouter()

router.post('/user',user.postUserInfo)

export default router

至此我们已经接近完成我们的第一个API了，还缺最后一步，将这个路由规则“挂载”到Koa上去。

挂载路由

为了节约篇幅，下面省略了一些代码，只写了上下文作为位置标记

// index.js
// ...
import logger from 'koa-logger'
import koaRouter from 'koa-router'
const router = koaRouter()
import api from './server/routes/api.js'
// ...
app.on('error',(err,ctx) => {
    console.log('server error', err)
})

// 挂载到koa-router上，同时会让所有的auth的请求路径前面加上'/auth'的请求路径
router.use('/api', api.routes()) 
// 将路由规则挂载到Koa上。
app.use(router.routes())

app.listen(3000,()=>{
  console.log('服务启动成功,端口：3000,地址：http://localhost:3000')
})
// ...

打开你的控制台，输入node app.js，一切运行正常没有报错的话，大功告成，我们的第一个API已经构建完成！

API 测试

接口在跟前端对接之前，我们应该先进行一遍测试，防止出现问题。

在测试接口的工具上我想postman的大名应该众所周知了，官网下载安装好后便可使用。

其它接口的完善

刚才实现的不过是一个简单的用户新增接口，但是我们要实现一个完整的系统demo，还需要做一些工作。

剩下的API添加，基本上只需要在model和controllers写好方法，定好接口即可~

下面主要列举一下上传接口以及分页查询接口的一些知识点。

图片上传

在项目根目录下我们创建的有一个upload文件夹，上传成功后的图片就存储到这里，那么这里的图片怎么通过链接访问呢？这就需要我们搭建一个简易的静态资源服务器了。

静态资源

这里提供两种方法：

koa-static中间件
```
npm install koa-static
```
```
// index.js
//...
import statics from 'koa-static'
import path from 'path'

app.use(logger())

// 静态服务
app.use(statics(path.join(__dirname, './upload/')))
```
我们在upload目录下新建一个image文件夹，用来放图片文件，然后挂载好后启动服务就可以使用http://localhost:3000/image/test.jpg查看图片了。

**注意：**将upload目录配置为静态资源，那么访问的时候不需要输入upload，而是直接访问下级目录
Nginx搭建静态资源

这里使用Nginx进行搭建，在官网下载稳定版本，解压后打开conf文件夹下的nginx.conf进行修改配置
```
server {
        listen       3001;
        server_name  localhost;

        location /upload/ {
            root E:/Project/WebStorm/Node/koa-demo/;
            autoindex on;
        }
}
```
然后运行nginx.exe即可，然后我们在upload中添加一张图片，打开浏览器输入http://localhost:3001/upload/test.jpg便可看见图片

接口编写

在models下创建一个resource.js

// models/resource.js
import demoDB from '../config/db'
const resModel = '../schema/resource'

const Res = demoDB.import(resModel)

const postResImage = async data => {
  await Res.create(data)
}

export default {
  postResImage
}

主要是用来存储图片的一些数据到数据库

下面我们在controllers下创建一个resource.js

多文件需要遍历ctx.request.files，与文件一起传过来的参数在ctx.request.body中获取

// controllers/resource.js
import fs from 'fs'
import path from 'path'
import res from '../models/resource'
import formatTime from '../utils/formatTime'
import _res from '../utils/response'
import probe from 'probe-image-size'

const imageUrl = 'http://localhost:3000/image/'
const imagePath = path.join(__dirname,'../../upload/image')

const videoUrl = 'http://localhost:3000/video/'
const videoPath = path.join(__dirname,'../../upload/video')

const uploadImage = async ctx => {
    const file = ctx.request.files.file;

    const reader = fs.createReadStream(file.path);	// 创建可读流

    // 获取图片流的尺寸,注意，这里不能直接使用reader,不然会导致图片损坏。
    let measure = await probe(fs.createReadStream(file.path))

    const upStream = fs.createWriteStream(`${imagePath}\\${file.name}`);		// 创建可写流

    const data = {
      name : file.name,
      size : (file.size / 1024 / 1024).toFixed(2),
      measure : `${measure.width}*${measure.height}`,
      thumbnailProxy : `${imageUrl}${file.name}`,
      operator : 'admin',
      time : formatTime()
    }
    await res.postRes(data)
    if(!fs.existsSync(imagePath)){
      fs.mkdir(imagePath,err => {
        if(err) throw err
        reader.pipe(upStream)	// 可读流通过管道写入可写流
        return ctx.body = _res.success('上传成功')
      })
    }else {
      reader.pipe(upStream)	// 可读流通过管道写入可写流
      return ctx.body = _res.success('上传成功')
    }
}

export default {
  uploadImage
}

接收到图片后，再想获取图片的尺寸需要npm install probe-image-size，刚开始的时候一直在image-size上折腾，真是搞了好久，一直以为是自己哪里用法不对。后来才发现是对流形式的不支持，就换到了probe-image-size.

最后在routes添加接口

// router/api.js
import koaRouter from 'koa-router'
const router = koaRouter()
import resource from '../controllers/resource'

router.post('/upload/image',resource.uploadImage)

export default router

获取视频缩略图

上传视频后在我们一般都需要获取视频的缩略图，用来在前端列表中展示。

我们使用FFmpeg，一个领先的多媒体框架。

首先在官网下载对应平台的包。我这里使用的是windows，下载完成后将FFmpeg解压到D:\ffmpeg下。

并配置好系统的环境变量，添加D:\ffmpeg\bin到系统变量。详细点击查看

如果设置环境变量无效的话，还可以手动设置ffpemg的位置。

FFMpeg.setFfmpegPath('D:/ffmpeg/bin/ffmpeg.exe')

然后在项目目录安装node的中间件fluent-ffmpeg

npm install fluent-ffmpeg

然后就可以使用了。

import FFMpeg from 'fluent-ffmpeg'
FFMpeg.setFfmpegPath('D:/ffmpeg/bin/ffmpeg.exe')

const screenshots = function(fileName){
  FFMpeg('upload/video/'+ fileName)
    .screenshots({
      timemarks: ['0.5'],
      filename: 'thumbnail-%b.png',
      count: 1,
      folder: 'upload/video'
    })
}

export default {
  screenshots
}

其它操作请参考官方文档

分页查询

这里的查询主要是查询上传的图片的信息，返回给前端进行列表展示。

所以接口与上传接口同在resource.js文件中。

// models/resource.js
// ...省略
const getResImage = async (data) => {
  const { pageNo, pageSize } = data
   return await Res.findAndCountAll({
      limit: parseInt(pageSize),
      offset: (parseInt(pageNo)-1) * parseInt(pageSize),
    }).then(result=>{
      return result
    })
}

export default {
  getResImage,
  postResImage
}

// controllers/resource.js
// ...省略
const getResImageList = async ctx => {
  const data = ctx.query

  const list = await res.getResImage(data)
  const _resData = {
    pages:{
      total: list.count
    },
    sources: list.rows
  }
  ctx.body = _res.success('成功',_resData)
}


export default {
  uploadFile,
  getResImageList
}

// router/api.js
router.get('/resource/image',resource.getResImageList)

至此，KOA2中实现RESTFul 风格的API就算完成了。

一对多的多表分页查询时会在子查询里中分页，可使用subQuery:true。详见项目中节目查询的代码。

总结

最后将本文的项目代码放至了Github，如果这个项目对你有帮助，希望大家可以fork，给我提建议，如果再有时间，可以点个Star那就更好啦~

参考文献