• 路由(Router)
  • 如何定义 Router
  • Router 详细定义说明
    • 注意事项
    • RESTful 风格的 URL 定义
  • router 实战
    • 参数获取
      • Query String 方式
      • 参数命名方式
      • 复杂参数的获取
    • 表单内容的获取
    • 表单校验
    • 重定向
      • 内部重定向
      • 外部重定向
    • 中间件的使用
    • 太多路由映射?

    路由(Router)

    Router 主要用来描述请求 URL 和具体承担执行动作的 Controller 的对应关系,框架约定了 app/router.js 文件用于统一所有路由规则。

    通过统一的配置,我们可以避免路由规则逻辑散落在多个地方,从而出现未知的冲突,集中在一起我们可以更方便的来查看全局的路由规则。

    如何定义 Router

    • app/router.js 里面定义 URL 路由规则
    1. // app/router.js
    2. module.exports = app => {
    3. const { router, controller } = app;
    4. router.get('/user/:id', controller.user.info);
    5. };
    • app/controller 目录下面实现 Controller
    1. // app/controller/user.js
    2. class UserController extends Controller {
    3. async info() {
    4. const { ctx } = this;
    5. ctx.body = {
    6. name: `hello ${ctx.params.id}`,
    7. };
    8. }
    9. }

    这样就完成了一个最简单的 Router 定义,当用户执行 GET /user/123user.js 这个里面的 info 方法就会执行。

    Router 详细定义说明

    下面是路由的完整定义,参数可以根据场景的不同,自由选择:

    1. router.verb('path-match', app.controller.action);
    2. router.verb('router-name', 'path-match', app.controller.action);
    3. router.verb('path-match', middleware1, ..., middlewareN, app.controller.action);
    4. router.verb('router-name', 'path-match', middleware1, ..., middlewareN, app.controller.action);

    路由完整定义主要包括5个主要部分:

    • verb - 用户触发动作,支持 get,post 等所有 HTTP 方法,后面会通过示例详细说明。
      • router.head - HEAD
      • router.options - OPTIONS
      • router.get - GET
      • router.put - PUT
      • router.post - POST
      • router.patch - PATCH
      • router.delete - DELETE
      • router.del - 由于 delete 是一个保留字,所以提供了一个 delete 方法的别名。
      • router.redirect - 可以对 URL 进行重定向处理,比如我们最经常使用的可以把用户访问的根目录路由到某个主页。
    • router-name 给路由设定一个别名,可以通过 Helper 提供的辅助函数 pathForurlFor 来生成 URL。(可选)
    • path-match - 路由 URL 路径。
    • middleware1 - 在 Router 里面可以配置多个 Middleware。(可选)
    • controller - 指定路由映射到的具体的 controller 上,controller 可以有两种写法:
      • app.controller.user.fetch - 直接指定一个具体的 controller
      • 'user.fetch' - 可以简写为字符串形式

    注意事项

    • 在 Router 定义中, 可以支持多个 Middleware 串联执行
    • Controller 必须定义在 app/controller 目录中。
    • 一个文件里面也可以包含多个 Controller 定义,在定义路由的时候,可以通过 ${fileName}.${functionName} 的方式指定对应的 Controller。
    • Controller 支持子目录,在定义路由的时候,可以通过 ${directoryName}.${fileName}.${functionName} 的方式制定对应的 Controller。

    下面是一些路由定义的方式:

    1. // app/router.js
    2. module.exports = app => {
    3. const { router, controller } = app;
    4. router.get('/home', controller.home);
    5. router.get('/user/:id', controller.user.page);
    6. router.post('/admin', isAdmin, controller.admin);
    7. router.post('/user', isLoginUser, hasAdminPermission, controller.user.create);
    8. router.post('/api/v1/comments', controller.v1.comments.create); // app/controller/v1/comments.js
    9. };

    RESTful 风格的 URL 定义

    如果想通过 RESTful 的方式来定义路由,我们提供了 app.resources('routerName', 'pathMatch', controller) 快速在一个路径上生成 CRUD 路由结构。

    1. // app/router.js
    2. module.exports = app => {
    3. const { router, controller } = app;
    4. router.resources('posts', '/api/posts', controller.posts);
    5. router.resources('users', '/api/v1/users', controller.v1.users); // app/controller/v1/users.js
    6. };

    上面代码就在 /posts 路径上部署了一组 CRUD 路径结构,对应的 Controller 为 app/controller/posts.js 接下来,你只需要在 posts.js 里面实现对应的函数就可以了。

    Method Path Route Name Controller.Action
    GET /posts posts app.controllers.posts.index
    GET /posts/new new_post app.controllers.posts.new
    GET /posts/:id post app.controllers.posts.show
    GET /posts/:id/edit edit_post app.controllers.posts.edit
    POST /posts posts app.controllers.posts.create
    PUT /posts/:id post app.controllers.posts.update
    DELETE /posts/:id post app.controllers.posts.destroy
    1. // app/controller/posts.js
    2. exports.index = async () => {};
    3. exports.new = async () => {};
    4. exports.create = async () => {};
    5. exports.show = async () => {};
    6. exports.edit = async () => {};
    7. exports.update = async () => {};
    8. exports.destroy = async () => {};

    如果我们不需要其中的某几个方法,可以不用在 posts.js 里面实现,这样对应 URL 路径也不会注册到 Router。

    router 实战

    下面通过更多实际的例子,来说明 router 的用法。

    参数获取

    Query String 方式

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.get('/search', app.controller.search.index);
    4. };
    5. // app/controller/search.js
    6. exports.index = async ctx => {
    7. ctx.body = `search: ${ctx.query.name}`;
    8. };
    9. // curl http://127.0.0.1:7001/search?name=egg

    参数命名方式

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.get('/user/:id/:name', app.controller.user.info);
    4. };
    5. // app/controller/user.js
    6. exports.info = async ctx => {
    7. ctx.body = `user: ${ctx.params.id}, ${ctx.params.name}`;
    8. };
    9. // curl http://127.0.0.1:7001/user/123/xiaoming

    复杂参数的获取

    路由里面也支持定义正则,可以更加灵活的获取参数:

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.get(/^\/package\/([\w-.]+\/[\w-.]+)$/, app.controller.package.detail);
    4. };
    5. // app/controller/package.js
    6. exports.detail = async ctx => {
    7. // 如果请求 URL 被正则匹配, 可以按照捕获分组的顺序,从 ctx.params 中获取。
    8. // 按照下面的用户请求,`ctx.params[0]` 的 内容就是 `egg/1.0.0`
    9. ctx.body = `package:${ctx.params[0]}`;
    10. };
    11. // curl http://127.0.0.1:7001/package/egg/1.0.0

    表单内容的获取

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.post('/form', app.controller.form.post);
    4. };
    5. // app/controller/form.js
    6. exports.post = async ctx => {
    7. ctx.body = `body: ${JSON.stringify(ctx.request.body)}`;
    8. };
    9. // 模拟发起 post 请求。
    10. // curl -X POST http://127.0.0.1:7001/form --data '{"name":"controller"}' --header 'Content-Type:application/json'

    附:

    这里直接发起 POST 请求会报错:’secret is missing’。错误信息来自 koa-csrf/index.js#L69 。

    原因:框架内部针对表单 POST 请求均会验证 CSRF 的值,因此我们在表单提交时,请带上 CSRF key 进行提交,可参考安全威胁csrf的防范

    注意:上面的校验是因为框架中内置了安全插件 egg-security,提供了一些默认的安全实践,并且框架的安全插件是默认开启的,如果需要关闭其中一些安全防范,直接设置该项的 enable 属性为 false 即可。

    「除非清楚的确认后果,否则不建议擅自关闭安全插件提供的功能。」

    这里在写例子的话可临时在 config/config.default.js 中设置

    1. exports.security = {
    2. csrf: false
    3. };

    表单校验

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.post('/user', app.controller.user);
    4. };
    5. // app/controller/user.js
    6. const createRule = {
    7. username: {
    8. type: 'email',
    9. },
    10. password: {
    11. type: 'password',
    12. compare: 're-password',
    13. },
    14. };
    15. exports.create = async ctx => {
    16. // 如果校验报错,会抛出异常
    17. ctx.validate(createRule);
    18. ctx.body = ctx.request.body;
    19. };
    20. // curl -X POST http://127.0.0.1:7001/user --data 'username=abc@abc.com&password=111111&re-password=111111'

    重定向

    内部重定向

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.get('index', '/home/index', app.controller.home.index);
    4. app.router.redirect('/', '/home/index', 302);
    5. };
    6. // app/controller/home.js
    7. exports.index = async ctx => {
    8. ctx.body = 'hello controller';
    9. };
    10. // curl -L http://localhost:7001

    外部重定向

    1. // app/router.js
    2. module.exports = app => {
    3. app.router.get('/search', app.controller.search.index);
    4. };
    5. // app/controller/search.js
    6. exports.index = async ctx => {
    7. const type = ctx.query.type;
    8. const q = ctx.query.q || 'nodejs';
    9. if (type === 'bing') {
    10. ctx.redirect(`http://cn.bing.com/search?q=${q}`);
    11. } else {
    12. ctx.redirect(`https://www.google.co.kr/search?q=${q}`);
    13. }
    14. };
    15. // curl http://localhost:7001/search?type=bing&q=node.js
    16. // curl http://localhost:7001/search?q=node.js

    中间件的使用

    如果我们想把用户某一类请求的参数都大写,可以通过中间件来实现。这里我们只是简单说明下如何使用中间件,更多请查看 中间件。

    1. // app/controller/search.js
    2. exports.index = async ctx => {
    3. ctx.body = `search: ${ctx.query.name}`;
    4. };
    5. // app/middleware/uppercase.js
    6. module.exports = () => {
    7. return async function uppercase(ctx, next) {
    8. ctx.query.name = ctx.query.name && ctx.query.name.toUpperCase();
    9. await next();
    10. };
    11. };
    12. // app/router.js
    13. module.exports = app => {
    14. app.router.get('s', '/search', app.middlewares.uppercase(), app.controller.search)
    15. };
    16. // curl http://localhost:7001/search?name=egg

    太多路由映射?

    如上所述,我们并不建议把路由规则逻辑散落在多个地方,会给排查问题带来困扰。

    若确实有需求,可以如下拆分:

    1. // app/router.js
    2. module.exports = app => {
    3. require('./router/news')(app);
    4. require('./router/admin')(app);
    5. };
    6. // app/router/news.js
    7. module.exports = app => {
    8. app.router.get('/news/list', app.controller.news.list);
    9. app.router.get('/news/detail', app.controller.news.detail);
    10. };
    11. // app/router/admin.js
    12. module.exports = app => {
    13. app.router.get('/admin/user', app.controller.admin.user);
    14. app.router.get('/admin/log', app.controller.admin.log);
    15. };

    也可直接使用 egg-router-plus。