node+koa2+mongodb搭建RESTful API风格后台

RESTful API风格

在开发之前先回顾一下，RESTful API 是什么? RESTful 是一种 API 设计风格，并不是一种强制规范和标准，它的特点在于请求和响应都简洁清晰，可读性强。不管 API 属于哪种风格，只要能够满足需要，就足够了。API 格式并不存在绝对的标准，只存在不同的设计风格。

API 风格

一般来说 API 设计包含两部分: 请求和响应。

请求：请求URL、请求方法、请求头部信息等。
响应：响应体和响应头部信息。

先来看一个请求 url 的组成：

https://www.baidu.com:443/api/articles?id=1
// 请求方法：GET
// 请求协议：protocal: https
// 请求端口：port: 443
// 请求域名：host: www.baidu.com
// 请求路径：pathname: /api/articles
// 查询字符串：search: id=1

根据 URL 组成部分：请求方法、请求路径和查询字符串，我们有几种常见的 API 风格。比如当删除 id=1 的作者编写的类别为 2 的所有文章时：

// 纯请求路径
GET https://www.baidu.com/api/articles/delete/authors/1/categories/2
// 一级使用路径，二级以后使用查询字符串
GET  https://www.baidu.com/api/articles/delete/author/1?category=2
// 纯查询字符串
GET  https://www.baidu.com/api/deleteArticles?author=1&category=2
// RESTful风格
DELETE  https://www.baidu.com/api/articles?author=1&category=2

前面三种都是 GET 请求，主要的区别在于多个查询条件时怎么传递查询字符串，有的通过使用解析路径，有的通过解析传参，有的两者混用。同时在描述 API 功能时，可以使用 articles/delete ，也可以使用 deleteArticles 。而第四种 RESTful API 最大的区别在于行为动词 DELETE 的位置，不在 url 里，而在请求方法中.

RESTful设计风格

REST（Representational State Transfer 表现层状态转移） 是一种设计风格，而不是标准。主要用于客户端和服务端的API交互，我认为它的约定大于它的定义，使得 api 在设计上有了一定的规范和原则，语义更加明确，清晰。

我们一起来看看 RESTFul API 有哪些特点：

基于“资源”，数据也好、服务也好，在 RESTFul 设计里一切都是资源，
资源用 URI（Universal Resource Identifier 通用资源标识） 来表示。
无状态性。
URL 中通常不出现动词，只有名词。
URL 语义清晰、明确。
使用 HTTP 的 GET 、 POST 、 DELETE 、 PUT 来表示对于资源的 增删改查 。
使用 JSON 不使用 XML。

举个栗子，也就是后面要实现的 api 接口：

GET      /api/blogs：查询文章
POST     /api/blogs：新建文章
GET       /api/blogs/ID：获取某篇指定文章
PUT       /api/blogs/ID：更新某篇指定文章
DELETE   /api/blogs/ID：删除某篇指定文章

关于更多RESTful API 的知识，小伙伴们可以戳：这里。

项目初始化

什么是Koa2

Koa官方网址。官方介绍：Koa 是一个新的 web 框架，由 Express 幕后的原班人马打造，致力于成为 web 应用和 API 开发领域中的一个更小、更富有表现力、更健壮的基石。

Koa2 的安装与使用对 Node.js 的版本也是有要求的，因为 node.js 7.6 版本开始完全支持 async/await，所以才能完全支持 Koa2。

Koa2 是 Koa 框架的最新版本，Koa3 还没有正式推出，Koa1.X 正走在被替换的路上。Koa2 与 Koa1 的最大不同，在于 Koa1 基于 co 管理 Promise/Generator 中间件，而 Koa2 紧跟最新的 ES 规范，支持到了 Async Function（Koa1 不支持），两者中间件模型表现一致，只是语法底层不同。

在 Express 里面，不同时期的代码组织方式虽然大为不同，但纵观 Express 多年的历程，他依然是相对大而全，API 较为丰富的框架，它的整个中间件模型是基于 callback 回调，而 callback 常年被人诟病。

简单来说 Koa 和 Express 的最大的区别在于 执行顺序 和 异步的写法 ，同时这也映射了 js 语法在处理异步任务上的发展历程。关于异步和两种框架区别，不在这里做过多探讨。来看看 Koa 中间件洋葱圈模型：

node+koa2+mongodb搭建RESTful API风格后台_第1张图片

1605446123292_4120046952-58e8693956b64.png

创建Koa2项目

创建文件 blog-api ,进入到该目录：

npm init

安装 Koa:

yarn add koa

安装 eslint, 这个选择安装，可以根据自己的需求来规范自己的代码,下面是我配置的 eslint:

yarn add eslint -D
yarn add eslint-config-airbnb-base -D
yarn add eslint-plugin-import -D

根目录下新建文件 .eslintrc.js 和 .editorconfig:

// .eslintrc.js

module.exports = {
  root: true,
  globals: {
    document: true,
  },
  extends: 'airbnb-base',
  rules: {
    'no-underscore-dangle': 0,
    'func-names': 0,
    'no-plusplus': 0,
  },
};

// .editorconfig

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

在根目录下新建文件 app.js：

const Koa = require('koa');

const app = new Koa();

app.use(async (ctx) => {
  ctx.body = 'Hello World';
});

app.listen(3000);

通过命令启动项目：

node app.js

在浏览器打开 http://localhost:3000/:

node+koa2+mongodb搭建RESTful API风格后台_第2张图片

[email protected]

项目开发

目录结构

规划项目结构，创建对应的文件夹：

blog-api
├── bin    // 项目启动文件
├── config   // 项目配置文件
├── controllers    // 控制器
├── dbhelper    // 数据库操作
├── error    // 错误处理
├── middleware    // 中间件
├── models    // 数据库模型
├── node_modules  
├── routers    // 路由
├── util    // 工具类
├── README.md    // 说明文档
├── package.json
├── app.js    // 入口文件
└── yarn.lock

自动重启

在编写调试项目，修改代码后，需要频繁的手动close掉，然后再重新启动，非常繁琐。安装自动重启工具 nodemon ：

yarn add nodemon -D

再安装 cross-env，主要为设置环境变量兼容用的：

yarn add cross-env

在 package.json 的 scripts 中增加脚本：

{
  "name": "blog-api",
  "version": "1.0.0",
  "description": "个人博客后台api",
  "main": "app.js",
  "scripts": {
    "dev": "cross-env NODE_ENV=development nodemon ./app.js",
    "rc": "cross-env NODE_ENV=production nodemon ./app.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Mingme <[email protected]>",
  "license": "ISC",
  "dependencies": {
    "cross-env": "^7.0.2",
    "koa": "^2.13.0",
    "koa-router": "^10.0.0"
  },
  "devDependencies": {
    "eslint": "^7.13.0",
    "eslint-config-airbnb-base": "^14.2.1",
    "eslint-plugin-import": "^2.22.1",
    "nodemon": "^2.0.6"
  }
}

这时候就能通过我们设置的脚本运行项目，修改文件保存后就会自动重启了。

以生产模式运行

yarn rc
// 或者
npm run rc

以开发模式运行

yarn dev
// 或者
npm run dev

koa 路由

路由(Routing)是由一个 URI(或者叫路径) 和一个特定的 HTTP 方法 (GET、POST 等) 组成的，涉及到应用如何响应客户端对某个网站节点的访问。

yarn add koa-router

接口统一以 /api 为前缀，比如：

http://localhost:3000/api/categories
http://localhost:3000/api/blogs

在 config 目录下创建 index.js:

// config/index.js
module.exports = {
  apiPrefix: '/api',
};

在 routers 目录下创建 index.js , category.js , blog.js :

// routers/category.js
const router = require('koa-router')();

router.get('/', async (ctx) => {
  // ctx  上下文 context ，包含了request 和response等信息
  ctx.body = '我是分类接口';
});

module.exports = router;

// routers/blog.js
const router = require('koa-router')();

router.get('/', async (ctx) => {
  ctx.body = '我是文章接口';
});

module.exports = router;

// routers/index.js
const router = require('koa-router')();
const { apiPrefix } = require('../config/index');

const blog = require('./blog');
const category = require('./category');

router.prefix(apiPrefix);

router.use('/blogs', blog.routes(), blog.allowedMethods());
router.use('/categories', category.routes(), category.allowedMethods());

module.exports = router;

在 app.js 中修改代码，引入路由：

// app.js
const Koa = require('koa');

const app = new Koa();

const routers = require('./routers/index');

// routers
app.use(routers.routes()).use(routers.allowedMethods());

app.listen(3000);

本地启动项目，看看效果：

node+koa2+mongodb搭建RESTful API风格后台_第3张图片

[email protected]

node+koa2+mongodb搭建RESTful API风格后台_第4张图片

[email protected]

根据不同的路由显示不同的内容，说明路由没问题了。

GET 请求

接下来看一下参数传递，假如是请求 id 为 1 的文章，我们 GET 请求一般这么写：

http://localhost:3000/api/blogs/1
http://localhost:3000/api/blogs?id=1

// routers/blog.js
const router = require('koa-router')();

router.get('/', async (ctx) => {
  /**
    在 koa2 中 GET 传值通过 request 接收，但是接收的方法有两种：query 和 querystring。
    query：返回的是格式化好的参数对象。
    querystring：返回的是请求字符串。
  */
  ctx.body = `我是文章接口id: ${ctx.query.id}`;
});

// 动态路由
router.get('/:id', async (ctx) => {
  ctx.body = `动态路由文章接口id: ${ctx.params.id}`;
});

module.exports = router;

如图：

node+koa2+mongodb搭建RESTful API风格后台_第5张图片

[email protected]

node+koa2+mongodb搭建RESTful API风格后台_第6张图片

[email protected]

POST/PUT/DEL

GET 把参数包含在 URL 中，POST 通过 request body 传递参数。
为了方便使用 koa-body 来处理 POST 请求和文件上传，或者使用 koa-bodyparser 和 koa-multer 也可以。

yarn add koa-body

为了统一数据格式，使数据JSON化，安装 koa-json:

yarn add koa-json

使用 koa-logger 方便调试：

yarn add koa-logger

在 app.js 里引入中间件：

const Koa = require('koa');

const path = require('path');

const app = new Koa();
const koaBody = require('koa-body');
const json = require('koa-json');
const logger = require('koa-logger');

const routers = require('./routers/index');

// middlewares
app.use(koaBody({
  multipart: true, // 支持文件上传
  formidable: {
    formidable: {
      uploadDir: path.join(__dirname, 'public/upload/'), // 设置文件上传目录
      keepExtensions: true, // 保持文件的后缀
      maxFieldsSize: 2 * 1024 * 1024, // 文件上传大小
      onFileBegin: (name, file) => { // 文件上传前的设置
        console.log(`name: ${name}`);
        console.log(file);
      },
    },
  },
}));
app.use(json());
app.use(logger());

// routers
app.use(routers.routes()).use(routers.allowedMethods());

app.listen(3000);

在 routers/blog.js 下添加路由：

// routers/blog.js

const router = require('koa-router')();

router.get('/', async (ctx) => {
  ctx.body = `我是文章接口id: ${ctx.query.id}`;
});

// 动态路由
router.get('/:id', async (ctx) => {
  ctx.body = `动态路由文章接口id: ${ctx.params.id}`;
});

router.post('/', async (ctx) => {
  ctx.body = ctx.request.body;
});

router.put('/:id', async (ctx) => {
  ctx.body = `PUT: ${ctx.params.id}`;
});

router.del('/:id', async (ctx) => {
  ctx.body = `DEL: ${ctx.params.id}`;
});

module.exports = router;

测试一下：

node+koa2+mongodb搭建RESTful API风格后台_第7张图片

[email protected]

node+koa2+mongodb搭建RESTful API风格后台_第8张图片

[email protected]

node+koa2+mongodb搭建RESTful API风格后台_第9张图片

[email protected]

错误处理

在请求过程中，还需要将返回结果进行一下包装，发生异常时，如果接口没有提示语,状态码的返回肯定是不友好的，下面定义几个常用的错误类型。
在 error 目录下创建 api_error_map.js 、 api_error_name.js 、 api_error.js:

// error/api_error_map.js

const ApiErrorNames = require('./api_error_name');

const ApiErrorMap = new Map();

ApiErrorMap.set(ApiErrorNames.NOT_FOUND, { code: ApiErrorNames.NOT_FOUND, message: '未找到该接口' });
ApiErrorMap.set(ApiErrorNames.UNKNOW_ERROR, { code: ApiErrorNames.UNKNOW_ERROR, message: '未知错误' });
ApiErrorMap.set(ApiErrorNames.LEGAL_ID, { code: ApiErrorNames.LEGAL_ID, message: 'id 不合法' });
ApiErrorMap.set(ApiErrorNames.UNEXIST_ID, { code: ApiErrorNames.UNEXIST_ID, message: 'id 不存在' });
ApiErrorMap.set(ApiErrorNames.LEGAL_FILE_TYPE, { code: ApiErrorNames.LEGAL_FILE_TYPE, message: '文件类型不允许' });
ApiErrorMap.set(ApiErrorNames.NO_AUTH, { code: ApiErrorNames.NO_AUTH, message: '没有操作权限' });

module.exports = ApiErrorMap;

// error/api_error_name.js

const ApiErrorNames = {
  NOT_FOUND: 'not_found',
  UNKNOW_ERROR: 'unknow_error',
  LEGAL_ID: 'legal_id',
  UNEXIST_ID: 'unexist_id',
  LEGAL_FILE_TYPE: 'legal_file_type',
  NO_AUTH: 'no_auth',
};

module.exports = ApiErrorNames;

// error/api_error.js

const ApiErrorMap = require('./api_error_map');

/**
 * 自定义Api异常
 */

class ApiError extends Error {
  constructor(errorName, errorMsg) {
    super();

    let errorInfo = {};
    if (errorMsg) {
      errorInfo = {
        code: errorName,
        message: errorMsg,
      };
    } else {
      errorInfo = ApiErrorMap.get(errorName);
    }

    this.name = errorName;
    this.code = errorInfo.code;
    this.message = errorInfo.message;
  }
}

module.exports = ApiError;

在 middleware 目录下创建 response_formatter.js 用来处理 api 返回数据的格式化：

// middleware/response_formatter.js

const ApiError = require('../error/api_error');
const ApiErrorNames = require('../error/api_error_name');

const responseFormatter = (apiPrefix) => async (ctx, next) => {
  if (ctx.request.path.startsWith(apiPrefix)) {
    try {
      // 先去执行路由
      await next();

      if (ctx.response.status === 404) {
        throw new ApiError(ApiErrorNames.NOT_FOUND);
      } else {
        ctx.body = {
          code: 'success',
          message: '成功!',
          result: ctx.body,
        };
      }
    } catch (error) {
      // 如果异常类型是API异常，将错误信息添加到响应体中返回。
      if (error instanceof ApiError) {
        ctx.body = {
          code: error.code,
          message: error.message,
        };
      } else {
        ctx.status = 400;
        ctx.response.body = {
          code: error.name,
          message: error.message,
        };
      }
    }
  } else {
    await next();
  }
};

module.exports = responseFormatter;

顺便安装 koa 的错误处理程序 hack ：

yarn add koa-onerror

在 app.js 中添加代码：

const Koa = require('koa');

const path = require('path');

const app = new Koa();
const onerror = require('koa-onerror');
const koaBody = require('koa-body');
const json = require('koa-json');
const logger = require('koa-logger');

const responseFormatter = require('./middleware/response_formatter');
const { apiPrefix } = require('./config/index');
const routers = require('./routers/index');

// koa的错误处理程序hack
onerror(app);

// middlewares
app.use(koaBody({
  multipart: true, // 支持文件上传
  formidable: {
    formidable: {
      uploadDir: path.join(__dirname, 'public/upload/'), // 设置文件上传目录
      keepExtensions: true, // 保持文件的后缀
      maxFieldsSize: 2 * 1024 * 1024, // 文件上传大小
      onFileBegin: (name, file) => { // 文件上传前的设置
        console.log(`name: ${name}`);
        console.log(file);
      },
    },
  },
}));
app.use(json());
app.use(logger());

// response formatter
app.use(responseFormatter(apiPrefix));

// routers
app.use(routers.routes()).use(routers.allowedMethods());

// 监听error
app.on('error', (err, ctx) => {
  // 在这里可以对错误信息进行一些处理，生成日志等。
  console.error('server error', err, ctx);
});

app.listen(3000);

在后续开发中，若遇到异常，将异常抛出即可。

连接数据库

mongoDB 数据库的安装教程：Linux 服务器(CentOS)安装配置mongodb+node。

mongoose ： nodeJS 提供连接 mongodb 的一个库。

mongoose-paginate ：mongoose 的分页插件。

mongoose-unique-validator ：可为 Mongoose schema 中的唯一字段添加预保存验证。

yarn add mongoose
yarn add mongoose-paginate
yarn add mongoose-unique-validator

在 config/index.js 中增加配置：

module.exports = {
  port: process.env.PORT || 3000,
  apiPrefix: '/api',
  database: 'mongodb://localhost:27017/test',
  databasePro: 'mongodb://root:[email protected]:27017/blog', // mongodb://用户名:密码@服务器公网IP:端口/库的名称
};

在 dbhelper 目录下创建 db.js:

const mongoose = require('mongoose');
const config = require('../config');

mongoose.Promise = global.Promise;

const IS_PROD = ['production', 'prod', 'pro'].includes(process.env.NODE_ENV);
const databaseUrl = IS_PROD ? config.databasePro : config.database;

/**
 *  连接数据库
 */

mongoose.connect(databaseUrl, {
  useUnifiedTopology: true,
  useNewUrlParser: true,
  useFindAndModify: false,
  useCreateIndex: true,
  config: {
    autoIndex: false,
  },
});

/**
 *  连接成功
 */

mongoose.connection.on('connected', () => {
  console.log(`Mongoose 连接成功: ${databaseUrl}`);
});

/**
 *  连接异常
 */

mongoose.connection.on('error', (err) => {
  console.log(`Mongoose 连接出错: ${err}`);
});

/**
 *  连接断开
 */

mongoose.connection.on('disconnected', () => {
  console.log('Mongoose 连接关闭！');
});

module.exports = mongoose;

在 app.js 中引入：

...
const routers = require('./routers/index');

require('./dbhelper/db');

// koa的错误处理程序hack
onerror(app);
...

启动项目就可以看到log提示连接成功：

[email protected]

这里说一下在 db.js 中有这么一行代码：

mongoose.Promise = global.Promise;

加上这个是因为：mongoose 的所有查询操作返回的结果都是 query ，mongoose 封装的一个对象，并非一个完整的 promise，而且与 ES6 标准的 promise 有所出入，因此在使用 mongoose 的时候，一般加上这句 mongoose.Promise = global.Promise。

开发 API

Mongoose 的一切始于 Schema 。在开发接口之前，那就先来构建模型，这里主要构建文章分类，和文章列表两种类型的接口，在字段上会比较简陋，主要用于举例使用，小伙伴们可以举一反三。
在 models 目录下创建 category.js 和 blog.js:

// models/category.js

const mongoose = require('mongoose');
const mongoosePaginate = require('mongoose-paginate');
const uniqueValidator = require('mongoose-unique-validator');

const schema = new mongoose.Schema({
  name: {
    type: String,
    unique: true,
    required: [true, '分类 name 必填'],
  },
  value: {
    type: String,
    unique: true,
    required: [true, '分类 value 必填'],
  },
  rank: {
    type: Number,
    default: 0,
  },
}, {
  timestamps: { createdAt: 'createdAt', updatedAt: 'updatedAt' },
});

// 自动增加版本号
/* Mongoose 仅在您使用时更新版本密钥save()。如果您使用update()，findOneAndUpdate()等等，Mongoose将不会 更新版本密钥。
作为解决方法，您可以使用以下中间件。参考 https://mongoosejs.com/docs/guide.html#versionKey */

schema.pre('findOneAndUpdate', function () {
  const update = this.getUpdate();
  if (update.__v != null) {
    delete update.__v;
  }
  const keys = ['$set', '$setOnInsert'];
  Object.keys(keys).forEach((key) => {
    if (update[key] != null && update[key].__v != null) {
      delete update[key].__v;
      if (Object.keys(update[key]).length === 0) {
        delete update[key];
      }
    }
  });
  update.$inc = update.$inc || {};
  update.$inc.__v = 1;
});

schema.plugin(mongoosePaginate);
schema.plugin(uniqueValidator);

module.exports = mongoose.model('Category', schema);

// models/blog.js

const mongoose = require('mongoose');
const uniqueValidator = require('mongoose-unique-validator');
const mongoosePaginate = require('mongoose-paginate');

const schema = new mongoose.Schema({
  title: {
    type: String,
    unique: true,
    required: [true, '必填字段'],
  }, // 标题
  content: {
    type: String,
    required: [true, '必填字段'],
  }, // 内容
  category: {
    type: mongoose.Schema.Types.ObjectId,
    required: [true, '必填字段'],
    ref: 'Category',
  }, // 分类_id,根据这个id我们就能从 category 表中查找到相关数据。
  status: {
    type: Boolean,
    default: true,
  }, // 状态
}, {
  timestamps: { createdAt: 'createdAt', updatedAt: 'updatedAt' },
  toJSON: { virtuals: true },
});

// 虚拟字段：根据_id查找对应表中的数据。
schema.virtual('categoryObj', {
  ref: 'Category',
  localField: 'category',
  foreignField: '_id',
  justOne: true,
});

// 自动增加版本号
/* Mongoose 仅在您使用时更新版本密钥save()。如果您使用update()，findOneAndUpdate()等等，Mongoose将不会 更新版本密钥。
作为解决方法，您可以使用以下中间件。参考 https://mongoosejs.com/docs/guide.html#versionKey */

schema.pre('findOneAndUpdate', function () {
  const update = this.getUpdate();
  if (update.__v != null) {
    delete update.__v;
  }
  const keys = ['$set', '$setOnInsert'];
  Object.keys(keys).forEach((key) => {
    if (update[key] != null && update[key].__v != null) {
      delete update[key].__v;
      if (Object.keys(update[key]).length === 0) {
        delete update[key];
      }
    }
  });
  update.$inc = update.$inc || {};
  update.$inc.__v = 1;
});

schema.plugin(mongoosePaginate);
schema.plugin(uniqueValidator);

module.exports = mongoose.model('Blog', schema);

在 dbhelper 目录下，定义一些对数据库增删改查的方法，创建 category.js 和 blog.js:

// dbhelper/category.js

const Model = require('../models/category');

// TODO: 此文件中最好返回 Promise。通过 .exec() 可以返回 Promise。
// 需要注意的是 分页插件本身返回的就是 Promise 因此 Model.paginate 不需要 exec()。
// Model.create 返回的也是 Promise

/**
 * 查找全部
 */
exports.findAll = () => Model.find().sort({ rank: 1 }).exec();

/**
 * 查找多个 筛选
 */
exports.findSome = (data) => {
  const {
    page = 1, limit = 10, sort = 'rank',
  } = data;
  const query = {};
  const options = {
    page: parseInt(page, 10),
    limit: parseInt(limit, 10),
    sort,
  };
  const result = Model.paginate(query, options);

  return result;
};

/**
 * 查找单个 详情
 */
exports.findById = (id) => Model.findById(id).exec();

/**
 * 增加
 */
exports.add = (data) => Model.create(data);

/**
 * 更新
 */
exports.update = (data) => {
  const { id, ...restData } = data;
  return Model.findOneAndUpdate({ _id: id }, {
    ...restData,
  },
  {
    new: true, // 返回修改后的数据
  }).exec();
};

/**
 * 删除
 */
exports.delete = (id) => Model.findByIdAndDelete(id).exec();

// dbhelper/blog.js

const Model = require('../models/blog');

// TODO: 此文件中最好返回 Promise。通过 .exec() 可以返回 Promise。
// 需要注意的是 分页插件本身返回的就是 Promise 因此 Model.paginate 不需要 exec()。
// Model.create 返回的也是 Promise

const populateObj = [
  {
    path: 'categoryObj',
    select: 'name value',
  },
];

/**
 * 查找全部
 */
exports.findAll = () => Model.find().populate(populateObj).exec();

/**
 * 查找多个 筛选
 */
exports.findSome = (data) => {
  const {
    keyword, title, category, status = true, page = 1, limit = 10, sort = '-createdAt',
  } = data;
  const query = {};
  const options = {
    page: parseInt(page, 10),
    limit: parseInt(limit, 10),
    sort,
    populate: populateObj,
  };

  if (status !== 'all') {
    query.status = status === true || status === 'true';
  }

  if (title) {
    query.title = { $regex: new RegExp(title, 'i') };
  }

  if (category) {
    query.category = category;
  }

  // 关键字模糊查询 标题 和 content
  if (keyword) {
    const reg = new RegExp(keyword, 'i');
    const fuzzyQueryArray = [{ content: { $regex: reg } }];
    if (!title) {
      fuzzyQueryArray.push({ title: { $regex: reg } });
    }
    query.$or = fuzzyQueryArray;
  }

  return Model.paginate(query, options);
};

/**
 * 查找单个 详情
 */
exports.findById = (id) => Model.findById(id).populate(populateObj).exec();

/**
 * 新增
 */
exports.add = (data) => Model.create(data);

/**
 * 更新
 */
exports.update = (data) => {
  const { id, ...restData } = data;
  return Model.findOneAndUpdate({ _id: id }, {
    ...restData,
  }, {
    new: true, // 返回修改后的数据
  }).exec();
};

/**
 * 删除
 */
exports.delete = (id) => Model.findByIdAndDelete(id).exec();

编写路由：

// routers/category.js

const router = require('koa-router')();
const controller = require('../controllers/category');

// 查
router.get('/', controller.find);

// 查 动态路由
router.get('/:id', controller.detail);

// 增
router.post('/', controller.add);

// 改
router.put('/:id', controller.update);

// 删
router.del('/:id', controller.delete);

module.exports = router;

// routers/blog.js

const router = require('koa-router')();
const controller = require('../controllers/blog');

// 查
router.get('/', controller.find);

// 查 动态路由
router.get('/:id', controller.detail);

// 增
router.post('/', controller.add);

// 改
router.put('/:id', controller.update);

// 删
router.del('/:id', controller.delete);

module.exports = router;

在路由文件里面我们只定义路由，把路由所对应的方法全部都放在 controllers 下：

// controllers/category.js
const dbHelper = require('../dbhelper/category');
const tool = require('../util/tool');

const ApiError = require('../error/api_error');
const ApiErrorNames = require('../error/api_error_name');

/**
 * 查
 */
exports.find = async (ctx) => {
  let result;
  const reqQuery = ctx.query;

  if (reqQuery && !tool.isEmptyObject(reqQuery)) {
    if (reqQuery.id) {
      result = dbHelper.findById(reqQuery.id);
    } else {
      result = dbHelper.findSome(reqQuery);
    }
  } else {
    result = dbHelper.findAll();
  }

  await result.then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 查 动态路由 id
 */
exports.detail = async (ctx) => {
  const { id } = ctx.params;
  if (!tool.validatorsFun.numberAndCharacter(id)) {
    throw new ApiError(ApiErrorNames.LEGAL_ID);
  }
  await dbHelper.findById(id).then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 添加
 */
exports.add = async (ctx) => {
  const dataObj = ctx.request.body;

  await dbHelper.add(dataObj).then((res) => {
    ctx.body = res;
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 更新
 */
exports.update = async (ctx) => {
  const ctxParams = ctx.params;
  // 合并 路由中的参数 以及 发送过来的参数
  // 路由参数 以及发送的参数可能都有 id 以 发送的 id 为准，如果没有，取路由中的 id
  const dataObj = { ...ctxParams, ...ctx.request.body };

  await dbHelper.update(dataObj).then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 删除
 */
exports.delete = async (ctx) => {
  const ctxParams = ctx.params;
  // 合并 路由中的参数 以及 发送过来的参数
  // 路由参数 以及发送的参数可能都有 id 以 发送的 id 为准，如果没有，取路由中的 id
  const dataObj = { ...ctxParams, ...ctx.request.body };
  if (!tool.validatorsFun.numberAndCharacter(dataObj.id)) {
    throw new ApiError(ApiErrorNames.LEGAL_ID);
  }

  await dbHelper.delete(dataObj.id).then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

// controllers/blog.js
const dbHelper = require('../dbhelper/blog');
const tool = require('../util/tool');

const ApiError = require('../error/api_error');
const ApiErrorNames = require('../error/api_error_name');

/**
 * 查
 */
exports.find = async (ctx) => {
  let result;
  const reqQuery = ctx.query;

  if (reqQuery && !tool.isEmptyObject(reqQuery)) {
    if (reqQuery.id) {
      result = dbHelper.findById(reqQuery.id);
    } else {
      result = dbHelper.findSome(reqQuery);
    }
  } else {
    result = dbHelper.findAll();
  }

  await result.then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 查 详情
 */
exports.detail = async (ctx) => {
  const { id } = ctx.params;
  if (!tool.validatorsFun.numberAndCharacter(id)) {
    throw new ApiError(ApiErrorNames.LEGAL_ID);
  }

  await dbHelper.findById(id).then(async (res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 增
 */
exports.add = async (ctx) => {
  const dataObj = ctx.request.body;

  await dbHelper.add(dataObj).then((res) => {
    ctx.body = res;
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 改
 */
exports.update = async (ctx) => {
  const ctxParams = ctx.params;
  // 合并 路由中的参数 以及 发送过来的参数
  // 路由参数 以及发送的参数可能都有 id 以 发送的 id 为准，如果没有，取路由中的 id
  const dataObj = { ...ctxParams, ...ctx.request.body };

  await dbHelper.update(dataObj).then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * 删
 */
exports.delete = async (ctx) => {
  const ctxParams = ctx.params;
  // 合并 路由中的参数 以及 发送过来的参数
  // 路由参数 以及发送的参数可能都有 id 以 发送的 id 为准，如果没有，取路由中的 id
  const dataObj = { ...ctxParams, ...ctx.request.body };
  if (!tool.validatorsFun.numberAndCharacter(dataObj.id)) {
    throw new ApiError(ApiErrorNames.LEGAL_ID);
  }

  await dbHelper.delete(dataObj.id).then((res) => {
    if (res) {
      ctx.body = res;
    } else {
      throw new ApiError(ApiErrorNames.UNEXIST_ID);
    }
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

上面使用了两个方法，isEmptyObject 判断是否是空对象，numberAndCharacter 对 id 格式做一个简单的检查。

// util/tool.js
/**
 * @desc 检查是否为空对象
 */
exports.isEmptyObject = (obj) => Object.keys(obj).length === 0;

/**
 * @desc 常规正则校验表达式
 */
exports.validatorsExp = {
  number: /^[0-9]*$/,
  numberAndCharacter: /^[0-9a-zA-Z]+$/,
  nameLength: (n) => new RegExp(`^[\\u4E00-\\u9FA5]{${n},}$`),
  idCard: /^(\d{6})(\d{4})(\d{2})(\d{2})(\d{3})([0-9]|X)$/,
  backCard: /^([1-9]{1})(\d{15}|\d{18})$/,
  phone: /^1[3456789]\d{9}$/,
  email: /^\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$/,
};

/**
 * @desc 常规正则校验方法
 */
exports.validatorsFun = {
  number: (val) => exports.validatorsExp.number.test(val),
  numberAndCharacter: (val) => exports.validatorsExp.numberAndCharacter.test(val),
  idCard: (val) => exports.validatorsExp.idCard.test(val),
  backCard: (val) => exports.validatorsExp.backCard.test(val),
};

到此，分类和文章相关的接口基本完成了，测试一下：

node+koa2+mongodb搭建RESTful API风格后台_第10张图片

[email protected]

node+koa2+mongodb搭建RESTful API风格后台_第11张图片

[email protected]

node+koa2+mongodb搭建RESTful API风格后台_第12张图片

[email protected]

鉴权

这里我使用的是 token 来进行身份验证的: jsonwebtoken
根据路由对一些非 GET 请求的接口做 token 验证。

// app.js
...
// 检查请求时 token 是否过期
app.use(tokenHelper.checkToken([
  '/api/blogs',
  '/api/categories',
  ...
], [
  '/api/users/signup',
  '/api/users/signin',
  '/api/users/forgetPwd',
]));
...

// util/token-helper.js

const jwt = require('jsonwebtoken');
const config = require('../config/index');
const tool = require('./tool');

// 生成token
exports.createToken = (user) => {
  const token = jwt.sign({ userId: user._id, userName: user.userName }, config.tokenSecret, { expiresIn: '2h' });
  return token;
};

// 解密token返回userId,userName用来判断用户身份。
exports.decodeToken = (ctx) => {
  const token = tool.getTokenFromCtx(ctx);
  const userObj = jwt.decode(token, config.tokenSecret);
  return userObj;
};

// 检查token
exports.checkToken = (shouldCheckPathArray, unlessCheckPathArray) => async (ctx, next) => {
  const currentUrl = ctx.request.url;
  const { method } = ctx.request;

  const unlessCheck = unlessCheckPathArray.some((url) => currentUrl.indexOf(url) > -1);

  const shouldCheck = shouldCheckPathArray.some((url) => currentUrl.indexOf(url) > -1) && method !== 'GET';

  if (shouldCheck && !unlessCheck) {
    const token = tool.getTokenFromCtx(ctx);
    if (token) {
      try {
        jwt.verify(token, config.tokenSecret);
        await next();
      } catch (error) {
        ctx.status = 401;
        ctx.body = 'token 过期';
      }
    } else {
      ctx.status = 401;
      ctx.body = '无 token，请登录';
    }
  } else {
    await next();
  }
};

在注册个登录的时候生成设置 token ：

// controllers/users.js

/**
 * @desc 注册
 */
 ...
exports.signUp = async (ctx) => {
  const dataObj = ctx.request.body;

  await dbHelper.signUp(dataObj).then((res) => {
    const token = tokenHelper.createToken(res);
    const { password, ...restData } = res._doc;
    ctx.res.setHeader('Authorization', token);
    ctx.body = {
      token,
      ...restData,
    };
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};

/**
 * @desc 登录
 */
exports.signIn = async (ctx) => {
  const dataObj = ctx.request.body;

  await dbHelper.signIn(dataObj).then((res) => {
    const token = tokenHelper.createToken(res);
    const { password, ...restData } = res;
    ctx.res.setHeader('Authorization', token);
    ctx.body = {
      token,
      ...restData,
    };
  }).catch((err) => {
    throw new ApiError(err.name, err.message);
  });
};
...

项目部署

部署就比较简单了，将项目文件全部上传到服务器上，然后全局安装 pm2，用 pm2 启动即可。

在 bin 目录下创建 pm2.config.json :

{
  "apps": [
    {
      "name": "blog-api",
      "script": "./app.js",
      "instances": 0,
      "watch": false,
      "exec_mode": "cluster_mode"
    }
  ]
}

在 package.json 中添加启动脚本：

{
  ...
  "scripts": {
    "dev": "cross-env NODE_ENV=development nodemon ./app.js",
    "rc": "cross-env NODE_ENV=production nodemon ./app.js",
    "pm2": "cross-env NODE_ENV=production NODE_LOG_DIR=/tmp ENABLE_NODE_LOG=YES pm2 start ./bin/pm2.config.json",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
 ...
}

然后,cd 到项目根目录：

npm run pm2

关于个人博客前台开发可以戳这里：Nuxt 开发搭建博客

node+koa2+mongodb搭建RESTful API风格后台

RESTful API风格

API 风格

RESTful设计风格

项目初始化

什么是Koa2

创建Koa2项目

项目开发

目录结构

自动重启

koa 路由

GET 请求

POST/PUT/DEL

错误处理

连接数据库

开发 API

鉴权

项目部署

你可能感兴趣的:(node+koa2+mongodb搭建RESTful API风格后台)