REST API 设计中 GET 方法的 HTTP 状态码最佳实践-Golang-PHP中文网

REST API 设计中 GET 方法的 HTTP 状态码最佳实践

本文详解 RESTful API 中 GET 请求（如 /cities）应返回的 HTTP 状态码：200 表示成功（含空列表），404 仅用于资源路径不存在，500 用于不可恢复的内部错误（如 JSON 序列化失败）。

本文详解 restful api 中 get 请求（如 `/cities`）应返回的 http 状态码：200 表示成功（含空列表），404 仅用于资源路径不存在，500 用于不可恢复的内部错误（如 json 序列化失败）。

在设计符合 REST 原则的 API 时，HTTP 状态码不仅是技术响应，更是语义契约——它向客户端明确传达“发生了什么”，而非“怎么发生的”。以 GET /cities 为例，其核心语义是“获取城市集合资源”，而非“获取至少一个城市”。因此，状态码的选择必须严格匹配资源状态与操作语义。

✅ 正确使用 200 OK
无论 cities 切片是否为空，只要请求路径有效、业务逻辑正常执行、数据可安全序列化，均应返回 200 OK。空数组 [] 是合法、完整、自描述的数据结构，客户端可通过检查 length 或 data 字段自行处理空结果。例如：

func FindCitiesHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json;charset=UTF-8")

    // 空列表是有效响应，非错误
    if len(cities) == 0 {
        json.NewEncoder(w).Encode([]City{}) // 显式返回空数组
        return
    }

    if err := json.NewEncoder(w).Encode(cities); err != nil {
        // 此处 err 属于底层编码失败（如写入中断、内存不足），非业务错误
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        return
    }
}

❌ 避免误用 404 Not Found
404 仅表示 请求的资源路径不存在（如 /citys 拼写错误，或 /cities/999 查单个不存在城市 ID）。而 /cities 作为集合端点，其存在性由路由定义决定；只要路由注册成功，该资源就“存在”——即使当前无数据。将空列表视为“资源未找到”，会误导客户端重试或报错，违背 REST 的幂等性与可缓存性原则。

⚠️ 500 Internal Server Error 用于不可控故障
当 json.Encoder 返回非 nil 错误（如 http.ErrBodyWriteAfterHeaders、io.ErrClosedPipe 或底层 write 系统调用失败），表明响应流已损坏或服务异常，此时必须立即终止流程并返回 500。注意：不应在 500 响应体中暴露敏感错误详情（如堆栈跟踪），生产环境建议统一返回简洁错误信息，并记录完整日志供排查：

if err := json.NewEncoder(w).Encode(cities); err != nil {
    log.Printf("JSON encoding failed for /cities: %v", err) // 记录详细错误
    http.Error(w, `{"error":"Failed to process request"}`, http.StatusInternalServerError)
    return
}

补充建议：