应使用 enum 而非常量类定义状态码，因其具备类型安全、不可变、可枚举、自带 tostring/valueof、支持扩展字段等优势，避免魔法值、误赋值、无法遍历及序列化问题。
为什么不用常量类而要用 enum 定义状态码
因为 enum 天然带类型安全、不可变、可枚举、自带 toString() 和 valueOf()，还能挂载额外字段（比如 code 和 message），避免散落在各处的魔法数字或字符串。用 public static final int 容易误赋值、无法遍历、IDE 不提示、序列化也容易出错。
常见错误现象：if (status == 2001) 这种写法一旦拼错或改码，编译器不报错；而 Status.USER_NOT_FOUND 写错 IDE 立刻标红。
- 每个状态码必须唯一，enum 构造时强制校验重复
code - 建议把
code设为int或String，避免跨服务时整型溢出（比如前端 JS 会丢失大于2^53的整数） - 不要在 enum 中写业务逻辑方法（如
isSuccess()），只存数据；判断逻辑提到工具类或扩展函数里
Java 枚举定义状态码的标准结构
核心是私有构造 + getter + 静态 map 缓存反查（避免每次遍历）：
public enum Status {
SUCCESS(0, "操作成功"),
USER_NOT_FOUND(4001, "用户不存在"),
INVALID_PARAM(4000, "参数不合法");
private final int code;
private final String message;
Status(int code, String message) {
this.code = code;
this.message = message;
}
public int getCode() { return code; }
public String getMessage() { return message; }
private static final Map<integer status> CODE_MAP = Arrays.stream(values())
.collect(Collectors.toMap(Status::getCode, Function.identity()));
public static Status fromCode(int code) {
return CODE_MAP.getOrDefault(code, UNKNOWN);
}
}</integer>
注意点：
-
UNKNOWN必须作为兜底项定义（哪怕只是UNKNOWN(-1, "未知状态")），否则fromCode(999)会返回null，引发 NPE - 不要用
Enum.valueOf()反查，它只认 name，不是 code - 如果状态码要支持国际化，
message字段应改为 key（如"user.not.found"），交由 ResourceBundle 渲染
Spring Boot 中如何自动绑定枚举到 HTTP 响应
让 @ResponseBody 返回 JSON 时默认输出 code 和 message，而不是整个 enum 名称：
- 加
@JsonFormat(shape = JsonFormat.Shape.OBJECT)注解到 enum 类上（Jackson 2.12+） - 或自定义
SimpleModule注册StdSerializer，重写序列化逻辑 - 更轻量做法：在 Controller 返回对象里用
@JsonProperty显式映射字段，例如：public class Result {<br> private final int code;<br> private final String message;<br> public Result(Status status) {<br> this.code = status.getCode();<br> this.message = status.getMessage();<br> }<br>}
容易踩的坑：@JsonValue 加在 getter 上会导致整个 enum 被序列化成单个值（比如只输出 4001），丢失 message —— 这不符合状态码需双字段返回的通用约定。
跨语言/微服务场景下 enum 的兼容性处理
Java enum 本质是类，不能直接被 Go/Python 解析。真正需要统一的是「状态码协议」，不是 Java 枚举本身：
- 所有服务共用一份 YAML/JSON 状态码清单（含
code、message_zh、message_en、http_status），生成各语言的对应类型 - Java 侧 enum 的
code必须与清单严格一致，CI 流程中加入校验脚本比对 - 避免在 enum 中使用非 ASCII 字符做
name（如USER_未找到），影响代码生成和日志检索 - 如果用 gRPC，直接在
.proto里定义enum StatusCode，生成 Java 类后，再用包装类桥接到你的Statusenum（保持业务层不变）
最常被忽略的一点：HTTP 状态码（如 404）和业务状态码（如 4001）必须分层设计。前者控制连接生命周期，后者表达业务语义 —— 混在一起会导致前端无法区分网络异常和业务拒绝。
