Why Returning Java Longs as JSON Can Break Your Frontend: IEEE754 Explained

Background

On August 3 the "Java Development Manual (Songshan edition)" added a front‑back‑end convention that forbids servers from returning a Long value for extremely large integers. The article explains why this rule exists and what problems may arise.

Key Questions

What is the maximum safe integer that JavaScript Number can represent?

Can powers of two within the Long range be safely converted to Number?

How does precision loss occur when converting decimal numbers to binary floating‑point?

What solutions exist if a server must return a large integer?

Fundamental Review – IEEE‑754 Double Precision

Double‑precision floating‑point numbers occupy 8 bytes (64 bits): 1 sign bit, 11 exponent bits, and 52 fraction bits. The exponent is stored as a bias (1023). The value is computed as (-1)^s * (1 + m/2^52) * 2^(E‑1023).

illustrates the bit layout.

Conversion Details

Because the fraction provides only 53 effective bits, the largest integer that can be represented without loss is 2^53‑1. Numbers larger than this (e.g., 2^53) lose precision, as demonstrated by 9007199254740992 + 1 == 9007199254740992.

Even powers of two that fit in a Long may be rounded incorrectly; for example 2^55 is displayed as 36028797018963970 instead of 36028797018963968.

Why the Rounding Happens

When a decimal is stored as a binary floating‑point number, the value is rounded to the nearest representable binary fraction. The output algorithm then chooses the shortest decimal that maps back to the same binary value, which can hide the original integer.

Practical Solutions

To avoid precision loss when returning large integers from a Java backend:

Convert the Long to String before JSON serialization.

Use a serializer feature such as SerializerFeature.BrowserCompatible that automatically converts numbers to strings.

If the API cannot be changed, introduce a new string field for the ID and deprecate the old Long field.

On the client side, libraries like js‑2‑java can parse the string back to a Java Long.

Conclusion

Understanding IEEE‑754 and JavaScript number limits is essential for designing robust APIs. Keeping integer values within 2^53‑1 or transmitting them as strings prevents silent data corruption.