3. 错误码设计原则：HTTP 状态码与业务错误码的映射、错误码的层级结构

在搜索服务的高并发场景下，错误码不仅是客户端判断请求成败的依据，更是后端排查慢查询、定位系统瓶颈的关键索引。一个设计混乱的错误码体系会导致告警误报、日志无法聚合、SLA 统计失真。本章从 HTTP 状态码与业务错误码的映射关系出发，构建可观测、可归因的错误码层级结构。

3.1 HTTP 状态码与业务错误码的映射原则

HTTP 状态码用于表达传输层的语义（如 4xx 表示客户端错误，5xx 表示服务端错误），而业务错误码用于表达应用层的具体失败原因（如“搜索索引不存在”“查询超时”）。两者应遵循 “粗粒度映射 + 细粒度补充” 原则：

• 2xx：仅映射业务成功（错误码为 0 或 SUCCESS）。
• 4xx：映射客户端可自行修复的错误，如参数校验失败、鉴权过期、请求频率超限。
• 5xx：映射服务端内部故障，如数据库连接池耗尽、缓存雪崩、索引加载失败。
• 禁止：将业务逻辑错误（如“商品已下架”）映射为 500，或将服务端超时映射为 400。

3.2 错误码的层级结构：系统级 / 模块级 / 业务级

为了在日志聚合、告警降噪、慢查询归因时能快速定位故障域，错误码应采用 三段式层级结构。每一层承载不同的定位粒度：

• 系统级（1 位）：标识错误来源系统，如搜索服务、用户中心、商品中心。
• 模块级（2 位）：标识子系统内的功能模块，如索引模块、查询模块、排序模块。
• 业务级（3 位）：标识具体的失败原因，如索引不存在、查询超时、排序字段非法。

推荐编码格式：X-YY-ZZZ，例如 1-03-007 表示“搜索服务 - 查询模块 - 查询超时”。

// 系统级：1 = 搜索服务，2 = 用户中心，3 = 商品中心
// 模块级：01 = 索引模块，02 = 缓存模块，03 = 查询模块
// 业务级：001 = 索引不存在，007 = 查询超时，012 = 排序字段非法

const (
    ErrSearchIndexNotFound = "1-01-001"
    ErrSearchQueryTimeout  = "1-03-007"
    ErrSearchSortInvalid   = "1-03-012"
)

下表展示了搜索服务中常见的错误码层级分配：

3.3 错误码层级结构图

下图展示了搜索服务中错误码的三段式层级关系，以及从 HTTP 状态码到业务错误码的映射路径：

3.4 慢查询场景下的错误码断言实战

在 Go 搜索服务中，错误码断言常用于慢查询根因分析。以下是一个典型的错误码断言流程：

1. 捕获慢查询：在中间件中记录请求耗时超过 500ms 的日志。
2. 提取错误码：从响应体中解析业务错误码字段 code。
3. 断言层级：先判断系统级是否为搜索服务（1），再判断模块级是否为查询模块（03），最后定位业务级原因。
4. 触发告警：如果错误码为 1-03-007（查询超时），则触发 P0 告警并自动拉取对应时间段的数据库慢查询日志。

type ErrorCode string

const (
    SystemSearch   = "1"
    ModuleQuery    = "03"
    ErrQueryTimeout = "1-03-007"
)

// AssertSlowQuery 断言慢查询根因
func AssertSlowQuery(code ErrorCode, latency time.Duration) string {
    parts := strings.Split(string(code), "-")
    if len(parts) != 3 {
        return "invalid_code_format"
    }
    if parts[0] != SystemSearch {
        return "not_search_service"
    }
    if parts[1] != ModuleQuery {
        return "not_query_module"
    }
    if code == ErrQueryTimeout && latency > 500*time.Millisecond {
        return "trigger_slow_query_alert"
    }
    return "other_error"
}

3.5 错误码设计检查清单