Egg 路由（Router）

Router 主要用來(lái)描述請(qǐng)求 URL 和具體承擔(dān)執(zhí)行動(dòng)作的 Controller 的對(duì)應(yīng)關(guān)系， 框架約定了 app/router.js 文件用于統(tǒng)一所有路由規(guī)則。

通過(guò)統(tǒng)一的配置，我們可以避免路由規(guī)則邏輯散落在多個(gè)地方，從而出現(xiàn)未知的沖突，集中在一起我們可以更方便的來(lái)查看全局的路由規(guī)則。

如何定義 Router

• app/router.js 里面定義 URL 路由規(guī)則

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('/user/:id', controller.user.info);
};

• app/controller 目錄下面實(shí)現(xiàn) Controller

// app/controller/user.js
class UserController extends Controller {
  async info() {
    const { ctx } = this;
    ctx.body = {
      name: `hello ${ctx.params.id}`,
    };
  }
}

這樣就完成了一個(gè)最簡(jiǎn)單的 Router 定義，當(dāng)用戶執(zhí)行 GET /user/123，user.js 這個(gè)里面的 info 方法就會(huì)執(zhí)行。

Router 詳細(xì)定義說(shuō)明

下面是路由的完整定義，參數(shù)可以根據(jù)場(chǎng)景的不同，自由選擇：

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

路由完整定義主要包括5個(gè)主要部分:

• verb - 用戶觸發(fā)動(dòng)作，支持 get，post 等所有 HTTP 方法，后面會(huì)通過(guò)示例詳細(xì)說(shuō)明。router.head - HEADrouter.options - OPTIONSrouter.get - GETrouter.put - PUTrouter.post - POSTrouter.patch - PATCHrouter.delete - DELETErouter.del - 由于 delete 是一個(gè)保留字，所以提供了一個(gè) delete 方法的別名。router.redirect - 可以對(duì) URL 進(jìn)行重定向處理，比如我們最經(jīng)常使用的可以把用戶訪問(wèn)的根目錄路由到某個(gè)主頁(yè)。
• router-name 給路由設(shè)定一個(gè)別名，可以通過(guò) Helper 提供的輔助函數(shù) pathFor 和 urlFor 來(lái)生成 URL。(可選)
• path-match - 路由 URL 路徑。
• middleware1 - 在 Router 里面可以配置多個(gè) Middleware。(可選)
• controller - 指定路由映射到的具體的 controller 上，controller 可以有兩種寫(xiě)法：app.controller.user.fetch - 直接指定一個(gè)具體的 controller'user.fetch' - 可以簡(jiǎn)寫(xiě)為字符串形式

注意事項(xiàng)

• 在 Router 定義中， 可以支持多個(gè) Middleware 串聯(lián)執(zhí)行
• Controller 必須定義在 app/controller 目錄中。
• 一個(gè)文件里面也可以包含多個(gè) Controller 定義，在定義路由的時(shí)候，可以通過(guò) ${fileName}.${functionName} 的方式指定對(duì)應(yīng)的 Controller。
• Controller 支持子目錄，在定義路由的時(shí)候，可以通過(guò) ${directoryName}.${fileName}.${functionName} 的方式制定對(duì)應(yīng)的 Controller。

下面是一些路由定義的方式：

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('/home', controller.home);
  router.get('/user/:id', controller.user.page);
  router.post('/admin', isAdmin, controller.admin);
  router.post('/user', isLoginUser, hasAdminPermission, controller.user.create);
  router.post('/api/v1/comments', controller.v1.comments.create); // app/controller/v1/comments.js
};

RESTful 風(fēng)格的 URL 定義

如果想通過(guò) RESTful 的方式來(lái)定義路由， 我們提供了 app.resources('routerName', 'pathMatch', controller) 快速在一個(gè)路徑上生成 CRUD 路由結(jié)構(gòu)。

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.resources('posts', '/api/posts', controller.posts);
  router.resources('users', '/api/v1/users', controller.v1.users); // app/controller/v1/users.js
};

上面代碼就在 /posts 路徑上部署了一組 CRUD 路徑結(jié)構(gòu)，對(duì)應(yīng)的 Controller 為 app/controller/posts.js 接下來(lái)， 你只需要在 posts.js 里面實(shí)現(xiàn)對(duì)應(yīng)的函數(shù)就可以了。

// app/controller/posts.js
exports.index = async () => {};

exports.new = async () => {};

exports.create = async () => {};

exports.show = async () => {};

exports.edit = async () => {};

exports.update = async () => {};

exports.destroy = async () => {};

如果我們不需要其中的某幾個(gè)方法，可以不用在 posts.js 里面實(shí)現(xiàn)，這樣對(duì)應(yīng) URL 路徑也不會(huì)注冊(cè)到 Router。

router 實(shí)戰(zhàn)

下面通過(guò)更多實(shí)際的例子，來(lái)說(shuō)明 router 的用法。

參數(shù)獲取

Query String 方式

// app/router.js
module.exports = app => {
  app.router.get('/search', app.controller.search.index);
};

// app/controller/search.js
exports.index = async ctx => {
  ctx.body = `search: ${ctx.query.name}`;
};

// curl http://127.0.0.1:7001/search?name=egg

參數(shù)命名方式

// app/router.js
module.exports = app => {
  app.router.get('/user/:id/:name', app.controller.user.info);
};

// app/controller/user.js
exports.info = async ctx => {
  ctx.body = `user: ${ctx.params.id}, ${ctx.params.name}`;
};

// curl http://127.0.0.1:7001/user/123/xiaoming

復(fù)雜參數(shù)的獲取

路由里面也支持定義正則，可以更加靈活的獲取參數(shù)：

// app/router.js
module.exports = app => {
  app.router.get(/^\/package\/([\w-.]+\/[\w-.]+)$/, app.controller.package.detail);
};

// app/controller/package.js
exports.detail = async ctx => {
  // 如果請(qǐng)求 URL 被正則匹配， 可以按照捕獲分組的順序，從 ctx.params 中獲取。
  // 按照下面的用戶請(qǐng)求，`ctx.params[0]` 的 內(nèi)容就是 `egg/1.0.0`
  ctx.body = `package:${ctx.params[0]}`;
};

// curl http://127.0.0.1:7001/package/egg/1.0.0

表單內(nèi)容的獲取

// app/router.js
module.exports = app => {
  app.router.post('/form', app.controller.form.post);
};

// app/controller/form.js
exports.post = async ctx => {
  ctx.body = `body: ${JSON.stringify(ctx.request.body)}`;
};

// 模擬發(fā)起 post 請(qǐng)求。
// curl -X POST http://127.0.0.1:7001/form --data '{"name":"controller"}' --header 'Content-Type:application/json'

附：

這里直接發(fā)起 POST 請(qǐng)求會(huì)報(bào)錯(cuò)：'secret is missing'。錯(cuò)誤信息來(lái)自 koa-csrf/index.js#L69 。

原因：框架內(nèi)部針對(duì)表單 POST 請(qǐng)求均會(huì)驗(yàn)證 CSRF 的值，因此我們?cè)诒韱翁峤粫r(shí)，請(qǐng)帶上 CSRF key 進(jìn)行提交，可參考安全威脅csrf的防范

注意：上面的校驗(yàn)是因?yàn)榭蚣苤袃?nèi)置了安全插件 egg-security，提供了一些默認(rèn)的安全實(shí)踐，并且框架的安全插件是默認(rèn)開(kāi)啟的，如果需要關(guān)閉其中一些安全防范，直接設(shè)置該項(xiàng)的 enable 屬性為 false 即可。

「除非清楚的確認(rèn)后果，否則不建議擅自關(guān)閉安全插件提供的功能?！?/blockquote>

這里在寫(xiě)例子的話可臨時(shí)在 config/config.default.js 中設(shè)置

exports.security = { csrf: false };

表單校驗(yàn)

// app/router.js module.exports = app => { app.router.post('/user', app.controller.user); }; // app/controller/user.js const createRule = { username: { type: 'email', }, password: { type: 'password', compare: 're-password', }, }; exports.create = async ctx => { // 如果校驗(yàn)報(bào)錯(cuò)，會(huì)拋出異常 ctx.validate(createRule); ctx.body = ctx.request.body; }; // curl -X POST http://127.0.0.1:7001/user --data 'username=abc@abc.com&password=111111&re-password=111111'

重定向

內(nèi)部重定向

// app/router.js module.exports = app => { app.router.get('index', '/home/index', app.controller.home.index); app.router.redirect('/', '/home/index', 302); }; // app/controller/home.js exports.index = async ctx => { ctx.body = 'hello controller'; }; // curl -L http://localhost:7001

外部重定向

// app/router.js module.exports = app => { app.router.get('/search', app.controller.search.index); }; // app/controller/search.js exports.index = async ctx => { const type = ctx.query.type; const q = ctx.query.q || 'nodejs'; if (type === 'bing') { ctx.redirect(`http://cn.bing.com/search?q=${q}`); } else { ctx.redirect(`https://www.google.co.kr/search?q=${q}`); } }; // curl http://localhost:7001/search?type=bing&q=node.js // curl http://localhost:7001/search?q=node.js

中間件的使用

如果我們想把用戶某一類請(qǐng)求的參數(shù)都大寫(xiě)，可以通過(guò)中間件來(lái)實(shí)現(xiàn)。 這里我們只是簡(jiǎn)單說(shuō)明下如何使用中間件，更多請(qǐng)查看 中間件。

// app/controller/search.js exports.index = async ctx => { ctx.body = `search: ${ctx.query.name}`; }; // app/middleware/uppercase.js module.exports = () => { return async function uppercase(ctx, next) { ctx.query.name = ctx.query.name && ctx.query.name.toUpperCase(); await next(); }; }; // app/router.js module.exports = app => { app.router.get('s', '/search', app.middleware.uppercase(), app.controller.search) }; // curl http://localhost:7001/search?name=egg

太多路由映射？

如上所述，我們并不建議把路由規(guī)則邏輯散落在多個(gè)地方，會(huì)給排查問(wèn)題帶來(lái)困擾。

若確實(shí)有需求，可以如下拆分：

// app/router.js module.exports = app => { require('./router/news')(app); require('./router/admin')(app); }; // app/router/news.js module.exports = app => { app.router.get('/news/list', app.controller.news.list); app.router.get('/news/detail', app.controller.news.detail); }; // app/router/admin.js module.exports = app => { app.router.get('/admin/user', app.controller.admin.user); app.router.get('/admin/log', app.controller.admin.log); };

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