讲解HTTP 状态码

HTTP 状态码，它们广泛用于 Java Web 开发中（以及所有基于 HTTP 协议的后端服务），用来表示服务器对客户端请求的处理结果。

HTTP 状态码是标准化的，由三位数字组成，根据第一位数字大致分为 5 大类：

📌 1xx：信息性状态码

主要用于临时响应，表示请求已接收，正在处理。
常用的：
- 100 Continue：客户端可以继续发送请求的剩余部分。

（1xx 在日常 Java 开发中基本用不到）

📌 2xx：成功状态码

表示请求被服务器成功接收并处理。

200 OK
- ✅ 最常见，表示请求成功，比如 GET 返回资源、POST 成功创建等。
201 Created
- 资源已成功创建，常用于 POST 新建操作。
204 No Content
- 请求成功但没有返回任何内容，比如 DELETE 后。

📌 3xx：重定向状态码

表示需要客户端采取进一步操作才能完成请求。

301 Moved Permanently
- 永久重定向，比如域名迁移。
302 Found
- 临时重定向，常用于网站维护。
304 Not Modified
- 客户端缓存的资源未修改，可以使用本地缓存。

📌 4xx：客户端错误状态码

表示请求有错误，问题出在客户端。

400 Bad Request
- 客户端请求语法错误、参数错误或无法解析请求体。
401 Unauthorized
- 未授权，需要认证（如未登录或 token 过期）。
403 Forbidden
- 已认证，但没有权限访问资源，比如权限不足。
404 Not Found
- 请求的资源不存在，比如访问了不存在的 URL。
405 Method Not Allowed
- 请求方法不被支持，比如 POST 到只支持 GET 的接口。
409 Conflict
- 请求与服务器资源状态冲突，比如并发更新导致版本冲突。

📌 5xx：服务器错误状态码

表示服务器处理请求时出错，问题在服务器端。

500 Internal Server Error
- 服务器内部错误，常见的 NullPointerException 等未捕获异常。
502 Bad Gateway
- 作为网关或代理的服务器，从上游服务器接收到无效响应。常见于反向代理（Nginx）连接后端服务失败。
503 Service Unavailable
- 服务不可用，通常是服务器过载或维护中。
504 Gateway Timeout
- 网关或代理服务器等待上游服务器响应超时。

✅ 常见状态码总结

状态码	含义	适用场景示例
200	OK	请求成功，常见 GET、POST 响应
201	Created	资源成功创建，比如注册新用户
204	No Content	删除成功无返回
400	Bad Request	参数格式错误、不符合 API 约定
401	Unauthorized	未登录或 token 失效
403	Forbidden	已登录但无权限访问资源
404	Not Found	请求地址或资源不存在
405	Method Not Allowed	请求方法错误，比如用 POST 请求 GET-only 接口
500	Internal Server Error	后端异常
502	Bad Gateway	代理服务器连接后端服务失败
503	Service Unavailable	后端服务器宕机或维护
504	Gateway Timeout	请求后端超时

📌 Java 开发中如何使用

在 Spring Boot 接口中可以通过返回特定的 HTTP 状态码来表达不同的结果：

java 复制代码

@RestController
@RequestMapping("/api")
public class UserController {

    @GetMapping("/user/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            // 返回 404 Not Found
            return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
        }
        // 返回 200 OK
        return ResponseEntity.ok(user);
    }

    @PostMapping("/user")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User savedUser = userService.save(user);
        // 返回 201 Created
        return ResponseEntity.status(HttpStatus.CREATED).body(savedUser);
    }
}

✅ 小提示

状态码是客户端和服务器沟通的标准语言。
在 Java 后端设计 API 时，合理地返回对应的状态码可以让前端更清楚请求结果，有助于开发和调试。
不要把所有错误都返回 200，比如校验失败返回 400，比返回 200+错误信息更规范。