REST API错误信息终端用户友好化处理的最佳实践咨询

一、前端提议的err_code方案合理，可结合OpenAPI规范优化 #

你担心仅靠Wiki维护错误码缺乏约束，完全可以把err_code的定义直接整合到OpenAPI规范中，替代零散的Wiki：

• 在OpenAPI的响应模块里，针对每个4xx状态码，明确列出所有可能的err_code及其业务语义，比如400 Bad Request下的ARTICLE_NAME_IS_NOT_UNIQUE、ARTICLE_CONTENT_EMPTY等。
• 这种方式既保留了后端与UI解耦的核心优势（后端只返回错误标识，前端负责渲染用户友好文案），又通过OpenAPI提供了强文档约束——前端开发可直接从规范中获取所有错误场景，无需依赖零散文档，甚至能自动生成前端的错误类型枚举（如TypeScript的enum），大幅减少沟通成本。

二、为每个错误分配独立4xx状态码不可取 #

HTTP状态码的核心作用是标识请求级别的错误类别（比如400表示请求参数错误、401表示未授权、409表示资源冲突），而非区分具体业务错误。同一接口的不同业务错误（比如文章名重复、内容为空）都属于400请求错误范畴，强行分配不同4xx状态码会：

• 违背HTTP规范的语义，导致状态码滥用；
• 快速耗尽可用的4xx状态码，后续新增错误无码可用；
• 增加前端判断逻辑的复杂度（需要处理大量零散状态码）。

正确的做法是用HTTP状态码标识错误大类，用err_code区分具体业务场景，二者配合使用。

三、规避后端依赖UI/UX需求的核心原则 #

要避免后端绑定UI文案，需明确错误响应中各字段的职责：

• err_code：后端返回的业务错误唯一标识，与UI无关，仅用于前端判断错误类型；
• message：后端返回的技术提示信息，仅供开发调试使用（比如"Database constraint violation: article_name must be unique"），前端无需将其展示给终端用户；
• 用户友好的文案完全由前端维护，前端通过err_code映射对应的本地化文案（支持多语言也更方便）。

统一的错误响应格式示例：

{
  "err_code": "ARTICLE_NAME_IS_NOT_UNIQUE",
  "message": "Article name already exists in database"
}

四、额外最佳实践 #

• 错误码命名规范：采用全大写下划线格式，语义清晰无歧义（比如ARTICLE_NAME_DUPLICATE比ARTICLE_ERROR_001更直观）；
• 前端全局错误处理：封装统一的错误处理逻辑，根据err_code自动匹配文案并展示，避免每个请求都重复写判断；
• 后端日志记录：除了返回err_code，后端需在日志中记录详细错误信息（如请求参数、堆栈跟踪），便于排查问题，但这些信息绝不返回给前端；
• 版本兼容：如果后续需要新增或修改错误码，需确保向前兼容（比如旧版本前端遇到未识别的err_code，可展示通用提示文案）。

内容的提问来源于stack exchange，提问作者Semyon Kirekov