有一类接口技术很多年没被提起但真要碰上时网上资料却大多停留在老古董阶段——我说的是WebService。这几年微服务接口基本都是RESTful风格的天下了JSON一梭子打天下但只要你接触过传统制造业、金融老旧系统、运营商内部平台就会发现基于SOAP协议的WebService依旧扛着大量核心业务。尤其是一些十多年前建设的系统对外提供数据能力的方式就是WebService新系统必须去对接它。我之前就碰到过这样一个需求模拟项目X需要把一个业务系统跟某个老平台打通对方只暴露了一个基于SOAP的WebService接口参数格式、安全认证方式都是人家定死的。我们这边用的技术栈是SpringBoot这就出现了一个几十年前的经典问题——如何用SpringBoot实现WebService服务端同时又作为客户端去调用别人家的接口。网上搜索WebService SpringBoot翻来覆去就是几篇老博客结论不少但代码缺胳膊少腿真正能落地跑通的很少。花了两天时间把这块从服务端发布到客户端调用完整踩了一遍故写一篇实操记录希望能帮你省下时间。博主介绍Mr. Yoho关注全栈技术喜欢折腾和研究技术细节。1. 核心思路拆解SpringBoot到底怎么跟WebService扯上关系先说一个根上的认知问题WebService和SpringBoot是否冲突答案是——根本不冲突WebService是基于SOAP协议的一种远程调用方式跟SpringBoot这种应用开发框架是两个维度的东西。SpringBoot负责把你的服务跑起来、管理Bean、提供内嵌容器WebService只是暴露在某个URL路径上的一组业务方法。不过这里有一个历史坑。传统的WebService开发在Java领域使用的是JAX-WS规范最常用的实现是JDK自带的Endpoint发布方式。单独用JDK发布WebService很简单写一个实现类用Endpoint.publish()方法就能发布。但是到了SpringBoot里你不需要自己去创建Endpoint并绑定端口因为服务本身已经运行在Tomcat容器里了你要做的就是通过某种方式把WebService的请求路径注册到SpringBoot内嵌的Servlet容器中。理解这一点非常关键SpringBoot本身不解析SOAP请求它只是一个宿主环境。你要做的是引入一个WebService框架CXF或者其它让这个框架在SpringBoot内嵌容器中注册一个Servlet专门拦截某个URL路径的SOAP请求再转发给你写的业务类。还有一种思路是用Spring自带的HttpInvoker或者JaxWsPortProxyFactoryBean来做客户端调用。但如果你要同时兼顾服务端发布和客户端调用选型上最省心的还是Apache CXF。CXF既能配合SpringBoot做服务端发布又能作为客户端框架生成代理进行调用一套框架两端解决不用来回切技术栈。我这次使用的组合是SpringBoot 2.x CXF 3.x。CXF 3.x对JAX-WS注解支持得非常好几乎可以像写普通类一样写WebService服务端。2. 工具选型解析CXF不是唯一方案但综合成本最低Java领域做WebService大体上有三条路线JDK自带JAX-WS实现轻量但整合SpringBoot麻烦、Apache CXF功能丰富、整合方便、Spring自家的Spring WS更偏文档型和XML操作配置繁琐。对大多数只用过SpringBoot的同学来说CXF是最容易上手的。JDK自带实现的问题在于你要自己管Endpoint的生命周期还要把它挂到Spring容器里。虽然可以用ServletRegistrationBean把一个CXFServlet如果是CXF或者JAX-WS的Servlet注册进去但自己写这些桥接逻辑非常容易出错。用cxf-spring-boot-starter的话框架帮我们把Servlet注册、Spring整合、自动配置全部做完了。项目引入依赖的时候要注意版本协同问题。SpringBoot 2.x对应CXF 3.xSpringBoot 3.x对应CXF 4.x。如果你用SpringBoot 3.x却引入CXF 3.x的包启动时会出现大量ClassNotFoundException或者NoSuchMethodError排查起来很浪费时间。最终引入依赖Maven方式大概像这样dependency groupIdorg.apache.cxf/groupId artifactIdcxf-spring-boot-starter-jaxws/artifactId version3.5.5/version /dependency dependency groupIdorg.apache.cxf/groupId artifactIdcxf-rt-transports-http/artifactId version3.5.5/version /dependency对了如果你用JDK 17以上还需要额外注意dependency groupIdjavax.xml.ws/groupId artifactIdjaxws-api/artifactId version2.3.1/version /dependency dependency groupIdjavax.jws/groupId artifactIdjavax.jws-api/artifactId version1.1/version /dependency原因也很直接JDK 11以后Java EE相关的API模块被移出了JDK默认引入范围而CXF依赖了这些API的编译期类。不补依赖的话编译时会报找不到javax.jws.WebService之类的错误。3. 全局配置文件注册路径与服务发布的那些坑引入依赖之后需要在SpringBoot配置文件中把CXF的基础路径设置好。这里涉及的一个概念是org.apache.cxf.transport.servlet.CXFServlet的默认URL匹配规则。CXF启动时会自动注册一个Servlet默认映射路径是/services/*也就是说你最终发布的WebService地址基本长这样http://ip:port/context-path/services/接口名。我习惯在配置文件中显式指定路径防止默认值跟业务路径冲突server: port: 8080 servlet: context-path: /demo cxf: path: /ws这样配置之后CXF的Servlet映射路径就是/demo/ws/*接口服务的最终访问地址就是http://localhost:8080/demo/ws/接口名?wsdl。有人会问为什么自定义配置之后生成的WSDL地址有时候不对这是CXF的一个老毛病你通过http://localhost:8080/demo/ws/xxx?wsdl访问时WSDL文档里面引用的地址往往是发布时CXF自动解析到的内部地址可能与外部访问地址不一致。这个问题我后面会在重构地址配置那部分详细说。这里值得多说一句如果你用的是SpringBoot 2.6或更高版本由于spring.mvc.pathmatch.matching-strategy默认值改成了PATH_PATTERN_PARSER启动时CXF偶尔会报路径匹配相关的警告一般不会导致故障但最好在配置里显式设置spring: mvc: pathmatch: matching-strategy: ant_path_matcher这个配置主要是给Swagger之类的组件用的不影响CXF但能避免控制台一堆异常堆栈看着舒坦也不会误判系统有问题。4. 服务端开发接口定义、实现类的三个核心注解服务端开发的核心工作其实就是三个注解的事。先说接口定义WebService接口用WebService标注接口方法上按需加WebMethod。这里我踩过最重要的一个坑CXF发布的WebService如果接口里有多个方法而某个方法没有加WebMethod注解它默认不会出现在发布内容里。这一点跟很多网上教程说的模糊情况不一样实测下来不加WebMethod的方法根本不会被发布出来。接口定义大概长这样package com.example.ws.service; import javax.jws.WebMethod; import javax.jws.WebService; WebService(name UserService, targetNamespace http://service.ws.example.com) public interface UserService { WebMethod String getUserInfo(String userId); WebMethod String createUser(String userName, String age); }有几个细节要注意。name属性决定了生成WSDL里wsdl:portType的名称targetNamespace一定要定义因为SOAP请求的namespace必须跟它一致客户端生成的代理才匹配得上。如果你不写targetNamespaceCXF会拿Java包名反推一个默认值两种服务端、客户端写法不一致时调用端很容易报SOAP解析错误。getUserInfo和createUser这种参数很简单的接口直接定义为String即可。但如果你在真实项目中接口参数是复杂对象比如需要传一个User对象那么这个User类也需要用XmlType注解标注否则CXF序列化时无法把Java对象转成XML片段。接下来是真正干活的时候——我在一个实际项目中就是没给参数对象加XmlRootElement注解结果服务端启动正常但是客户端一调用就报javax.xml.bind.MarshalException当时一度以为是CXF版本问题排查了很久才定位到是XML序列化注解缺失。所以复杂参数对象的类型上务必注意别让坑藏在这里。实现类代码如下package com.example.ws.service.impl; import javax.jws.WebService; import com.example.ws.service.UserService; WebService( serviceName UserServiceService, portName UserServicePort, targetNamespace http://service.ws.example.com, endpointInterface com.example.ws.service.UserService ) public class UserServiceImpl implements UserService { Override public String getUserInfo(String userId) { return {\userId\:\ userId \,\name\:\张三\}; } Override public String createUser(String userName, String age) { return create user success: userName , age: age; } }实现类上的WebService注解比接口上的更讲究serviceName会出现在WSDL的wsdl:service节点一般是接口名Service后缀用于客户端定位服务。portName对应绑定端口名称。endpointInterface必须写清楚接口的全限定名它是连接接口和实现类的桥梁。在线下单出现过的一个问题是serviceName随便写了一个跟包名不符的值结果线上服务调试时客户端的代理生成总是找不到对应服务节点。后来查资料才弄明白CXF实际上以实现类的WebService注解配置为准生成WSDL如果serviceName没有严格对应WSDL解析方式客户端在搜索目标服务时就会报错。所以如果你手动写了serviceName和portName一定要跟客户端调用的serviceName保持完全一致这个点亿级数据量系统也可能踩到。最后需要给出一个配置类把上面这个实现类发布成WebService这一步极常用错。网上很多老式教程用的是applicationContext.xml配jaxws:endpoint标签的方式但SpringBoot项目现在基本不用XML配置用Configuration类更干净。package com.example.ws.config; import javax.xml.ws.Endpoint; import org.apache.cxf.Bus; import org.apache.cxf.jaxws.EndpointImpl; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import com.example.ws.service.impl.UserServiceImpl; Configuration public class WebServiceConfig { Autowired private Bus bus; Bean public Endpoint endpoint() { EndpointImpl endpoint new EndpointImpl(bus, new UserServiceImpl()); endpoint.publish(/userService); return endpoint; } }注意endpoint.publish(/userService)里的路径是相对于CXF的Servlet路径的。配置文件中设了cxf.path/ws所以最终访问地址是http://localhost:8080/demo/ws/userService?wsdl。有个非常关键且容易踩的点是EndpointImpl这个类以下划线跟业务类名称作为构造参数这里直接用new UserServiceImpl()相当于已经实例化了一个实现类它会注册到Spring容器里吗答案是——不会。new UserServiceImpl()创建的是一个脱离Spring容器管理的实例这意味着实现类里如果用Autowired注入Service或Mapper会是null一调用业务方法就空指针。正确的做法是让Spring管理实现类然后从Spring上下文中获取或者通过构造器注入Configuration public class WebServiceConfig { Autowired private Bus bus; Autowired private UserServiceImpl userService; Bean public Endpoint endpoint() { EndpointImpl endpoint new EndpointImpl(bus, userService); endpoint.publish(/userService); return endpoint; } }这里有一个容易忽略的细节EndpointImpl的publish方法会真正把Endpoint注册到Servlet的处理器链上。如果你没有加Bean标注而是直接在PostConstruct里手动发布也行但用Bean的好处是——如果发布失败SpringBoot启动直接报错你第一时间就能发现。如果用PostConstruct启动日志可能被吞掉服务起来后你根本不知道WebService到底发布成功没有。5. 客户端开发三种调用方式中最稳的方案选择客户端调用WebService核心思路是用CXF提供的代理工厂JaxWsProxyFactoryBean动态生成一个接口的代理实例然后直接调用接口方法。这本质上就是动态代理机制跟你平时用Feign调用REST接口在体验上非常接近。package com.example.ws.client; import org.apache.cxf.jaxws.JaxWsProxyFactoryBean; import com.example.ws.service.UserService; public class UserServiceClient { public static void main(String[] args) { JaxWsProxyFactoryBean factory new JaxWsProxyFactoryBean(); factory.setServiceClass(UserService.class); factory.setAddress(http://localhost:8080/demo/ws/userService); UserService userService (UserService) factory.create(); String result userService.getUserInfo(1001); System.out.println(result); } }这种方式的优点是快、直接、少依赖不需要提前生成客户端代码。因为服务端和客户端往往在同一个项目中至少在本次模拟项目X中两部分代码处于一个工程树中所以客户端直接引用服务端的接口类即可。这是最简方案。但实际项目中客户端常常不在同一个服务里此时有两种做法方式A把服务端接口复制到客户端工程保持包名、注解完全一致。方式B用wsimport命令先拉取WSDL生成客户端代理代码再调用。方式A坑比较多因为接口类的targetNamespace、参数类、方法签名必须和服务端的完全一致稍有一个不对SOAP消息解析就会失败。方式B虽然生成的代码冗余度大但是通用性好不依赖服务端是否开放源码。如果你想用wsimport生成代码命令大致是wsimport -keep -p com.example.ws.client.generated http://localhost:8080/demo/ws/userService?wsdl生成之后你会得到一堆Java文件里面有一套完整的JDK JAX-WS风格的代理类直接实例化UserServiceService再拿到端口调用即可。这种方式生成的代码适合跨团队、跨语言的场景因为它不依赖任何CXF的客户端类库纯JDK标准。如果你希望调用的时候打印SOAP请求和响应报文方便排查问题可以在创建代理前开启CXF日志拦截器factory.getInInterceptors().add(new LoggingInInterceptor()); factory.getOutInterceptors().add(new LoggingOutInterceptor());导入类是import org.apache.cxf.interceptor.LoggingInInterceptor; import org.apache.cxf.interceptor.LoggingOutInterceptor;实际使用中LoggingInInterceptor打印的是对方返回的SOAP响应报文LoggingOutInterceptor打印的是你发出去的SOAP请求报文。这两个拦截器在联调初期非常救命能看到实际的XML消息内容而不是只看一脸懵的状态码。6. 高级配置WebService超时设置与地址重构提到客户端调用新手很容易忽略的就是超时时间。CXF默认的超时时间比较长有人实测甚至超过好几分钟一旦对方服务假死或者网络不通你的线程会长时间挂起直到很晚才报ConnectException。这在联调时非常影响排查效率。正确的做法是在客户端设置连接超时和接收超时factory.getClient().getOutInterceptors().add(new org.apache.cxf.interceptor.LoggingOutInterceptor()); // 设置连接超时 org.apache.cxf.transport.Conduit conduit org.apache.cxf.frontend.ClientProxy.getClient(userService).getConduit(); conduit.getClient().setConnectionTimeout(3000); conduit.getClient().setReceiveTimeout(10000);注意在CXF 3.3.0以上版本中conduit.getClient()已经改成了conduit.getClient()或者直接在Conduit中操作。这里不同版本API略有差异如果你是CXF 3.5.x版本直接用上面代码第5行的getClient()即可。有一个非常容易遇到的细节SocketTimeout和ConnectTimeout的作用范围不一样。连接超时只管TCP握手建立连接的时间接收超时管的是从发出请求到收到响应的整个等待时间。如果你接的是业务的报表查询接口底层可能执行了几分钟此时接收超时不能设置太短否则会误报超时而连接超时长度一般很短因为网络不通往往几秒内就能判断出来。再来说说服务端WSDL地址重构问题。我在本地测试的时候发现通过localhost访问正常但把地址换成内网IP后再去访问WSDL里面显示的soap:address地址还是localhost。这就导致客户端拿WSDL生成代码后调用失败。解决办法是在配置文件中使用CXF提供的CXFServlet初始化参数cxf: path: /ws servlet: load-on-startup: 1不过这只能解决Servlet映射不能解决WSDL内嵌地址问题。真正能解决地址重构的方式是配置一个System.setProperty或者使用自定义AddressRewriteInterceptor但说实话配置复杂一般情况下你直接用客户端调用方式不依赖WSDL的自动生成的话完全不需要纠结这个问题。我不建议在生产环境依赖客户端去拉WSDL的方式动态生成代理因为拉WSDL生成代理的方式常常必须在服务启动时执行而服务启动时服务端可能没起来就会打乱你的部署顺序。所以把接口类和服务端定义保持一致用JaxWsProxyFactoryBean直接调用才是日常项目中最稳的做法。7. 报文调试与追踪好看懂SOAP才是真正的掌握WebService联调时最大的困惑不是写代码而是看不懂SOAP报文。尤其当参数嵌套复杂或者返回值结构庞大时一眼看过去全是尖括号标签难免头皮发麻。实际调试时我的建议是先抓报文再猜问题。加日志拦截器之后的输出大概长这样soap:Envelope xmlns:soaphttp://schemas.xmlsoap.org/soap/envelope/ soap:Body ns2:getUserInfo xmlns:ns2http://service.ws.example.com/ arg01001/arg0 /ns2:getUserInfo /soap:Body /soap:Envelope注意看arg0这个标签名。如果你接口定义的参数名是userIdCXF默认生成SOAP消息时会把参数标签命名为arg0这是CXF的一个“传统艺能”。很多同学一看到arg0就慌了以为参数名丢了。实际上CXF默认不保留Java方法参数名如果你想在SOAP报文中显示有意义的参数名需要在接口或实现类上加上WebParam(name userId)注解WebMethod String getUserInfo(WebParam(name userId) String userId);这个细节在对接一些严格校验参数的第三方系统时非常重要对方可能在WSDL或者接口文档里定义了固定的SOAP标签名比如userCode如果你生成的是arg0对方直接拒绝请求。看返回报文时常见场景是返回值里面嵌套了XML结构。比如接口返回一个字符串内容是JSON格式那么在SOAP响应里其实就是一个普通的String文本外层被包在一个形如return{userId:1001}/return的标签里。此时你只需要做字符串解析问题不大。但如果你的返回值不是简单字符串而是一个对象例如UserInfoDTO那么CXF会把整个DTO序列化成一段XML标签层级跟DTO的属性是一一映射的。理解了这一点排查时就不会在报文里迷路。调试工具的使用上我除了用代码日志拦截器偶尔也会用SoapUI工具做冒烟验证。在SoapUI里粘贴WSDL地址它会自动生成请求模板你可以直接修改参数后发送请求。不过需要注意的是SoapUI生成的请求模板默认带上SOAPAction头而一些服务端对SOAPAction校验很严格如果报文发出去报SOAPAction缺失或错误大概率是服务端接口的WebMethod(action ...)没配好。8. 常见问题与排查技巧实录两天实战下来把碰到的问题整理成了一张速查表排查问题的时候按表索骥能省不少时间。现象根本原因解决办法启动报org.apache.cxf.wsdl11.WSDLManagerImpl异常CXF与SpringBoot版本不匹配统一升级CXF版本或降低SpringBoot版本调用时返回No such operation接口方法没有加WebMethod或者operationName配置错确认接口所有需要暴露的方法都加了WebMethod注解返回Could not find conduit客户端地址配错或者WebService未发布成功先用浏览器访问?wsdl确认地址存在返回401或403服务端有权限拦截或CXF拦截器校验失败检查服务端WebService配置、拦截器是否加了认证逻辑WSDL地址是localhost但外部访问需要内网IPCXF自动生成地址时使用的本机解析名不对忽略WSDL自动生成地址直接用JaxWsProxyFactoryBean指定地址XML解析异常unexpected element客户端接口targetNamespace与服务端不一致检查两端的targetNamespace、portType名称是否一致对象返回序列化失败返回类型的DTO没有XmlRootElement注解给参宿类型或者返回类型DTO添加JAXB注解客户端调用超时接收超时时间设置过短或者对方服务响应慢调大setReceiveTimeout或者优化服务端耗时逻辑日志打印不出SOAP报文没有加LoggingInInterceptor/LoggingOutInterceptor在factory或者endpoint上添加日志拦截器还有一个非常经典的坑是SpringBoot项目里同时引入了spring-boot-starter-web和CXF后CXF的Servlet路径如果设置的跟SpringMVC的DispatcherServlet路径冲突接口会出现404。比如你的项目里既有普通REST接口又有WebService接口路径设计时一定要给WebService单独分一段比如/ws开头不要跟/api之类的REST路径混在一起。这个点在规划阶段就要想好不然上生产后改路径会影响已有的调用方。另外WebService服务端发布后你可以在浏览器直接访问http://localhost:8080/demo/ws/userService?wsdl查看WSDL。需要注意的是CXF默认会生成WSDL但页面可能渲染得比较慢且第一次访问时CXF才会真正初始化该Endpoint的WSDL信息。如果浏览器直接报404第一个确认的点是CXF的Servlet路径到底配没配成功第二个确认点是endpoint.publish(/userService)有没有执行成功第三个确认点才是你访问的URL路径是否有拼写错误。我当时调试时花了半小时反复检查代码最后才发现是自己把路径拼成了/userService/多了一个斜杠。拼接地址时注意一个关键但容易被忽略的点endpoint.publish(/userService)内部会做字符串处理如果在路径末尾加上一个斜杠/userService/CXF会把这个/userService/连同斜杠当作服务名的一部分最后访问的地址会变成http://localhost:8080/demo/ws/userService/?wsdl而你按习惯访问http://localhost:8080/demo/ws/userService?wsdl时就找不到。服务发布路径末尾的斜杠严格来说是敏感字符我不建议你乱加。为了稳妥我通常会在发布路径前后都做一次Trim检查并且在自测时用一个封装方法统一拼接地址避免不同模块拼接层级产生多余斜杠。这个细节在真实项目中非常有价值尤其当服务端和客户端不是由同一人开发时光对齐路径就要耗掉半天能直接用工具类收敛的地方就提前收敛。9. 另一种服务端发布方式用CXFServlet灵活植入任意路径前面讲的是用EndpointImpl的标准做法其实CXF还有另一种发布方式也值得掌握尤其在你想完全掌控URL映射的时候——手动注入CXFServlet并通过ServletRegistrationBean注册。如果你不想使用cxf.path配置而是想让WebService在一个完全自定义的URL上生效可以自己定义配置类Configuration public class CxfServletConfig { Bean public ServletRegistrationBeanCXFServlet cxfServlet() { CXFServlet cxfServlet new CXFServlet(); ServletRegistrationBeanCXFServlet registration new ServletRegistrationBean(cxfServlet, /customWs/*); registration.setLoadOnStartup(1); return registration; } Bean public Endpoint userEndpoint() { EndpointImpl endpoint new EndpointImpl(bus, userService); endpoint.publish(/userService); return endpoint; } }这种方式在多模块项目里特别实用。如果你的系统是一个平台里面挂了好几个业务模块每个模块都想暴露自己的WebService接口你可以给每个模块注册一个独立路径的CXFServlet让它们各自负责各自的接口避免所有接口都挤在同一个/services前缀下。不过需要注意多个CXFServlet注册时每个Servlet内部维护的Bus可能独立也可能共享这取决于你是否为每个Servlet单独配置了Bus。共享Bus的话发布的Endpoint要保证路径唯一否则CXF会报Endpoints冲突表现是启动时一切正常但运行时一个地址访问两个方法直接乱套。这个场景虽然少见但一旦出现排查起来非常痛苦。对于绝大多数单模块项目我还是默认推荐使用cxf.pathEndpointImpl.publish()的方式简单直接代码量最少出问题的点也最少。10. 最后分享点个人经验WebService这套东西放在今天看确实有点“复古”但它依旧活跃在大量企业级系统的对接场景中。SpringBoot做WebService服务端和客户端核心思路跟做REST接口是相通的——定义好接口契约让框架帮你完成协议转换和序列化。你需要重点控制的是接口契约的准确性和一致性简单说就是包名、注解、targetNamespace、参数标签名这些必须跟对方保持一致才不会在联调阶段一头雾水。我个人实际操作中比较深的体会是不要在联调阶段才想到去核对SOAP报文格式。一开始就该把LoggingInInterceptor和LoggingOutInterceptor打开把请求和响应报文打印出来先自己比对一遍再跟对方联调。这一点跟写REST接口时先看一下Swagger里的JSON结构是一个道理。另一个建议是如果业务有选择余地优先考虑RESTful接口如果没得选必须用WebService那就老老实实把CXF这套标准链路走熟别东拼西抄网上几年前的代码。CXF版本和SpringBoot版本匹配、路径统一规划、参数注解写清楚这三大问题处理好了WebService的开发其实非常顺利。最后如果你初次接触JAXB注解对XML结构的影响建议花半小时跑一个简单的对象序列化测试感受一下嵌套字段怎么映射成XML标签层级这对排查那些“字段对不上”“结构不对”的怪问题非常有用。