跳到主要内容

4.16. 允许 Versioning 和 Evolution

4.16. 允许 Versioning 和 Evolution​

设计 application protocol 最具挑战性的方面之一, 是确保它能随时间演进, 同时保持与现有 deployment 的兼容性.

使用 HTTP 的 application SHOULD 从一开始就为 extensibility 设计. 这包括:

  • Protocol negotiation: 提供机制, 使 client 和 server 能协商使用哪个 version 或 feature.

  • Graceful degradation: 允许旧 client 与新 server 协作 (反之亦然), 即便它们不支持所有 feature.

  • Feature discovery: 允许 client 发现 server 支持哪些 feature.

  • Ignoring unknown elements: 规定 implementation 应忽略未知 header field, content 或其他 protocol element, 而不是将其视为 error.

versioning 的常见方法包括:

  • Media type versioning: 为不同 version 使用不同 media type (例如 application/vnd.example.v1+json, application/vnd.example.v2+json).

  • URL versioning: 在 URL 中包含 version (例如 /v1/resource, /v2/resource). 不过, 这可能产生 caching 和 resource identity 方面的问题.

  • Header field versioning: 使用自定义 header field 指示 version.

  • Feature-based negotiation: 允许协商单个 feature, 而不是对整个 protocol 进行 versioning.

application SHOULD:

  • 清楚记录 versioning 如何工作.

  • 提供如何维护 backward compatibility 的指导.

  • 考虑 versioning 对 caching 和其他 HTTP feature 的影响.

  • 避免对现有 version 做出 breaking change; 当需要 incompatible change 时, 改为定义新 version.

application SHOULD NOT:

  • 使用 URL query parameter 进行 versioning, 因为这可能干扰 caching.

  • 造成 protocol 的不同 version 使用相同 identifier (URL, media type) 表示不同事物的情况.

  • 在新 version 发布时强制 client 立即升级.

最后于 更新