本文详解 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 Found404 仅表示 请求的资源路径不存在（如 /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
}补充建议：
- 对数据库连接失败等数据层异常，应在数据访问层提前捕获，返回
503 Service Unavailable（表示临时不可用，鼓励客户端重试）； - 若需区分“无数据”与“查询条件不匹配”，可在响应体中增加元字段（如
"count": 0），而非滥用状态码； - 所有错误响应建议采用统一 JSON 格式（如
{ "error": "...", "code": "INTERNAL_ERROR" }），便于客户端解析。
遵循这些规范，你的 API 将更健壮、可预测，也更容易被前端、网关及自动化工具正确消费。
