对于最新的稳定版本，请使用 Spring Integration 6.4.3！spring-doc.cadn.net.cn

转换器

消息转换器在实现消息生成者和消息使用者的松散耦合方面起着非常重要的作用。 您可以在这些组件之间添加转换器，而不是要求每个消息生成组件都知道下一个使用者期望的类型。 泛型转换器，例如将String转换为 XML 文档，也可以高度重用。spring-doc.cadn.net.cn

对于某些系统，最好提供规范的数据模型，但 Spring 集成的一般理念是不需要任何特定的格式。 相反，为了获得最大的灵活性， Spring 集成旨在提供最简单的扩展模型。 与其他端点类型一样，在 XML 或 Java 注释中使用声明性配置使简单的 POJO 能够适应消息转换器的角色。 本章的其余部分介绍了这些配置选项。spring-doc.cadn.net.cn

为了最大限度地提高灵活性， Spring 不需要基于 XML 的消息有效负载。 尽管如此，如果这确实是您的应用程序的正确选择，那么该框架确实提供了一些方便的转换器来处理基于 XML 的有效负载。 有关这些转换器的更多信息，请参见 XML 支持 - 处理 XML 负载。

使用 Java 和其他 DSL 配置 Transformer

对于简单的Java和注释配置，Spring bean POJO方法必须用@Transformer注解，当从输入通道使用消息时，框架会调用它：spring-doc.cadn.net.cn

public class SomeService {

    @Transformer(inputChannel = "transformChannel", outputChannel = "nextServiceChannel")
    public OutputData exampleTransformer(InputData payload) {
        ...
    }

}

有关更多信息，请参阅注释支持。spring-doc.cadn.net.cn

对于 Java、Groovy 或 Kotlin DSL，.transform()运算符的IntegrationFlow表示 transformer 端点：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("transformChannel")
             .transform(someService, "exampleTransformer")
             .channel("nextServiceChannel")
             .get();
}
@Bean
fun someFlow() =
    integrationFlow("transformChannel") {
        transform(someService, "exampleTransformer")
        channel("nextServiceChannel")
    }
@Bean
someFlow() {
    integrationFlow 'transformChannel',
            {
                transform someService, 'exampleTransformer'
                channel 'nextServiceChannel'
            }
}

有关这些 DSL 的更多信息，请参阅相应的章节：spring-doc.cadn.net.cn

使用 XML 配置 Transformer

这<transformer>元素用于创建消息转换终端节点。 除了input-channel和output-channel属性，它需要一个ref属性。 这ref可能指向包含@Transformer注释（请参阅使用注释配置转换器），或者它可以与method属性。spring-doc.cadn.net.cn

<int:transformer id="testTransformer" ref="testTransformerBean" input-channel="inChannel"
             method="transform" output-channel="outChannel"/>
<beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />

使用ref属性，如果自定义转换器处理程序实现可以在其他<transformer>定义。 但是，如果自定义转换器处理程序实现的范围应限定为<transformer>，你可以定义一个内部 Bean 定义，如下例所示：spring-doc.cadn.net.cn

<int:transformer id="testTransformer" input-channel="inChannel" method="transform"
                output-channel="outChannel">
  <beans:bean class="org.foo.TestTransformer"/>
</transformer>
同时使用refattribute 和内部处理程序定义位于同一<transformer>不允许配置，因为它会产生不明确的条件并导致引发异常。
如果ref属性引用一个扩展AbstractMessageProducingHandler（例如框架本身提供的 transformers），通过将 output channel 直接注入到 handler 中来优化配置。 在这种情况下，每个ref必须发送到单独的 bean 实例（或prototype-scoped bean）或使用内部的<bean/>配置类型。 如果您无意中从多个 bean 引用了相同的消息处理程序，则会收到配置异常。

使用 POJO 时，用于转换的方法可能需要Messagetype 或入站消息的有效负载类型。 它还可以单独接受消息头值，或者通过使用@Header和@Headersparameter 注解。 该方法的返回值可以是任何类型。 如果返回值本身是一个Message，该通道将传递到 transformer 的 output 通道。spring-doc.cadn.net.cn

从 Spring Integration 2.0 开始，消息转换器的转换方法不能再返回null. 返回null会导致异常，因为应始终期望 Message Transformer 将每个源消息转换为有效的目标消息。 换句话说，消息转换器不应该用作消息过滤器，因为有一个专用的<filter>选项。 但是，如果您确实需要这种类型的行为（组件可能会返回null这不应被视为错误），您可以使用 Service Activator 。 其requires-replyvalue 为false默认情况下，但可以设置为true为了引发null返回值，就像 transformer 一样。spring-doc.cadn.net.cn

转换器和 Spring 表达式语言 （SpEL）

与路由器、聚合器和其他组件一样，从 Spring Integration 2.0 开始，只要转换逻辑相对简单，转换器也可以从 SPEL 支持中受益。 下面的示例展示了如何使用 SPEL 表达式：spring-doc.cadn.net.cn

<int:transformer input-channel="inChannel"
	output-channel="outChannel"
	expression="payload.toUpperCase() + '- [' + T(System).currentTimeMillis() + ']'"/>

前面的示例在不编写自定义转换器的情况下转换有效负载。 我们的 payload（假设为String） 是大写的，与当前时间戳连接，并应用了一些格式。spring-doc.cadn.net.cn

共 电 转换器

Spring 集成提供了一些 transformer 实现。spring-doc.cadn.net.cn

对象到字符串转换器

因为使用toString()表示Object中，Spring Integration 提供了一个ObjectToStringTransformer（另请参阅Transformersfactory），其中输出为Message替换为 Stringpayload. 那String是调用toString()作。 下面的示例演示如何声明 object-to-string 转换器的实例：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("in")
             .transform(Transformers.objectToString())
             .channel("out")
             .get();
}
@Bean
fun someFlow() =
    integrationFlow("in") {
        transform(Transformers.objectToString())
        channel("out")
    }
@Bean
someFlow() {
    integrationFlow 'in',
            {
                transform Transformers.objectToString()
                channel 'out'
            }
}
<int:object-to-string-transformer input-channel="in" output-channel="out"/>

这个转换器的一个潜在用途是向fileNamespace。 而该 channel 适配器仅支持String、byte-array 或java.io.Filepayloads 中，在 Adapter 处理必要的转换之前立即添加此转换器。 只要toString()call 是你想要写入文件的内容。 否则，您可以使用前面显示的通用 'transformer' 元素来提供基于 POJO 的自定义 transformer。spring-doc.cadn.net.cn

调试时，通常不需要此转换器，因为logging-channel-adapter能够记录消息负载。 有关更多详细信息，请参见 Wire Tap。

对象到字符串转换器非常简单。 它调用toString()在入站有效负载上。 从 Spring Integration 3.0 开始，这条规则有两个例外：spring-doc.cadn.net.cn

  • 如果有效负载是char[]，它会调用new String(payload).spring-doc.cadn.net.cn

  • 如果有效负载是byte[]，它会调用new String(payload, charset)哪里charset默认为 UTF-8。 这charset可以通过在 transformer 上提供 charset 属性来修改。spring-doc.cadn.net.cn

对于更复杂的作（例如在运行时动态选择字符集），可以改用基于 SPEL 表达式的转换器，如下例所示：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("in")
             .transform("new String(payload, headers['myCharset']")
             .channel("out")
             .get();
}
<int:transformer input-channel="in" output-channel="out"
       expression="new String(payload, headers['myCharset']" />

如果您需要序列化Object转换为字节数组，或将字节数组反序列化回Object，Spring Integration 提供了对称的序列化转换器。 默认情况下，这些使用标准的 Java 序列化，但你可以提供 Spring 的实现Serializer或Deserializer策略serializer和deserializer属性。 另请参阅Transformersfactory 类。 下面的示例展示了如何使用 Spring 的序列化器和反序列化器：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("objectsIn")
             .transform(Transformers.serializer())
             .channel("bytesOut")
             .channel("bytesIn")
             .transform(Transformers.deserializer("com.mycom.*", "com.yourcom.*"))
             .channel("objectsOut")
             .get();
}
<int:payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>

<int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"
    allow-list="com.mycom.*,com.yourcom.*"/>
当反序列化来自不受信任来源的数据时，您应该考虑添加allow-list的包和类模式。 默认情况下，所有类都被反序列化。

Object-自-Map和Map-自-Object变形金刚

Spring 集成还提供Object-自-Map和Map-自-Objecttransformers，它使用 JSON 来序列化和反序列化对象图。 对象层次结构被内省到最原始的类型 （String,int等）。 此类型的路径由 SPEL 描述，它将成为key在变换的Map. 基元类型变为值。spring-doc.cadn.net.cn

请考虑以下示例：spring-doc.cadn.net.cn

public class Parent{
    private Child child;
    private String name;
    // setters and getters are omitted
}

public class Child{
    private String name;
    private List<String> nickNames;
    // setters and getters are omitted
}

前面示例中的两个类将转换为以下内容Map:spring-doc.cadn.net.cn

{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Jen ...}

基于 JSON 的Map允许您在不共享实际类型的情况下描述对象结构，这样，只要您保持结构，就可以将对象图还原并重新构建为不同类型的对象图。spring-doc.cadn.net.cn

例如，可以使用Map-自-Object转换器：spring-doc.cadn.net.cn

public class Father {
    private Kid child;
    private String name;
    // setters and getters are omitted
}

public class Kid {
    private String name;
    private List<String> nickNames;
    // setters and getters are omitted
}

如果您需要创建“结构化”映射，则可以提供flatten属性。 默认值为 'true'。 如果将其设置为 'false'，则结构为Map之Map对象。spring-doc.cadn.net.cn

请考虑以下示例：spring-doc.cadn.net.cn

public class Parent {
	private Child child;
	private String name;
	// setters and getters are omitted
}

public class Child {
	private String name;
	private List<String> nickNames;
	// setters and getters are omitted
}

前面示例中的两个类将转换为以下内容Map:spring-doc.cadn.net.cn

{name=George, child={name=Jenna, nickNames=[Bimbo, ...]}}

为了配置这些转换器， Spring 集成提供了相应的 XML 组件和 Java DSL 工厂：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("directInput")
             .transform(Transformers.toMap())
             .channel("output")
             .get();
}
<int:object-to-map-transformer input-channel="directInput" output-channel="output"/>

您还可以设置flatten属性设置为 false，如下所示：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("directInput")
             .transform(Transformers.toMap(false))
             .channel("output")
             .get();
}
<int:object-to-map-transformer input-channel="directInput" output-channel="output" flatten="false"/>

Spring 集成为 Map-to-Object 提供了 XML 名称空间支持，Java DSL 工厂具有fromMap()方法，如下例所示：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("input")
             .transform(Transformers.fromMap(org.something.Person.class))
             .channel("output")
             .get();
}
<int:map-to-object-transformer input-channel="input"
                         output-channel="output"
                         type="org.something.Person"/>

或者，您可以使用ref属性和原型范围的 bean，如下例所示：spring-doc.cadn.net.cn

@Bean
IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("inputA")
             .transform(Transformers.fromMap("person"))
             .channel("outputA")
             .get();
}

@Bean
@Scope("prototype")
Person person() {
    return new Person();
}
<int:map-to-object-transformer input-channel="inputA"
                               output-channel="outputA"
                               ref="person"/>
<bean id="person" class="org.something.Person" scope="prototype"/>
'ref' 和 'type' 属性是互斥的。 此外，如果使用 'ref' 属性，则必须指向 'prototype' 范围的 bean。 否则，一个BeanCreationException被抛出。

从版本 5.0 开始，您可以提供ObjectToMapTransformer使用自定义的JsonObjectMapper— 当您需要特殊格式的日期或空集合的 null（和其他用途）时。 有关更多信息，请参阅 JSON 转换器JsonObjectMapper实现。spring-doc.cadn.net.cn

Stream Transformer

这StreamTransformer变换InputStreampayloads 添加到byte[]（ 或String如果charset）。spring-doc.cadn.net.cn

以下示例演示如何使用stream-transformer元素：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("input")
             .transform(Transformers.fromStream("UTF-8"))
             .channel("output")
             .get();
}
<int:stream-transformer input-channel="directInput" output-channel="output"/> <!-- byte[] -->

<int:stream-transformer id="withCharset" charset="UTF-8"
    input-channel="charsetChannel" output-channel="output"/> <!-- String -->

以下示例演示如何使用StreamTransformer类和@Transformer注解在 Java 中配置流转换器：spring-doc.cadn.net.cn

@Bean
@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToBytes() {
    return new StreamTransformer(); // transforms to byte[]
}

@Bean
@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToString() {
    return new StreamTransformer("UTF-8"); // transforms to String
}

JSON 转换器

Spring 集成提供了 Object-to-JSON 和 JSON to-Object 转换器。 下面的一对示例演示如何在 XML 中声明它们：spring-doc.cadn.net.cn

<int:object-to-json-transformer input-channel="objectMapperInput"/>

<int:json-to-object-transformer input-channel="objectMapperInput"
    type="foo.MyDomainObject"/>

默认情况下，前面清单中的 transformer 使用 vanillaJsonObjectMapper. 它基于 Classpath 中的实现。 您可以提供自己的自定义JsonObjectMapperimplementation 或基于所需的库（例如 GSON），如下例所示：spring-doc.cadn.net.cn

<int:json-to-object-transformer input-channel="objectMapperInput"
    type="something.MyDomainObject" object-mapper="customObjectMapper"/>

从版本 3.0 开始，object-mapperattribute 引用新策略接口的实例：JsonObjectMapper. 此抽象允许使用 JSON 映射器的多个实现。 提供了包装 Jackson 2 的实现，并在 Classpath 上检测到版本。 类为Jackson2JsonObjectMapper分别。spring-doc.cadn.net.cn

您可能希望考虑使用FactoryBean或工厂方法来创建JsonObjectMapper具有所需的特性。 下面的示例展示了如何使用这样的工厂：spring-doc.cadn.net.cn

public class ObjectMapperFactory {

    public static Jackson2JsonObjectMapper getMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
        return new Jackson2JsonObjectMapper(mapper);
    }
}

下面的示例展示了如何在 XML 中执行相同的作：spring-doc.cadn.net.cn

<bean id="customObjectMapper" class="something.ObjectMapperFactory"
            factory-method="getMapper"/>

从版本 2.2 开始，object-to-json-transformer将content-typeheader 设置为application/json，如果输入消息还没有该标头。spring-doc.cadn.net.cn

如果您希望将content-typeheader 设置为其他值，或者使用某些值（包括application/json），请使用content-type属性。 如果要禁止显示标头的设置，请将content-type属性设置为空字符串 （）。 这样做会导致消息中没有""content-type标头，除非 Importing 消息中存在此类标头。spring-doc.cadn.net.cn

从版本 3.0 开始，ObjectToJsonTransformer将反映 Source 类型的 Headers 添加到消息中。 同样，JsonToObjectTransformer在将 JSON 转换为对象时可以使用这些类型标头。 这些 Headers 在 AMQP 适配器中映射，因此它们与 Spring-AMQP 完全兼容JsonMessageConverter.spring-doc.cadn.net.cn

这使以无需任何特殊配置即可工作：spring-doc.cadn.net.cn

使用 Headers 确定类型时，不应提供class属性，因为它优先于标头。

除了 JSON 转换器之外， Spring 集成还提供了一个内置的#jsonPath用于表达式的 SPEL 函数。 有关更多信息，请参阅 Spring 表达式语言 （SpEL）。spring-doc.cadn.net.cn

从 3.0 版本开始， Spring 集成还提供了一个内置的#xpath用于表达式的 SPEL 函数。 有关更多信息，请参阅 #xpath SPEL 函数。spring-doc.cadn.net.cn

从版本 4.0 开始，ObjectToJsonTransformer支持resultType属性，以指定节点 JSON 表示形式。 结果节点树表示取决于提供的JsonObjectMapper. 默认情况下，ObjectToJsonTransformer使用Jackson2JsonObjectMapper并将对象到节点树的转换委托给ObjectMapper#valueToTree方法。 节点 JSON 表示形式为使用JsonPropertyAccessor当下游消息流使用具有 JSON 数据属性访问权限的 SpEL 表达式时。 有关更多信息，请参见 Property Accessors 。spring-doc.cadn.net.cn

从版本 5.1 开始，resultType可以配置为BYTES生成一条消息，并使用byte[]payload 的 Payload作，以便在使用使用此数据类型的下游处理程序时方便使用。spring-doc.cadn.net.cn

从版本 5.2 开始，JsonToObjectTransformer可以配置ResolvableType以支持在使用目标 JSON 处理器进行反序列化期间使用泛型。 此外，此组件现在首先查询请求消息标头，以了解是否存在JsonHeaders.RESOLVABLE_TYPE或JsonHeaders.TYPE_ID否则，将回退到配置的类型。 这ObjectToJsonTransformer现在还会填充JsonHeaders.RESOLVABLE_TYPE标头。spring-doc.cadn.net.cn

从版本 5.2.6 开始，JsonToObjectTransformer可随附valueTypeExpression要解析ResolvableType以便在运行时根据请求消息从 JSON 转换的有效负载。 默认情况下，它会咨询JsonHeaders在请求消息中。 如果此表达式返回null或ResolvableTypebuilding 会抛出一个ClassNotFoundException，transformer 将回退到提供的targetType. 此逻辑以表达式的形式存在，因为JsonHeaders可能没有真正的类值，而是一些类型 ID，这些 ID 必须根据某些外部注册表映射到目标类。spring-doc.cadn.net.cn

Apache Avro 转换器

版本 5.2 添加了简单的转换器，用于与 Apache Avro 进行转换。spring-doc.cadn.net.cn

它们并不复杂，因为没有 schema 注册表;转换器只使用嵌入在SpecificRecord从 Avro 架构生成的实现。spring-doc.cadn.net.cn

发送到SimpleToAvroTransformer必须具有实现SpecificRecord;transformer 可以处理多种类型。 这SimpleFromAvroTransformer必须配置SpecificRecordclass 用作反序列化的默认类型。 您还可以指定 SPEL 表达式来确定要使用setTypeExpression方法。 默认的 SPEL 表达式是headers[avro_type] (AvroHeaders.TYPE），默认情况下，它由SimpleToAvroTransformer替换为源类的完全限定类名。 如果表达式返回null这defaultType被使用。spring-doc.cadn.net.cn

这SimpleToAvroTransformer还有一个setTypeExpression方法。 这允许生产者和使用者分离，发送者可以将标头设置为表示类型的某个令牌，然后使用者将该令牌映射到类型。spring-doc.cadn.net.cn

Protocol Buffers 转换器

版本 6.1 增加了对从 Protocol Buffers 数据内容转换和转换为 Protocol Buffers 数据内容的支持。spring-doc.cadn.net.cn

这ToProtobufTransformer转换com.google.protobuf.Message消息有效负载转换为本机字节数组或 JSON 文本有效负载。 这application/x-protobuf内容类型（默认使用）生成字节数组输出有效负载。 如果内容类型为application/json添加com.google.protobuf:protobuf-java-util如果在 Classpath 上找到，则输出为 text JSON payload。 如果未设置内容类型标头，ToProtobufTransformer默认为application/x-protobuf.spring-doc.cadn.net.cn

这FromProtobufTransformer将字节数组或文本 protobuf 有效负载（取决于内容类型）转换回com.google.protobuf.Message实例。 这FromProtobufTransformer应显式指定预期的类类型（使用setExpectedType方法），或使用 SpEL 表达式确定要反序列化的类型，使用setExpectedTypeExpression方法。 默认的 SPEL 表达式是headers[proto_type] (ProtoHeaders.TYPE），它由ToProtobufTransformer替换为源的完全限定类名com.google.protobuf.Message类。spring-doc.cadn.net.cn

例如，编译以下 IDL：spring-doc.cadn.net.cn

syntax = "proto2";
package tutorial;

option java_multiple_files = true;
option java_package = "org.example";
option java_outer_classname = "MyProtos";

message MyMessageClass {
  optional string foo = 1;
  optional string bar = 2;
}

将生成一个新的org.example.MyMessageClass类。spring-doc.cadn.net.cn

然后使用：spring-doc.cadn.net.cn

// Transforms a MyMessageClass instance into a byte array.
ToProtobufTransformer toTransformer = new ToProtobufTransformer();

MyMessageClass test = MyMessageClass.newBuilder()
                                .setFoo("foo")
                                .setBar("bar")
                                .build();
// message1 payload is byte array protocol buffer wire format.
Message message1 = toTransformer.transform(new GenericMessage<>(test));

// Transforms a byte array payload into a MyMessageClass instance.
FromProtobufTransformer fromTransformer = new FromProtobufTransformer();

// message2 payload == test
Message message2 =  fromTransformer.transform(message1);

配置带有注释的转换器

您可以添加@Transformer注解添加到需要Messagetype 或消息负载类型。 返回值的处理方式与前面描述的完全相同在描述<transformer>元素. 以下示例演示如何使用@Transformer注解来转换String转换为Order:spring-doc.cadn.net.cn

@Transformer
Order generateOrder(String productId) {
    return new Order(productId);
}

Transformer 方法也可以接受@Header和@Headers注解，如Annotation Support. 以下示例演示如何使用@Header注解：spring-doc.cadn.net.cn

@Transformer
Order generateOrder(String productId, @Header("customerName") String customer) {
    return new Order(productId, customer);
}

另请参阅使用注释通知终端节点。spring-doc.cadn.net.cn

标头筛选器

有时，您的转换使用案例可能就像删除几个标头一样简单。 对于这样的用例， Spring 集成提供了一个 Headers 过滤器，它允许你指定应该从输出消息中删除的某些 Headers 名称（例如，出于安全原因删除 Headers 或仅临时需要的值）。 基本上，Header 过滤器与 Header Enricher 相反。 后者在 Header Enricher 中讨论。 以下示例定义了一个标头过滤器：spring-doc.cadn.net.cn

@Bean
public IntegrationFlow someFlow() {
    return IntegrationFlow
             .from("inputChannel")
             .headerFilter("lastName", "state")
             .channel("outputChannel")
             .get();
}
<int:header-filter input-channel="inputChannel"
		output-channel="outputChannel" header-names="lastName, state"/>

如您所见，报头过滤器的配置非常简单。 它是一个典型的端点，具有输入和输出通道以及header-names属性。 该属性接受需要删除的 Headers 的名称（如果有多个，则用逗号分隔）。 因此，在前面的示例中，出站消息中不存在名为 'lastName' 和 'state' 的标头。spring-doc.cadn.net.cn

基于编解码器的转换器

请参阅 编解码器。spring-doc.cadn.net.cn