错误码方案

[sorrycc]

为什么做

作为「答疑提效」的一部分，把已经梳理的 FAQ 和 Error Code 规范化和工程化，让开发者通过错误码能自行解决大量问题，这对于 Umi/Bigfish 开发者和用户来说是双赢的。

计划

• 梳理错误码列表 2h @云谦 @韩泽邦
• 实现错误码 Markdown2JSON 的转换
• 部署文档到 Umi 官网
• 部署文档到 Bigfish 官网 @韩泽邦
• Umi 层接入之 build 错误 2h @云谦
• Umi 层接入之（待定）
• Bigfish 层接入 2h
• 宣传文档 1h

方案

错误码梳理

• 包含字段：标题、Code、Type（error、warn）、集成状态（framework、doctor，可多选）、From（build、core、plugin、runtime 等）、Url（可选，扩展时必须提供）、详细描述和解法
• 以文档的方式梳理错误码，然后通过脚本编译出 json 格式给框架用
• 网站上通过 https://umijs.org/docs/error-code#ERR_CASE_SENSIVE 的方式访问
• Bigfish 会有额外的错误码，需通过脚本对两篇文档进行合并
• 允许通过插件扩展错误码数据，扩展的 Code 需自带前缀，比如 ERR_BIGFISH_TERN_CONFIG
• 新发现的错误码先存语雀文档，讨论后决定加入框架或 Doctor
• 得额外维护一份 error message 到 error code 的 match 表

// match map
export const matchMap = {
  ERR_CASE_SENSIVE({ err }) { return err.message.includes('case sensive') },
};

接入 Umi

根据「From」的不同会有不同的接入方式。

• 比如 build 类，在报错时通过匹配 error message 实现
• 比如 core 类，umi 内核的报错主动抛的，直接调相应方法即可
• 比如 runtime 类，待定（先看有没有）

用户看到的报错信息最终是这样，

ERR_CASE_SENSIVE, 大小写不匹配问题
Check https://umijs.org/docs/error-code#ERR_CASE_SENSIVE for more details.

Error Message
Error Stack

关键代码，

// error.ts
// 放 utils 里？
export function buildError(opts: { code: string, errorData, err: Error }) {
  assert(opts.errorData[code], ``);
  err.message = [`${opts.code}, ${opts.errorData[code].title}`, `Check ...`, err.message].join('\n');
  return err;
}
export function parseErrorData() {
  return JSON.parse(readFileSync('path/to/errorData.json'));
}
export function findErrorCode(opts: { err: Error, errorCodeMap }) {
  // match err.message with errorCodeMap
  const codes = Object.keys(errorCodeMap);
  // ...
}

// modifyAppData Hook
const initialErrorData = parseErrorData();
api.appData.errorData = api.applyPlugins({
  key: 'modifyErrorData',
  initialValue: initialErrorData,
});
api.appData.errorCodeMap = api.applyPlugins({
  key: 'modifyErrorCodeMap',
  initialValue: initialErrorCodeMap,
});

// Throw Core Error
throw new Error(buildError({ code: 'ERR_CORE_XXX', errorData, err }));

// Throw Build Error
const code = findErrorCode({ err, errorCodeMap });
throw new Error(buildError({ code, errorData, err }));

接入 Bigfish

提供额外的错误码和 match 表即可。

api.modifyErrorData();
api.modifyErrorCodeMap();

错误码

ERR_CASE_SENSIVE

• Title: 大小写不匹配问题
• Type: error
• From: build
• Integrated: framework, doctor

详细描述。

参考

文档

• Bigfish 4 FAQ
• Bigfish Block
• Bigfish Error Code

错误码

• Bigfish: 强约束
• React: Error Decoder
• TypeScript: Error Code
• Father: Doctor Rules
• ESLint: Rules