Spring处理字段格式化的实战指南

更新时间：2025年10月27日 10:15:29 作者：lang20150928

本文讲解 Spring 如何在客户端环境（如 Web 应用）中处理字段的格式化与解析,特别是字符串与对象之间的双向转换,并支持国际化（Locale）,将从整体架构、核心概念、SPI 接口、使用方式和实际应用五个维度,帮你系统性地理解,需要的朋友可以参考下

一、整体架构：Spring 类型转换体系

Spring 提供了两套互补的类型转换机制：

模块	用途	特点
`core.convert` 包下的 `Converter` SPI	通用类型转换（如 `Long` ↔ `Date`）	通用性强，不涉及字符串格式化或 Locale
`format` 包下的 `Formatter` SPI	客户端字段格式化（如 `String` ↔ `Date`，带格式和语言）	面向 UI 层，支持 `Locale`，适合 Web 应用

它们都由一个统一的服务接口管理：
ConversionService —— 是 Spring 内部进行类型转换的核心接口。

关键点：

Converter：用于任意类型之间转换（后台逻辑用）。
Formatter：专门用于 String 和目标类型之间转换（前端展示/提交用）。
两者都被 ConversionService 管理，可共存。

二、核心概念：Formatter SPI

1. Formatter<T> 接口

这是 Spring 为“客户端字段格式化”设计的核心接口：

public interface Formatter<T> extends Printer<T>, Parser<T> {
}

它由两个子接口组成：

(1) Printer<T>：对象 → 字符串（用于显示）

String print(T fieldValue, Locale locale);

把 Java 对象（如 Date）按指定语言环境（Locale）格式化成字符串，用于页面展示。
例如：new Date() → "2025-04-05"

(2) Parser<T>：字符串 → 对象（用于解析请求）

T parse(String clientValue, Locale locale) throws ParseException;

把用户提交的字符串（如表单输入）解析为 Java 对象。
例如："2025-04-05" → java.util.Date

要求：

实现必须是 线程安全 的（因为会被多个请求共享）。
解析失败应抛出 ParseException 或 IllegalArgumentException。

2. 内置 Formatter 实现（开箱即用）

Spring 提供了一些常用的 Formatter 实现：

Formatter	作用
`NumberStyleFormatter`	格式化数字（支持千分位、小数点等）
`CurrencyStyleFormatter`	显示货币（如 ¥1,234.00）
`PercentStyleFormatter`	百分比显示（如 50%）
`DateFormatter`	用 `SimpleDateFormat` 格式化日期

示例：DateFormatter 实现了 print() 和 parse()，使用 pattern 和 Locale 来格式化日期。

三、高级特性：注解驱动的格式化（Annotation-driven Formatting）

为了更方便地配置格式化规则，Spring 支持通过 注解 + 工厂模式 来绑定格式化逻辑。

1. AnnotationFormatterFactory<A extends Annotation>

这个接口的作用是：将某个注解映射到具体的 Printer 和 Parser

public interface AnnotationFormatterFactory<A extends Annotation> {
    Set<Class<?>> getFieldTypes();        // 支持哪些字段类型？
    Printer<?> getPrinter(A annotation, Class<?> fieldType);
    Parser<?> getParser(A annotation, Class<?> fieldType);
}

示例：NumberFormatAnnotationFormatterFactory

它处理 @NumberFormat 注解：

@NumberFormat(style = Style.CURRENCY)
private BigDecimal price;

当 Spring 遇到这个字段时，会查找注册的 AnnotationFormatterFactory
找到后调用 getPrinter() / getParser() 获取对应的格式化工厂
最终使用 CurrencyStyleFormatter 来格式化金额

2. 常见格式化注解（在 org.springframework.format.annotation 包下）

注解	用途
`@NumberFormat`	数字格式化（支持 pattern 或 style）
`@DateTimeFormat`	日期时间格式化（支持 ISO 格式、自定义 pattern）

示例：

public class MyModel {
    @DateTimeFormat(iso = ISO.DATE)  // 格式：yyyy-MM-dd
    private Date birthDate;

    @NumberFormat(pattern = "#,###.00")
    private Double salary;
}

这样就不需要在每个 controller 里手动写 new SimpleDateFormat(...)，而是统一管理。

四、注册机制 SPI：如何让 Spring 知道你的 Formatter？

Spring 提供了几个 SPI 接口来注册格式化器。

1. FormatterRegistry（核心注册中心）

它是 ConverterRegistry 的扩展，允许你注册：

void addFormatterForFieldType(Class<?> fieldType, Formatter<?> formatter);
void addFormatterForAnnotation(AnnotationFormatterFactory<?> factory);

所有 formatter/converter 都要注册到这里才能生效。

2. FormattingConversionService（推荐实现类）

这是一个标准实现，实现了 ConversionService + FormatterRegistry，适合大多数场景。

你可以：

编程式注册（Java Config）
声明式注册（XML）

3. FormatterRegistrar（批量注册工具）

有时候你需要一次性注册多个 formatter（比如所有日期相关的），但直接注册不方便（比如类型擦除问题），这时可以用：

public interface FormatterRegistrar {
    void registerFormatters(FormatterRegistry registry);
}

常见用途：

注册 Joda-Time 所有格式化器
设置全局日期格式
批量注册 JSR-310 (java.time) 类型的 formatter

五、实战应用：如何配置全局日期格式？

默认情况下，未标注 @DateTimeFormat 的 Date 字段会用 DateFormat.SHORT（如 4/5/25）格式化，这通常不符合中国习惯。

目标：设置全局日期格式为 yyyyMMdd

方法一：Java 配置（推荐）

@Configuration
public class AppConfig {

    @Bean
    public FormattingConversionService conversionService() {
        // 创建 ConversionService，但不注册默认 formatter
        DefaultFormattingConversionService service = new DefaultFormattingConversionService(false);

        // 保留 @NumberFormat 支持
        service.addFormatterForFieldAnnotation(new NumberFormatAnnotationFormatterFactory());

        // 设置全局日期格式：yyyyMMdd
        DateFormatterRegistrar registrar = new DateFormatterRegistrar();
        registrar.setFormatter(new DateFormatter("yyyyMMdd"));
        registrar.registerFormatters(service);

        return service;
    }
}

方法二：XML 配置（传统项目）

<bean id="conversionService" class="org.springframework.format.support.FormattingConversionServiceFactoryBean">
    <property name="registerDefaultFormatters" value="false"/>
    <property name="formatters">
        <set>
            <bean class="org.springframework.format.number.NumberFormatAnnotationFormatterFactory"/>
        </set>
    </property>
    <property name="formatterRegistrars">
        <set>
            <bean class="org.springframework.format.datetime.joda.JodaTimeFormatterRegistrar">
                <property name="dateFormatter">
                    <bean class="org.springframework.format.datetime.joda.DateTimeFormatterFactoryBean">
                        <property name="pattern" value="yyyyMMdd"/>
                    </bean>
                </property>
            </bean>
        </set>
    </property>
</bean>

六、总结：一句话理解全文

Spring 的 Formatter SPI 是为 客户端环境（如 Web 页面）设计的一套 基于 Locale 的字符串 ↔ 对象 转换机制，相比通用的 Converter，它更适合处理用户输入和输出的格式化需求，且支持注解驱动（如 @DateTimeFormat）、可集中配置、易于扩展。

七、常见问题解答（FAQ）

Q1: Formatter 和 PropertyEditor 有什么区别？

PropertyEditor 是 JavaBeans 规范的老技术，线程不安全，API 不够灵活。
Formatter 是 Spring 3 新引入的，线程安全、强类型、支持 Locale，推荐替代 PropertyEditor。

Q2: 在 Spring MVC 中怎么启用这些 formatter？

只要把自定义的 FormattingConversionService 注入到 Spring MVC 的配置中即可：

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addFormatter(new DateFormatter("yyyyMMdd"));
    }
}

或者使用 <mvc:annotation-driven conversion-service="conversionService"/> XML 配置。

Q3: JSR-310 时间类（LocalDate、LocalDateTime）支持吗？

支持！Spring 会自动注册 java.time 类型的 formatter。你可以通过 DateTimeFormatterRegistrar 控制其格式。

如果你正在开发 Web 应用，尤其是需要处理表单提交、日期显示、货币格式等功能，那么这一套 Formatter 机制就是你应该掌握的核心技能之一。

需要我根据你的具体场景（比如 Spring Boot 项目）给出一个完整的配置示例吗？

以上就是Spring处理字段格式化的实战指南的详细内容，更多关于Spring处理字段格式化的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

JavaBean valication验证实现方法示例
这篇文章主要介绍了JavaBean valication验证实现方法,结合实例形式分析了JavaBean valication验证相关概念、原理、用法及操作注意事项,需要的朋友可以参考下
2020-03-03
Java中的Map集合简单汇总解析
这篇文章主要介绍了Java中的Map集合简单汇总解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2019-10-10
java获取Date类型的年份实例代码
这篇文章主要给大家介绍了关于java如何获取Date类型的年份,针对java获取Date时间的各种方式汇总,有常用的时间获取方式,还有一些其他特殊时间获取方式,需要的朋友可以参考下
2024-06-06
Spring Data Jpa实现自定义repository转DTO
这篇文章主要介绍了Spring Data Jpa实现自定义repository转DTO,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-08-08
Maven setting.xml配置文件详解
本篇文章主要介绍了Maven setting.xml 配置文件详解，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2017-12-12
SpringBoot+Dubbo+Zookeeper知识整合过程详解
本文首先介绍了分布式系统的基本概念和分类,包括单一应用架构、垂直应用架构、分布式服务架构和流动计算架构,通过一个完整的Spring Boot + Dubbo + Zookeeper框架搭建示例,展示了如何将这些技术整合到一个实际的项目中,感兴趣的朋友一起看看吧
2025-02-02
java对象初始化代码详解
这篇文章主要介绍了java对象初始化代码详解，涉及实例变量的初始化，类变量的初始化等相关介绍几代码示例，具有一定参考价值，需要的朋友可以了解下。
2017-11-11
Java中CountDownLatch工具类详细解析
这篇文章主要介绍了Java中CountDownLatch工具类详细解析,创建CountDownLatch对象时,会传入一个count数值,该对象每次调用countDown()方法会使count -- ,就是count每次减1,需要的朋友可以参考下
2023-11-11
Spring Boot教程之提高开发效率必备工具lombok
这篇文章主要介绍了Spring Boot教程之提高开发效率必备工具lombok的相关资料,需要的朋友可以参考下
2022-08-08
java反射总结实例详解
这篇文章主要结合实例形式分析了介绍了java基于反射得到对象属性值的方法,Class类，基本数据类型，类的反射等，需要的朋友可以参考下
2017-04-04