第十一章：接口

接口

一、简介

1.1 接口是什么

接口是前后端通信的桥梁

简单理解：一个接口就是 服务中的一个路由规则，根据请求响应结果

接口的英文单词是 API（Application Program Interface），所以有时也称之为 API 接口

这里的接口指的是『数据接口』，与编程语言（Java、Go等）中的接口语法不同

1.2 接口的作用

实现 前后端通信

1.3 接口的开发与调用

大多数接口都是由 后端工程师开发的，开发语音不限

一般情况下接口都是由**前端工程师调用的，但有时后端工程师也会调用接口**，比如短信接口、支付接口等

1.4 接口的组成

一个接口一般由如下几个部分组成：

• 请求方法
• 接口地址（URL）
• 请求参数
• 响应结果

一个接口示例：身份证查询

体验一下：https://api.asilu.com/idcard/?id=152502199405148245

二、RESTful API

RESTful API 是一种特殊风格的接口，主要特点有如下几个：

• URL 中的路径表示 资源，路径中不能有 动词，例如 create、delete、update 等这些都不能有
• 操作资源要与 HTTP 请求方法 对应
• 操作结果要与 HTTP 响应状态码 对应

规则示例：

操作	请求类型	URL	返回
新增歌曲	POST	/song	返回新生成的歌曲信息
删除歌曲	DELETE	/song/10	返回一个空文档
修改歌曲	PUT	/song/10	返回更新后的歌曲信息
修改歌曲	PATCH	/song/10	返回更新后的歌曲信息
获取所有歌曲	GET	/song	返回歌曲列表数组
获取单个歌曲	GET	/song/10	返回单个歌曲信息

扩展阅读：RESTful API 设计指南

三、json-server

json-server 本身是一个 JS 编写的工具包，可以快速搭建 RESTful API 服务（json-server 官方地址）

操作步骤：

1. 全局安装 json-server

   npm i -g json-server
   

2. 创建 JSON 文件（db.json），编写基本结构

   {
       "song": [
           {
               "id": 1,
               "name": "干杯",
               "singer": "五月天"
           },
           {
               "id": 2,
               "name": "当",
               "singer": "动力火车"
           },
           {
               "id": 3,
               "name": "不能说的秘密",
               "singer": "周杰伦"
           }
       ]
   }
   

3. 以 JSON 文件所在文件夹作为工作目录，执行如下命令

   json-server --watch db.json
   

默认监听端口为 3000

四、接口测试工具

介绍几个接口测试工具：

• apipost (中文)
• apifox (中文)
• postman (英文)

五、接口的创建

以“记账本”为例，来创建账单接口：（以 RESTful API 规则来创建接口）

• 获取账单列表接口
• 创建账单接口
• 删除账单接口
• 获取单条账单接口
• 更新单个账单接口

1. 首先在 routes 文件夹下创建 web 文件夹，用来管理网页端的路由规则的文件；再创建 api 文件夹，用来管理接口的路由规则的文件：

   

2. 创建接口路由规则文件 account.js，与账单相关的接口会放到该文件下

3. 将 account.js 导入到 app.js 中并使用它：

   // 导入 account 接口路由文件
   const accountRouter = require('./routes/api/account')
   
   // 使用 account 接口路由文件
   app.use('/api', accountRouter)
   

4. 对 account.js 开始创建接口路由规则，其接口路由规则的格式如下：（按照 RESTful API 规则创建接口）

   使用 res.json() 来直接返回一个 json 格式的数据：（补充：render 和 json 不能同时使用）

   res.json({
       // 响应编号（一般用 20000 或 0000 来表示成功；用 1001~100n 来表示失败）
       code: 'xxxx',
       // 响应的信息（成功的信息|失败的信息）
       msg: 'xxxx',
       // 响应的数据（成功为获取到的 json 数据或空对象；失败为 null）
       data: xxxx
   })
   

   比如：设置获取所有账单的接口

   router.get('/account', function (req, res) {
     AccountModel.find().sort({ time: -1 }).then((data) => {
       // 成功的响应
       res.json({
         // 响应编号（一般用 20000 或 0000 来表示成功）
         code: '0000',
         // 响应的信息
         msg: '读取成功',
         // 响应的数据
         data: data
       })
     }).catch(() => {
       // 失败的响应
       res.json({
         code: '1001',
         msg: '读取失败',
         data: null
       })
     })
   })
   

5. 进行接口测试：（注意：进行接口测试时，需要将数据库启动以及 http 服务也要启动）

代码示例：

/**
 * 该文件是用来创建记账单接口：
 *      1.获取账单列表接口
 *      2.创建账单接口
 *      3.删除账单接口
 *      4.获取单条账单接口
 *      5.更新单个账单接口
 */
var express = require('express');
var router = express.Router();

// 导入 moment  --- 用来修改时间的格式
const moment = require('moment')
// 导入 AccountModel
const AccountModel = require('../../model/AccountModel')

// 1.获取账单列表接口
router.get('/account', function (req, res) {
  AccountModel.find().sort({ time: -1 }).then((data) => {
    // 成功的响应
    res.json({
      // 响应编号（一般用 20000 或 0000 来表示成功）
      code: '0000',
      // 响应的信息
      msg: '读取成功',
      // 响应的数据
      data: data
    })
  }).catch(() => {
    // 失败的响应
    res.json({
      code: '1001',
      msg: '读取失败',
      data: null
    })
  })
});

// 2.创建账单接口
router.post('/account', (req, res) => {
  AccountModel.create({
    ...req.body,
    // 修改 time 的值
    time: moment(req.body.time).toDate()
  }).then((data) => {
    // 成功提醒
    res.json({
      code: '0000',
      msg: '创建成功',
      data: data
    })
  }).catch(() => {
    res.json({
      code: '1002',
      msg: '创建失败',
      data: null
    })
  })
})

// 3.删除账单接口
router.delete('/account/:id', (req, res) => {
  // 获取要删除记录的id
  let id = req.params.id
  // 删除数据库中的数据
  AccountModel.deleteOne({ _id: id }).then(() => {
    // 删除提醒
    res.json({
      code: '0000',
      msg: '删除成功',
      data: {}
    })
  }).catch(() => {
    res.json({
      code: '1003',
      msg: '删除失败',
      data: null
    })
  })
})

// 4.获取单条账单接口
router.get('/account/:id', (req, res) => {
  // 获取单条账单的 id
  let id = req.params.id
  // 根据 id 去查询对应的账单
  AccountModel.findById(id).then((data) => {
    // 成功响应
    res.json({
      code: '0000',
      msg: '查询成功',
      data: data
    })
  }).catch(() => {
    // 失败响应
    res.json({
      code: '1004',
      msg: '查询失败',
      data: null
    })
  })
})

// 5.更新单个账单接口（patch：局部更新  put：整体替换掉）
router.patch('/account/:id', (req, res) => {
  // 获取单条账单的 id
  let { id } = req.params
  // 根据 id 去更新账单信息
  AccountModel.updateOne({ _id: id }, req.body).then(() => {
    // 再次查询数据库，来获取更新后的账单信息
    AccountModel.findById(id).then((data) => {
      res.json({
        code: '0000',
        msg: '更新成功',
        data: data
      })
    }).catch(() => {
      res.json({
        code: '1004',
        msg: '查询失败',
        data: null
      })
    })
  }).catch(() => {
    res.json({
      code: '1005',
      msg: '更新失败',
      data: null
    })
  })
})

module.exports = router;