一  什么是好的错误信息(Error Message)?

• Context:  什么导致了错误？发生错误的时候代码想做什么？

• The error itself:  到底是什么导致了失败？具体的原因和当时的数据是什么？

• Mitigation: 有什么解决方案来克服这个错误，也可以理解为 Solutions

 ProblemBuilder.newBuilder(TestProblemId.ERROR1, StandardSeverity.ERROR, "Hawaiian pizza")                .withLongDescription("Pineapple on pizza would put your relationship with folks you respect at risk.")                .withShortDescription("pineapple on pizza isn't allowed")                .because("the Italian cuisine should be respected")                .documentedAt("https://www.bbc.co.uk/bitesize/articles/z2vftrd")                .addSolution(s -> s.withShortDescription("eat pineapple for desert"))                .addSolution(s -> s.withShortDescription("stop adding pineapple to pizza"));

• context: such as app name, component, status code，使用一个字符串描述当时的上下文，如应用名称 + 组件名称 +具体的错误状态码等，这个由你自己决定，当然JSON字符串也可以，如 {"app":"uic", "component": "login", "code":"111"}

• description: Long(Short) to describe error 错误描述，有Long和Short两者

• because/reason:  explain the reason with data 详细解释错误的原因，当然必须包含相应的数据

• documentedAt: error link 错误对应的HTTP连接，更详细地介绍该错误

• solutions: possible solutions 可能的解决方案，如提示访问者检查email拼写是否正确，短信的Pass Code是否输入正确等。

二  错误码(Error Code)的设计

• System/App short name: 系统或者应用的名称，如 RST, OSS等。如果你熟悉Jira的话，基本也是这个规范，Java程序员应该都知道HHH和SPR代表什么吧？ 

• Component short name or code: 系统内部的组件名称或者编码，如LOGIN,  AUDIT，001 这些都可以，方便更快地定位错误。

• Status code: 错误的状态码，这个是一个三位数字的状态码，如200，404，500，主要是借鉴自 HTTP Status Code，毕竟绝大多数开发者都了解HTTP状态码，我们没有必要再重新设计。

• OSS-001-404:  你应该知道是OSS的某一组件报告资源没有找到吧

• RST-002-500：这个是一个组件的内部错误

• UIC-LOGIN-404：这个应该是会员登录时查找不到指定的账号

三  错误消息的编写格式

long description(short desc): because/reason --- document link -- solutions

• 错误的长描述直接书写，短描述使用括弧进行包含。这种写法在合同中非常常见，如阿里云计算有限公司(阿里云)  ，你签署劳动合同时，公司的称谓基本也是全名(代称) 这种方式。好多同学会在错误日志中书写登录失败，但是登录系统中有多种登录方式，所以远不如Failed to log in with email and password(Login Failed), Failed to log in with phone and passcode(Login Failed), Failed to log in with oauth2(Login Failed) 更清晰。

• 错误具体原因:  接下来是冒号，然后书写详细的原因，如 email user@example.com not found ，gender field is not allowed in package.json 一定要包含具体的数据信息，包括输入的，还是和劳动合同一样，抬头之后就是你的具体岗位和薪水，虽然合同是格式化的，但是每一个人具体的岗位和薪水是不同的，这些参数都是从外部获取的。此处有安全同学发问，如何数据脱敏？这个是另外的问题，大多数开发者应该了解如何进行mask，这里我们就跳过。当出现劳动纠纷这个错误时，具体原因中的数据，如岗位和薪水等，这样劳动仲裁局就可以快速定位并解决该"错误"。

• document link: 接下来我们使用三种划线---进行分隔，输入对应的error link。三划线作为分隔符在很多的场景中多有使用，如mdx, yaml等，大家不会太陌生。 如果没有link那就忽略就可以。

• solutions：自然的文本表述即可，能说明清楚就可以，也是放在三中划线后。

APP-100-400=Failed to log in system with email and password(Email login failed): can not find account with email {} --- please refer https://example.com/login/byemail  --- Solutions: 1. check your email  2. check your password

四  组装和保存错误码 + Message

### error messages for your AppAPP-100-400=Failed to log in system with email and password(Email login failed): can not find account with email {0} --- please refer https://example.com/login/byemail  --- Solutions: 1. check your email  2. check your passwordAPP-100-401=Failed to log in system with phone and pass(Phone login failed): can not find account with phone {0} --- please refer https://example.com/login/byphone  --- Solutions: 1. check your phone  2. check your pass code in SMS

• 国际化支持：Java的同学都知道，如果你的错误消息想调整为中文，创建一个ErrorMessages-zh_CN.properties 即可。原文中的建议是Don’t localize error messages，但是考虑到国内大多数程序员未必能用英文表达清楚，所以中文也是可以的。题外话：如果中国的程序员都能用英文清晰地阅读文章和表达自己的思想和观点，我们在计算机方面的水平可能会提升到更高的台阶。

• 各种语言对properties的文件解析都有支持，不只是Java，其他语言也有，而且properties文件本身也不复杂，所以该properties文件可以给Node.js, Rust等其他语言使用，如果是Java enum和POJO基本就不可能啦。

• properties文件格式丰富：支持注释，换行符，多行转义等也都没有问题。

• error code的自动提示
  
  

  
  

• 快速查看：鼠标移上去就可以，按下CMD鼠标移上去也可以， Alt+Space也可以，当然点击直接定位就更不用说啦。

• 重构和查找支持：虽然Error Code是字符串，但是也是properties的key，所以rename这个error code，所有引用的地方都会rename。还支持find usage，那些地方引用了该error code等，都非常方便。当然如果Error Code在系统中没有被使用，也会灰色标识。

• 折叠自动显示功能：当你的代码处于折叠状态时，IDEA直接将message拿过来进行显示，你在code review的时候方便多啦，也便于你理解代码。

• 直接修改message的值

五  代码实现

import org.slf4j.helpers.MessageFormatter;
public class AppErrorMessages {    private static final String BUNDLE_FQN = "app.ErrorMessages";    private static final ResourceBundle RESOURCE_BUNDLE = ResourceBundle.getBundle(BUNDLE_FQN, new Locale("en", "US"));    public static String message(@PropertyKey(resourceBundle = BUNDLE_FQN) String key, Object... params) {         if (RESOURCE_BUNDLE.containsKey(key)) {            String value = RESOURCE_BUNDLE.getString(key);            final FormattingTuple tuple = MessageFormatter.arrayFormat(value, params);            return key + " - " + tuple.getMessage();        } else {            return MessageFormatter.arrayFormat(key, params).getMessage();        }    }}

public class ErrorCodeLogger implements Logger {    private Logger delegate;    private static final String BUNDLE_FQN = "app.ErrorMessages";    private static final ResourceBundle RESOURCE_BUNDLE = ResourceBundle.getBundle(BUNDLE_FQN, new Locale("en", "US"));
    public ErrorCodeLogger(Logger delegate) {        this.delegate = delegate;    }
    @Override    public void trace(@PropertyKey(resourceBundle = BUNDLE_FQN) String msg) {        delegate.trace(RESOURCE_BUNDLE.getString(msg));    }}

六  FAQ

1  为何选择3位的HTTP Status Code作为Error的Status Code？

• Informational responses (100–199)
• Successful responses (200–299)

• Redirection messages (300–399)
• Client error responses (400–499)

• Server error responses (500–599)

• UIC-LOGIN-666:  太顺利啦，完美登录。但是你团队中有欧美老外的话，他可能理解为理解为恶意登录，登录失败

• APP-LOGIN-062:  如果你团队有杭州土著的话，不要使用62这个数字

• APP-001-013: 如果该error code要透传给最终用户，请不要使用13这个数字，会引发不适

2  properties文件存储error code和message，真的比enum和POJO好吗？

#[derive(Debug)]enum ErrorMessages {    AppLogin404 {        email: String,    },    AppLogin405(String),}
impl fmt::Display for ErrorMessages {    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {        // extract enum name parameter        // output message from java-properties        write!(f, "{:?}", self)    }}

3  为何不在Error Code中提供错误级别

• 错误的级别会动态调整的：如随着时空的变化，之前非常严重的错误级别，现在并不那么严重啦。如果资源找不到可能之前非常严重，但是现在添加了备份方案，可以从备份服务器中再查找一次，所以这个错误出现在主服务上可能现在就不是那么严重啦。

• 不同团队对错误级别的认知不一样：如OSS-404在OSS团队的data server上找不到，元信息都是有的，结果在data server上没有找到对应的数据，这个是非常严重的错误。雷卷在业务团队，如负责Serverless Jamstack，其中的一个文件缺失，如html, css, image，可能并不是一个大问题，等一会重试下，不行就再上传一下。我想表达的是同样的错误，在不同团队中的重要性并不一样。

4  能否提供共享库？

5  其他的考量

• 内外有别：如内部开发者的错误中可能会包括服务器的具体信息，当然给最终消费者，如平台的FaaS开发者，可能就不能输出这样的信息，有一定的安全风险。

• 小心在错误中暴露敏感数据：输出到错误日志的数据一定要进行mask，当然也不要影响你定位错误，这个要看具体的场景。

• 不要将错误消息作为 API 契约：在API的场景中，响应错误有两种方式：根据错误码做响应，如REST API；另外一种是根据消息做出响应，如GraphQL，所以这个你自行选择。

• Error Code的一致性：错误消息会输出给不同的消费者，如REST API，界面等，可能错误的提示消息有所不同，如国际化、脱敏等，但是最好都是相同的error code，也就是front end + backend 共享相同的error code，方便定位错误和统计。

七  总结

如何进行CDN以及下载优化分析