Koa 学习 01 Koa 介绍和基本使用（路由、静态资源托管、中间件）
Koa 介绍
- Koa 是一个新的 web 框架，由 Express 幕后的原班人马打造，致力于成为 web 应用和 API 开发领域中的一个更小、更富有表现力、更健壮的基石。
- 官网：https://koajs.com/
- GitHub 仓库：https://github.com/koajs/koa
- 一个翻译的中文网：https://koa.bootcss.com/
- Koa 的原理和内部结构很像 Express，但是语法和内部结构进行了升级
- Koa 内部使用 ES6 编写，号称是下一代 Node.js Web 框架
- 它的主要特点是通过利用 async 函数，帮你丢弃回调函数
- Koa 1 是基于 ES2015 中的 Generator 生成器函数结合 CO 模块
- Koa 2 完全抛弃了 Generator 和 co，升级为了 ES2017 中的 async/await 函数
- 正是由于 Koa 内部基于最新的异步处理方式，所以使用 Koa 处理异常更加简单
- Koa 中提供了 context 上下文对象
- Koa 包装和扩展了 Nodejs 中的 req 和 res
- Express 只是扩展了 req 和 res
- Koa 并没有捆绑任何中间件， 而是提供了一套优雅的方法，帮助您快速而愉快地编写服务端应用程序。
- Koa 本身并不支持路由、模板、发送文件、JSONP 等功能，需要单独安装对应的中间件
- 有很多开发工具/框架都是基于 Koa 的
- Egg.js - 企业级 Web 开发框架
- 构建工具 Vite - Vue 3 构建工具
- Koa vs Express 官方对比
- 其他评价
- koa 2 好用，设计上的确有优势。优势不在能实现更强的功能，而是可以更简单地完成功能。
- koa 2 社区远不如 express
- koa 1 在思想上与 koa 2 是一致的，但是 koa 2 的实现更漂亮
- Awesome Koa - 第三方仓库，收录了一些和 Koa 相关的资源，教程、中间件等
Koa 基本使用
使用 Koa 启动一个 HTTP 服务
npm init -y
# 安装 koa
npm i koa
// app.js
const Koa = require('koa')
const app = new Koa()
// Koa 没有路由系统，只有中间件功能
// ctx:context 上下文对象，包含请求和响应相关方法
app.use(ctx => {
// 发送响应
ctx.body = 'Hello Koa'
})
app.listen(3000, () => {
console.log('server is running on http://localhost:3000')
})
nodemon ./app.js
Koa 中的路由
Koa 本身不自带路由功能，如果想要对不同的请求路径进行分发处理，需要自己手动编码处理。
app.use(ctx => {
const path = ctx.path
console.log(path);
if (path === '/') {
ctx.body = 'home page'
} else if (path === '/foo') {
ctx.body = 'foo page'
} else {
ctx.body = '404 Not Found.'
}
})
实际上 Koa 将一些功能单独封装成 npm 包，其中包括路由功能。
在 Koa.js (github.com) 中搜索 route 仓库可以找到几个官方提供的路由工具包，推荐使用 koajs/router，它使用 Express 风格的方法（app.get、app.post 等），详情参考API 文档。
# 安装
npm i @koa/router
// app.js
const Koa = require('koa')
const Router = require('@koa/router')
const app = new Koa()
const router = new Router()
router.get('/', ctx => {
ctx.body = 'home page'
})
router.post('/', ctx => {
ctx.body = 'post /'
})
router.get('/foo', ctx => {
ctx.body = 'foo page'
})
router.get('/bar', ctx => {
// 重定向
ctx.redirect('/foo')
})
router.get('/users/:id', ctx => {
ctx.body = ctx.params
})
app
// 挂载路由配置
.use(router.routes())
// 配置允许的请求方法：OPTIONS 请求的 Allow 请求头
.use(router.allowedMethods())
app.listen(3000, () => {
console.log('server is running on http://localhost:3000')
})
Koa 中的静态资源托管
koajs/static 模块封装了静态资源托管的功能。
npm i koa-static
// app.js
const Koa = require('koa')
const static = require('koa-static')
const path = require('path')
const app = new Koa()
// http://localhost:3000/css/style.css 访问 /public/css/style.css 文件
app.use(static(path.join(__dirname, './public')))
app.listen(3000, () => {
console.log('server is running on http://localhost:3000')
})
Koa 的中间件不能通过第一个参数设置请求路径，通过下面的方式给静态资源目录添加虚拟路径会报错：
app.use('/public', static(path.join(__dirname, './public')))
可以使用 Koa 的另一个模块 koajs/mount 将 Koa 应用或中间件装载到指定路径：
npm i koa-mount
// mount(<路径>, <中间件>)
app.use(mount('/public', static(path.join(__dirname, './public'))))
Koa 中间件
中间件执行栈
Koa 最大的特色和 Express 一样，也是完全基于中间件（middleware）构建的 web 框架。
Koa 中间件和 Express 中间件有很大的区别，Koa 中间件完全基于洋葱模型（如图）：
- 多个中间件会形成一个栈结构（middle stack），以“先进后出”（first-in-last-out）的顺序执行。
- 最外层的中间件首先执行。
- 调用
next函数的时候，会把执行权交给下一个中间件 - …
- 最内层的中间件最后执行
- 执行结束后，把执行权交回上一层的中间件
- …
- 最外层的中间件收回执行权后，执行 next 函数后面的代码
下面通过代码查看中间件的栈结构：
const one = (ctx, next) => {
console.log('>> one')
next()
console.log('<< one')
}
const two = (ctx, next) => {
console.log('>> two')
next()
console.log('<< two')
}
const three = (ctx, next) => {
console.log('>> three')
next()
console.log('<< three')
}
app.use(one)
app.use(two)
app.use(three)
打印结果：
>> one
>> two
>> three
<< three
<< two
<< one
如果中间件内部没有调用 next 函数，那么执行权就不会传递下去。例如将 two 函数中的 next() 注释，打印结果：
>> one
>> two
<< two
<< one
异步中间件
迄今为止，所有例子的中间件都是同步的，不包含异步操作。如果有异步操作（比如读取数据库、读取文件），中间件就必须写成 async 函数：
const Koa = require('koa')
const path = require('path')
const fsPromises = require('fs').promises
const app = new Koa()
app.use(async (ctx, next) => {
const data = await fsPromises.readFile(path.join(__dirname, './views/index.html'))
// 设置 content-type 为 text/html
// 或者在读取文件的时候设置编码为 `utf8`
ctx.type = 'html'
ctx.body = data
next()
})
app.listen(3000, () => {
console.log('server is running on http://localhost:3000')
})
合并多个中间件
Koa 默认只能一个一个挂载中间件：
app.use(one)
app.use(two)
app.use(three)
可以使用中间件组合工具 koajs/compose，将多个中间件合并成同一个中间件去挂载。
npm i koa-compose
app.use(compose([one, two, three]))
全局异常处理
下面是捕获并手动响应错误的中间件：
app.use(ctx => {
try {
JSON.parse('string')
ctx.body = 'Hello Koa'
} catch (error) {
ctx.response.status = 500
ctx.response.body = '服务端内部错误'
}
})
也可以使用 Koa 提供的快捷方法 ctx.throw 来响应错误：
app.use(ctx => {
try {
JSON.parse('string')
ctx.body = 'Hello Koa'
} catch (error) {
// ctx.response.status = 500
// ctx.response.body = '服务端内部错误'
// ctx.throw(500) // body => Internal Server Error
ctx.throw(404) // body => Not Found
}
})
上例是对单个中间件的错误捕获处理，如果要统一的处理程序中的异常，就要利用洋葱中间件的模型，将捕获错误的代码写在最外层：
const Koa = require('koa')
const app = new Koa()
// 最外层添加异常捕获的中间件
app.use((ctx, next) => {
try {
next()
} catch (error) {
ctx.response.status = 500
ctx.response.body = error.message
}
})
app.use(ctx => {
JSON.parse('string')
ctx.body = 'Hello Koa'
})
...
可以看到 Koa 处理错误的方式相比 Express 方便一些：不需要在每个中间件中 try-catch 捕获错误并将错误传递给 next。
注意上例使用的都是同步中间件，如果是异步中间件就要在 try-catch 中使用 await：
// 最外层添加异常捕获的中间件
app.use(async (ctx, next) => {
try {
// 使用 await 等待下一个中间件处理完成
await next()
} catch (error) {
ctx.response.status = 500
ctx.response.body = error.message
}
})
// 同步中间件：A
app.use((ctx, next) => {
next()
})
// 异步中间件：B
app.use(async ctx => {
// 读取不存在的文件
await fsPromises.readFile('file.txt')
})
但是这样不会捕获中间件 B 的错误，因为上层的中间件 A 是同步的，并未等待下层中间件的结果，最外层的错误处理中间件 await 的是中间件 A 的执行结果。
解决办法有：
// 方案一，同步中间件返回下层中间件的执行结果
// 同步中间件：A
app.use((ctx, next) => {
return next()
})
// 方案二，将同步中间件改为异步中间件，await next()
// 同步中间件：A
app.use(async (ctx, next) => {
await next()
})
这属于 JS 的 Promise 语法问题，与 Koa 和中间件无关。
建议：所有的中间件都使用 asycn 异步函数，使用 await 等待 next()。
另一种异步处理方式
除了使用外层中间件的方式捕获错误，Koa 还可以通过监听 error 事件捕获错误：
// 可以在任意位置监听事件
app.on('error', err => {
console.log(err)
})
**注意：**使用外层中间件 try-catch 捕获并处理了错误，并不会触发 error 事件。
如果既要在中间件中处理异常，又要触发 error 事件，可以在中间件中手动触发 error 事件：
// 最外层添加异常捕获的中间件
app.use(async (ctx, next) => {
try {
await next()
} catch (error) {
ctx.response.status = 500
ctx.response.body = error.message
// 触发 error 事件
ctx.app.emit('error', error, ctx)
}
})
实际项目中，使用二者之一即可（建议使用中间件）。