一、总架构图
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
}
}
}
