Router
Router is mainly used to describe the corresponding 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, we can avoid the routing logics scattered in many places which may cause many unknown conflicts, and we can more easily check global routing rules.
# How to Define Router
- Define the routing rule in
app/router.js
file
// app/router.js |
- Implement the Controller in
app/controller
directory
// app/controller/user.js |
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.
router.verb('path-match', app.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.
- router.head - HEAD
- router.options - OPTIONS
- router.get - GET
- router.put - PUT
- router.post - POST
- router.patch - PATCH
- router.delete - DELETE
- router.del - this is a alias method due to the reservation of delete.
- router.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
andurlFor
provided by Helper. (Optional) - path-match - URL path of the route.
- middleware1 - multiple Middlewares can be configured in Router. (Optional)
- controller - set the route to map to the specific controller, and the controller can be written in two 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/router.js |
# RESTful Style URL Definition
We provide app.router.resources('routerName', 'pathMatch', 'controller')
to generate CRUD structures on a path for convenience if you prefer the RESTful style URL definition.
// app/router.js |
The codes above produce 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 |
PATCH | /posts/:id | post | app.controllers.posts.update |
DELETE | /posts/:id | post | app.controllers.posts.destroy |
// app/controller/posts.js |
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 |
# Via Named Parameters
// app/router.js |
# Acquiring Complex Parameters
Regular expressions, as well, can be used in routing rules to acquire parameters more flexibly:
// app/router.js |
# Acquiring Form Contents
// app/router.js |
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. Refer to Keep Away from CSRF Threat for more detail.
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 = { |
# Form Verification
// app/router.js |
# Redirection
# Internal Redirection
// app/router.js |
# External Redirection
// app/router.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 |
# 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 there is a need for some reasons, you can split routing rules like below:
// app/router.js |
or using egg-router-plus.