跳到主要内容
版本：4.4.3

自定义转换

DeepSeek V3 中英对照 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 附带了一组预定义的转换器注册：

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

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

转换器消歧义​

通常，我们会检查 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> { … }

基于类型的转换器​

影响映射结果的最简单方法是通过 @Field 注解指定所需的原生 MongoDB 目标类型。这使得可以在领域模型中使用非 MongoDB 类型（如 BigDecimal），同时以原生的 org.bson.types.Decimal128 格式持久化值。

示例 1. 显式目标类型映射

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
}

  • 表示有效 ObjectId 的字符串 id 值会被自动转换。详情请参阅 映射层中 _id 字段的处理方式。

  • 目标类型被明确定义为 Decimal128，这会被转换为 NumberDecimal。否则，BigDecimal 值会被转换为 String。

  • Date 值由 MongoDB 驱动程序本身处理，并存储为 ISODate。

上面的代码片段对于提供简单的类型提示非常方便。为了更精细地控制映射过程，你可以使用 MongoConverter 实现（例如 MappingMongoConverter）来注册 Spring 转换器。

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

备注

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

编写转换器​

以下示例展示了如何实现一个将 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;
  }
}

读取转换器​

以下示例展示了一个 Converter 的实现，它将 Document 转换为 Person 对象：

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

注册转换器​

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