应使用枚举而非public static final int定义状态码，因其提供类型安全、语义清晰、分组能力及编译期校验；推荐自定义HttpCode枚举并配合@JsonValue/@JsonCreator实现序列化与反序列化。
为什么不能直接用 public static final int 定义状态码常量
Java 中看似最直觉的方式是写一堆 public static final int OK = 200，但这样会丢失语义和类型安全。比如传参时你无法约束方法只接受合法的状态码值，IDE 也无法在误用（如传入 999）时给出提示；更麻烦的是，HTTP 状态码本身有类别（1xx/2xx/3xx/4xx/5xx），纯 int 无法表达这种分组逻辑，后续做日志分类或监控聚合时还得靠硬编码判断。
推荐方案：用 enum 封装状态码并实现 HttpStatus 接口
Spring 已提供 org.springframework.http.HttpStatus 枚举，但它是 Spring 内部维护的，不建议直接在业务常量类里复用（尤其当项目未强依赖 Spring Web 时）。更可控的做法是自定义枚举，并保持与标准 HTTP 语义对齐：
public enum HttpCode {
CONTINUE(100, "Continue"),
OK(200, "OK"),
CREATED(201, "Created"),
NO_CONTENT(204, "No Content"),
BAD_REQUEST(400, "Bad Request"),
UNAUTHORIZED(401, "Unauthorized"),
FORBIDDEN(403, "Forbidden"),
NOT_FOUND(404, "Not Found"),
METHOD_NOT_ALLOWED(405, "Method Not Allowed"),
INTERNAL_SERVER_ERROR(500, "Internal Server Error"),
SERVICE_UNAVAILABLE(503, "Service Unavailable");
private final int value;
private final String reasonPhrase;
HttpCode(int value, String reasonPhrase) {
this.value = value;
this.reasonPhrase = reasonPhrase;
}
public int value() { return value; }
public String reasonPhrase() { return reasonPhrase; }
}
- 每个枚举项天然具备不可变性，
final语义由 JVM 保证，无需额外声明 - 构造器私有 + 字段
final，确保实例状态不可篡改 - 暴露
value()和reasonPhrase()方法，比直接暴露字段更灵活（未来可加缓存、国际化等） - 避免使用
name()或ordinal()做状态码解析——它们和 HTTP 数值无关，极易出错
如何在 Controller 中安全返回这些状态码
不要手动拼接 ResponseEntity.status(code.value()).body(...)，容易漏掉 reasonPhrase 或类型转换错误。统一提供静态工厂方法：
public class Responses {
public static <T> ResponseEntity<T> ok(T body) {
return ResponseEntity.status(HttpCode.OK.value())
.header("X-Status", HttpCode.OK.name())
.body(body);
}
public static ResponseEntity<?> badRequest(String message) {
return ResponseEntity.status(HttpCode.BAD_REQUEST.value())
.body(Map.of("error", message));
}
// 更通用的入口
public static <T> ResponseEntity<T> of(HttpCode code, T body) {
return ResponseEntity.status(code.value()).body(body);
}
}
- 所有返回路径都经过
Responses，便于后续统一加 trace-id 注入、审计日志或熔断统计 - 避免在 Controller 里出现裸数字（如
status(404)），强制走枚举校验 - 如果用 Spring Boot，可配合
@ResponseStatus注解在自定义异常上，但注意它只影响默认响应体，不控制 header 或 payload 结构
常见踩坑点：序列化、反序列化与前端对接
前端通常期望 JSON 响应里带 code 字段（如 {"code": 404, "message": "Not Found"}），但你的 HttpCode 枚举默认不会被 Jackson 自动转成数字。必须显式配置：
- 全局禁用枚举序列化为 name：
@JsonFormat(shape = JsonFormat.Shape.NUMBER)加在字段或 getter 上 - 或者注册模块：
new SimpleModule().addSerializer(HttpCode.class, new StdSerializer(HttpCode.class) {...}) - 反序列化时，Jackson 默认不支持从数字转回枚举，需自定义
JsonDeserializer，或改用@JsonValue+@JsonCreator（推荐）：
public enum HttpCode {
// ... same as before
@JsonValue
public int getValue() { return value; }
@JsonCreator
public static HttpCode fromValue(int value) {
for (HttpCode c : HttpCode.values()) {
if (c.value == value) return c;
}
throw new IllegalArgumentException("Unknown status code: " + value);
}
}
没做这一步，前端传来的 {"code": 400} 在反序列化时会直接报错，而不是优雅 fallback 到默认值。
真正难的不是定义常量，而是让这个常量贯穿整个请求生命周期——从参数校验、异常抛出、响应构造，到序列化输出，每个环节都要对齐。漏掉任意一环，final 就只是个装饰词。
