KoaJS on Dapeng Zhang

TypeScript 3 + Koajs + Node.js

Wed, 09 Jul 2025 10:42:24 +0000

自NodeJS早期以来，Express一直是NodeJS开发人员事实上的标准Web框架。
但是，JavaScript在过去几年中已经走过了漫长的道路，像promises和async函数这样的功能使得构建更小，更强大的Web框架成为可能。

Koa就是这样一个框架。
它由Express背后的团队构建，以利用最新的JavaScript和NodeJS功能，特别是异步功能。

与Express和其他node框架（如Hapi）不同，Koa不需要使用回调。
这消除了难以跟踪的错误的巨大潜在来源，并使框架非常容易为新开发人员选择。

在本文中，我将向您介绍如何使用Koa和TypeScript来开发新的Web应用程序项目

第一步、安装和配置

Koa需要一个具有异步功能支持的Node版本，因此在开始之前确保安装了Node 8.x（或更高版本）。
Node 8将于2017年10月成为新的长期支持版本，因此它是启动新项目的绝佳选择。

我们现在将创建一个安装了以下内容的新node项目：

Koa
Koa Router
TypeScript
TS-Node 和 Nodemon(用于在开发期间自动构建和重启)

为项目创建一个新文件夹，然后执行以下命令：

npm init # and follow the resulting prompts to set up the project
npm i koa koa-router
npm i --save-dev typescript ts-node nodemon
npm i --save-dev @types/koa @types/koa-router

现在，在项目的根目录中，创建一个新的tsconfig.json文件并添加以下内容：

{
 "compilerOptions": {
 "module": "commonjs",
 "target": "es2017",
 "noImplicitAny": true,
 "outDir": "./dist",
 "sourceMap": true
 },
 "include": [
 "./src/***/*",
 ]
}

请注意，我们将TypeScript配置为转换为ES2017 - 这可确保我们利用Node的本机async/await功能。

第二步、创建服务器

由于Koa的核心是微框架，因此启动和运行它非常简单。在项目目录中，创建一个src文件夹，在其中创建一个新文件：server.ts，其中包含以下内容：

import * as Koa from 'koa';
import * as Router from "koa-router";

const app = new Koa();
const router = new Router();

router.get('/*', async (ctx) => {
 ctx.body = "Hi TS";
})

app.use(router.routes());

app.listen(8080);

console.log("Server running on port 8080");

第三步、使用Nodemon和TS-Node运行服务器

在开发过程中，每次进行更改时都要记住重新启动服务器会很麻烦，所以我想设置我的服务器端项目以自动重新启动代码更改。

为此，我们将向我们的项目添加watch-server npm脚本。
为此，请将以下内容添加到package.json的"scripts"部分：

"watch-server": "nodemon --watch 'src/***/*' -e ts,tsx --exec 'ts-node' ./src/server.ts"

现在开始新的TypeScript Koa项目，只需执行以下操作即可

npm run watch-server

您应该看到以下输出：

> xx@xx watch-server /Users/durban/nodejs/ts_node_koa_blog
> nodemon --watch 'src/***/*' -e ts,tsx --exec 'ts-node' ./src/server.ts

[nodemon] 1.18.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching: src/***/*
[nodemon] starting `ts-node ./src/server.ts`
Server running on port 8080

现在您应该能够在浏览器中访问http//localhost:8080/ :)

第四步、构建应用程序 - 添加中间件

主要的Koa库只包含基本的HTTP功能。
要构建完整的Web应用程序，我们需要添加适当的中间件，例如Logging, Error Handling, CSRF Protection等。在Koa中，中间件本质上是一堆函数，通过app.use()创建。
收到Web请求后，它将传递给堆栈中的第一个函数。
该函数可以处理请求，然后可选地将其传递给下一个中间件函数。
让我们将上面的示例扩展为包含一个中间件函数，该函数将每个Web请求的URL记录到控制台：

import * as Koa from 'koa';
import * as Router from "koa-router";

const app = new Koa();

app.use(async (ctx, next) => {
 // Log the request to the console
 console.log("Url: ", ctx.url);

 // Pass the request to the next middleware function
 await next();
})

const router = new Router();

router.get('/*', async (ctx) => {
 ctx.body = "Hi TS";
})

app.use(router.routes());

app.listen(8080);

console.log("Server running on port 8080");

在上面的示例中，我们现在定义两个中间件函数：

第一个中间件函数从请求上下文(ctx.url)获取Url，并使用console.log()将其输出到控制台
然后该函数await next()，告诉Koa将请求传递给堆栈中的下一个中间件函数
第二个中间件函数来自koa-router - 它使用请求的url来匹配我们通过router.get()配置的路由现在，当您在浏览器中访问http://localhost:8080/时，您应该看到类似于以下内容的输出：

> xx@xx watch-server /Users/durban/nodejs/ts_node_koa_blog
> nodemon --watch 'src/***/*' -e ts,tsx --exec 'ts-node' ./src/server.ts

[nodemon] 1.18.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching: src/***/*
[nodemon] starting `ts-node ./src/server.ts`
Server running on port 8080
Url: /
Url: /
Url: /blog
Url: /blog

第五步、标准中间件

显然，你真的不想为你的网络应用重新发明轮子。
根据您要创建的应用程序类型，以下中间件可能很有用：

Koa路由器
https://github.com/alexmingoia/koa-router

Koa Body Parser（用于JSON和Form Data支持）
https://github.com/dlau/koa-body

Koa Cross-Site-Request-Forgery（CSRF）预防
https://github.com/koajs/csrf

Koa Examples（许多有用的东西，包括错误处理）
https://github.com/koajs/examples

我已经创建了一个基本的TypeScript和Koa项目。可以进行后面自己感兴趣的开发了。

KoaJS 2 之 migration with knex

Thu, 03 Jul 2025 16:49:59 +0000

安装knexfile

npm install -g knex

然后在项目的根目录

knex init

将会产生knexfile.js,内容类似如下

// Update with your config settings.
module.exports = {
 development: {
 client: 'mysql',
 connection: {
 host: '127.0.0.1',
 user: 'root',
 password: '',
 database: '<YOUR TEST DB NAME>',
 charset: 'utf8'
 }
 },
 staging: {
 ...
 },
 production: {
 ...
 }
};

如果想要根据具体环境来执行具体配置，可以使用如下命令来指定环境

knex migrate:latest --env production

更多的使用可以参考Knex docs

创建Migration

knex migrate:make create_person

将会创建migrations目录并且将migration的文件放入文件夹中

默认的内容如下：

exports.up = function(knex, Promise){

}

exports.down = function(knex, Promise){

}

接下来我们在这里面实现具体的表信息

exports.up = function(knex, Promise){
 return Promise.all([
 knex.schema.createTable('person', function(table){
 table.increments('id').primary();
 table.integer('parentId').unsigned().references('id').inTable('person');
 table.string('firstName');
 table.string('fullName');
 table.integer('age');
 table.json('address');
 })
 ]);
}

exports.down = function(knex, Promise){
 return Promise.all([
 knex.schema.dropTable('person')
 ]);
}

当应用migration的时候up被调用，当执行回滚的时候down被调用

在这些功能中，你可以使用Knex Schema functions

执行如下命令来使用新的migration

knex migrate:latest

更新数据库表

knex migrate:make update_person

内容如下

exports.up = function(knex, Promise) {
 return Promise.all([
 knex.schema.table('person', function(table){
 table.string('twitter');
 })
 ])
}

exports.down = function(knex, Promise) {
 return Promise.all([
 knex.schema.table('person', function(table){
 table.dropColumn('twitter');
 })
 ]);
}

回滚操作

回滚操作执行下面的命令

knex migrate:rollback

knex对于创建跟修改表变得很容易。

KoaJS 实现文件下载很简单

Thu, 03 Jul 2025 11:58:13 +0000

Express框架下载文件的方法，我想已经有人已经知道了。

这里说下Koajs的方法。

首先设置Content-disposition

let filename = 'xxxx';
ctx.set('Content-disposition', 'attachment; filename=' + filename + '.pdf');//attachment

或者

ctx.set('Content-disposition', 'inline; filename=' + filename + '.pdf');//inline

以上两种的区别是一个是attachment，意思就是附件，还有一种是inline，意思就是内附。区别就是attachment打开的时候可以下载文件，inline有时候可以下载，有时候可以直接浏览，好像跟浏览器有关。

然后设置下文件类型

ctx.set('Content-type', 'application/pdf');

给body赋值，这里是一个Buffer。

然后把文件内容读出来

let gReadData = new Buffer();//这里自己根据自己的具体情况去实现就好了。

在函数最后

return ctx.body = gReadData;

整体代码大概如下：

module.exports.downloadPdf = async (ctx,next) => {
 let filename = 'xxxx';
 ctx.set('Content-disposition', 'attachment; filename=' + filename + '.pdf');
 ctx.set('Content-type', 'application/pdf');
 return ctx.body = gReadData;
}

Koa+React实现form表单上传文件

Wed, 02 Jul 2025 16:00:49 +0000

在nodejs里面通过html的表单上传图片，跟php比较起来还是麻烦一些，特别是在react中使用表单提交含有文件的数据。

最近也在做这个操作，找了很多资料，一直都是有个co-busboy这个，其实它也是基于busboy去封装的，不过这个更适合在koa里面使用。

以往的表单提交，我们用浏览器去debug的时候，会看到，提交了一个post提交的数据，这个一般只是值的提交，不包括有文件，但是在react中，

好像就更加复杂了一些，对于表单提交要单独自己写一个提交的事件去处理，累死submit这样的jquey函数。

而且提交成功后，我们用chrome去debug的时候，会发现提交的是一个Request Payload这样的，跟Form Data不一样，而且我们在koa中，

用body也是获取不到对应的值的，一切都是繁琐加着繁琐，自己考虑一下，像php这样的，是人家都帮你做好了，用起来很顺手，最终需要解决的就是，

如果把提交的data从header中去解析出来，其实busboy做的还是很好的。下面我大概说下我是如何去操作的。

web使用的jquery，通过FormData

在componentDidMount方法中初始化一下submit。

let handleAction = this.props.handleAction;
$("#BackgroundForm").submit(function(e){
 let formData = new FormData($(this)[0]);
 $.ajax({
 url:'/theapp/upload/background',
 data:formData,
 dataType:'json',
 type:'post',
 cache: false,
 contentType: false,
 processData: false,
 beforeSend:function(){
 $('#submitButton').attr('disabled',true);
 },
 success:function(data){
 if(data.success == true){
 handleAction(true);
 $('#errorContainer').html('').hide();
 }else if(data.success == false){
 let message = '<ul><li>'+data.message+'!</li></ul>';
 $('#errorContainer').html(message).show();
 $('#submitButton').attr('disabled',false);
 }
 },error:function(err){
 console.log(err);
 }
 });
 return false;
});

在server中的操作是这样的

const upload = function (ctx, key, streamName) {
 return new Promise(function (resolve, reject) {
 ctx.qiniuClient.upload(fs.createReadStream(streamName), key, function (err, result) {
 if (err) {
 return reject(err);
 }
 resolve(result);
 });
 });
};
theapp.post('/upload/background', co.wrap(function *(ctx, next) {
 let parts = parse(ctx.req);
 let part;
 //初始化数据
 let title = '';
 let theme = '';
 let theorder = '';
 let token = '';
 let big_url;
 let thumb_url;
 //获取form-data提交的数据
 while (part = yield parts) {
 if (Array.isArray(part)) {
 let name = part[0];
 let value = part[1];
 if (name == 'title') {
 title = value;
 }
 if (name == 'theme') {
 theme = value;
 }
 if (name == 'theorder') {
 theorder = value;
 }
 if (name == 'access_token') {
 token = value;
 }
 } else {
 let streamName = '/tmp/' + Math.random();
 let stream = fs.createWriteStream(streamName);
 part.pipe(stream);
 if (part.fieldname == 'big_url') {
 big_url = streamName;
 }
 if (part.fieldname == 'thumb_url') {
 thumb_url = streamName;
 }
 }
 }
 if (!big_url) {
 throw new Error('请上传背景大图');
 }
 if (!thumb_url) {
 throw new Error('请上传背景小图');
 }
 if (!title) {
 fs.unlinkSync(big_url);
 fs.unlinkSync(thumb_url);
 throw new Error('名称不能为空');
 }
 if (!theme) {
 fs.unlinkSync(big_url);
 fs.unlinkSync(thumb_url);
 throw new Error('主题不能为空');
 }
 if (!theorder) {
 theorder = 0;
 }
 //名称判断存在
 const url = ctx.config.hostDomain + '/admin/query';
 const sql = `SELECT * FROM qeeniao.app_dft_background WHERE title = '${title}'`;
 const options = {
 timeout: ctx.config.httpTimeout,
 method: 'POST',
 data: {'sql': sql, 'access_token': token}
 };
 const requestData = yield urllib.request(url, options);
 let data = requestData.data.toString();
 data = JSON.parse(data);
 if (data.length > 0) {
 fs.unlinkSync(big_url);
 fs.unlinkSync(thumb_url);
 throw new Error('名称已经存在');
 }
 //上传图片
 let big_res = yield upload(ctx, {
 'key': 'image/background/hd/' + title + '.jpg'
 }, big_url);
 big_url = big_res['url'];
 let thumb_res = yield upload(ctx, {
 'key': 'image/background/thumbnail/' + title + '.jpg'
 }, thumb_url);
 thumb_url = thumb_res['url'];
 //提交数据库
 let postData = {
 'title': title,
 'theme': theme,
 'theorder': theorder,
 'big_url': big_url,
 'thumb_url': thumb_url,
 'access_token': token
 };
 let postUrl = ctx.config.hostDomain + '/admin/add/background';
 let postoptions = {
 timeout: ctx.config.httpTimeout,
 method: 'POST',
 data: postData
 };
 let postRes = yield urllib.request(postUrl, postoptions);
 postRes = postRes.data.toString();
 postRes = JSON.parse(postRes);
 ctx.body = postRes;
}));

这里使用了一个qn的库

在启动的时候我把他加入了context中

app.context.qiniuClient = qn.create({
 accessKey: "Your accessKey",
 secretKey: "Your secretKey",
 bucket: "Your bucket",
 origin: 'Your origin'
});

这样处理起来就没问题了，其实要是如果koa把busboy自己封装起来是最好的。

KoaJS-2 实现验证码验证

Wed, 02 Jul 2025 16:00:26 +0000

首先安装验证码插件

这里推荐使用ccap，这个插件是我在寻找过程中，觉得能跟koa搭配比较好的一个插件，其他的要不就是需要express，要不就是需要安装其他一系列比较大的类库。

npm install ccap --save

如何使用？

const ccap = require('ccap')();
home.get('/home', (ctx, next) => {
 return next().then(() => {
 ctx.body = ctx.session.captcha;
 });
});
home.get('/captcha', (ctx, next) => {
 return next().then(() => {
 let ary = ccap.get();
 let txt = ary[0];
 let buf = ary[1];
 ctx.body = buf;
 ctx.type = 'image/png';
 ctx.session.captcha = txt;
 });
});

KoaJS 2.0.0 webpack 结合动态调试代码

Wed, 02 Jul 2025 15:39:52 +0000

koa2.0.0 的路由和视图渲染完之后的一个问题就是，如何高效的开发前端代码。

因为我之前的前端代码是用webpack进行打包，然后打包过程中，使用babel实现了，ES6语法的转换，这行我就不能太干脆的丢弃webpack，然后里面使用了react+react-router+reflux,整个开发体系还是比较可以的。为了整合之前的代码，需要将之前的connect框架改为koa2.0.0，毕竟koa的实现方式还有与express，connect等这样的框架，实现方式不太一样，所以，稍微还有有点小困难，不过我这里记录下，也就不困难了。

从webpack-dev-server说起，我们使用webpack-dev-server是为了能够时时监控我们的代码改变，然后用它自己的socket-io去刷新我们的页面，实现了代码修改即页面重载，当然只是在开发环境。

webpack-dev-server并没有多大的改变，只是将原来的一个proxy的操作去掉了，然后整合到koa的启动文件里面了。

const webpack = require('webpack');
const WebpackDevServer = require('webpack-dev-server');
const config = require('./webpack.config.development');
const debug = require('debug');
new WebpackDevServer(webpack(config), {
 publicPath: config.output.publicPath,
 hot: true,
 noInfo: false,
 historyApiFallback: true,
 stats: { colors: true },
 headers: { 'Access-Control-Allow-Origin': '*' }
}).listen(8080, '127.0.0.1', function(err,result) {
 if (err) {
 console.log(err);
 }
 console.log('Webpack Listening at 127.0.0.1:8080');
});

关于webpack的config文件的代码是不需要改变的，继续使用。

下面就是在koa的启动文件里面加入启动需要的proxy处理。

//解析 开发环境 development
app.use(convert(proxy({
 host:'http://127.0.0.1:8080/js',
 match: /^\/js\//
})));

就这么简单，这里使用了两个中间件：

koa-proxy，koa-convert。

解释一下好了，就是将访问的path中有带/js/部分的路径，进行重新proxy一下就好，这样就将文件转向到了webpack-dev-server这边的对应的文件了。相关的其他的问题可以参考我之前的几篇文章.

KoaJS 2.0.0 表单提交

Wed, 02 Jul 2025 11:31:55 +0000

对于koa2.0.0的表单提交如何处理，也是费了我很久的时间，在多次尝试与研究之下，可以这样来处理：

proxy.post('/admin/:path', (ctx, next) => {
 const url = ctx.config.hostDomain + '/admin/' +ctx.params.path;
 const options = {
 timeout: ctx.config.httpTimeout,
 method: ctx.request.method,
 headers: ctx.request.headers,
 data: ctx.request.body
 };
 return next().then(() => {
 const request = urllib.request(url, options);
 return request.then( (data) => {
 ctx.body = data.data.toString()
 });
 }).catch((err) => {
 console.log(err);
 });
});

我这里只是做了一个接口的调用，其实最重要的是在获得request后如何去进行对应的promise的操作和获取结果，这里其实很简单的：

return next().then(() => {
 const request = urllib.request(url, options);
 return request.then( (data) => {
 ctx.body = data.data.toString()
 });
}).catch((err) => {
 console.log(err);
});

注意这里的两个return操作，做完request的操作后，直接在开头进行一个return操作就可以了，这样body的值也回调过去了。

KoaJS 2.0.0的测试版本-视图渲染、静态文件调用的配置

Wed, 02 Jul 2025 11:31:52 +0000

针对koa2.0.0的测试版本，在使用的过程中遇到了很多的问题，这篇文章讲解一下如何进行操作html的调用和静态文件的调用

因为koa2.0.0版本的升级，很多的中间件都没有跟随着一起调整，所以有些中间件就出现了很多问题，这里说的就是针对试图文件的调用渲染和静态文件的调用

视图文件的调用使用的是如下的中间件：koa-swig

安装koa-swig:

cnpm install koa-swig --save

配置如下：

app.context.render = co.wrap(render({
 root: path.join(__dirname, 'dest'),
 autoescape: true,
 cache: 'memory', // disable, set to false 
 ext: 'html'
}));

路由中调用的方式如下：

router.get('/home', (ctx, next) => {
 return next().then(() => {
 ctx.render('index.html');
 });
});

这里到这里就解决了视图调用的问题，访问的时候如果页面中调用的是本地的js或者css的话，会包404的错误，就是找不到对应的路由，OK，下面记录下。

这里调用得了两个中间件:koa-convert,koa-static

const convert = require('koa-convert');
const serve = require('koa-static');

安装这两个中间件：

cnpm install koa-static koa-convert --save

对应的配置如下：

app.use(convert(serve(__dirname + '/dest')));

这里就是很简单了，刚开始的时候是无效的，后来在github上问了一下，就找打了解决办法。可以到这里看下：https://github.com/koajs/static/issues/59

好了，到这里两个部分的操作就完成了。

KoaJS 2.0.0 与 Router整合

Wed, 02 Jul 2025 11:31:43 +0000

最近koajs更新了一个很重要的版本，就是2.0.0,虽然这个版本是一个还在开发中的版本，但是已经可以下载使用了，当然，我用来下，唉，遗憾的是，虽然koa更新了，但是对应的中间插件并没有更新，这个是为什么呢，其他中间件的人不积极呗，只能试用了下，最重要的一个就是，Router这个中间件，既然也没有更新，不兼容最新版本的koa，好吧，还有在issue中发现了两点，已经有人根据koa-router，自己写了一个koa-66,使用完还不错，下面正式记录一下：

安装 koa@2.0.0-alpha.2

cnpm install koa@2.0.0-alpha.2 --save

安装koa-66

cnpm install koa-66 --save

安装完了看个示例吧,app.js代码如下

'use strict';
const Koa = require('koa');
const app = new Koa();
const co = require('co');
const Router = require('koa-66');
// const router = new Router();
const mountRouter = new Router();
const Controller = require('./router');
app.use((ctx, next) => {
 const start = new Date;
 return next().then(() => {
 const ms = new Date - start;
 console.log(`${ctx.method} ${ctx.url} - ${ms}`);
 });
});
// app.use((ctx) => {
// ctx.body = 'Hello World!';
// });
mountRouter.mount('/blog', Controller.router);
app.use(mountRouter.routes());
app.listen(3002);

router.js代码如下：

/**
 * Created by durban on 15/10/17.
 */
const Router = require('koa-66');
const router = new Router();
router.get('/home', (ctx, next) => {
 return next().then(() => {
 console.log(ctx);
 console.log(ctx.req);
 ctx.body = 'Router Hello World!';
 });
});
router.get('/views/:id', (ctx,next) => {
 return next().then(() => {
 console.log(ctx.params);
 ctx.body = 'views';
 });
});
router.get('/about', (ctx, next) => {
 return next().then(() => {
 ctx.body = 'about';
 });
});
module.exports.router = router;

好了，运行app.js,开始测试吧，终于搞定了router的代码不用跟app.js写在一起了。

当然这里的node版本是最新的版本v4.2.1。

KoaJS 异常处理全局统一处理

Tue, 01 Jul 2025 11:36:12 +0000

记录下koajs的异常使用:

下面介绍一下几个文件

test.js启动文件

router.js 路由文件

api/Admin.js 逻辑处理文件

koajs的异常处理逻辑代码如下[放在test.js 启动文件中]

/**
 * 统一处理默认Error
 */
app.use(function *(next) {
 try {
 yield next;
 } catch (err) {
 this.status = err.status;
 this.body = {
 name: "GowhichApiServerError",
 code: err.status || 600,
 message: err.message || "Server internal error.",
 success: false
 }
 }
});

600 :我自己定义的,为了区别系统的错误

接下来简单的看下路由:

router.post('/xxx/xxxxx', Admin.mailxxxxImport);
router.post('/xxxx/xxxx', Admin.mailxxxxBill);

这个router 我使用的是koa-router

好了, 到这里应该说一切都没问题了.下面就看我们如何出发这个错误了

那么在Admin.js里面我们写段代码:

module.exports.mailxxxxBill = function *(next){
 var uid = _uid(this.request);
 var taskid = this.request.body.taskid;

 if (!uid || !taskid) {
 return this.throw('任务参数不能为空');
 }
 
 //测试使用
 return this.throw('任务参数不能为空');
}

没错就是这句代码:

this.throw('任务参数不能为空');

当触发的时候,就会调用test.js的错误处理逻辑,可以了,动起来吧.