@yunflyjs/errors

简介

快速定位问题以及统一统计错误信息 Error 类。

快速上手

yarn add @yunflyjs/errors

import { NotFoundError } from '@yunflyjs/errors'

@Get("/users/:id")
getOne(@Param("id") id: number) {
  const user = this.userService.findOneById(id);
  if (!user) {
    throw new NotFoundError("找不到此用户"); // message 可选
  }

  return user;
}

如果是结合 yunfly，最后的返回结果为：

{
  code: 404,
  msg: "找不到此用户"
}

YunkeError 属性说明

所有的内置 Error 类都是继承于 YunkeError 类，那么我们就需要了解一下 YunkeError 类包含的内容：

interface YunkeError {
  // 错误名
  name: string;
  // HTTP 状态码
  httpCode?: number;
  // 自定义错误码
  code?: number | string;
  // 错误信息
  message?: string;
  // 错误详情
  // 因为有些信息不能返回给用户，但是需要记录到阿里云，故通过此属性保留
  messageDetail?: any;
}

name

会自动读取当前 Error 类的类名，不需要配置，自动读取当前类名。

code

code 的命名有三种规则：

• 规则 1：http 错误类

http 错误类 code 参考业界标准，例如 400、401、403、500、503 等。

• 规则 2：yunfly 框架及周边生态

从 10000 开头，每个应用占 100 个间隔，例如 redis 错误为为 10100 - 10199，默认值是 10100

• 规则 3：rpc 调用错误

rpc 调用错误根据 go 语言返回的结果确定，如果没有，则默认为 -1。

• 规则 4：用户自定义错误

严格上，用户自定义错误只要不和上述规则冲突即可，推荐从 40000 开始。

httpCode

对于内置错误类而言，HTTP 状态码规则如下：

• HTTP 错误类，HTTP 状态码和 code 码是相同的，例如 401，HTTP 状态码和错误码都为 401
• 对于 rpc 调用错误，统一 500
• yunfly 框架及周边生态错误错误，导致服务器报错的，就是 500，其他视情况而定
• 用户自定义错误类，就由用户自己确定

message

错误信息，可自定义。

messageDetail

错误详情，例如在 rpc 调用时出现错误时，会返回很多的错误信息，这个信息实际是不需要给用户看的，我们可以通过赋值给 messageDetail 属性来达到最终记录到阿里云日志的效果（框架会读这个字段）。

内置 Error 类列表

内置的 Error 分为三类，分别为：

HTTP 相关 Error：

错误类	含义	HTTP 状态码	code 码
BadRequestError	参数错误	400	400
UnauthorizedError	用户未登录	401	401
ForbiddenError	用户无权限	403	403
NotFoundError	找不到相关资源	404	404
MethodNotAllowedError	方法不允许	405	405
TooManyRequestsError	过多请求	429	429
InternalServerError	代码不严谨导致的服务器错误	500	500
BadGatewayError	网关错误	502	502
ServiceUnavailableError	服务不可用	503	503
GatewayTimeoutError	网关超时	504	504

RPC Error：

错误类	含义	HTTP 状态码	code 码
RpcError	RPC 错误	500	code 由 go 返回的决定，默认值是 -1

yunfly 框架及周边生态：

错误类	含义	HTTP 状态码	code 码范围
YunflyError	yunfly 框架自身异常	500	10000 ~ 1099
ApolloError	Apollo 错误	500	10100 ~ 10199
RedisError	Redis 错误	500	10200 ~ 10299
EctdError	ECTD 错误	500	10300 ~ 10399
MysqlError	Mysql 错误	500	10400 ~ 10499
MongoDBError	MongoDB 错误	500	10500 ~ 10599

使用方式

错误类可以有四种抛出方式，分别为：

• 1、全部使用默认值

throw new BadRequest()

• 2、更改 message 信息

throw new BadRequest("用户名不为空") // 仅修改 message

• 3、更改更多的信息

与已有参数是 merge 关系

throw new YunkeError({ message: "用户名不为空", code: 400001 }) // 同时修改 message 和 httpCode

• 4、传递已有的错误

import { RpcError } from '@yunflyjs/errors'
const { error, response } = await userServiceV2.getUser({
  request, metadata
});

if (error) {
  throw new RpcError(error) // 抛出已有的 Error 类
}

• 5、针对 RpcError 和 InternalServerError

因为 RpcError 和 InternalServerError 是基于已有的 Error 信息进行抛错的，而原有的 Error message 属性实际是不需要展示给用户的，例如代码运行报错，error 的 message 内容就是某行某语法不正确，这个东西我们只需要记录日志即可。

所以针对这两个类做了特殊处理，将他们的第一个参数的 message 属性当做 messageDetail，并且提供了第二个参数作为 message，如果没传，则默认为 “服务器异常，请重试”，具体使用方式如下：

import { RpcError, InternalServerError} from '@yunflyjs/errors'

try {
  // ...
} catch(error) {
  throw new InternalServerError(error) // 无第二个参数情况下，message 为 “服务器异常，请重试”
  throw new InternalServerError(error, "出错了~") // 传了参数，则为传递的参数 “出错了~”
}


// 道理同上
throw new RpcError(error) 
throw new RpcError(error, "出错了~")

自定义 Error 类

内置类肯定是没办法满足所有需求的，我们还需要定义一些自己的业务类，具体步骤如下：

import { YunkeError, YunkeErrorOptions } from '@yunflyjs/errors'

// 继承 yunke error
class CustomError extends YunkeError {
  // 其他几个信息也可以自定义
  constructor(options?: YunkeErrorOptions) {
    super(options);
    this.code = this.code ?? 400001;
    // ?? 的意思是前者为 undefined 或者 null 时，则使用后者
    this.httpCode = this.httpCode ?? 400;
    // || 的意思是，前面为 falsy 时，则使用后者（因为 Error 类的 message 默认值是 '', 所以这里使用了 || ）
    this.message = this.message || '自定义错误信息'; 
  }
}

错误日志查看

有了上述错误信息，我们就可以轻松定位 Error 信息，例如我们需要定位用户登录失败的问题：

• 1.首先拿到 trace-id

• 2.登录贾维斯日志查询并选择相应的环境

• 3.输入 trace-id

• 4.根据 Error 类进行判断，可以推断出是 Go 服务的报错