• NodeJs04


    REST API的设计

    前言

    客户端通过请求URL,传递参数,去获取指定的数据,这就是API(ApplicationProgramInterface)。

    API是前端和客户端操作后端数据的一种方式,一种接口。当一个Web应用以API的方式对外提供功能和接口时,整个应用的架构模式是这样的:

    但是,URL怎么约定,参数以什么编码方式传,响应数据的格式是什么样的,以及响应码怎么约定,API版本升级怎么设计,这些问题是设计这些API的后端人员不得不考虑的问题。

    2000年,Roy Fielding博士在论文中提出REST(Representational State Transfer)风格的软件API架构模式。该模式对上面的问题提出了针对性的解决方案,迅速被大家接受,逐渐流行起来。

    REST是一种API的设计模式,它将数据库的数据看做是一个个的资源。客户端的请求就是对这些资源的操作,这些操作无外乎增删改查四种。这种模式简单易读,易于维护。

    这种设计模式提倡我们遵循以下原则。

    数据格式

    REST提倡数据格式应该使用轻量级,易于阅读的json格式。这要求我们除了GET请求方式外,其他请求方式的请求体都应该是json,响应体也是json。
    所以,请求头和响应头的Content-Type都应该为application/json

    请求方式

    REST将请求看做是对某个资源的增删改查操作,正好对应了Http请求的GET,POST, PUT, DELETE 4种请求方法。
    对应关系如下:

    • 获取资源:GET方式
    • 创建资源:POST方式
    • 更新资源:PUT方
    • 删除资源:DELETE方式

    URL设计

    REST提倡声明式的URL设计。URL设计需要考虑层次化,可扩展,易于维护。每一个URL都表示对某个资源的操作,假设我们要操作服务器的博客数据,可以这样设计:

    • 通用的资源操作方式:
      // 获取所有博客
      GET /api/blogs  
      // 获取指定博客
      GET /api/blogs/1234
      // 创建博客
      POST /api/blogs
      // 更新指定博客
      PUT /api/blogs/1234
      // 删除指定博客
      DELETE /api/blogs/1234
      
    • 资源的过滤操作,使用查询参数来限定条件:
      // 分页获部分博客
      GET /api/blogs?page=1&size=15&sort=time  
      
    • 按层次组织资源:
      // 获取某个博客下面的所有评论
      GET /api/blogs/143/comments
      
      层次化的设计有可能会让URL太长,不便于阅读,比如:
      // 获取某个博客下面的某个评论的某个回复
      GET /api/blogs/123/comments/12343/replys/2231
      
      所以,我们也可以使用扁平化的方式设计所有的资源:
      // 获取某个博客的所有评论,使用查询参数来限定条件
      GET /api/comments?blogId=123
      // 获取某个评论的所有回复
      GET /api/replys?commentId=123
      
    • API的版本升级。
      我们的API会不断的更新迭代,比如:获取所有订单的URL参数多加了一个时间戳。如果我们直接更改原来接口的逻辑,会导致旧版本的客户端获取失败。因此,通过添加一个路径/v1来让我们的API更加维护性。
      // 获取所有订单, 第一版
      GET /api/v1/orders
      // 获取所有订单, 第二版
      GET /api/v2/orders
      

    响应设计

    响应设计分为数据结构设计和响应码设计。

    • 响应数据结构设计

      客户端对资源的操作有可能成功,也有可能失败。以前我一直使用使用这样的数据结构:

      {
          code: 1/0, // 会有很多标识码,11, 12, 13 ...
          msg: "获取成功/获取失败",
          data: [...]/{}
      }
      

      整体的结构一定不能变,数据的变化体现在data字段。这样非常方便客户端的解析或者序列化(静态语言)。

    • 响应码设计

      响应码分为http响应码和逻辑响应码。http响应码很简单,如果成功就200,服务器出错就500。而逻辑响应码则是需要自己来定义,比如:1表示用户不存在,2表示密码错误。

    前后端分离

    在以前的时代,用户请求一个网页,服务端通过JSP技术,或者其他模板引擎技术动态渲染后,返回给用户。它们看起来像这样:

    这样做的坏处是,后端和前端融合在一起,哪怕前端代码不是由后端人员来写,仍然需要2方人员进行必要的交流和沟通,降低了开发效率;而且前端和后端共同部署,灵活性差;而且后台处理静态资源的性能较差,也不应该去处理静态资源压缩,缓存等问题,应该交给代理服务器来处理,比如Nginx。

    前后端分离最极致作法是:前端和后端各自独立编写,独立部署,通过API接口进行交互。他们看起来像这样:

    项目实战:电商管理后台

    目标,实现一个有账户模块,权限模块,商品和分类模块和订单模块,给商家和管理员使用的后台系统。

    项目采用前后端分离的开发方式,本身只实现API功能,并没有提供界面。

    项目结构搭建和实施流程

    在之前TODO项目的基础上,增加一个middleware包和test包,前者用来存放中间件的包,因为权限管理需要用中间件来实现;后者是测试相关包。

    1. 每个模块的实现顺序为:model层 --> service层 --> router层。
    2. 单元测试:service层写脚本测试;router层使用postman测试。

    配置文件的环境切换

    开发环境和生产环境的配置一般是不一样的,比如端口配置,数据库配置。一般我们是通过环境变量NODE_ENV来区分。为了能够动态切换配置,就需要根据当前NODE_ENV的值来加载不同的配置对象。

    做法就是:

    1. 建立config目录,创建dev.jsprod.js分别存放对应的配置信息
    2. 编写index.js,实现动态切换配置的逻辑。

    目录结构:

    编写入口文件

    添加依赖:

    npm i body-parser express express-async-errors mongoose morgan
    

    编写app.jsdb.js文件。

    app.js

    //引入dib
    require('./db')
    
    const config = require('./config');
    const morgan = require('morgan')
    const bodyParser = require('body-parser');
    const express = require('express')
    // 引入异常捕获处理
    require('express-async-errors');
    
    const app = express();
    
    //注册中间件
    // log中间件
    app.use(morgan('combined'));
    
    //注册自定义的中间件
    
    // 注册body-parser中间件
    // parse application/x-www-form-urlencoded
    app.use(bodyParser.urlencoded({ extended: false }));
    // parse application/json
    app.use(bodyParser.json());
    
    // 注册路由
    app.use("/users", require('./router/account'));
    
    // 注册异常处理中间件
    app.use((err, req, res, next)=>{
        res.fail(err.toString())
    });
    
    //启动
    app.listen(config.PORT);
    
    

    db.js

    const config = require('./config');
    const mongoose  = require('mongoose');
    mongoose.connect(`mongodb://127.0.0.1/${config.DB}`);
    
    const db = mongoose.connection;
    
    db.on('error', (err)=>{
        console.log(err);
    });
    
    db.on("open", ()=>{
        console.log("mongodb connect successfully!");
    });
    

    账户模块

    先编写model,再service,最后router;最后对service和router进行测试。

    REST中间件

    为了方便进行REST结果的返回,我们编写一个res_md.js中间件,作用是给每个res对象安装2个方法,注意该中间件注册的顺序尽量放在前面。代码如下:

    module.exports = function (req, res, next) {
      res.success = (data = null) =>{
        res.send({
            code: 0,
            msg: "操作成功",
            data: data
        })
      };
      res.fail = (msg)=>{
        res.send({
            code: -1,
            msg: msg
        })
      };
    
      next();
    };
    

    账户model

    const mongoose = require('mongoose')
    const schema = new mongoose.Schema({
        username: {
            type: String,
            required: [true, "用户名不能缺少"]
        },
        password: {
            type: String,
            required: [true, "密码不能缺少"]
        },
        age: {
            type: Number,
            min: [0, "年龄不能小于0"],
            max: [120, "年龄不能大于120"]
        },
        role: {
            type: Number,
            default: 0 // 0是商家, 10086是管理员
        },
        created:{
            type: Date,
            default: Date.now()
        }
    });
    
    module.exports = mongoose.model('user', schema);
    

    账户service

    const User = require('../model/user');
    const config = require('../config')
    const crypto = require('lxj-crypto')
    
    /**
     * 根据用户名获取某个用户
     * @param username
     * @returns {Promise<*>}
     */
    async function getUserByUsername(username) {
        return await User.findOne({username: username}).select("-__v")
    }
    
    
    async function checkCanInsertUser(user) {
        //检查密码是否为空
        if(!user.password || user.password.length===0){ 
            throw Error("密码不能为空")
        }
        //检查用户是否已经存在
        let res = await getUserByUsername(user.username);
        if(res){
            throw Error("用户名已经存在")
        }
    }
    
    
    /**
     * 添加普通用户
     * @param user
     * @returns {Promise<void>}
     */
    async function addUser(user) {
        await checkCanInsertUser(user);
    
        user.role = 0;
        user.created = Date.now();
    
        //对密码进行加密,加密的方式:使用username作为随机数对password进行哈希
        user.password = crypto.md5Hmac(user.password, user.username)
        await User.create(user)
    }
    
    async function deleteUser(id) {
        let res = await User.deleteOne({_id:id});
        if(!res || res.n===0){
            throw Error("删除用户失败")
        }
    }
    
    /**
     * 登录的方法
     * @param user
     * @returns token
     */
    async function login(user) {
        // 1. 对密码进行加密
        user.password = crypto.md5Hmac(user.password, user.username)
        // 2. 进行查询
        let res = await User.findOne({username:user.username, password: user.password});
        if(!res){
            throw Error("用户名或者密码错误")
        }
    
        // 说明用户名和密码验证成功,需要生产token返回给客户端,以后客户端的header中带上这个token
        // token 生产方法:用aes进行对指定的data加密
        let tokenData = {
            username: user.username,
            expire: Date.now() + config.TokenDuration
        };
        let token = crypto.aesEncrypt(JSON.stringify(tokenData), config.TokenKey);
        return token
    }
    
    module.exports = {
        getUserByUsername,
        addUser, 
        deleteUser,
        login
    };
    

    账户router

    let router = require("express").Router();
    let accountService = require('../service/accout')
    
    
    router.get("/:username", async (req, res)=>{
        let user = await accountService.getUserByUsername(req.params.username);
        res.success(user);
    });
    
    // 登录
    router.post("/login", async (req, res)=>{
        let token = await accountService.login(req.body);
        res.success({token});
    });
    
    // 注册
    router.post("/register", async (req, res)=>{
        await accountService.register(req.body)
        res.success()
    });
    
    router.delete("/:id", async (req, res)=>{
        await accountService.deleteUser(req.params.id)
        res.success()
    });
    
    module.exports = router;
    
  • 相关阅读:
    关于时间的字词
    Postgresql 存储过程调试 1
    Delphi 调试日子
    Delphi 调试日子
    TList,TObjectList 使用——资源释放
    Lazarus开发环境编译选项配置
    Delphi 递归搜索.SVN文件夹并“处理”
    Delphi 路径相关函数
    如何掌握程序语言(王垠)
    struct/class等内存字节对齐问题详解
  • 原文地址:https://www.cnblogs.com/xiaocongcong888/p/9436233.html
Copyright © 2020-2023  润新知