https://www.yuque.com/books/share/78a0f8da-df9c-4dfc-991a-b52d07b3c3e5?# 《Koa 教程》
介绍
Koa 中的 Context 对象
参见:https://koa.bootcss.com/#context。
Koa 中的路由
原生路由
网站一般都有多个页面。通过ctx.request.path可以获取用户请求的路径,由此实现简单的路由。
const main = ctx => {
if (ctx.request.path !== '/') {
ctx.response.type = 'html';
ctx.response.body = '<a href="/">Index Page</a>';
} else {
ctx.response.body = 'Hello World';
}
};
koa-router 模块
原生路由用起来不太方便,我们可以使用封装好的 koa-router 模块。
1、安装
npm i @koa/router
2、示例
const Koa = require('koa');
const Router = require('@koa/router');
const app = new Koa();
const router = new Router();
router.get('/', (ctx, next) => {
// ctx.router available
});
app
.use(router.routes())
.use(router.allowedMethods());
静态资源托管
如果网站提供静态资源(图片、字体、样式表、脚本…),为它们一个个写路由就很麻烦,也没必要。koa-static 模块封装了这部分的请求。
1、安装
npm install koa-static
2、示例
const serve = require('koa-static');
const Koa = require('koa');
const app = new Koa();
// $ GET /package.json
app.use(serve('.'));
// $ GET /hello.txt
app.use(serve('test/fixtures'));
// or use absolute paths
app.use(serve(__dirname + '/test/fixtures'));
app.listen(3000);
console.log('listening on port 3000');
给静态资源设置虚拟路径
使用 Koa 提供的 koa-mount 。
重定向
有些场合,服务器需要重定向(redirect)访问请求。比如,用户登陆以后,将他重定向到登陆前的页面。ctx.response.redirect()方法可以发出一个302跳转,将用户导向另一个路由。
ctx.response.redirect('/');
ctx.response.body = '<a href="/">Index Page</a>';
Koa 中间件
中间件栈
异步中间件
迄今为止,所有例子的中间件都是同步的,不包含异步操作。如果有异步操作(比如读取数据库),中间件就必须写成 async 函数。
app.use(async (ctx, next) => {
const data = await util.promisify(fs.readFile)('./views/index.html')
ctx.type = 'html'
ctx.body = data
next()
})
上面代码中,fs.readFile 是一个异步操作,必须写成 await fs.readFile(),然后中间件必须写成 async 函数。
中间件的合成
koa-compose 模块可以将多个中间件合成为一个。
1、安装
npm install koa-compose
2、示例
const compose = require('koa-compose');
const logger = (ctx, next) => {
console.log(`${Date.now()} ${ctx.request.method} ${ctx.request.url}`);
next();
}
const main = ctx => {
ctx.response.body = 'Hello World';
};
const middlewares = compose([logger, main]);
app.use(middlewares);
Koa 中的错误处理
500 错误
如果代码运行过程中发生错误,我们需要把错误信息返回给用户。HTTP 协定约定这时要返回500状态码。Koa 提供了ctx.throw()方法,用来抛出错误,ctx.throw(500)就是抛出500错误。
const main = ctx => {
ctx.throw(500);
};
404 错误
如果将ctx.response.status设置成404,就相当于ctx.throw(404),返回404错误。
const main = ctx => {
ctx.response.status = 404;
ctx.response.body = 'Page Not Found';
};
处理错误的中间件
为了方便处理错误,最好使用 try…catch 将其捕获。但是,为每个中间件都写 try…catch 太麻烦,我们可以让最外层的中间件,负责所有中间件的错误处理。
const handler = async (ctx, next) => {
try {
await next();
} catch (err) {
ctx.response.status = err.statusCode || err.status || 500;
ctx.response.body = {
message: err.message
};
}
};
const main = ctx => {
ctx.throw(500);
};
app.use(handler);
app.use(main);
error 事件的监听
运行过程中一旦出错,Koa 会触发一个error事件。监听这个事件,也可以处理错误。
const main = ctx => {
ctx.throw(500);
};
app.on('error', (err, ctx) =>
console.error('server error', err);
);
如果 req/res 期间出现错误,并且 无法 响应客户端,Context实例仍然被传递:
app.on('error', (err, ctx) => {
log.error('server error', err, ctx)
});
当发生错误并且仍然可以响应客户端时,也没有数据被写入 socket 中,Koa 将用一个 500 “内部服务器错误” 进行适当的响应。在任一情况下,为了记录目的,都会发出应用级 “错误”。
释放 error 事件
需要注意的是,如果错误被try…catch捕获,就不会触发error事件。这时,必须调用ctx.app.emit(),手动释放error事件,才能让监听函数生效。
const handler = async (ctx, next) => {
try {
await next();
} catch (err) {
ctx.response.status = err.statusCode || err.status || 500;
ctx.response.type = 'html';
ctx.response.body = '<p>Something wrong, please contact administrator.</p>';
ctx.app.emit('error', err, ctx);
}
};
const main = ctx => {
ctx.throw(500);
};
app.on('error', function(err) {
console.log('logging error ', err.message);
console.log(err);
});
上面代码中,main 函数抛出错误,被 handler 函数捕获。catch 代码块里面使用 ctx.app.emit() 手动释放 error 事件,才能让监听函数监听到。
Koa 开发 Web App 功能
Cookies
ctx.cookies 用来读写 Cookie。
const main = function(ctx) {
const n = Number(ctx.cookies.get('view') || 0) + 1;
ctx.cookies.set('view', n);
ctx.response.body = n + ' views';
}
访问 http://127.0.0.1:3000 ,你会看到1 views。刷新一次页面,就变成了2 views。再刷新,每次都会计数增加1。
表单
Web 应用离不开处理表单。本质上,表单就是 POST 方法发送到服务器的键值对。koa-body模块可以用来从 POST 请求的数据体里面提取键值对。
const koaBody = require('koa-body');
const main = async function(ctx) {
const body = ctx.request.body;
if (!body.name) ctx.throw(400, '.name required');
ctx.body = { name: body.name };
};
app.use(koaBody());
文件上传
koa-body 模块还可以用来处理文件上传。
const os = require('os');
const path = require('path');
const koaBody = require('koa-body');
const main = async function(ctx) {
const tmpdir = os.tmpdir();
const filePaths = [];
const files = ctx.request.body.files || {};
for (let key in files) {
const file = files[key];
const filePath = path.join(tmpdir, file.name);
const reader = fs.createReadStream(file.path);
const writer = fs.createWriteStream(filePath);
reader.pipe(writer);
filePaths.push(filePath);
}
ctx.body = filePaths;
};
app.use(koaBody({ multipart: true }));
零、Koa 源码目录结构
.
├── History.md
├── LICENSE
├── Readme.md
├── dist
│ └── koa.mjs
├── lib
│ ├── application.js # 最核心的模块
│ ├── context.js # 上下文对象
│ ├── request.js # Koa 自己实现的请求对象
│ └── response.js # Koa 自己实现的响应对象
└── package.json
一、基本结构
application.js
module.exports = class Application {
listen(...args) {
const server = http.createServer((req, res) => {
res.end('My Koa')
})
return server.listen(...args)
}
}
二、实现中间件功能
收集中间件
使用方式:
const Koa = require('./koa')
const app = new Koa()
app.use((ctx, next) => {
ctx.body = 'foo'
})
app.use((ctx, next) => {
ctx.body = 'Koa'
})
app.listen(3000)
application.js
const http = require('http')
module.exports = class Application {
constructor () {
this.middleware = []
}
use(fn) {
if (typeof fn !== 'function')
throw new TypeError('middleware must be a function!')
this.middleware.push(fn)
}
listen(...args) {
const server = http.createServer((req, res) => {
res.end('My Koa')
})
return server.listen(...args)
}
}
调用中间件
const http = require('http')
module.exports = class Application {
constructor() {
this.middleware = [] // 存储用户所有的中间件处理函数
}
use(fn) {
this.middleware.push(fn)
}
listen(...args) {
const server = http.createServer(this.callback())
return server.listen(...args)
}
compose(middleware) {
return function () { // 可以配置额外参数
const dispatch = i => {
if (i >= middleware.length) return Promise.resolve()
const fn = middleware[i]
return Promise.resolve(
fn({}, () => dispatch(i + 1))
)
}
return dispatch(0)
}
}
callback() {
const fnMiddleware = this.compose(this.middleware)
const handleRequest = (req, res) => {
fnMiddleware()
.then(() => {
// 处理结束
res.end('end')
})
.catch(err => {
// 发生异常
res.end('error')
})
}
return handleRequest
}
}
三、处理上下文对象
初始化上下文对象
context 上下文对象的使用方式:
/**
* Koa Context
*/
const Koa = require('./koa')
const app = new Koa()
// Koa Context 将 node 的 request 和 response 对象封装到单个对象中,为编写 Web 应用程序和 API 提供了许多有用的方法。
// 每个请求都将创建一个 Context,并在中间件中作为参数引用
app.use((ctx, next) => {
console.log(ctx) // Context 对象
console.log(ctx.req) // Node 的 request 对象
console.log(ctx.res) // Node 的 response 对象
console.log(ctx.request) // Koa 中封装的请求对象
console.log(ctx.request.header) // 获取请求头对象
console.log(ctx.request.method) // 获取请求方法
console.log(ctx.request.url) // 获取请求路径
console.log(ctx.request.path) // 获取不包含查询字符串的请求路径
console.log(ctx.request.query) // 获取请求路径中的查询字符串
// Request 别名
// 完整列表参见:https://koa.bootcss.com/#request-
console.log(ctx.header)
console.log(ctx.method)
console.log(ctx.url)
console.log(ctx.path)
console.log(ctx.query)
// Koa 中封装的响应对象
console.log(ctx.response)
// Response 别名
ctx.status = 200
ctx.message = 'Success'
ctx.type = 'plain'
ctx.body = 'Hello Koa'
})
app.listen(3000)
context.js
const context = {
}
module.exports = context
request.js
const url = require('url')
const request = {
get url () {
return this.req.url
},
get path () {
return url.parse(this.req.url).pathname
},
get query () {
return url.parse(this.req.url, true).query
},
get method () {
return this.req.method
}
}
module.exports = request
response.js
const response = {}
module.exports = response
application.js
const http = require('http')
const context = require('./context')
const request = require('./request')
const response = require('./response')
class Application {
constructor() {
this.middleware = [] // 保存用户添加的中间件函数
// 为了防止多个实例共享 Request、Response、Context 导致数据被意外修改,这里重新拷贝一份
this.request = Object.create(request)
this.response = Object.create(response)
this.context = Object.create(context)
}
listen(...args) {
const server = http.createServer(this.callback())
server.listen(...args)
}
use(fn) {
this.middleware.push(fn)
}
// 异步递归遍历调用中间件处理函数
compose(middleware) {
return function (context) {
const dispatch = index => {
if (index >= middleware.length) return Promise.resolve()
const fn = middleware[index]
return Promise.resolve(
// TODO: 上下文对象
fn(context, () => dispatch(index + 1)) // 这是 next 函数
)
}
// 返回第 1 个中间件处理函数
return dispatch(0)
}
}
createContext(req, res) {
// 为了避免请求之间 context 数据交叉污染,这里为每个请求单独创建 context 请求对象
const context = Object.create(this.context)
const request = Object.create(this.request)
const response = Object.create(this.response)
context.app = request.app = response.app = this
context.req = request.req = response.req = req // 原生的请求对象
context.res = request.res = response.res = res // 原生的响应对象
request.ctx = response.ctx = context // 在 Request 和 Response 中也可以拿到 context 上下文对象
request.response = response // Request 中也可以拿到 Response
response.request = request // Response 中也可以拿到 Request
context.originalUrl = request.originalUrl = req.url // 没有经过任何处理的请求路径
context.state = {} // 初始化 state 数据对象,用于给模板视图提供数据
return context
}
callback() {
const fnMiddleware = this.compose(this.middleware)
const handleRequest = (req, res) => {
// 1、创建上下文请求对象
const context = this.createContext(req, res)
// 2、传入上下文对象执行中间件栈
fnMiddleware(context)
.then(() => {
console.log('end')
res.end('My Koa')
})
.catch(err => {
res.end(err.message)
})
}
return handleRequest
}
}
module.exports = Application
处理上下文对象中的别名
context.js
const context = {
// get method () {
// return this.request.method
// },
// get url () {
// return this.request.url
// }
}
defineProperty('request', 'method')
defineProperty('request', 'url')
defineProperty('response', 'body')
function defineProperty (target, name) {
// context.__defineGetter__(name, function () {
// return this[target][name]
// })
Object.defineProperty(context, name, {
get () {
return this[target][name]
},
set (value) {
this[target][name] = value
}
})
}
module.exports = context
四、处理 ctx.body
response.js
const response = {
set status (value) {
this.res.statusCode = value
},
_body: '', // 真正用来存数据的
get body () {
return this._body
},
set body (value) {
this._body = value
}
}
module.exports = response
respond
application.js
const http = require('http')
const { Stream } = require('stream')
const context = require('./context')
const request = require('./request')
const { body } = require('./response')
const response = require('./response')
class Application {
constructor() {
this.middleware = [] // 保存用户添加的中间件函数
this.context = Object.create(context)
this.request = Object.create(request)
this.response = Object.create(response)
}
...
callback() {
const fnMiddleware = this.compose(this.middleware)
const handleRequest = (req, res) => {
// 每个请求都会创建一个独立的 Context 上下文对象,它们之间不会互相污染
const context = this.createContext(req, res)
fnMiddleware(context)
.then(() => {
respond(context)
// res.end(context.body)
// res.end('My Koa')
})
.catch(err => {
res.end(err.message)
})
}
return handleRequest
}
}
function respond (ctx) {
const body = ctx.body
const res = ctx.res
if (body === null) {
res.statusCode = 204
return res.end()
}
if (typeof body === 'string') return res.end(body)
if (Buffer.isBuffer(body)) return res.end(body)
if (body instanceof Stream) return body.pipe(ctx.res)
if (typeof body === 'number') return res.end(body + '')
if (typeof body === 'object') {
const jsonStr = JSON.stringify(body)
return res.end(jsonStr)
}
}
module.exports = Application