Type based Converter

Custom Conversions

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

@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 注释在转换器实现中使用。由于不会从类路径或容器扫描中拾取转换器实例，因此必须显式注册转换器，以避免对转换服务进行不必要的注册以及由此注册产生的副作用。转换器使用 CustomConversions 注册，CustomConversions 是一个中心设施，允许基于源类型和目标类型注册和查询已注册的转换器。 CustomConversions 附带一组预定义的转换器注册：

JSR-310 转换器，用于在 java.time、java.util.Date 和 String 类型之间进行转换。

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

Converter Disambiguation

总体而言，我们检查 Converter 实现从哪些源类型和目标类型进行转换以及转换到哪些源类型和目标类型。根据其中一个是否是底层数据访问 API 本机可以处理的类型，我们将转换器实例注册为读转换器或写转换器。以下示例显示了写转换器和读转换器（请注意，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 格式永久存储值。

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>  表示有效的 `ObjectId` 的字符串 _id_ 值会自动转换。请参阅 xref:mongodb/template-crud-operations.adoc#mongo-template.id-handling[How the `_id` Field is Handled in the Mapping Layer] 了解更多详细信息。
<1>  所需的目标类型被明确定义为 `Decimal128`，转化成 `NumberDecimal`。否则 `BigDecimal` 值会被转化成 `String`。
<1>  `Date` 值由 MongoDB 驱动程序本身处理，并存储为 `ISODate`。

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

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

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

Writing Converter

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

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 实现：

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());
	}
}