Java XFire 入门：搭建一个简单的 Web Service 服务

XFire 是一个用于构建 SOAP Web Service 的 Java 框架，曾广泛用于 Java EE 项目。它可以把普通 Java 类发布为 SOAP 服务，并根据接口生成 WSDL，供其他语言或平台的客户端调用。对于维护旧系统、理解 SOAP 服务的基本结构，或者需要复现既有 XFire 项目，掌握它仍有实际价值。

但要先说明：XFire 已停止维护，属于较早期的技术。新项目通常应评估仍在维护的 JAX-WS 实现或其他方案，不宜仅因为示例简单就直接选用 XFire。本文使用 XFire 1.2.6 演示一个传统的 Servlet Web 应用：服务端提供问候和加法操作，部署到支持 javax.servlet 的 Servlet 容器中，再通过 WSDL 了解服务契约。

一、XFire 适合什么场景

Web Service 在这里特指以 SOAP 消息交换数据、通常通过 HTTP 传输的服务。SOAP 消息遵循 XML 结构，服务契约通常用 WSDL 描述。客户端可以根据 WSDL 生成代理代码，因此调用方不必和服务端使用同一种编程语言。

• 维护已有系统：项目已经使用 XFire，新增接口需要沿用既有运行环境和调用约定。
• 对接 SOAP 系统：对方提供 WSDL，且对 SOAP、XML 或既有服务契约有明确要求。
• 学习传统 Web Service：希望了解服务接口、实现类、WSDL 与 HTTP 端点之间的关系。

如果服务仅供新应用之间调用，且没有 SOAP 兼容要求，应先比较维护成本、客户端生态和部署约束，而不是默认采用 XFire。XFire 本身也不是权限管理、身份认证或加密方案；发布服务后，仍需由应用和部署环境承担这些责任。

二、准备开发环境

下面的示例依赖旧版 Java EE API，使用 javax.servlet 命名空间。建议用 JDK 8 和 Tomcat 7 这类兼容旧 Servlet 应用的环境验证；具体兼容性仍应以项目实际依赖和容器为准。不要把此处配置直接照搬到只支持 jakarta.servlet 的新容器中。

创建 Maven Web 项目，目录结构如下：

xfire-hello/
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── example/
        │       └── GreetingService.java
        │       └── GreetingServiceImpl.java
        └── webapp/
            └── WEB-INF/
                └── web.xml
                └── classes/
                    └── META-INF/
                        └── xfire/
                            └── services.xml

通常不需要把 services.xml 手工放进 src/main/webapp/WEB-INF/classes。Maven 的 Java 资源目录 src/main/resources 会被复制到构建输出的类路径中。因此，建议实际按下面的结构放置配置文件：

src/main/resources/META-INF/xfire/services.xml

三、配置 Maven 依赖

在项目根目录创建 pom.xml。示例使用 XFire 1.2.6 的聚合依赖 xfire-all，并以传统 WAR 方式打包：

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>example</groupId>
    <artifactId>xfire-hello</artifactId>
    <version>1.0.0</version>
    <packaging>war</packaging>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.codehaus.xfire</groupId>
            <artifactId>xfire-all</artifactId>
            <version>1.2.6</version>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>xfire-hello</finalName>
    </build>
</project>

provided 表示 Servlet API 由容器提供，不打包进应用。旧版框架的传递依赖可能与较新的库发生版本冲突；如果 Maven 构建失败或部署时报类加载错误，应检查依赖树和容器日志，而不是随意把多个版本的同名 JAR 全部放进 WEB-INF/lib。

四、定义服务接口和实现

服务接口决定要向客户端公开哪些操作。把接口与实现分开，便于明确服务契约，也避免将内部业务类直接暴露为网络接口。

创建 src/main/java/example/GreetingService.java：

package example;

public interface GreetingService {
    String hello(String name);

    int add(int left, int right);
}

创建 src/main/java/example/GreetingServiceImpl.java：

package example;

public class GreetingServiceImpl implements GreetingService {

    @Override
    public String hello(String name) {
        if (name == null || name.trim().isEmpty()) {
            return "Hello, guest!";
        }
        return "Hello, " + name.trim() + "!";
    }

    @Override
    public int add(int left, int right) {
        return left + right;
    }
}

这里的参数是简单类型，适合入门验证。int 加法可能发生整数溢出，例如结果超出 Java int 的取值范围时会回绕；真实业务应根据需求选择更合适的范围与错误处理方式。hello 中的空值处理只是示例业务逻辑，并不代表 XFire 自动校验了输入。

五、配置 XFire 服务

创建 src/main/resources/META-INF/xfire/services.xml：

<beans xmlns="http://xfire.codehaus.org/config/1.0">
    <service>
        <name>GreetingService</name>
        <namespace>http://example.com/xfire/greeting</namespace>
        <serviceClass>example.GreetingService</serviceClass>
        <implementationClass>example.GreetingServiceImpl</implementationClass>
    </service>
</beans>

其中，serviceClass 指向服务接口，implementationClass 指向实现类，name 是服务名称，namespace 是 XML 命名空间。命名空间是服务契约的一部分，不是访问服务器的 URL；正式使用时应选择稳定且由组织管理的 URI，避免随意改动导致客户端契约不兼容。

六、配置 Servlet 入口

创建 src/main/webapp/WEB-INF/web.xml，将 XFire Servlet 映射到 /services/*：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">

    <servlet>
        <servlet-name>xfire</servlet-name>
        <servlet-class>org.codehaus.xfire.transport.http.XFireServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>xfire</servlet-name>
        <url-pattern>/services/*</url-pattern>
    </servlet-mapping>
</web-app>

容器的 Servlet 规范版本必须与部署目标一致。如果目标容器只支持较早版本，应相应调整 web.xml 的命名空间和版本声明。关键是 XFire 使用的 javax.servlet API 必须与容器提供的 API 匹配；将旧框架部署到使用 jakarta.servlet 的环境时，不能只靠修改 XML 声明解决包名不兼容问题。

七、构建、部署与确认服务

在项目根目录运行：

mvn clean package

构建成功后会生成 target/xfire-hello.war。将它部署到 Servlet 容器后，假设应用上下文路径为 /xfire-hello，服务端点通常可通过以下地址访问：

http://localhost:8080/xfire-hello/services/GreetingService

可尝试在浏览器中打开带有 ?wsdl 的地址：

http://localhost:8080/xfire-hello/services/GreetingService?wsdl

如果服务配置被正确发现，响应通常会包含 WSDL。实际端点地址会受容器端口、应用上下文路径、反向代理和 XFire 配置影响；以部署环境返回的 WSDL 为准。WSDL 中包含的服务地址如果错误，也可能是代理转发或外部访问地址配置不一致，不一定意味着 Java 接口写错。

在类 Unix 系统中，也可以用 curl 查看 WSDL 是否可访问：

curl -i "http://localhost:8080/xfire-hello/services/GreetingService?wsdl"

拿到 WSDL 后，可使用适合目标语言的 SOAP 客户端或代码生成工具进行调用。不同 XFire 版本、绑定和服务配置会影响 SOAP 操作包装元素与命名空间。不要仅凭 Java 方法名猜测请求 XML；先查看 WSDL 中的操作、消息、绑定和地址，再按契约构造请求。这样也能避免把 SOAP 1.1 与 SOAP 1.2 的内容类型、信封命名空间混用。

八、参数限制和数据类型边界

SOAP 参数并非任意 Java 对象都能直接、可靠地暴露。框架需要把 Java 类型映射到 XML Schema 类型；简单标量通常最容易互操作，复杂对象则涉及字段、访问器、集合、继承、空值、日期时间和类型映射等问题。本文只使用 String 和 int，是为了把重点放在服务发布流程，而不是暗示复杂对象无需配置就一定能被各类客户端一致理解。

• 优先使用明确的契约类型：对外接口尽量采用跨语言容易表达的数据类型，并确认生成的 WSDL 与预期一致。
• 避免随意暴露内部模型：数据库实体或带有复杂继承关系的对象可能形成难以维护的契约。可为服务定义专用的数据传输类型。
• 对输入做应用级校验：检查长度、范围、必填字段及业务规则。SOAP 能描述部分类型约束，但不会替代完整的业务校验。
• 处理错误契约：确定异常如何映射为 SOAP Fault，并避免把堆栈、数据库地址等内部细节返回给调用方。

具体支持哪些类型、集合和映射方式，取决于 XFire 版本、绑定和配置。不要把其他框架的注解或默认行为直接套用到 XFire；通过实际生成的 WSDL 和目标客户端互操作测试确认结果。

九、常见错误排查

1. 访问服务返回 404

先核对应用上下文路径、Servlet 映射和服务名称。示例的映射是 /services/*，服务名是 GreetingService；如果应用部署名不同，最终 URL 也会不同。还要确认 WAR 已成功部署，而不是仅完成 Maven 打包。

2. 服务找不到或启动时报告类不存在

检查 services.xml 是否位于 src/main/resources/META-INF/xfire/services.xml，以及配置中的完整类名是否与 Java 源码的包名一致。可检查构建产物中是否存在 WEB-INF/classes/META-INF/xfire/services.xml。

3. Servlet 类或 Servlet API 不兼容

检查容器是否提供与应用匹配的 javax.servlet API，以及依赖是否意外把 Servlet API 打包进 WAR。若环境要求 jakarta.servlet，旧 XFire 依赖很可能无法直接部署，应评估迁移或使用兼容旧 API 的隔离环境。

4. WSDL 中的地址不适合外部客户端

服务在反向代理或负载均衡器后面时，应用内部看到的主机名、协议和端口可能与外部访问地址不同。客户端按 WSDL 生成代理后可能连接错误地址。应检查代理转发头、容器配置和部署拓扑，并以外部客户端实际获取到的 WSDL 验证。

5. 客户端调用报参数或命名空间错误

对照 WSDL 检查操作名称、消息结构、命名空间和数据类型。SOAP 参数名称、元素包装方式并不保证等同于 Java 方法参数的直观写法。先用 WSDL 生成客户端，通常比手写 XML 更不容易遗漏契约细节。

6. 改了接口但旧客户端仍然失败

WSDL 是客户端生成代理的重要依据。修改方法名称、参数类型、命名空间或返回结构，都可能造成契约变化。接口升级前应明确版本兼容策略，并针对旧客户端进行回归测试。

十、安全与生产使用边界

发布一个可访问的 SOAP 地址，并不意味着服务已经受到保护。示例没有实现认证、授权、访问控制、请求限流或传输加密，也没有展示对恶意 XML 的专门防护。它只用于说明如何把服务发布出来，不能作为安全方案的替代品。

• 使用 HTTPS：通过 TLS 保护传输链路，妥善管理证书和终止 TLS 的代理配置。HTTPS 不能代替调用方身份认证或业务授权。
• 实施身份认证与授权：根据系统架构在应用、网关或基础设施层验证调用方，并按操作和数据实施授权。不要把秘密凭据硬编码在源码或示例配置中。
• 限制网络暴露面：只向确有需要的网络或调用方开放端点，配置访问控制、监控和合理的请求大小限制。
• 审慎处理 XML：解析外部 XML 时，要关注拒绝服务、资源消耗及外部实体相关风险。应根据实际使用的解析器与框架版本核实安全配置；不能假设旧框架默认已经防护。
• 控制错误信息：记录必要的诊断信息，但不要向远程调用方返回内部堆栈、凭据、路径或敏感数据。
• 评估依赖风险：XFire 已停止维护，依赖树可能包含年代久远的组件。上线前应做依赖审计、漏洞检查和兼容性测试，并为升级或迁移制定计划。

如果业务要求 WS-Security、可靠消息、事务或复杂的 SOAP 策略，必须确认所用实现及版本明确支持所需能力，并进行端到端验证。不能把“可以通过 HTTP 接收 SOAP 请求”当作具备上述安全或消息保障能力。

总结

一个最小的 XFire Web Service 由几部分组成：定义服务接口和实现类，在 services.xml 中注册服务，用 XFire Servlet 暴露 HTTP 入口，最后通过部署地址访问端点并检查 WSDL。本文的示例适合演示基本发布流程，也可作为维护旧项目时的排查起点。

真正接入其他系统时，还需要验证 WSDL 与客户端的互操作性，设计稳定的数据契约，处理异常和输入校验，并在部署层落实认证、授权、HTTPS 与网络访问控制。考虑到 XFire 已停止维护，新项目应把技术生命周期和依赖安全列入选型；只有在兼容既有系统或明确需要复现旧环境时，才适合继续使用这套方案。