Java Web Service 完整教程

目录

1. 第一部分：基础概念

   
   （图片来源网络，侵删）
   • 1 什么是 Web Service？
   • 2 Web Service 的核心特点
   • 3 Web Service 的两种主流风格：SOAP vs. REST

2. 第二部分：核心技术栈

   • 1 JAX-WS (Java API for XML Web Services) - 用于 SOAP
   • 2 JAX-RS (Java API for RESTful Web Services) - 用于 REST
   • 3 Spring Boot - 现代化开发的王者

3. 第三部分：实战演练

   • 1 使用 JAX-WS 创建 SOAP Web Service (Tomcat 部署)
   • 2 使用 JAX-RS (Jersey) 创建 RESTful Web Service
   • 3 使用 Spring Boot 创建 RESTful Web Service (推荐)

4. 第四部分：进阶与最佳实践

   • 1 Web Service 测试工具
   • 2 WSDL (Web Services Description Language)
   • 3 安全性考虑
   • 4 版本控制

第一部分：基础概念

1 什么是 Web Service？

Web Service 是一种基于 Web 的、跨平台的、自描述的、模块化的应用程序，它可以使用标准的 HTTP 协议进行通信，允许不同的系统在网络上相互交互，而无需考虑底层平台、编程语言或实现技术的差异。

Web Service 就是一个“网络上的函数”，你可以通过 HTTP 请求来调用它,并获取返回的数据。

2 Web Service 的核心特点

• 跨平台: 基于 XML/JSON 等标准数据格式，任何语言（Java, Python, C# 等）都可以调用。
• 跨语言: 与跨平台类似，只要能发送 HTTP 请求并解析 XML/JSON,就可以调用。
• 基于标准: 主要依赖 HTTP, XML, JSON, SOAP, REST 等开放标准。
• 松耦合: 服务提供方和使用方之间不需要紧密绑定，它们通过一个“契约”（WSDL 或 API 文档）来定义交互方式。
• 自描述: 服务通常通过一个描述文件（如 WSDL）来告诉客户端它提供了哪些功能、如何调用。

3 Web Service 的两种主流风格：SOAP vs. REST

这是理解 Web Service 最关键的区别。

• SOAP 像一个功能强大的邮局包裹，有严格的打包格式（XML）、安全认证和签收流程，适合重要的、需要保证安全的文件传输。
• REST 像一个高效的快递服务，你直接告诉快递员（HTTP）你要哪个地址（URI）的什么东西（资源），是用取（GET）还是放（POST），简单直接,适合大多数日常通信。

第二部分：核心技术栈

1 JAX-WS (Java API for XML Web Services)

• 定义: Java 官方定义的一套用于创建 SOAP Web Service 的 API。
• 实现: Sun (Oracle) 提供了参考实现，Metro 是最常用的，IBM 的 WebSphere 也提供了自己的实现。
• 特点: 是 Java EE 的一部分，功能强大，支持 WS-* 标准（如安全、事务）。
• 现状: 在传统的 Java EE 项目中（如 JBoss, WebLogic）仍然广泛使用，但在新项目中，尤其是在 Spring 生态中,使用较少。

2 JAX-RS (Java API for RESTful Web Services)

• 定义: Java 官方定义的一套用于创建 RESTful Web Service 的 API。
• 实现: JAX-RS 只是一个规范，需要具体的实现框架，主流的实现有：
  • Jersey: 由 Oracle 赞助，是 JAX-RS 的参考实现,功能成熟稳定。
  • RESTEasy: 由 Red Hat 赞助，是 JBoss/WildFly 的一部分。
  • Apache CXF: 一个功能非常强大的开源框架，同时支持 SOAP 和 REST。
• 特点: 简单、灵活、注解驱动，是目前 Java Web Service 开发的主流选择。

3 Spring Boot - 现代化开发的王者

Spring Boot 并不是 Web Service 的规范，但它极大地简化了 Web Service 的开发。

• 与 JAX-RS 的关系: Spring Boot 可以非常方便地集成 Jersey 或 RESTEasy，但更常用的是它自己的 Spring MVC 框架。
• Spring MVC 的 REST 支持: Spring Boot 利用 Spring MVC 的 @RestController 和 @RequestMapping 等注解，可以非常轻松地创建 RESTful API，这种方式已经成为 Java 开发的事实标准。
• 优势:
  • 约定优于配置: 无需大量 XML 配置。
  • 自动配置: Tomcat 服务器、数据源等自动配置好。
  • 生态丰富: 无缝集成 Spring Security, Spring Data, Spring Cloud 等强大组件。
  • 社区活跃: 拥有最广泛的开发者社区和最多的学习资源。

学习建议:

• 入门: 先学习 JAX-RS (Jersey) 理解 REST 的基本概念。
• 实战/工作: 直接学习 Spring Boot，这是目前企业招聘的主流要求,效率最高。

第三部分：实战演练

1 使用 JAX-WS 创建 SOAP Web Service

目标: 创建一个简单的计算器服务,可以加两个数。

步骤 1: 创建 Java 项目

创建一个标准的 Java Dynamic Web Project (在 Eclipse 或 IDEA 中)。

步骤 2: 创建服务端点接口

这个接口定义了 Web Service 的公共方法。

// src/com/example/calculator/Calculator.java
package com.example.calculator;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// @WebService: 将这个类标记为一个 Web Service
@WebService
// @SOAPBinding: 定义 SOAP 的风格，默认是 DOCUMENT，这里明确为 RPC
@SOAPBinding(style = SOAPBinding.Style.RPC)
public interface Calculator {
    // @WebMethod: 将这个公共方法暴露为 Web Service 的一个操作
    @WebMethod
    public int add(int a, int b);
}

步骤 3: 创建服务端点实现类

// src/com/example/calculator/CalculatorImpl.java
package com.example.calculator;
import javax.jws.WebService;
// 注意：实现类需要实现上面的接口
@WebService(endpointInterface = "com.example.calculator.Calculator")
public class CalculatorImpl implements Calculator {
    @Override
    public int add(int a, int b) {
        return a + b;
    }
}

步骤 4: 发布 Web Service

你需要一个发布器，最简单的方式是使用 JDK 自带的 Endpoint。

// src/com/example/calculator/Publisher.java
package com.example.calculator;
import javax.xml.ws.Endpoint;
public class Publisher {
    public static void main(String[] args) {
        // 定义服务的访问地址
        String address = "http://localhost:8080/calculator";
        // 发布服务
        Endpoint.publish(address, new CalculatorImpl());
        System.out.println("SOAP Web Service is published at: " + address);
    }
}

步骤 5: 部署和测试

1. 部署: 运行 Publisher.java 的 main 方法，服务就被发布到你本地的 Tomcat（或其他容器）上了。
2. 访问 WSDL: 在浏览器中访问 http://localhost:8080/calculator?wsdl，如果看到 XML 内容，说明发布成功，这就是服务的“说明书”。
3. 测试: 可以使用 wsimport 命令生成客户端代码，或者使用 SoapUI 等工具来调用这个服务。

2 使用 JAX-RS (Jersey) 创建 RESTful Web Service

目标: 创建一个用户管理服务，可以提供获取用户列表和单个用户信息的 REST API。

步骤 1: 创建 Maven 项目

在 pom.xml 中添加 Jersey 依赖：

<dependencies>
    <!-- Jersey 核心依赖 -->
    <dependency>
        <groupId>org.glassfish.jersey.containers</groupId>
        <artifactId>jersey-container-servlet</artifactId>
        <version>2.39</version>
    </dependency>
    <!-- 为了支持 JSON -->
    <dependency>
        <groupId>org.glassfish.jersey.media</groupId>
        <artifactId>jersey-media-json-jackson</artifactId>
        <version>2.39</version>
    </dependency>
</dependencies>

步骤 2: 创建资源类

// src/main/java/com/example/user/User.java
// 简单的 POJO
public class User {
    private int id;
    private String name;
    // getters, setters, constructor
}
// src/main/java/com/example/user/UserResource.java
package com.example.user;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import java.util.Arrays;
import java.util.List;
@Path("/users") // 定义这个资源的基 URI
public class UserResource {
    // 模拟一个数据库
    private List<User> users = Arrays.asList(
        new User(1, "Alice"),
        new User(2, "Bob")
    );
    @GET // 处理 HTTP GET 请求
    @Produces(MediaType.APPLICATION_JSON) // 声明返回 JSON 格式
    public List<User> getAllUsers() {
        return users;
    }
    @GET
    @Path("/{userId}") // 定义一个路径参数
    @Produces(MediaType.APPLICATION_JSON)
    public getUserById(@PathParam("userId") int id) {
        return users.stream()
                    .filter(user -> user.getId() == id)
                    .findFirst()
                    .orElse(null);
    }
}

步骤 3: 配置 Jersey Servlet

在 web.xml 中注册 Jersey 的 Servlet：

<web-app ...>
    <servlet>
        <servlet-name>Jersey Web Application</servlet-name>
        <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>jersey.config.server.provider.packages</param-name>
            <param-value>com.example.user</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Jersey Web Application</servlet-name>
        <url-pattern>/api/*</url-pattern>
    </servlet-mapping>
</web-app>

步骤 4: 部署和测试

1. 将项目部署到 Tomcat。
2. 测试 API:
   • 获取所有用户: GET http://localhost:8080/your-app-name/api/users
   • 获取 ID 为 1 的用户: GET http://localhost:8080/your-app-name/api/users/1
   • 可以使用浏览器、Postman 或 curl 命令进行测试。

3 使用 Spring Boot 创建 RESTful Web Service (强烈推荐)

这是目前最高效、最主流的方式。

步骤 1: 创建 Spring Boot 项目

使用 Spring Initializr (Web 工具),选择：

• Project: Maven Project
• Language: Java
• Spring Boot: 选择一个稳定版本 (e.g., 3.x.x)
• Dependencies: Spring Web (包含了 RESTful 开发所需的一切)

步骤 2: 创建资源类

代码与 Jersey 版本非常相似，但注解来自 Spring。

// src/main/java/com/example/user/User.java
// POJO 同上
// src/main/java/com/example/user/UserController.java
package com.example.user;
import org.springframework.web.bind.annotation.*;
import java.util.Arrays;
import java.util.List;
@RestController // @Controller + @ResponseBody 的组合，直接返回对象转为 JSON
@RequestMapping("/api/users") // 类级别的路径映射
public class UserController {
    private List<User> users = Arrays.asList(
        new User(1, "Alice"),
        new User(2, "Bob")
    );
    @GetMapping // 默认处理 GET 请求，映射到 /api/users
    public List<User> getAllUsers() {
        return users;
    }
    @GetMapping("/{userId}") // 处理 /api/users/{userId} 的 GET 请求
    public User getUserById(@PathVariable int userId) { // @PathVariable 绑定路径变量
        return users.stream()
                    .filter(user -> user.getId() == userId)
                    .findFirst()
                    .orElse(null);
    }
}

步骤 3: 运行和测试

1. 运行主应用程序（带有 @SpringBootApplication 注解的类）。
2. Spring Boot 会自动启动一个内嵌的 Tomcat 服务器。
3. 测试 API:
   • 获取所有用户: GET http://localhost:8080/api/users
   • 获取 ID 为 1 的用户: GET http://localhost:8080/api/users/1
   • 同样可以使用 Postman 或 curl。

对比: 可以看到，Spring Boot 的代码更简洁，无需任何 XML 配置,开箱即用。

第四部分：进阶与最佳实践

1 Web Service 测试工具

• Postman: 现代 API 测试的行业标准，功能强大,图形化界面友好。
• SoapUI: 专门用于测试 SOAP 和 REST 服务的工具，尤其擅长处理 SOAP。
• curl: 命令行工具，快速、简单,适合开发者进行快速验证。
• Swagger / OpenAPI: 用于设计、构建、记录和使用 RESTful API 的工具，它可以生成一个交互式的 API 文档（UI），让开发者可以直接在页面上测试 API，Spring Boot 集成 Swagger 非常方便。

2 WSDL (Web Services Description Language)

• 定义: XML 格式的文件，用于描述 SOAP Web Service 的功能、方法、参数、消息格式等。
• 作用: 客户端通过读取 WSDL 文件，可以知道如何正确地调用这个服务，无需关心其内部实现，它是 SOAP 服务的“说明书”。
• 生成: 在 JAX-WS 中，WSDL 通常由服务器自动生成（如 ?wsdl）。

3 安全性考虑

• 认证:
  • SOAP: 通常使用 WS-Security 标准，支持 UsernameToken, X.509 Certificates 等。
  • REST: 常用 OAuth 2.0 和 JWT (JSON Web Token)，Spring Security 提供了非常成熟的 JWT 支持。
• 授权: 确定已认证的用户是否有权限访问某个资源。
• HTTPS: 无论 SOAP 还是 REST，在生产环境中都应使用 HTTPS 来加密传输,防止数据被窃听。

4 版本控制

API 是会演变的，如何在不破坏现有客户端的情况下更新 API？

• URI 路径版本控制: /api/v1/users, /api/v2/users，最清晰,最推荐。
• 请求头版本控制: 在 Accept 或自定义头中添加版本信息。
• 查询参数版本控制: ?version=1，不推荐,因为容易混淆缓存。
• 向后兼容: 设计新版本时，尽量保持旧版本的 API 可用,逐步废弃。

总结与学习路径

1. 理解概念: 弄清楚 Web Service 是什么，SOAP 和 REST 的区别。
2. 动手实践 (基础):
   • 尝试用 JAX-WS 写一个简单的 SOAP 服务，理解其“重量级”和“契约优先”的特点。
   • 尝试用 JAX-RS (Jersey) 写一个 RESTful 服务，理解“资源导向”和“注解驱动”。
3. 拥抱主流 (进阶):
   • 重点学习 Spring Boot，这是你未来工作中最可能用到的技术，掌握 @RestController, @GetMapping, @PostMapping, @PathVariable, @RequestBody 等核心注解。
   • 学习如何集成 Swagger 来生成 API 文档。
   • 学习 Spring Security，了解如何为你的 REST API 添加基于 JWT 的认证和授权。
4. 深入探索 (专家):
   • 了解 Spring Cloud，用于构建分布式系统中的服务治理（如服务发现、配置中心）。
   • 学习 API 网关（如 Spring Cloud Gateway）。
   • 深入理解 RESTful 设计原则，如何设计出“好”的 API。

这份教程为你铺开了一张完整的 Java Web Service 学习地图,祝你学习顺利！