Spring Boot 中处理 JSON 数值溢出问题：从报错到优雅解决

一、问题背景：为什么我的接口突然报错了？

假设你正在开发一个 Spring Boot 接口，接收类似这样的 JSON 请求：

{
  "size": 111111111111111111111
}

然后突然收到用户的反馈：请求报错啦！

查看日志，发现一个刺眼的异常：

JSON parse error: Numeric value (111111111111111111111) out of range of int

翻译成"人话"：

前端传的 size 值太大，后端用 int 类型接收时，超出了 int 的范围（-2147483648 ~ 2147483647），导致 JSON 解析失败！

---

二、为什么会发生这个错误？

1. Java 数据类型的"容量"限制

• int 类型最大只能表示 2147483647。
• 当 JSON 中的数值超过这个范围时，int 装不下，就会触发溢出错误。

2. 谁在幕后"搞事情"？

• Jackson 库 ：Spring Boot 默认使用 Jackson 解析 JSON。
  当字段类型是 int 或 Integer，但 JSON 数值过大时，Jackson 会直接抛异常！

---

三、解决方案：三步搞定

第一步：修改字段类型（治本）

直接将 size 的字段类型改为 Long，一步到位解决问题！

public class EsSearchResultRequest {
    private Long size;  // ✅ 改为 Long 类型
    // 其他字段...
}

为什么有效？

• Long 的范围是 -9223372036854775808 ~ 9223372036854775807，足够容纳超大数值。

---

第二步：全局异常处理（优雅提示）

在 GlobalExceptionHandler 中捕获异常，返回友好提示：

@ExceptionHandler(HttpMessageNotReadableException.class)
public ResponseEntity<String> handleHttpMessageNotReadable(HttpMessageNotReadableException ex) {
    String errorMessage = "请求参数格式错误，请检查数值范围";
    // 提取具体错误原因（可选）
    if (ex.getCause() instanceof JsonMappingException) {
        errorMessage = ex.getCause().getMessage(); 
    }
    return ResponseEntity.badRequest().body(errorMessage);
}

效果示例：

前端收到提示：

Numeric value (111111111111111111111) out of range of int

---

第三步：数据校验（防御性编程）

如果业务要求 size 必须是较小的数值，可添加校验逻辑：

public class EsSearchResultRequest {
    @Min(value = 1, message = "size 最小为 1")
    @Max(value = 1000, message = "size 最大为 1000")
    private Long size;
    // 其他字段...
}

校验失败时提示：

size 最大为 1000

---

四、扩展知识：为什么不用 Integer？

类型	范围	推荐场景
int	-2³¹ ~ 2³¹-1	小数值（如状态码）
Long	-2⁶³ ~ 2⁶³-1	大数值（如 ID、时间戳）
BigInteger	无限（内存限制）	天文数字

经验法则：

• 不确定数值大小时，优先用 Long。
• 永远不要用 int 存储可能超大的值！

---

五、常见问题 FAQ

1. 前端传的是字符串，也会报错吗？

• 不会！如果 JSON 中 size 是字符串 "111111111111111111111"，需在后端用 String 类型接收，再手动转换。

2. 数据库字段类型需要改吗？

• 如果 size 要存到数据库（如 MySQL），记得同步修改为 BIGINT，否则会插入失败！

3. 为什么异常处理要捕获 HttpMessageNotReadableException？

• 这是 Spring 在解析请求体失败时抛出的"总异常"，涵盖所有 JSON 解析错误（如类型不匹配、格式错误等）。

---

六、总结：避坑指南

1. 设计阶段 ：根据业务场景选择合适的数据类型。
   • 不确定时，无脑用 Long！
2. 编码阶段 ：
   • 添加数据校验（如 @Min、@Max）。
   • 全局异常处理，返回友好提示。
3. 协作阶段 ：
   • 告知前端参数范围和格式要求。
   • 更新接口文档，明确 size 的类型和限制。

---