用途:为 Java XML-RPC API 提供契约设计规范,重点处理故障信号传递与跨语言互操作性。
主要能力与约定:
- 异常处理:所有 API 接口方法都应声明 throws XmlRpcException;失败一律通过抛出该异常表达,异常序列化为标准 fault 结构(faultCode、faultString)。不建议使用 enabledForException 扩展,因为它序列化 Java 异常及链式异常,仅对 Java 客户端有效。
- 返回值:异常表示失败,返回值表示成功。XML-RPC 库不支持 void,类 void 操作应返回 int 且始终返回 0,返回值本身没有意义,失败只通过异常表达。避免返回 -1 等错误码,也不要在 DTO 中放置 error 字段,否则请求在服务端看起来是成功的,客户端必须检查响应才能发现失败,增加调试难度。
- 成功与失败的边界:操作成功返回具体值;查询无结果返回空或 false,这属于成功情况;系统错误或操作失败则抛出 XmlRpcException。
- DTO 序列化:使用 JAXB 注解(如 @XmlRootElement、@XmlAttribute),而非 java.io.Serializable,以生成可读的、跨语言的 XML 输出。
- 幂等性:动作类 API 需明确选择幂等或严格语义,例如对已运行服务调用 start 时返回 0,或抛出异常;两种均可,但应在契约中记录并保持一致。
使用方式:设计或评审 XML-RPC 接口时,按上述规则定义方法签名、返回类型与异常声明,并参照资料提供的检查清单逐项核对。
限制:具体依赖版本、安装命令、代码集成方式与部署细节暂未提供;分类应归为编程与开发类设计指南,而非可执行工具。