MTOM是W3C定义的SOAP二进制传输优化机制，通过xop:Include引用和MIME多部件替代Base64编码，避免约33%体积膨胀；仅对≥1KB二进制有效，需服务端@MTOM注解、客户端显式启用及流式DataHandler配合。
MTOM 是什么：不是协议，而是优化策略
MTOM（Message Transmission Optimization Mechanism）不是独立协议，而是 W3C 定义的一套「绕过 Base64 编码」的传输优化机制。它不改变 SOAP 的语义或 XML 信息集，只改写“怎么在线上传输”——把原本必须编码进 XML 的 xs:base64Binary 字段，替换成一个 xop:Include 引用，并把原始二进制数据作为独立 MIME 部件（Content-Type: application/xop+xml）随 SOAP 消息一起发出去。
核心效果就一条：避免 Base64 带来的 ~33% 体积膨胀。比如 1MB 文件，Base64 后变成约 1.33MB；MTOM 下仍为 1MB（加少量 MIME 封装开销）。但注意：这个优势只在二进制块 ≥ 1KB 时才明显，小数据反而因 MIME 多部分封装更慢。
@MTOM 注解怎么用：服务端启用的关键一步
在 JAX-WS 中，仅靠 WSDL 声明 base64Binary 不会自动启用 MTOM，必须显式标注。最常用方式是给实现类加 @MTOM 注解：
@MTOM(enabled = true, threshold = 2048)
@WebService
public class DocumentUploadService {
public String uploadDocument(DataHandler file) {
// ...
}
}
-
enabled = true是开关，缺省为false -
threshold = 2048表示 ≥ 2KB 的二进制才走 MTOM 分离；小于该值仍走 inline Base64 —— 这是性能权衡，不是 bug - 必须配合 JAXB 映射中使用
javax.activation.DataHandler或byte[]（后者需确保 WSDL 正确生成xmime:expectedContentTypes） - 仅标注服务端不够：客户端也必须显式启用 MTOM，否则会报
Unexpected element {http://www.w3.org/2004/08/xop/include}Include类错误
客户端怎么配：不设 messageEncoding 就等于没开
以 JAX-WS 标准客户端为例，光写 service.getPort(...) 不行，必须获取绑定并设置 MTOM 属性：
MyService service = new MyService();
MyPort port = service.getMyPort();
BindingProvider bp = (BindingProvider) port;
Map<String, Object> reqCtx = bp.getRequestContext();
reqCtx.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://.../service");
// 关键：启用 MTOM
reqCtx.put("com.sun.xml.ws.transport.http.client.streaming.chunk.size", 8192);
reqCtx.put("com.sun.xml.ws.encoding.mtom.enabled", true);
如果是 Spring Boot + CXF，配置项更直观：
<bean id="mtomClient" class="org.apache.cxf.jaxws.JaxWsProxyFactoryBean"> <property name="serviceClass" value="com.example.MyService"/> <property name="address" value="http://.../service"/> <property name="bindingId" value="http://cxf.apache.org/bindings/soap11?mtom-enabled=true"/> </bean>
- 不同运行时关键词不同：
com.sun.xml.ws.encoding.mtom.enabled（Metro）、mtom-enabled=true（CXF）、messageEncoding="Mtom"（WCF） - 客户端未启用 MTOM 时，收到 MTOM 响应会解析失败，常见错误是
SAXParseException: Content is not allowed in prolog—— 因为底层把 XOP 包当纯 XML 解析了 - 务必检查 HTTP 请求头：
Content-Type应为multipart/related; type="application/xop+xml"; start="<rootpart>"</rootpart>，而非text/xml
为什么传大文件还卡？阈值、内存和流式处理三者必须对齐
开了 MTOM 却发现上传 50MB 文件超时或 OOM，大概率是三个地方没协同：
- 服务端
@MTOM(threshold=2048)和客户端实际发送的数据类型不匹配 —— 比如你传的是byte[]，但 JAXB 默认把它全加载进内存再切分；应改用DataHandler+InputStream实现流式读取 - 应用服务器（如 WebSphere、Tomcat）有默认请求体大小限制：
maxPostSize（Tomcat）或requestBufferSize（WebSphere），MTOM 的 multipart body 会被整体拦截 - WSDL 中未正确声明
xmime:expectedContentTypes，导致 JAXB 无法将 MIME 部件自动绑定到DataHandler字段，抛出UnmarshalException: unexpected element
真正稳定的 MTOM 文件上传，必须满足：WSDL 描述准确 + 服务端注解开启 + 客户端显式启用 + 两端都用流式类型（DataHandler）+ 服务器调大 multipart 限制。少一环，就退回 Base64 膨胀模式，或者直接失败。
