Koa2 Restful Server

一、总架构图

koa框架.png

二、基本流程说明：

Step1 => 前端 Client (H5, iOS, Android, Postman, ...) 发送 HTTP 请求给 Server

Step2 => Koa2 默认定义该请求为 ctx

"假设 HTTP 请求的 url 为 //127.0.0.1:3000/modules/port/{params_1}/{params_2}?query_1='参数1'&query_2='参数2'"
"
假设 HTTP 请求的 data 为
    {
      field_a:'字段a',
      field_b:'字段b'
    }
"
ctx = {
        params:{
                params_1:'占位符参数1',
                params_2:'占位符参数2',
                ...
              },
        query:{
                query_1:'参数1',
                query_2:'参数2',
                ...
              },
        request:{
                  body:{
                         field_a:'字段a',
                         field_b:'字段b',
                         ...
                       }
                 }
       }

Step3 => 根据 HTTP 请求的 url 查找对应的模块路由接口：routes + ports

Step4 => 通过路由进入 Controller 中对应的接口：ports

Step5 => Controller 通过以下方式整合得到最终Client 期望得到的返回结果

1.Services 中定义的方法( 主要业务逻辑 )
2.async/await （异步流程控制）
3.部分JavaScript操作 ( 参数解析, 变量暂存, 响应格式化打包... )

Step6 => 打包结果并格式化数据结构通过 ctx.body 返回给client

三、Get started

1.全局安装 wa-cli-zq 脚手架

$ npm install wa-cli-zq -g

2.初始化项目

$ wa init server

3.添加业务模块 [ 需进入 api 文件夹，业务模块用单数，如：user , product , order .... ]

$ cd api => (进入 api 文件夹)
$ wa add user => (初始化 user 业务模块：默认路由api接口为 /users/port1)
$ cd .. => (退出 api 文件夹)

四、业务开发建议

*专注于 api 文件夹对应业务模块

重要：【黑箱模式：In：ctx.query, ctx.request.body => Out：ctx.body】

1.定义 model 数据结构 => (api/example/model.js)

2.黑箱入口In：根据功能定义接口名称 =>(api/example/routes.js)

3.黑箱出口Out：根据定义的接口编写核心代码流程 =>(api/controllers.js)

4.根据controller流程需要编写细节服务services =>(api/services.js)

5.反复调整编写 3 <=> 4 , 偶尔调整 1 , 2

6.通过 Postman 验证接口功能是否达到预期

五、代码采样

1.model.js

const mongoose = require('mongoose');

const taskSchema = mongoose.Schema({
    basicTask: { type: String ,ref:'BasicTask'},
    count: { type: Number },
    staff: { type: String ,ref:'User'},
    manager:{type:String,ref:'User'},
    date:{type:Date},
    startTime:{type:Date},
    finishTime:{type:Date},
    finalOutput:{type:String},
    finalBonus:{type:Number},
    status: { type: String}
});

module.exports = mongoose.model('Task', taskSchema)

2.routes.js 黑箱入口

const Router = require('koa-router')
const router = new Router({ prefix: '/tasks' })
const Controllers = require('./controllers')

router.post('/createTask', Controllers.port1)
router.post('/getProcessingTasks',Controllers.port2)
router.post('/checkProcessingTask',Controllers.port3)

module.exports = router

3.controllers.js 黑箱 通过 In 来的数据产出 Out

const Services = require('./services')
const Services_from_workRecord = require('../workRecord/services')

module.exports = {
    port1: async (ctx) => {
        // 整合请求条件
        // query 为 指定员工 指定状态为处理中
        let query = {
            staff: ctx.request.body.staff,
            status: 'processing'
        }
        // 将条件丢给Services => Database => findTask方法等待返回结果
        // 结果为 true => 该员工存在正在进行中的任务
        // 结果为 false => 该员工当前无任务
        let ProcessingTask = await Services.Database.findTask(query)
        // 对返回结果的情况做判断进行不同的处理
        if (ProcessingTask) {
            // 如果结果未 true, 则直接返回如下结果
            ctx.body = {
                status: 1,
                message: 'A processing task'
            }
        } else {
            // 如果结果未 false, 则准备一些任务表需要的数据：date, ctx中传来的任务数据等...
            let date = new Date(new Date(new Date().getTime() + 8 * 3600 * 1000).toDateString())
            let startTime = new Date()
            let status = 'processing'
            ctx.request.body.date = date
            ctx.request.body.startTime = startTime
            ctx.request.body.status = status
            // 数据准备完成 将其丢给 Services => Database => createTask 方法然后等待返回值
            let newTask = await Services.Database.createTask(ctx.request.body)
            // 返回值为新建立的任务表
            // 此时即可直接跳出黑箱返回结果给Client , 但是由于业务需求需要再进行一个记录操作
            // 调用工作记录模块的Services_from_workRecord => Database => setProcessingTask 然后等待返回值
            await Services_from_workRecord.Database.setProcessingTask({ date: date, staff: newTask.staff }, newTask._id)
            // 此时返回值自定义任意形式都行，没什么用，不关心，异步操作完成后直接返回如下给Client 
            ctx.body = {
                status: 0,
                message: 'Created new Task successfully'
            }
           // 由于洋葱圈模型在最外层使用了总error捕获中间件
           // 整个流程只考虑成功的情况，不需要考虑出现 error catch(error)
           // 除非自定义错误
           // let err = new Error('message')
           // err.code = '自定义code'  默认为 500
           // throw err  
        }
    },
    port2: async (ctx) => {
        let query = {
            status: 'processing'
        }
        let ProcessingTasks = await Services.Database.findTasks(query)
        let ProcessingTasks_addTimeSpan = await Services.Function.calculateTimeSpan(ProcessingTasks)
        ctx.body = {
            status: 0,
            payload: ProcessingTasks_addTimeSpan
        }
    },
    port3: async (ctx) => {
        let ID = ctx.query.taskID
        let data = ctx.request.body
        await Services.Database.checkTask(ID, data)
        await Services_from_workRecord.Database.finishProcessingTask({ processingTask: ID },parseFloat(data.finalBonus))
        ctx.body = {
            status: 0
        }
    }
}

4.services.js

const Task = require('./model')

module.exports = {
    Database: {
        findTask: async (query) => {
            return await Task.findOne(query)
        },
        createTask: async (data) => {
            return await Task.create(data)
        },
        findTasks: async (query) => {
            return await Task.find(query).populate('staff manager basicTask')
        },
        checkTask: async (ID, data) => {
            let task = await Task.findById(ID)
            task.finalOutput = data.finalOutput
            task.finalBonus = data.finalBonus
            task.finishTime = new Date()
            task.status = 'finished'
            return await task.save()
        }
    },
    Function: {
        calculateTimeSpan: async (tasks) => {
            let newTasks = tasks.map(task => {
                let totalSecond = (new Date().getTime() - new Date(task.startTime).getTime()) / 1000
                totalSecond = totalSecond <= 0 ? 0 : totalSecond
                let h = totalSecond / 3600 > 0 ? (Math.floor(totalSecond / 3600)) : 0
                let min = (totalSecond - 3600 * h) / 60 > 0 ? Math.floor((totalSecond - 3600 * h) / 60) : 0
                let s = Math.floor(totalSecond - h * 3600 - min * 60)
                h = h < 10 ? ('0' + h) : h
                min = min < 10 ? ('0' + min) : min
                s = s < 10 ? ('0' + s) : s
                return { ...task._doc, h, min, s }
            })
            return newTasks
        }
    }
}