知识卡片

普通读书笔记卡 · 519.d.2

兼容演进三条承诺

理解等级:高级

已发布接口的非破坏性演进遵守三条规则:不删除已有元素、不重定义含义、新增元素可选。新增必填参数应放到新动作,保留旧动作;新动作本身也不能变成旧客户端必须执行的步骤。承诺还应说明客户端如何容忍未知内容;仅发布新版文档不足以保证所有使用者及时迁移。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • 用超媒体思考与设计 · 查看原书依据

      Don’t redefine things. You cannot change the meaning or use of an existing element of the interface. For example, if the response message was published as a user object, you cannot change it to a user collection. If the output property count was documented as containing the number of records in the collection, you cannot change its meaning to the number of records on a single page response. Make additions optional. After the initial publication of the API, any additional inputs or outputs must be documented as optional—you cannot add new required properties for existing interfaces.

    参考来源

    - 位置:《RESTful Web API Patterns and Practices Cookbook Connecting and Orchestrating Microservices and Distributed Data (Mike Amundsen)》第02章《用超媒体思考与设计》(来源项目 book-sources;源文件:extracted/RESTful Web API Patterns and Practices Cookbook Connecting and Orchestrating Microservices and Distributed Data (Mike Amundsen)/_epub-src/OEBPS/ch02.xhtml;小节:服务演进) - 结论依据:原文以已发布接口的非破坏性演进遵守三条规则:不删除已有元素、不重定义含义、新增元素可选的机制或场景为依据;同小节余文补充本卡所列条件,按2022年原书语境整理。 - 原始内容:Don’t redefine things. You cannot change the meaning or use of an existing element of the interface. For example, if the response message was published as a user object, you cannot change it to a user collection. If the output property count was documented as containing the number of records in the collection, you cannot change its meaning to the number of records on a single page response. Make additions optional. After the initial publication of the API, any additional inputs or outputs must be documented as optional—you cannot add new required properties for existing interfaces.