|
如需使用最新稳定版本,请使用 Spring Integration 7.0.4! |
转换器
消息转换器在实现消息生产者和消息消费者的解耦方面发挥着非常重要的作用。
无需要求每个消息生产组件都知道下一个消费者期望的类型,您可以在这些组件之间添加转换器。
通用转换器(例如将String转换为 XML 文档的转换器)也具有很高的可重用性。
对于某些系统,提供规范数据模型可能是最佳选择,但 Spring Integration 的总体理念是不强制要求任何特定格式。 相反,为了获得最大的灵活性,Spring Integration 旨在提供最简单的扩展模型。 与其他端点类型一样,使用 XML 中的声明式配置或 Java 注解,可以轻松地将普通 POJO 适配为消息转换器角色。 本章其余部分将介绍这些配置选项。
| 为了最大化灵活性,Spring 不要求基于 XML 的消息负载。 尽管如此,如果基于 XML 的负载确实是您应用程序的正确选择,该框架仍提供了一些方便的转换器来处理此类负载。 有关这些转换器的更多信息,请参阅 XML 支持 - 处理 XML 负载。 |
使用 Java 和其他 DSL 配置转换器
对于简单的 Java 和注解配置,Spring Bean POJO 方法必须标记为 @MessageMapping 注解,框架会在从输入通道消费消息时调用该方法:
public class SomeService {
@Transformer(inputChannel = "transformChannel", outputChannel = "nextServiceChannel")
public OutputData exampleTransformer(InputData payload) {
...
}
}
在 注解支持 中查看更多详细信息。
对于 Java、Groovy 或 Kotlin DSL,.transform() 运算符中的 IntegrationFlow 表示转换端点:
-
Java DSL
-
Kotlin DSL
-
Groovy DSL
@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 的更多信息,请参见相应的章节:
使用 XML 配置转换器
<transformer>元素用于创建消息转换端点。
除了input-channel和output-channel属性外,它还需要一个ref属性。
ref可以指向包含单个方法上@Transformer注解的对象(参见使用注解配置转换器),也可以与method属性中提供的显式方法名值结合使用。
<int:transformer id="testTransformer" ref="testTransformerBean" input-channel="inChannel"
method="transform" output-channel="outChannel"/>
<beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />
如果自定义转换器处理器实现可以在其他 <transformer> 定义中重用,则通常建议使用 ref 属性。
然而,如果自定义转换器处理器实现应限定在单个 <transformer> 定义范围内,则可以定义一个内部 Bean 定义,如下示例所示:
<int:transformer id="testTransformer" input-channel="inChannel" method="transform"
output-channel="outChannel">
<beans:bean class="org.foo.TestTransformer"/>
</transformer>
在同一个 <transformer> 配置中同时使用 ref 属性和内部处理器定义是不允许的,因为这会创建歧义条件并导致抛出异常。 |
如果 ref 属性引用了扩展自 AbstractMessageProducingHandler 的 Bean(例如框架自身提供的转换器),则配置将通过直接将输出通道注入处理器来进行优化。
在这种情况下,每个 ref 必须指向单独的 Bean 实例(或 prototype 作用域的 Bean),或者使用内部的 <bean/> 配置类型。
如果您意外地从多个 Bean 引用了同一个消息处理器,将会抛出配置异常。 |
当使用 POJO 时,用于转换的方法可能期望接收入站消息的 Message 类型或有效负载类型。
它还可以通过分别使用 @Header 和 @Headers 参数注解,单独接受或作为完整映射接受消息头值。
方法的返回值可以是任何类型。
如果返回值本身是一个 Message,则将其传递给转换器的输出通道。
自 Spring Integration 2.0 起,消息转换器的转换方法不再允许返回 null。
返回 null 会导致异常,因为消息转换器应始终被期望将每个源消息转换为有效的目标消息。
换句话说,消息转换器不应用作消息过滤器,因为为此有专用的 <filter> 选项。
然而,如果您确实需要这种行为(即组件可能返回 null 且不应被视为错误),您可以使用服务激活器。
其 requires-reply 值默认为 false,但可以设置为 true,以便像转换器一样对 null 返回值抛出异常。
转换器与 Spring 表达式语言 (SpEL)
与路由器、聚合器和其他组件一样,从 Spring Integration 2.0 开始,只要转换逻辑相对简单,转换器也可以受益于 SpEL 支持。 以下示例展示了如何使用 SpEL 表达式:
<int:transformer input-channel="inChannel"
output-channel="outChannel"
expression="payload.toUpperCase() + '- [' + T(System).currentTimeMillis() + ']'"/>
上述示例在不编写自定义转换器的情况下对有效载荷进行了转换。
我们的有效载荷(假定为 String)被转换为大写,与当前时间戳连接,并应用了一些格式化。
常用转换器
Spring Integration 提供了一些转换器实现。
对象到字符串转换器
由于使用 toString() 表示法来表示 Object 的情况相当常见,Spring Integration 提供了一个 ObjectToStringTransformer(另请参阅 Transformers 工厂),其输出为带有 String payload 的 Message。
该 String 是调用入站消息有效负载上的 toString() 操作的结果。
以下示例展示了如何声明一个对象到字符串转换器的实例:
-
Java DSL
-
Kotlin DSL
-
Groovy DSL
-
XML
@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"/>
此转换器的一个潜在用途是将某些任意对象发送到 file 命名空间中的 'outbound-channel-adapter'。
虽然该通道适配器默认仅支持 String、字节数组或 java.io.File 类型的负载,但在此适配器之前立即添加此转换器即可处理必要的转换。
只要 toString() 调用的结果正是您希望写入文件的内容,这种方法就能正常工作。
否则,您可以使用前面展示的通用 'transformer' 元素提供基于自定义 POJO 的转换器。
调试时,通常不需要此转换器,因为 logging-channel-adapter 能够记录消息负载。
有关更多详细信息,请参阅 Wire Tap。 |
对象到字符串的转换器非常简单。
它对入站负载调用 toString()。
自 Spring Integration 3.0 起,此规则有两个例外:
-
如果有效载荷为
char[],它将调用new String(payload)。 -
如果负载是
byte[],它将调用new String(payload, charset),其中charset默认为 UTF-8。 可以通过在转换器上提供 charset 属性来修改charset。
如需更高级的功能(例如在运行时动态选择字符集),您可以改用基于 SpEL 表达式的转换器,如下示例所示:
-
Java DSL
-
XML
@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 序列化,但您可以通过分别使用 serializer 和 deserializer 属性来提供 Spring Serializer 或 Deserializer 策略的实现。
另请参阅 Transformers 工厂类。
以下示例展示了如何使用 Spring 的序列化和反序列化器:
-
Java DSL
-
XML
@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-to-Map和Map-to-Object转换器
Spring Integration 还提供了 Object-to-Map 和 Map-to-Object 转换器,它们使用 JSON 来序列化和反序列化对象图。
对象层次结构会被内省到最原始的类型(String、int 等)。
到该类型的路径通过 SpEL 描述,它将成为转换后的 Map 中的 key。
原始类型将成为值。
考虑以下示例:
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:
{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Jen ...}
基于 JSON 的 Map 允许您在不共享实际类型的情况下描述对象结构,这使得只要保持结构一致,即可将对象图还原并重建为不同类型的对象图。
例如,前面的结构可以使用 Map-to-Object 转换器恢复为以下对象图:
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 对象。
考虑以下示例:
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:
{name=George, child={name=Jenna, nickNames=[Bimbo, ...]}}
要配置这些转换器,Spring Integration 提供了相应的 XML 组件和 Java DSL 工厂:
-
Java DSL
-
XML
@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,如下所示:
-
Java DSL
-
XML
@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 Integration 提供了用于 Map-to-Object 的 XML 命名空间支持,Java DSL 工厂具有 fromMap() 方法,如下例所示:
-
Java DSL
-
XML
@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,如下示例所示:
-
Java DSL
-
XML
@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 等场景(以及其他用途)。
有关 JsonObjectMapper 实现的更多信息,请参阅 JSON 转换器。
流转换器
The StreamTransformer 将 InputStream 负载转换为 byte[](如果提供了 charset,则转换为 String)。
以下示例展示了如何在 XML 中使用 stream-transformer 元素:
-
Java DSL
-
XML
@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 -->
以下示例展示了如何在 Java 中使用 StreamTransformer 类和 @Transformer 注解来配置流转换器:
@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 Integration 提供对象到 JSON 和 JSON 到对象的转换器。 以下示例对展示了如何在 XML 中声明它们:
<int:object-to-json-transformer input-channel="objectMapperInput"/>
<int:json-to-object-transformer input-channel="objectMapperInput"
type="foo.MyDomainObject"/>
默认情况下,上述列表中的转换器使用普通的 JsonObjectMapper。
它是基于类路径中的实现构建的。
您可以提供自己的自定义 JsonObjectMapper 实现,并配备适当的选项或基于所需的库(例如 GSON),如下示例所示:
<int:json-to-object-transformer input-channel="objectMapperInput"
type="something.MyDomainObject" object-mapper="customObjectMapper"/>
|
从 3.0 版本开始, |
您可能希望考虑使用 FactoryBean 或工厂方法来创建具有所需特性的 JsonObjectMapper。
以下示例展示了如何使用此类工厂:
public class ObjectMapperFactory {
public static Jackson2JsonObjectMapper getMapper() {
ObjectMapper mapper = new ObjectMapper();
mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
return new Jackson2JsonObjectMapper(mapper);
}
}
以下示例展示了如何在 XML 中实现相同的功能:
<bean id="customObjectMapper" class="something.ObjectMapperFactory"
factory-method="getMapper"/>
|
从版本 2.2 开始, 如果您希望将 |
从 3.0 版本开始,ObjectToJsonTransformer 会在消息中添加反映源类型的头部信息。
同样地,JsonToObjectTransformer 在将 JSON 转换为对象时可以使用这些类型头部信息。
这些头部信息在 AMQP 适配器中进行了映射,从而与 Spring-AMQP 的 JsonMessageConverter 完全兼容。
这使以下流程无需任何特殊配置即可正常工作:
-
…→amqp-outbound-adapter---→ -
---→amqp-inbound-adapter→json-to-object-transformer→…当出站适配器配置为
JsonMessageConverter,而入站适配器使用默认的SimpleMessageConverter时。 -
…→object-to-json-transformer→amqp-outbound-adapter---→ -
---→amqp-inbound-adapter→…当出站适配器配置为
SimpleMessageConverter,而入站适配器使用默认的JsonMessageConverter时。 -
…→object-to-json-transformer→amqp-outbound-adapter---→ -
---→amqp-inbound-adapter→json-to-object-transformer→当两个适配器都配置为
SimpleMessageConverter时。
使用请求头确定类型时,不应提供 class 属性,因为它会优先于请求头。 |
除了 JSON 转换器外,Spring Integration 还提供了一个内置的 #jsonPath SpEL 函数,可用于表达式中。
更多信息请参阅 Spring 表达式语言 (SpEL)。
自 3.0 版本起,Spring Integration 还提供了一个内置的 #xpath SpEL 函数,用于表达式中。
有关更多信息,请参阅 #xpath SpEL 函数。
从版本 4.0 开始,ObjectToJsonTransformer 支持 resultType 属性,用于指定节点的 JSON 表示形式。
结果节点树的表示形式取决于提供的 JsonObjectMapper 的实现。
默认情况下,ObjectToJsonTransformer 使用 Jackson2JsonObjectMapper,并将对象到节点树的转换委托给 ObjectMapper#valueToTree 方法。
当下游消息流使用 SpEL 表达式访问 JSON 数据的属性时,节点的 JSON 表示形式可为使用 JsonPropertyAccessor 提供效率提升。
有关更多信息,请参阅 属性访问器。
从版本 5.1 开始,可以将 resultType 配置为 BYTES,以便在操作此数据类型的下游处理器工作时生成带有 byte[] 负载的消息,从而提供便利。
从版本 5.2 开始,JsonToObjectTransformer 可以配置为 ResolvableType,以支持在使用目标 JSON 处理器进行反序列化时处理泛型。
此外,该组件现在会优先检查请求消息头中是否存在 JsonHeaders.RESOLVABLE_TYPE 或 JsonHeaders.TYPE_ID,如果未找到则回退到已配置的类型。
ObjectToJsonTransformer 现在还会根据请求消息负载填充 JsonHeaders.RESOLVABLE_TYPE 头信息,以支持任何可能的下游场景。
从版本 5.2.6 开始,可以提供一个 JsonToObjectTransformer 和一个 valueTypeExpression,以便在运行时针对请求消息解析用于将 JSON 负载转换的 ResolvableType。
默认情况下,它会查询请求消息中的 JsonHeaders。
如果此表达式返回 null 或 ResolvableType,构建过程将抛出 ClassNotFoundException,此时转换器将回退到提供的 targetType。
此逻辑以表达式的形式存在,因为 JsonHeaders 可能不包含实际的类值,而是某些类型 ID,需要根据外部注册表将其映射到目标类。
Apache Avro 转换器
版本 5.2 添加了简单的转换器,用于与 Apache Avro 进行相互转换。
它们是不成熟的,因为没有模式注册表;转换器仅使用从 Avro 模式生成的 SpecificRecord 实现中嵌入的模式。
发送到 SimpleToAvroTransformer 的消息必须具有实现 SpecificRecord 的负载;转换器可以处理多种类型。
SimpleFromAvroTransformer 必须配置一个用作反序列化默认类型的 SpecificRecord 类。
您还可以指定 SpEL 表达式,使用 setTypeExpression 方法来确定要反序列化的类型。
默认的 SpEL 表达式是 headers[avro_type](AvroHeaders.TYPE),默认情况下由 SimpleToAvroTransformer 填充源类的完全限定类名。
如果表达式返回 null,则将使用 defaultType。
The SimpleToAvroTransformer 也拥有一个 setTypeExpression 方法。
这实现了生产者和消费者之间的解耦,发送方可以将头信息设置为代表类型的某个Tokens,而接收方随后将该Tokens映射为具体的类型。
协议缓冲区转换器
版本 6.1 增加了对与 Protocol Buffers 数据内容相互转换的支持。
The ToProtobufTransformer 将 com.google.protobuf.Message 消息负载转换为原生字节数组或 JSON 文本负载。
The application/x-protobuf 内容类型(默认使用)生成字节数组输出负载。
如果内容类型为 application/json,且在类路径中找到 com.google.protobuf:protobuf-java-util,则输出为文本 JSON 负载。
如果未设置内容类型头,ToProtobufTransformer 默认为 application/x-protobuf。
FromProtobufTransformer 将字节数组或文本 Protobuf 负载(取决于内容类型)转换回 com.google.protobuf.Message 实例。
FromProtobufTransformer 应显式指定预期的类类型(使用 setExpectedType 方法),或使用 SpEL 表达式通过 setExpectedTypeExpression 方法确定要反序列化的类型。
默认的 SpEL 表达式是 headers[proto_type](ProtoHeaders.TYPE),它由 ToProtobufTransformer 填充,包含源 com.google.protobuf.Message 类的完全限定类名。
例如,编译以下 IDL:
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 类。
然后使用:
// 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 注解添加到期望接收 Message 类型或消息负载类型的方法中。
返回值的处理方式与前面描述的完全相同,参见描述 <transformer> 元素的章节。
以下示例展示了如何使用 @Transformer 注解将 String 转换为 Order:
@Transformer
Order generateOrder(String productId) {
return new Order(productId);
}
转换器方法也可以接受 @Header 和 @Headers 注解,如 Annotation Support 中所述。
以下示例展示了如何使用 @Header 注解:
@Transformer
Order generateOrder(String productId, @Header("customerName") String customer) {
return new Order(productId, customer);
}
见 Also 使用注解建议端点。
请求头过滤器
有时,您的转换用例可能很简单,只需删除几个标头。 对于此类用例,Spring Integration 提供了一个标头过滤器,允许您指定应从输出消息中删除的特定标头名称(例如,出于安全原因删除标头,或仅临时需要的值)。 基本上,标头过滤器是标头增强器的相反操作。 后者在 标头增强器 中进行了讨论。 以下示例定义了一个标头过滤器:
-
Java DSL
-
XML
@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 属性。
该属性接受需要移除的头部名称(如果有多个,则以逗号分隔)。
因此,在上面的示例中,名为 'lastName' 和 'state' 的头部不会出现在出站消息中。
基于编解码器的转换器
查看 编解码器。