egg-errors
Errors for Egg.js
egg-errors provide two kinds of errors that is Error and Exception.
Exception is system error that egg will log an error and throw exception, but it will be catched by onerror plugin.
Error is business error that egg will transform it to response.
Install
$ npm i egg-errors --save copy
Usage
Create an Error
const { EggError, EggException } = require ( 'egg-errors' );
let err = new EggError ( 'egg error' );
console. log (EggError. getType (err)); // ERROR copy
Create an Exception
err = new EggException ( 'egg exception' );
console. log (EggException. getType (err)); // EXCEPTION copy
You can import an error from an normal error object
err = new Error ( 'normal error' );
console. log (EggError. getType (err)); // BUILTIN
err = EggError. from (err);
console. log (EggError. getType (err)); // ERROR copy
Customize Error
Error can be extendable.
const { EggBaseError } = require ( 'egg-errors' );
class CustomError extends EggBaseError {
constructor (message) {
super ({ message, code: 'CUSTOM_CODE' });
}
} copy
or using typescript you can customize ErrorOptions.
import { EggBaseError, ErrorOptions } from 'egg-errors' ;
class CustomErrorOptions extends ErrorOptions {
public data : object ;
}
class CustomError extends EggBaseError< CustomErrorOptions > {
public data : object ;
protected options : CustomErrorOptions ;
constructor (options ?: CustomErrorOptions ) {
super (options);
this .data = this .options.data;
}
} copy
Recommend use message instead of options in user land that it can be easily understood by developer, see http error .
HTTP Errors
HTTP Errors is BUILTIN errors that transform 400 ~ 500 status code to error objects. HttpError extends EggBaseError providing two properties which is status and headers;
const { ForbiddenError } = require ( 'egg-errors' );
const err = new ForbiddenError ( 'your request is forbidden' );
console. log (err.status); // 403 copy
Support short name too:
const { E403 } = require ( 'egg-errors' );
const err = new E403 ( 'your request is forbidden' );
console. log (err.status); // 403 copy
FrameworkBaseError
FrameworkBaseError is for egg framework/plugin developer to throw framework error.it can format by FrameworkErrorFormater
FrameworkBaseError extends EggBaseError providing three properties which is module、serialNumber and errorContext
FrameworkBaseError could not be used directly, framework/plugin should extends like this
const { FrameworkBaseError } = require ( 'egg-errors' );
class EggMysqlError extends FrameworkBaseError {
// module should be implement
get module () {
return 'EGG_MYSQL' ;
}
}
const err = new EggMysqlError ( 'error message' , '01' , { traceId: 'xxx' });
console. log (err.module); // EGG_MYSQL
console. log (err.serialNumber); // 01
console. log (err.code); // EGG_MYSQL_01
console. log (err.errorContext); // { traceId: 'xxx' } copy
use the static method .create(message: string, serialNumber: string | number, errorContext?: any) to new a frameworkError and format it convenient
const { FrameworkBaseError } = require ( 'egg-errors' );
class EggMysqlError extends FrameworkBaseError {
// module should be implement
get module () {
return 'EGG_MYSQL' ;
}
}
const err = EggMysqlError. create ( 'error message' , '01' , { traceId: 'xxx' });
console. log (err.message);
// =>
framework.EggMysqlError: error message [ https: //eggjs.org/zh-cn/faq/EGG_MYSQL/01 ] copy
FrameworkErrorFormater will append a faq guide url in error message.this would be helpful when developer encountered a framework error
the faq guide url format: ${faqPrefix}/${err.module}/${err.serialNumber}, faqPrefix is https://eggjs.org/zh-cn/faq by default. can be extendable or set process.env.EGG_FRAMEWORK_ERR_FAQ_PERFIX to override it.
const { FrameworkErrorFormater } = require ( 'egg-errors' );
class CustomErrorFormatter extends FrameworkErrorFormater {
static faqPrefix = 'http://www.custom.com/faq' ;
} copy
format error to message, it will not effect origin error
const { FrameworkBaseError, FrameworkErrorFormater } = require ( 'egg-errors' );
class EggMysqlError extends FrameworkBaseError {
// module should be implement
get module () {
return 'EGG_MYSQL' ;
}
}
const message = FrameworkErrorFormater. format ( new EggMysqlError ( 'error message' , '01' ));
console. log (message);
// => message format like this
framework.EggMysqlError: error message [ https: //eggjs.org/zh-cn/faq/EGG_MYSQL/01 ]
... stack
...
code: "EGG_MYSQL_01"
serialNumber: "01"
errorContext:
pid:
append faq guide url to err.message
const { FrameworkBaseError, FrameworkErrorFormater } = require ( 'egg-errors' );
class EggMysqlError extends FrameworkBaseError {
// module should be implement
get module () {
return 'EGG_MYSQL' ;
}
}
const err = FrameworkErrorFormater. formatError ( new EggMysqlError ( 'error message' , '01' ));
console. log (err.message); // error message [ https://eggjs.org/zh-cn/faq/EGG_MYSQL/01 ] copy
Available Errors
BaseError
|- EggBaseError
| |- EggError
| |- HttpError
| | |- NotFoundError, alias to E404
| | `- ...
| |- FrameworkBaseError
| `- CustomError
`- EggBaseException
|- EggException
`- CustomException copy
Questions & Suggestions
Please open an issue here .
License
MIT
Contributors
This project follows the git-contributor spec , auto updated at Tue Feb 22 2022 11:32:47 GMT+0800.