koa-router 8 升级迁移手册

在公司内有小伙伴用了 koa-router 8，但是我发现他的用法并不正确，没有注意到 breaking changes。于是翻译一波这个……

如果想要体验一下最新版本，只要 npm install koa-router@next 即可。

更新日志

7.x 中：

router.use('/nested/path', otherRouter.routes())
router.use('/users', userAuth());

8.x 的变更：

const router = new Router({prefix: '/nested/path'});
router.nest('/nested/path', otherRouter);

const router = new Router({prefix: '/users'});
router.use(userAuth());

7.x 中：

parentRouter.use(childRouter.routes());

8.x 的变更：

parentRouter.nest(childRouter);

// use -> nest
forums.use(posts.routes());

简言之，上面变成了下面这种形式：

forums.nest(posts);

在使用完 .routes() 之后在声明路由将不再适用。你必须在使用 .routes() 之前声明好路由。.routes() 是一个在那个时段的路由的快照。在使用完 .routes 后没有变更将会对上一个 routes() 调度产生影响。

app.use(router.routes());
router.post('/some-endpoint', () => {});

需要变更为：

router.post('/some-endpoint', () => {});
// 必须在 调用 .routes() 前注册路由!
app.use(router.routes());

.use() 不再支持路径前缀。取而代之的，嵌套一个路由。

const router = new Router();
router.use('/admin', authenticateAdmin);
router.get('/secrets', () => {});
app.use(router.routes());

变更为：

const secretsRouter = new Router();
const adminRouter = new Router();
secretsRouter.get('/secrets', () => {});
adminRouter.nest('/admin', secretsRouter);
app.use(adminRouter.routes());

调用 routes() 后对路由进行变更不会影响先前由 routes() 返回的中间件。

当路由嵌套时，仍然可对其进行更改。在路由或者任何祖先上调用 routes() 后，路由的更改将被忽略。

router.use('*', ...)

变更为：

router.use(...);

「按 URL 出现顺序运行参数中间件」变更为根据 param 调用的顺序。

router.get('users-index', '/users', () => { ... });
router.url('users-index', {}, { query: { page: 1 } });
// => /users?page=1

变更为：

router.get('users-index', '/users', () => { ... });
router.url('users-index', { page: 1 });
// => /users?page=1

重定向命名路由：

旧的页面的 GET 的处理程序因为首先被定义，所以它首先被匹配。在定义重定向时，她其实只是另一个符合匹配的处理程序。重定向你的处理程序，而不是重定向这种方法。

const router = create()
    .get('newpage', '/newpage', () => {})
    .get('oldpage', '/oldpage', () => {})
    .redirect('oldpage', 'newpage');

变更为：

const router = create()
    .get('newpage', '/newpage', () => {})
    .get('oldpage', '/oldpage', (ctx) => ctx.redirect(ctx.router.path('oldpage')));

参考资料：

• Upgrading from 7.x to 8