Skip to content

Commit

Permalink
docs: how to customize error handler (#1651)
Browse files Browse the repository at this point in the history
  • Loading branch information
dead-horse authored Nov 13, 2017
1 parent 858c110 commit 8c6f16d
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 63 deletions.
57 changes: 25 additions & 32 deletions docs/source/en/core/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ For convenience of locating problems, exceptions must be guaranteed to be Error
| HTML & TEXT | local & unittest | - | onerror built-in error page |
| HTML & TEXT | others | YES | redirect to errorPageUrl |
| HTML & TEXT | others | NO | onerror built-in error page(simple, not recommended) |
| JSON | local & unittest | - | JSON Object with details |
| JSON | others | - | JSON object without details |
| JSON & JSONP | local & unittest | - | JSON Object or JSONP response body with details |
| JSON & JSONP| others | - | JSON object or JSONP response body without details |

### errorPageUrl

Expand All @@ -78,38 +78,31 @@ module.exports = {

## Create your universal exception handler

Once the default handler no longer meet your needs, you still can leverage Middleware to create a new handler.

As following implementation, you can create a new file in `app/middleware`, for example `error_handler.js`:

```js
// app/middleware/error_handler.js
module.exports = () => {
return function* errorHandler(next) {
try {
yield next;
} catch (err) {
// `app.emit('error', err, this)` should be invoked after exceptions are caught
// Exceptions will be caught and printed out.
this.app.emit('error', err, this);
// Composing the object in handler when exceptions are thrown
this.body = {
success: false,
message: this.app.config.env === 'prod' ? 'Internal Server Error' : err.message,
};
}
};
};
```

Adding your customized `error_handler` in `config/config.default.js`:
Once the default handler no longer meet your needs, you still can customize your owner error handler by onerror's configurations.

```js
// config/config.default.js
module.exports = {
middleware: [ 'errorHandler' ],
errorHandler: {
// errorHandler only handle exceptions from requests under /api/, and onerror will do the same things for the rest.
match: '/api',
onerror: {
all(err, ctx) {
// Define an error handler for all type of Response.
// Once config.all present, other type of error handers will be ignored.
this.body = 'error';
this.status = 500;
},
html(err, ctx) {
// html hander
this.body = '<h3>error</h3>';
this.status = 500;
},
json(err, ctx) {
// json hander
this.body = { message: 'error' };
this.status = 500;
},
jsonp(err, ctx) {
// Generally, we don't need to customize jsonp error handler.
// It will call json error handler and wrap to jsonp type response.
},
};
```
Expand Down Expand Up @@ -167,4 +160,4 @@ Adding yours to `middleware` in config:
module.exports = {
middleware: [ 'notfoundHander' ],
};
```
```
55 changes: 24 additions & 31 deletions docs/source/zh-cn/core/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ exports.buy = function* (ctx) {
| HTML & TEXT | local & unittest | - | onerror 自带的错误页面,展示详细的错误信息 |
| HTML & TEXT | 其他 || 重定向到 errorPageUrl |
| HTML & TEXT | 其他 || onerror 自带的没有错误信息的简单错误页(不推荐) |
| JSON | local & unittest | - | JSON 对象,带详细的错误信息 |
| JSON | 其他 | - | json 对象,不带详细的错误信息 |
| JSON & JSONP | local & unittest | - | JSON 对象或对应的 JSONP 格式响应,带详细的错误信息 |
| JSON & JSONP | 其他 | - | JSON 对象或对应的 JSONP 格式响应,不带详细的错误信息 |

### errorPageUrl

Expand All @@ -79,38 +79,31 @@ module.exports = {

## 自定义统一异常处理

尽管框架提供了默认的统一异常处理机制,但是应用开发中经常需要对异常时的响应做自定义,特别是在做一些接口开发的时候。这时我们可以通过自定义[中间件](../basics/middleware.md)的方式来自行定义统一的异常处理函数。

例如我们可以在 `app/middleware` 中新增一个 `error_handler.js` 的文件

```js
// app/middleware/error_handler.js
module.exports = () => {
return function* errorHandler(next) {
try {
yield next;
} catch (err) {
// 注意:自定义的错误统一处理函数捕捉到错误后也要 `app.emit('error', err, this)`
// 框架会统一监听,并打印对应的错误日志
this.app.emit('error', err, this);
// 自定义错误时异常返回的格式
this.body = {
success: false,
message: this.app.config.env === 'prod' ? 'Internal Server Error' : err.message,
};
}
};
};
```

然后在 `config/config.default.js` 中引入这个中间件
尽管框架提供了默认的统一异常处理机制,但是应用开发中经常需要对异常时的响应做自定义,特别是在做一些接口开发的时候。框架自带的 onerror 插件支持自定义配置错误处理方法,可以覆盖默认的错误处理方法。

```js
// config/config.default.js
module.exports = {
middleware: [ 'errorHandler' ],
errorHandler: {
// 非 `/api/` 路径不在这里做错误处理,留给默认的 onerror 插件统一处理
match: '/api',
onerror: {
all(err, ctx) {
// 在此处定义针对所有响应类型的错误处理方法
// 注意,定义了 config.all 之后,其他错误处理方法不会再生效
this.body = 'error';
this.status = 500;
},
html(err, ctx) {
// html hander
this.body = '<h3>error</h3>';
this.status = 500;
},
json(err, ctx) {
// json hander
this.body = { message: 'error' };
this.status = 500;
},
jsonp(err, ctx) {
// 一般来说,不需要特殊针对 jsonp 进行错误定义,jsonp 的错误处理会自动调用 json 错误处理,并包装成 jsonp 的响应格式
},
},
};
```
Expand Down

0 comments on commit 8c6f16d

Please sign in to comment.