Custom Conversions

Spring Converter 实现的以下示例将 String 转换为自定义 Email 值对象：

The following example of a Spring Converter implementation converts from a String to a custom Email value object:

@ReadingConverter
public class EmailReadConverter implements Converter<String, Email> {

  public Email convert(String source) {
    return Email.valueOf(source);
  }
}

如果您编写一个其源类型和目标类型都是本机类型的 Converter，我们将无法确定是否应该将其视为读转换器还是写转换器。将转换器实例同时注册为两个实例可能会导致意外结果。例如，Converter<String, Long> 是有歧义的，尽管在编写时尝试将所有 String 实例转换为 Long 实例可能没有意义。为了强制基础设施仅为单向注册一个转换器，我们提供 @ReadingConverter 和 @WritingConverter 注释在转换器实现中使用。

If you write a Converter whose source and target type are native types, we cannot determine whether we should consider it as a reading or a writing converter. Registering the converter instance as both might lead to unwanted results. For example, a Converter<String, Long> is ambiguous, although it probably does not make sense to try to convert all String instances into Long instances when writing. To let you force the infrastructure to register a converter for only one way, we provide @ReadingConverter and @WritingConverter annotations to be used in the converter implementation.

由于不会从类路径或容器扫描中拾取转换器实例，因此必须显式注册转换器，以避免对转换服务进行不必要的注册以及由此注册产生的副作用。转换器使用 CustomConversions 注册，CustomConversions 是一个中心设施，允许基于源类型和目标类型注册和查询已注册的转换器。

Converters are subject to explicit registration as instances are not picked up from a classpath or container scan to avoid unwanted registration with a conversion service and the side effects resulting from such a registration. Converters are registered with CustomConversions as the central facility that allows registration and querying for registered converters based on source- and target type.

CustomConversions 附带一组预定义的转换器注册：

CustomConversions ships with a pre-defined set of converter registrations:

  • JSR-310 Converters for conversion between java.time, java.util.Date and String types.

本地时间类型的默认转换器（例如 LocalDateTime 到 java.util.Date）依赖于系统默认时区设置在这些类型之间进行转换。你可以通过注册自己的转换器来覆盖默认转换器。

Default converters for local temporal types (e.g. LocalDateTime to java.util.Date) rely on system-default timezone settings to convert between those types. You can override the default converter, by registering your own converter.

Converter Disambiguation

总体而言，我们检查 Converter 实现从哪些源类型和目标类型进行转换以及转换到哪些源类型和目标类型。根据其中一个是否是底层数据访问 API 本机可以处理的类型，我们将转换器实例注册为读转换器或写转换器。以下示例显示了写转换器和读转换器（请注意，Converter 上的限定词的顺序存在差异）：

Generally, we inspect the Converter implementations for the source and target types they convert from and to. Depending on whether one of those is a type the underlying data access API can handle natively, we register the converter instance as a reading or a writing converter. The following examples show a writing- and a read converter (note the difference is in the order of the qualifiers on Converter):

// Write converter as only the target type is one that can be handled natively
class MyConverter implements Converter<Person, String> { … }

// Read converter as only the source type is one that can be handled natively
class MyConverter implements Converter<String, Person> { … }