Type based Converter

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> { … }

Type based Converter

影响映射结果的最简单方式是通过 @Field 注解指定所需的本机 MongoDB 目标类型。这允许在处理域模型中非 MongoDB 类型（如 BigDecimal）的同时，以本机 org.bson.types.Decimal128 格式永久存储值。

The most trivial way of influencing the mapping result is by specifying the desired native MongoDB target type via the @Field annotation. This allows to work with non MongoDB types like BigDecimal in the domain model while persisting values in native org.bson.types.Decimal128 format.

Example 1. Explicit target type mapping
public class Payment {

  @Id String id; 1

  @Field(targetType = FieldType.DECIMAL128) 2
  BigDecimal value;

  Date date; 3

}
{
  "_id"   : ObjectId("5ca4a34fa264a01503b36af8"), 1
  "value" : NumberDecimal(2.099), 2
  "date"   : ISODate("2019-04-03T12:11:01.870Z") 3
}
1 String id values that represent a valid ObjectId are converted automatically. See How the _id Field is Handled in the Mapping Layer for details.
2 The desired target type is explicitly defined as Decimal128 which translates to NumberDecimal. Otherwise the BigDecimal value would have been truned into a String.
3 Date values are handled by the MongoDB driver itself an are stored as ISODate.

上面的片段便于提供简单的类型提示。为了对映射过程进行更细粒度的控制，您可以使用 MongoConverter 实现（如 MappingMongoConverter）来注册 Spring 转换器。

The snippet above is handy for providing simple type hints. To gain more fine-grained control over the mapping process, you can register Spring converters with the MongoConverter implementations, such as the MappingMongoConverter.

MappingMongoConverter 在尝试映射对象本身之前会检查是否有任何 Spring 转换器可以处理特定的类。要“劫持”MappingMongoConverter 的正常映射策略（可能是为了提高性能或其他自定义映射需求），首先需要创建 Spring Converter 接口的实现，然后使用 MappingConverter 注册该实现。

The MappingMongoConverter checks to see if any Spring converters can handle a specific class before attempting to map the object itself. To 'hijack' the normal mapping strategies of the MappingMongoConverter, perhaps for increased performance or other custom mapping needs, you first need to create an implementation of the Spring Converter interface and then register it with the MappingConverter.

有关 Spring 类型转换服务的更多信息，请参阅参考文档 here。

For more information on the Spring type conversion service, see the reference docs here.

Writing Converter

以下示例显示了从 Person 对象转换为 org.bson.Document 的 Converter 实现：

The following example shows an implementation of the Converter that converts from a Person object to a org.bson.Document:

import org.springframework.core.convert.converter.Converter;

import org.bson.Document;

public class PersonWriteConverter implements Converter<Person, Document> {

  public Document convert(Person source) {
    Document document = new Document();
    document.put("_id", source.getId());
    document.put("name", source.getFirstName());
    document.put("age", source.getAge());
    return document;
  }
}

Reading Converter

以下示例显示了从 Document 转换为 Person 对象的 Converter 实现：

The following example shows an implementation of a Converter that converts from a Document to a Person object:

public class PersonReadConverter implements Converter<Document, Person> {

  public Person convert(Document source) {
    Person p = new Person((ObjectId) source.get("_id"), (String) source.get("name"));
    p.setAge((Integer) source.get("age"));
    return p;
  }
}

Registering Converters

class MyMongoConfiguration extends AbstractMongoClientConfiguration {

	@Override
	public String getDatabaseName() {
		return "database";
	}

	@Override
	protected void configureConverters(MongoConverterConfigurationAdapter adapter) {
		adapter.registerConverter(new com.example.PersonReadConverter());
		adapter.registerConverter(new com.example.PersonWriteConverter());
	}
}