简介这是一份面向 WSO2 Enterprise Integrator 6.6.0 的中文使用手册定位为 WSO2 ESB 升级版的企业集成实操指南适合中间件工程师、架构师以及正在选型或落地 WSO2 产品的团队阅读。文档先介绍 WSO2 三款开源产品API Manager、Enterprise Integrator、Identity Server的定位与分工再深入 ESB 配置文件的消息流架构梳理请求从传输层、Axis2 管道、中介框架到目标端点的完整路径说明短期无状态集成流与长期有状态业务流程BPEL、BPMN、人工任务的实现方式。同时覆盖 REST 代理、路由转发、REST 与 WebService 双向转换、TCP 转 WebService 等高频场景帮助读者理解中介框架下的消息转换与路由机制以及 ESB、业务流程、Analytics 等多配置文件的适用条件。资源为单个 doc 文档体积仅 1.43MB内容组织紧凑可直接按章节查阅协议配置与集成示例也适合作为实施过程中的速查手册。目前已有 2041 人学习对初次接触 WSO2 EI 的开发者或需要快速搭建企业集成方案的工程师具有实用参考价值。1. 拿到 EI 6.6.0 手动搭建集成网关资历老、资料散、坑也实在做系统集成的这些年不少人第一次接触 WSO2 Enterprise Integrator 都是被同一个问题逼来的手头有旧系统要接新服务协议五花八门——REST 的要转成 SOAP 发给老平台TCP 报文要塞进 WebService还要带鉴权和路由。某个开发者当时在模拟项目X里就是这么被卡的翻遍官网文档发现资料虽全但太散中文实操笔记更是各说各话。这份 WSO2-EI 6.6.0 使用手册解决的就是这个痛点它把 ESB 概要文件的两类消息流讲明白了还内置 REST2SOAP、SOAP2REST、TCP2SOAP 三个可照着做的案例。适合刚接手集成中间件、被协议转换折腾的开发者也适合需要快速评估 EI 和 ESB 差异的技术负责人。2. EI 6.6.0 到底整合了什么从 ESB 到三大配置文件的边界理清2.1 产品家族不是三选一是按场景分工WSO2 生态里常被拿出来说的三件套——API Manager、Enterprise Integrator、Identity Server——各管一段。API Manager 管 API 全生命周期从创建发布到流量控制和版本管理都在它手里Identity Server 管身份与访问单点登录、身份联合、细粒度访问控制是它的主场。真正干集成活儿的是 Enterprise Integrator它把原本分散的 ESB、消息代理、业务流程服务器和流处理器收进了一个运行时。选型时容易踩的误区是以为上了 EI 就得把 AM 和 IS 也一起部署。实际不是这样EI 6.6.0 自带注册表和安全管理能力单机就能撑起一条完整的集成链路。只有当你要对外大规模发布 API 或者做跨系统统一身份认证时才需要把另外两个产品拉进来。从手册里给的产品生态图来看三者是互补关系而不是依赖关系。2.2 ESB 概要文件短期无状态集成流的默认入口手册花了大篇幅讲 ESB 概要文件的七步消息流转这套机制值得记熟因为它决定了后续所有代理服务和序列的调试思路。流程大致是客户端发消息进 ESB传输层按协议接收消息经过管道时先做 QoS 处理比如安全校验接着进入中介框架完成转换和路由注意转换和路由不是严格分先后而是交织在一起由 Synapse 实现最后再经过一条出口管道由传输层做协议转换并送达目标端点。响应处理完全反过来走这条链。很多人把 ESB 和消息队列搞混。ESB 不负责消息的持久化和可靠投递它侧重的是格式转换、内容路由和服务编排。EI 6.6.0 里如果要做可靠消息需要启用 Message Broker 配置文件MB这套东西在集成方案里负责消息的存储转发。两者搭配使用是常见设计ESB 做接入和转换Broker 做缓冲和解耦。2.3 业务流程概要文件BPEL、BPMN 和人工任务的差异化实现长期运行的有状态流程走的是另一条路手册里拆成三条分支讲得很清楚。BPEL 流程和人工任务以 SOAP 服务形式暴露走 Axis2 Web 服务通道BPMN 流程则以 REST API 暴露部署在嵌入式 Tomcat 上。这三者的传输入口不一样进入后分别交给 ODE BPEL 引擎、Activiti BPMN 引擎和人工任务运行时去处理流程实例数据统一通过数据访问对象层持久化到数据库。实际项目里短期接口转换用 ESB 概要文件就够了一旦涉及审批流、多步人工确认这类长事务再去启用业务流程概要文件。手册里点名了 Activiti 5.21.0 和 Apache ODE 引擎这意味着你的 BPMN 文件版本兼容性要按这套引擎来核BPMN 2.0 标准虽然通用但某些扩展元素在不同引擎上表现不一样批次升级时容易翻车。2.4 EI 6.6.0 的组件清单ESB、MB、BPS、SP 一次收齐版本 6.6.0 是 EI 6.xx 系列的最新版它把四个产品的功能封进了同一个发行包ESB 做中介和路由MB 做可靠消息BPS 跑业务流程SP 做流处理。单从架构上看这套设计能在同一个 Carbon 平台上统一管理省去了多套中间件之间的对接成本。成本的一面是包体变大。下载 Zip Archive 解压后目录里有多个配置文件目录对应不同配置文件。启动哪个取决于你跑什么场景不需要的概要文件完全可以不启动避免 JVM 内存被无谓占用。这是 EI 和单独装 ESB 的一个重要区别灵活性和资源消耗成正比。3. ESB 核心概念落地从 Transport 到 Registry 的配置要点3.1 Transports 和 Message Builders/Formatters 的配对逻辑WSO2 ESB 支持的传输协议列表很长HTTP、HTTPS、JMS、TCP、FIX、SFTP 等一大串。每种传输进来后消息要被转成统一的 XML 表示靠的是 Message Builders从 XML 再转回原始格式发出去靠的是 Message Formatters。这俩是成对出现的按内容类型匹配。实际调试中最常见的翻车点是新增了一个协议但没配对应的 builder/formatter消息进来直接报错或者变成乱码。手册里提到 TCP 传输的三种消息类型——字节、字符、字符串——以定界符或者定长字节判断请求边界这个配置细节在 axis2.xml 里折腾过的人都有印象。HTTP 相关的 builder/formatter 基本默认可用但 TCP、FIX 这类冷门协议必须手工改配置文件才能让传输层正确解析。3.2 Endpoints 三种定义方式和 format 参数取舍Endpoint 代表后台服务地址配一个 endpoint 才能让 ESB 知道消息往哪送。手册给出了一个典型的 address endpoint 配置endpoint address urihttp://localhost:9000/services/SimpleStockQuoteService formatsoap11/ /endpoint这里 format 决定消息在发送端的最终形态合法的取值有soap11、soap12、pox和get。选soap11意味着 ESB 会把当前消息转换成 SOAP 1.1 信封再发出去选pox就是纯 XML 不带 SOAP 包装get会把消息转成 HTTP GET 请求参数。所谓 Leave As-Is是保留消息原样不做格式转换。三种 endpoint 类型之间address 是最直接的指定 uri 就行WSDL endpoint 是从 WSDL 里提取地址适用于服务地址经常变的环境load balancing endpoint 则是把同一个服务的一组地址配进来让 ESB 在多个实例间分发流量。负载均衡的权重和会话亲和性都在 endpoint 配置里调整不需要额外部署 LB 组件。3.3 Proxy Service 的 InSequence、OutSequence 与 Fault Sequence代理服务是 ESB 的虚拟服务不真正执行业务逻辑业务在外部端点完成。每次消息进入代理服务时会经过 InSequence在这个阶段你可以做校验、改写、路由决定外部服务响应后响应消息从 OutSequence 回来由这里做最后的加工再还给客户端。出错时走 Fault Sequence这个 sequence 常被新手忽略导致线上报错时连个日志都看不见。配置代理服务时最值得留意的参数是receiving sequence机制。从 4.x 版本开始你可以在 send mediator 里显式指定一个 sequence 来接收响应而不是默认回到 OutSequence。这在异步场景下非常有用同一个代理服务可以并发处理多个请求每个请求的响应回到各自指定的接收序列而不是一股脑全挤回 OutSequence。3.4 Mediators 和 Sequences消息流的积木与流水线Mediator 是消息处理的最小单元输入一个消息经过转换或路由输出一个消息。ESB 预置了几十个 mediator从发消息的 send、改属性的 property、调日志的 log到做分支判断的 filter、做内容增强的 enrich都有现成的。而 Sequence 就是把一堆 mediator 按顺序串起来形成一条可复用的流水线。写 sequence 时有个好习惯把常用的路由和转换逻辑拆成独立 sequence 存到 Registry用 key 引用而不是每个代理服务里复制粘贴。这样改一处全局生效不用逐个代理服务去翻。ESB 的 xpath 表达式在 filter mediator 里的取值逻辑是基于 Synapse 的和标准 XPath 有细微差别判断节点的写法不对会直接走 else 分支排查时要能想到这一层。3.5 Registry 两级缓存和 cachableDuration 参数注册表是 ESB 存放配置和资源的中央仓库sequence、endpoint、WSDL、数据源定义都按路径存在里面。内置注册表按作用域分为本地仓库、配置仓库和治理仓库三部分本地仓库存各节点私有数据不参与共享配置仓库在同类产品实例间共享ESB 集群就靠它同步配置治理仓库跨产品共享存服务描述、endpoint、数据源这类全平台通用资产。registry providerorg.wso2.carbon.mediation.registry.WSO2Registry parameter namecachableDuration15000/parameter /registry这个cachableDuration的单位是毫秒控制注册表资源的缓存刷新周期。ESB 在消息流里引用注册表资源后会放到缓存里缓存期间资源内容变了也不会重新加载必须等缓存过期。把值调大能提升消息处理速度——查注册表的次数少调小则让配置更新能更快生效。折中方案是开发环境设 5000生产环境按变更频率设 15000 或更高保存配置后等待一个缓存周期再做验证不然会误以为发布失效。4. 基于 Integration Studio 复现三个典型案例REST2SOAP、SOAP2REST、TCP2SOAP4.1 开发环境搭建EI 运行时和 Integration Studio 的分工手册明确推荐用 Integration Studio 做可视化开发它基于 Eclipse支持拖拽式编排适合不习惯手写 XML 的人。而 EI 6.6.0 本身是运行时负责把开发好的配置跑起来。两者的版本要匹配EI 6.6.0 对应配套的 Integration Studio 版本混用容易出现打包部署不兼容。搭建时先下载 EI 6.6.0 的 Zip Archive解压后设置JAVA_HOME然后跑bin/integrator.sh或bin/integrator.bat启动运行时。Integration Studio 这边创建一个新的 Integration Project在项目里建 Proxy Service 或 Sequence。开发完成后导出 CAR 文件Carbon Archive部署到 EI 运行时的repository/deployment/server/carbonapps目录运行时热部署自动加载。手册项目目录里那些案例截图对应的也就是这套工程结构。4.2 REST2SOAP代理服务接入 REST 请求再转发 SOAP 服务这个案例是最典型的协议转换场景客户端只发 REST 请求后台服务是 SOAP 接口。在 Integration Studio 中新建一个 Proxy Service传输协议选 HTTP/HTTPSInSequence 里加一个 payload factory mediator把 REST 请求的 JSON 或表单参数拼装成 SOAP 信封再通过 send mediator 发往目标 SOAP endpoint。proxy nameRestToSoapProxy transportshttp https startOnLoadtrue target inSequence payloadFactory media-typexml format soapenv:Envelope xmlns:soapenvhttp://schemas.xmlsoap.org/soap/envelope/ xmlns:serhttp://service.example.com soapenv:Body ser:getCustomer ser:id$1/ser:id /ser:getCustomer /soapenv:Body /soapenv:Envelope /format args arg xmlns:mhttp://schemas.xmlsoap.org/soap/envelope/ evaluatorxml expression$trp:customerId/ /args /payloadFactory send endpoint address urihttp://localhost:9080/customerService formatsoap11/ /endpoint /send /inSequence outSequence send/ /outSequence /target /proxy代码里$trp:customerId是传输属性取值对应 HTTP 请求参数里的 customerIdpayloadFactory 的$1引用第一个 arg 的值做占位替换。formatsoap11保证 send 发出去的是标准 SOAP 1.1 信封。OutSequence 里的send不带 endpoint 会把响应直接送回客户端此时响应默认还是 SOAP 格式如果客户端要 REST 形式需要在 OutSequence 里再做一次 payloadFactory 把 SOAP 响应转成 JSON很多人在这里漏掉反向转换导致联调失败。4.3 SOAP2REST反向转换的自定义实现要点SOAP2REST 场景在手册里标记为自定义构造没有直接给模板但实现逻辑和 REST2SOAP 是镜像的。代理服务接收 SOAP 请求解析 SOAP Body 里的业务参数用 payloadFactory 构造 REST 格式的消息再通过 HTTP endpoint 以 POST 或 GET 方式发出去。关键点在两处一是 endpoint 的 format 参数必须选pox或get不能是soap11否则 ESB 会把消息重新包成 SOAP 信封发给 REST 服务。二是 OutSequence 里同样要把 REST 回来的 JSON 还原成 SOAP 结构返回客户端。整个过程中 property mediator 常被用来暂存 SOAP 请求里的字段值等 REST 响应回来再从属性里取出来拼装。JSON 和 XML 之间的字段映射容易出差错建议在开发环境用 SoapUI 同时起两个客户端分别模拟 REST 方和 SOAP 方这样两端格式问题能第一时间定位到。4.4 TCP2SOAP修改 axis2.xml 启用 TCP 传输的完整路径TCP 传输需要动配置文件这是手册里明确点名的步骤。找到 EI 运行时目录下的conf/axis2/axis2.xml在 transport receiver 和 transport sender 区域分别添加 TCP 相关的配置。配置好后重启运行时才会生效不能热加载。transportReceiver nametcp classorg.apache.synapse.transport.nhttp.NhttpTransportListener parameter nameport6060/parameter /transportReceiverTCP 入站消息在 ESB 里靠分隔符或定长字段切分请求边界常用的是在parameter namerequestStreaming或消息类型相关配置里指定分隔符值。收到完整 TCP 报文后接下来要做的处理同 REST2SOAP 一样用 payloadFactory 把原始字节或字符串拼装成 SOAP Body然后 send 到 SOAP endpoint。手册提醒 JMS 传输也要走同样的配置修改流程不能指望默认配置就能直接用。4.5 SampleService 和内容路由的实操笔记手册里附带的 SampleService 案例是官网最简单的入门版只做了一件事接收 REST 请求直接转发到后台服务不做任何转换。先跑通这个案例能确认环境没问题再去碰路由案例。路由案例基于消息内容做判断常见实现是 filter mediator 按 XPath 或 JSONPath 分流到不同 endpoint。filter sourcejson-eval($.hospitalType) regexGeneral then sendendpoint keyGeneralHospitalEP//send /then else sendendpoint keySpecialHospitalEP//send /else /filterjson-eval($.hospitalType)从 JSON 消息体里取 hospitalType 字段匹配 General 则走综合医院端点否则走专科端点。这里要注意 filter source 的表达式解析基于 SynapseJSON 路径表达式的语法与标准 JSONPath 有细节差异写完后最好在管理控制台的尝试工具里先验证再部署。5. 避坑与常见问题axis2.xml、WSDL、缓存、协议四类典型故障排查5.1 代理服务启动后接口 404WSDL 获取失败但不影响启动现象代理服务部署后控制台显示运行中但调用接口返回 404。原因启动时 ESB 尝试获取代理服务关联的 WSDL若 WSDL 不可达ESB 记录错误并继续启动该服务——手册明确写了这一点——但服务对外暴露的元数据不完整导致路由不到正确处理器。另有一种可能代理服务配置里wsdlEndpoint指向的外部地址在启动瞬间不可用影响的是服务描述而非消息处理。解决确认 WSDL 地址可访问临时方案是把 WSDL 文件拷到本地用wsdlURI指向文件路径。更常见的做法是手动编写代理服务的 WSDL 或复用已有服务的 WSDL而不是依赖启动时动态拉取。每次修改 WSDL 相关配置后必须重启运行时代理服务不会感知外部 WSDL 的变更。5.2 新协议配置了但请求进不来axis2.xml 热加载是假象现象在 Integration Studio 里改了 axis2.xml 里的 TCP 配置并保存运行时日志看不到 TCP 监听端口。原因axis2.xml 是运行时启动时加载的全局配置在线修改不会触发重载需要重启 EI 进程。解决改完配置后完整停掉 integrator 进程再启动启动日志里确认对应 transport listener 的端口已打开。对 TCP 这类非默认协议建议在修改前先备份 axis2.xml改坏后可以快速回滚不要手动改完就完事拿启动日志核对一遍是最稳妥的验证方式。5.3 注册表配置改了不生效cachableDuration 过期前用的是旧缓存现象更新了某个 sequence 定义但代理服务调用时还是旧逻辑持续很久才变过来。原因注册表资源被 ESB 缓存cachableDuration设置 15000 毫秒意味着资源变更最长要等 15 秒才会被重新加载。集群环境下各节点独立缓存更新不是即时同步的。解决要么把发布变更的验证窗口拉长到超过缓存周期要么开发环境把cachableDuration临时调小到 1000 毫秒缩短等待。生产环境不建议系统性地调小缓存会拖累消息吞吐。发布配置后该做的验证等一个缓存周期再执行别刚保存完就去试并发。5.4 路由到错误端点filter 表达式解析和预期不一致现象filter mediator 明明写了等于判断但消息走了 else 分支。原因表达式写法不匹配实际消息内容。XPath 在 Synapse 里和标准 XPath 对命名空间的处理有差异json-eval对 JSON 数组和嵌套对象的下标是从 0 还是从 1 开始也要实测。另一个隐蔽点表达式取到的值带前后空格或换行导致字符串比较失败。解决在 filter 前加一个 log mediator 把属性和消息体打出来确认表达式的实际取值。排查工具方面Integration Studio 里有消息跟踪视图EI 管理控制台也提供调试接口。比翻日志更快的方式是先在控制台尝试工具里手动跑一遍表达式确认取值正确再部署。条件比较上尽量用正则而非全等匹配给数据留点余量。5.5 协议转换响应冲突REST 转发后返回的却是 SOAP 信封现象REST2SOAP 案例联调时客户端发 REST 请求后台 SOAP 服务确实收到了但返回给客户端的响应是 SOAP XML不是预期的 JSON。原因OutSequence 直接用了不带参数的send响应消息维持 SOAP 格式原样返回。ESB 只处理入站转换出站方向如果不显式转换消息就以 SOAP 信封的形态回到客户端。解决在 OutSequence 里显式加 payloadFactory 把响应 Body 内容抽取出来转成 JSON 结构或者用一个property namemessageType valueapplication/json强制设置响应消息的内容类型。注意 JSON 结构要从 SOAP Body 的命名空间里解析出来别把 envelope 包装一起输出。这类问题的隐蔽之处在于本地直接用 SoapUI 调代理服务时看不到问题因为 SoapUI 能解析 SOAP要到真实 REST 客户端联调时才会暴露。6. 把手册收成一张速查表常用 Mediator 和表达式的实战用法Property Mediator 是最常被用到的存储和读取工具。写入时用set-property读取时用get-property(name)或者简写$ctx:name。它存的值可以是消息上下文里的临时变量也可以覆盖传输属性。跨 sequence 传参时我习惯用 property 承载临时值而不是在消息体里拼来拼去。Enrich Mediator 用于从源内容提取数据并合并到当前消息的指定位置。写作格式复合场景比 payloadFactory 更灵活它不用手工拼整个信封只需指定源表达式和目标位置。搭配json-eval($.name)或 XPath 表达式在处理动态响应时比写死模板省力得多。表达式速查表达式示例适用场景JSONPathjson-eval($.customer.name)提取 JSON 消息体字段Propertyget-property(hospitalType)/$ctx:name访问或复用消息属性XPath//getCustomer/id在 XML/SOAP 信封里定位节点Concatfn:concat(Routing to , get-property(Hospital))拼接日志或动态创建路由目标手册里这四种表达式的选取逻辑消息体是 JSON 用json-eval消息体是 XML 用 XPath跨消息流传参用 property需要拼接字符串去构造日志或者动态 URL 用fn:concat。实际项目里一条消息流往往要混合用先 property 取到 ID再 concat 拼出服务地址最后 XPath 从响应里抽取结果。将手册收成速查表之后日常写代理服务时的习惯变成了固定套路先是 log 打印入站消息接下来 property 抽取关键字段payloadFactory 或 enrich 重组消息体filter 按字段值分支send 发往 endpoint——这套流程覆盖了大部分 REST 和 SOAP 协议转换需求。从那以后每次部署新的代理服务都强制走一遍先在控制台尝试工具里验证表达式、再导出 CAR 包、最后用独立客户端联调的正向流程协议转换的返工率降了不止一半希望这份梳理也能帮你少走几步弯路。本文还有配套的精品资源点击获取