Zalando RESTful API 指南：API 实现最佳实践

在分布式系统架构中，API 的设计和实现质量直接影响系统的可靠性和可维护性。Zalando 的 RESTful API 指南中特别强调了 API 兼容性变更时客户端和服务端的正确处理方式，这是一个值得深入探讨的技术话题。

问题背景

在 API 演进过程中，一个常见场景是服务端添加了新字段而客户端尚未更新。当客户端执行 GET-EDIT-PUT 操作序列时，如果实现不当，可能导致以下问题：

1. 客户端获取资源时忽略未知字段
2. 编辑时只处理已知字段
3. 提交时将丢失服务端新增的未知字段数据

这种数据丢失问题在分布式系统中尤为危险，因为它可能悄无声息地破坏数据完整性。

解决方案核心原则

根据 Zalando 指南，解决方案的核心是：

客户端必须保持对未知字段的容忍性，即在处理响应时：

• 可以忽略不理解的新字段
• 但不能在后续 PUT 请求中丢弃这些字段

实现模式与技术方案

通用实现策略

1. 中间表示层：不应直接将 JSON 映射为领域对象，而应保留原始数据结构
2. 增量更新：只修改需要变更的字段，保持其他字段不变
3. 字段透传：确保未知字段在请求-响应循环中完整保留

Java/Jackson 实现示例

对于使用 Jackson 的 Java 客户端，推荐以下实现方式：

// 使用 JsonNode 作为中间表示，避免字段丢失
ObjectMapper mapper = new ObjectMapper();
JsonNode resource = mapper.readTree(getResponseBody());

// 创建可修改的副本
ObjectNode updatedResource = resource.deepCopy();

// 只更新需要修改的字段
updatedResource.put("knownField", newValue);

// 发送更新
putRequest(updatedResource.toString());

这种实现方式确保了：

• 未知字段在 deepCopy() 中被保留
• 只显式修改需要变更的字段
• 原始数据结构完整传递

服务端实现建议

服务端同样需要遵循一些最佳实践：

1. 严格输入验证：验证必需字段，但对未知字段保持开放
2. 字段合并策略：PUT 操作应采用合并策略而非全量替换
3. 版本兼容性：考虑支持多版本字段处理逻辑

测试验证要点

为确保实现正确性，应包含以下测试场景：

1. 客户端旧版本处理服务端新字段的完整循环
2. 部分字段更新不影响未提及字段
3. 错误处理当必需字段被意外删除时

总结

API 的演进兼容性需要客户端和服务端的协同配合。通过采用中间表示层、字段透传和增量更新等模式，可以构建出健壮的 API 交互机制。Zalando 的这条指南不仅适用于 RESTful API，其背后的"宽容阅读器"理念也可应用于其他分布式系统通信场景。

在实际工程实践中，团队应该将这类模式固化为代码模板或共享库，确保所有客户端实现都能一致地遵循这些重要原则。