WebService 的参数是客户端与服务器之间进行数据交换的核心，理解参数的类型、结构和规范对于开发和使用 WebService 至关重要。
（图片来源网络，侵删）
下面我将从几个关键维度来全面描述 WebService 参数：
参数的传输格式
参数在网络上传输时,需要被序列化成一种标准化的文本格式，最常见的两种格式是 SOAP 和 REST。
a) SOAP (Simple Object Access Protocol)
SOAP 是一个协议，它规定了消息的格式，SOAP 消息是一个 XML 文档，其结构非常严格。
-
特点:
（图片来源网络，侵删）- 强类型: 参数类型在 WSDL (Web Services Description Language) 文件中有明确定义，是强类型的。
- 结构化: 消息结构是预定义的，包含
<Envelope>,<Header>,<Body>等标签。 - 自描述: XML 本身就是自描述的，易于机器解析。
- 重量级: 由于 XML 结构相对冗长，SOAP 消息通常比 REST 更大。
-
参数结构示例: 假设有一个名为
GetUser的操作，需要一个userId参数。<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetUserRequest xmlns="http://example.com/user"> <userId>12345</userId> </GetUserRequest> </soap:Body> </soap:Envelope><userId>: 这就是我们要传递的参数，它的类型（如int,string）在 WSDL 中定义。
b) REST (Representational State Transfer)
REST 不是一种协议，而是一种架构风格，它通常使用 HTTP 协议来传输数据，数据格式非常灵活，最常用的是 JSON。
-
特点:
- 轻量级: JSON 格式比 XML 更简洁，解析速度更快。
- 无状态: 每个请求都包含处理该请求所需的所有信息。
- 基于 HTTP: 充分利用 HTTP 方法（GET, POST, PUT, DELETE）来操作资源。
- 弱类型: 参数类型通常由开发者在文档中约定，而不是像 WSDL 那样强制规定。
-
参数结构示例: 同样是获取用户信息，通过 REST API 调用。
（图片来源网络，侵删）-
URL 传递参数 (Query Parameters):
GET /api/users/1234512345: 直接作为 URL 路径的一部分，是获取该资源的标识符。
-
请求体 传递参数 (Request Body, 通常用于 POST/PUT): 假设我们要创建一个新用户。
POST /api/users Content-Type: application/json { "name": "John Doe", "email": "john.doe@example.com", "age": 30 }name,email,age: 这些都是 POST 请求的参数，以 JSON 对象的形式放在请求体中。
-
参数的传递位置
根据 WebService 的风格，参数可以放在 HTTP 请求的不同位置。
a) SOAP
参数几乎总是放在 HTTP 请求体 中，被包裹在 SOAP 信封里。
b) REST
参数的位置非常灵活：
-
URL 路径
- 描述: 用于标识特定的资源，通常是一个 ID 或唯一标识符。
- 示例:
GET /api/users/{userId}中的{userId}。
-
查询字符串
- 描述: 用于过滤、排序、分页等，对资源进行附加条件。
- 示例:
GET /api/products?category=electronics&sort=price_desc中的category和sort。
-
请求头
- 描述: 用于传递元数据，如认证信息、内容类型等，虽然不是业务参数，但也是重要的参数。
- 示例:
Authorization: Bearer <token>中的Authorization。
-
请求体
- 描述: 用于传递复杂的数据结构，如创建新资源或更新现有资源时提交的表单或 JSON 对象。
- 示例: POST/PUT 请求中的 JSON 或 XML 数据。
参数的数据类型
参数可以是各种数据类型,从简单的原始类型到复杂的自定义对象。
-
简单类型:
- 字符串
- 整数
- 浮点数
- 布尔值
- 日期/时间
-
复杂类型:
- 对象/结构体: 由多个简单类型或其他复杂类型组成，一个
Address对象可能包含street,city,zipCode等属性。 - 数组/列表: 一组相同类型的元素，一个
UserList可能包含多个User对象。 - 枚举: 一组预定义的常量值。
OrderStatus可以是Pending,Shipped,Delivered。
- 对象/结构体: 由多个简单类型或其他复杂类型组成，一个
-
特殊类型:
- Base64: 用于传输二进制数据（如图片、文件）。
- Any/动态类型: 允许传递任意结构的数据，灵活性高但类型安全性低。
参数的规范描述文档
为了让调用方知道如何正确使用参数,WebService 必须提供一份规范文档。
a) WSDL (Web Services Description Language)
- 用于: SOAP WebService。
- 作用: 是一份 XML 文件，它像“说明书”一样，详细描述了 WebService 的所有信息：
- 可用的服务端点。
- 可用的操作（方法）。
- 每个操作的输入参数（
message/part）。 - 每个操作的输出参数（返回值）。
- 每个参数的数据类型（
types定义）。 - 通信协议（如 SOAP/HTTP）。
b) OpenAPI (Swagger) 规范
- 用于: RESTful API。
- 作用: 是一份 JSON 或 YAML 文件，它描述了 REST API 的所有细节：
- API 的基本信息（标题、版本、描述）。
- 可用的路径（如
/api/users）。 - 每个路径支持的 HTTP 方法（GET, POST 等）。
- 每个方法的请求参数：包括参数名、位置（path, query, header）、是否必需、数据类型、示例等。
- 请求体的结构和示例。
- 响应的结构和示例，包括成功和错误的情况。
总结与对比
| 特性 | SOAP WebService | RESTful API |
|---|---|---|
| 参数格式 | XML (严格结构) | JSON (常用), XML, HTML 等 |
| 参数位置 | 主要在 HTTP 请求体 | 灵活：URL 路径、查询字符串、请求头、请求体 |
| 参数类型 | 强类型，由 WSDL 严格定义 | 弱类型，由文档约定 |
| 规范文档 | WSDL | OpenAPI (Swagger) |
| 风格 | 协议导向 | 架构风格导向 |
| 复杂度 | 较高，标准严格 | 较低，更灵活、轻量 |
最佳实践
- 清晰命名: 参数名应清晰、无歧义，并遵循一致的命名规范（如驼峰命名法
userId或下划线命名法user_id）。 - 文档先行: 在开发 API 之前，先编写好 OpenAPI 或 WSDL 文档，这有助于前后端并行开发和后期维护。
- 提供示例: 在文档中为每个参数和请求/响应提供清晰的示例，这能极大降低调用方的使用门槛。
- 版本控制: 当参数结构发生变更时，应创建 API 的新版本，而不是直接破坏旧的接口，以确保向后兼容性。
- 验证与校验: 服务器端必须对所有传入的参数进行严格的验证和校验，以确保数据的有效性和安全性，防止注入攻击等。
