RESTful API返回设计：嵌套对象与新增字段方案选型

结论优先：面向合作方的公共API场景下，更推荐选择方案（b），理由如下： #

• 语义清晰无歧义 #

  静态基础属性和查询动态属性拆分非常明确：建议把嵌套的key从product改成productType更贴合语义，嵌套对象内的字段是产品类型的固有属性，不随查询参数变化，合作方可以直接缓存复用；外层的quantityAvailable、priceForDates是和当前请求的日期范围强相关的动态结果，对接的开发人员不用思考就能快速区分两类字段的含义，不会出现把动态价格当成产品固定单价这类低级错误。

• 接入成本更低 #

  合作方可以复用你们其他接口已经公开的ProductType结构的解析逻辑，不需要为这个接口单独写一套兼容额外字段的解析代码，后续你们如果给ProductType新增固有属性，或者给查询结果新增更多动态字段（比如适用优惠、可预约时段限制等），完全不会影响已有逻辑的兼容性。

• 无字段冲突风险 #

  后续迭代过程中，动态扩展的外层字段和ProductType的固有字段完全隔离，不会出现重名冲突导致的解析异常，对公共API的长期维护非常友好。

补充说明：方案（a）仅适合以下特殊场景 #

如果你们对外暴露的所有涉及ProductType的接口，都会默认返回quantityAvailable、priceForDates这类字段，且这些字段已经被定义为ProductType对外公开的固有属性，没有单独返回纯ProductType结构的场景，可以选择方案（a），否则不建议公共API使用该方案。

内容的提问来源于stack exchange，提问作者Ben123