Precise Formatting Solutions for Money Field Serialization with Jackson in Java

Background and Challenges

In modern web application development, JSON has become the mainstream format for data exchange. Java developers frequently use the Jackson library for serialization and deserialization between objects and JSON. However, when dealing with financial or monetary data, a common yet often overlooked issue is the precise formatting of numerical values. Specifically, when using the BigDecimal type to represent amounts, even after setting two decimal places via the setScale(2) method, trailing zeros (such as the last zero in 25.50) may be omitted during JSON serialization, resulting in data being displayed as 25.5 on the client side. This inconsistency not only affects user experience but can also lead to calculation errors in strict financial systems.

Core Solution: Custom Serializer

To address this issue, the most direct and flexible approach is to create a custom Jackson serializer. By extending the JsonSerializer<BigDecimal> class, developers can fully control how BigDecimal values are converted to JSON strings. Below is a complete implementation example:

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;
import java.io.IOException;
import java.math.BigDecimal;

public class MoneySerializer extends JsonSerializer<BigDecimal> {
    @Override
    public void serialize(BigDecimal value, JsonGenerator jgen, SerializerProvider provider) 
            throws IOException {
        // Set scale to 2 decimal places with rounding rule
        String formattedValue = value.setScale(2, BigDecimal.ROUND_HALF_UP).toString();
        jgen.writeString(formattedValue);
    }
}

In the entity class, apply the custom serializer to the target field using the @JsonSerialize annotation:

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import java.math.BigDecimal;

public class MoneyBean {
    @JsonProperty("amountOfMoney")
    @JsonSerialize(using = MoneySerializer.class)
    private BigDecimal amount;

    // Standard getter and setter methods
    public BigDecimal getAmount() {
        return amount;
    }

    public void setAmount(BigDecimal amount) {
        this.amount = amount;
    }
}

Test serialization with ObjectMapper:

import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.Test;
import java.math.BigDecimal;
import static org.junit.Assert.assertEquals;

public class MoneySerializationTest {
    @Test
    public void testJsonSerialization() throws Exception {
        MoneyBean moneyBean = new MoneyBean();
        moneyBean.setAmount(new BigDecimal("20.3"));

        ObjectMapper mapper = new ObjectMapper();
        String json = mapper.writeValueAsString(moneyBean);
        
        // Verify output format is 20.30
        assertEquals("{\"amountOfMoney\":\"20.30\"}", json);
    }
}

The advantages of this method include: 1) precise control over output format, ensuring two decimal places are always displayed; 2) support for complex formatting logic, such as currency symbols or thousand separators; 3) decoupling from business logic, allowing the serializer to be reused.

Alternative Approaches

Beyond custom serializers, Jackson offers other configuration options suitable for different scenarios:

Using @JsonFormat Annotation: The @JsonFormat(shape=JsonFormat.Shape.STRING) annotation forces the BigDecimal field to be serialized as a string, preserving its original format. This approach is simple and quick but lacks fine-grained control over formatting details like decimal places.

import com.fasterxml.jackson.annotation.JsonFormat;
import java.math.BigDecimal;

public class SimpleMoneyBean {
    @JsonFormat(shape = JsonFormat.Shape.STRING)
    private BigDecimal amount;
    
    // Getters and setters omitted
}

Global Module Configuration: For large-scale projects, if the same serialization rules need to be applied to all BigDecimal types, this can be achieved by registering a custom module:

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.module.SimpleModule;

public class GlobalSerializationConfig {
    public static void configureObjectMapper(ObjectMapper mapper) {
        SimpleModule module = new SimpleModule();
        module.addSerializer(BigDecimal.class, new MoneySerializer());
        mapper.registerModule(module);
    }
}

This method avoids repetitive annotations on each field but may affect other BigDecimal fields that do not require formatting, so careful evaluation is needed.

Best Practices and Recommendations

When selecting a serialization strategy, consider the following factors:

1. Precision Requirements: Financial systems must ensure accurate representation of amounts, making custom serializers the most reliable choice.
2. Code Maintainability: If there are numerous monetary fields in a project, global module configuration might be more efficient; if only a few fields need special handling, annotation-based approaches are clearer.
3. Performance Impact: Custom serializers add minimal overhead, which is negligible in most applications. For high-performance scenarios, consider caching formatted results.
4. Client Compatibility: Serializing amounts as strings (rather than numbers) avoids floating-point precision issues in JavaScript, ensuring consistency between frontend and backend data.

Additionally, it is advisable to cover edge cases in unit tests, such as zero values (0.00), large amounts, and negative values, to ensure serialization behavior meets expectations.

Conclusion

The Jackson library offers multiple mechanisms to handle the formatting of BigDecimal fields during serialization. Through custom JsonSerializer implementations, developers can achieve precise two-decimal-place output for monetary amounts, meeting the stringent requirements of financial applications. Alternative approaches like the @JsonFormat annotation and global module configuration provide flexibility for different scenarios. In practice, the most suitable strategy should be selected based on project needs, supplemented with thorough testing to ensure data integrity and accuracy throughout the serialization process.