Skip to content

Latest commit

 

History

History
355 lines (267 loc) · 11.2 KB

router.md

File metadata and controls

355 lines (267 loc) · 11.2 KB
Raw

Router

Router is mainly used to describe the relationship between the request URL and the Controller that processes the request eventually. All routing rules are unified in the app/router.js file by the framework.

By unifying routing rules, routing logics are free from scatter that may cause unkown conflicts and it will be easier for us to check global routing rules.

We provide 2 ways to use router. One is auto router, another one is config router.

Auto router

Every page in /client folder will be routed automatically. For example, visit http://localhost:6001/page-a, /client/page-a.jsx will be rendered.

Client source Router Memo
client/index.jsx / Default router
client/index/index.jsx / Default router
client/a.jsx /a Auto router
client/a/index.jsx /a Auto router
client/a/b.jsx /a/b Auto router
client/a/b/index.jsx /a/b Auto router

PS. hot-loading is supported, suppose that a.jsx was added dynamically after the application started, then http://localhost:6001/a is available without restarting the application.

If auto router can't meet your needs, please follow the next steps to use config router.

How to Define Router

  • Define the routing rule in app/router.js file
// app/router.js
module.exports = app => {
  app.get('/user/:id', app.controller.user.info);
};
  • Implement the Controller in app/controller directory
// app/controller/user.js
exports.info = function* (ctx) {
  ctx.body = {
    name: `hello ${ctx.params.id}`,
  };
};

This simplest Router is done by now, when users do the request GET /user/123, the info function in user.js will be invoked.

Router config in detail

Below is the complete definition of router, parameters can be determined depending on different scenes.

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

The complete definition of router includes 5 major parts:

  • verb - actions that users trigger, including get, post and so on, and will be explained in detail later.
    • app.head - HEAD
    • app.options - OPTIONS
    • app.get - GET
    • app.put - PUT
    • app.post - POST
    • app.patch - PATCH
    • app.delete - DELETE
    • app.del - this is a alias method due to the reservation of delete.
    • app.redirect - redirects the request URL. For example, the most common case is to redirect the request accessing the root directory to the homepage.
  • router-name defines a alias for the route, and URL can be generated by helper method pathFor and urlFor provided by Helper. (Optional)
  • path-match - URL path of the route.
  • middleware1 - multiple Middleware can be configured in Router. (Optional)
  • controller - specific the controller of this router, this param can be tow types:
    • app.controller.user.fetch - directly point to a controller
    • 'user.fetch' - simplified as a string,

Notices

  • multiple Middlewares can be configured to execute serially in Router definition
  • Controller must be defined under app/controller directory
  • multiple Controllers can be defined within one file, and the specific one can be specified in the form of ${fileName}.${functionName} when defining the routing rule.
  • Controller supports sub-directories, and the specific one can be specified in the form of ${directoryName}.${fileName}.${functionName} when defining the routing rule.

Here are some examples of writing routing rules:

app.get('/home', app.controller.home);
app.get('/user/:id', app.controller.user.page);
app.post('/admin', isAdmin, app.controller.admin);
app.post('user', '/user', isLoginUser, hasAdminPermission, app.controller.user.create);
app.post('/api/v1/comments', app.controller.v1.comments.create); // app/controller/v1/comments.js

RESTful style URL definition

We provide app.resources('router-name', 'path-match', 'controller-name') to generate CRUD structures on a path for convenience if you prefer the RESTful style URL definition.

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

The codes above produces a bunch of CRUD path structures for Controller app/controller/posts.js, and the only thing you should do next is to implement related functions in 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 
// app/controller/posts.js
exports.index = function* () {};

exports.new = function* () {};

exports.create = function* () {};

exports.show = function* () {};

exports.edit = function* () {};

exports.update = function* () {};

exports.destroy = function* () {};

Methods that are not needed may not be implemented in posts.js and the related URL paths will not be registered to Router neither.

Router in Action

More practical examples will be shown below to demonstrate how to use the router.

Acquiring Parameters

via Query String

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

// app/controller/search.js
module.exports = function* (ctx) {
  ctx.body = `search: ${ctx.query.name}`;
};

// curl http://127.0.0.1:6001/search?name=beidou

via Named Parameters

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

// app/controller/user.js
exports.info = function* (ctx) {
  ctx.body = `user: ${ctx.params.id}, ${ctx.params.name}`;
};

// curl http://127.0.0.1:6001/user/123/somebody

acquiring complex parameters

Regular expressions, as well, can be used in routing rules to aquire parameters more flexibly:

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

// app/controller/package.js
exports.detail = function* (ctx) {
  // If the request URL is matched by the regular expression, parameters can be acquired from ctx.params according to the capture group orders.
  // For the user request below, for example, the value of `ctx.params[0]` is `beidou/1.0.0`
  ctx.body = `package:${ctx.params[0]}`;
};

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

Acquiring Form Contents

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

// app/controller/form.js
module.exports = function* (ctx) {
  ctx.body = `body: ${JSON.stringify(ctx.request.body)}`;
};

// simulate a post request.
// curl -X POST http://127.0.0.1:7001/form --data '{"name":"controller"}' --header 'Content-Type:application/json'

P.S.:

If you perform a POST request directly, an error will occur: 'secret is missing'. This error message comes from koa-csrf/index.js#L69.

Reason: the framework verifies the CSFR value specially for form POST requests, so please submit the CSRF key as well when you submit a form. For more detail refer to Keep Away from CSRF Threat

Note: the verification is performed because the framework builds in a security plugin egg-security that provides some default security practices and this plugin is enabled by default. In case you want to disable some security protections, just set the enable attribute to false.

"Unless you clearly confirm the consequence, it's not recommended to disable functions provided by the security plugin"

Here we do the config temporarily in config/config.default.js for an example

exports.security = {
  csrf: false
};

Form Verification

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

// app/controller/user.js
const createRule = {
  username: {
    type: 'email',
  },
  password: {
    type: 'password',
    compare: 're-password',
  },
};

exports.create = function* (ctx) {
  // throws exceptions if the verification fails
  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'

Redirection

Internal Redirection

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

// app/controller/home.js
exports.index = function* (ctx) {
  ctx.body = 'hello controller';
};

// curl -L http://localhost:7001

External Redirection

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

// app/controller/search.js
module.exports = function* (ctx) {
  const type = ctx.query.type;
  const q = ctx.query.q || 'nodejs';

  if (type === 'bing') {
    this.redirect(`http://cn.bing.com/search?q=${q}`);
  } else {
    this.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

Using Middleware

A middleware can be used to change the request parameter to uppercase. Here we just briefly explain how to use the middleware, and refer to Middleware for detail.

// app/controller/search.js
module.exports = function* (ctx) {
  ctx.body = `search: ${ctx.query.name}`;
};

// app/middleware/uppercase.js
module.exports = () => {
  return function* (next) {
    this.query.name = this.query.name && this.query.name.toUpperCase();
    yield next;
  };
};

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

// curl http://localhost:7001/search2?name=beidou

Too Many Routing Maps?

As described above, we do not recommend that you scatter routing logics all around, or it will bring trouble in trouble shooting.

If it is a must for some reasons, you can split routing rules like below:

// app/router.js
module.exports = app => {
  require('./router/news')(app);
  require('./router/admin')(app);
};

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

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