每日饮水量记录增减操作的REST API最优设计方案咨询

最优选型推荐 #

优先选方案c的简化变体：不需要单独的operation字段，PATCH请求直接传入正负值代表增减量，搭配可选的PATCH upsert逻辑（替代单独POST接口）是当前场景下的最优解。

各方案对比说明 #

• 方案a（单PUT三合一）：完全不适合当前场景。前端的操作都是增量调整，用PUT需要先查询当前日期的总饮水量，计算后再提交全量值，不仅多了一次查询请求，还会出现并发更新丢失的问题：两个增量请求同时查询到相同的当前值，计算后提交，最终只会生效一次更新，数据不准。另外PUT的语义是全量替换，三合一逻辑虽然能跑，但不符合常规REST设计习惯，后续维护容易出歧义。
• 方案b（POST+全量PATCH）：和方案a有一样的问题，PATCH传全量amount还是需要前端先查后改，解决不了并发丢更的问题，完全没必要。
• 方案c（带operation的增量PATCH）：能解决并发问题，但是operation字段属于冗余设计，增减操作完全可以用正负值直接表达，没必要多传一个字段增加前后端的对接成本。

附加疑问解答 #

1. PATCH/PUT触发amount低于0自动删除资源是否符合REST规范？ #

完全符合。REST规范从来没有禁止服务端根据业务规则对资源做附加处理，只要返回的状态码匹配操作结果即可：如果更新后amount小于0触发删除，直接返回204 No Content就符合语义，没有合规问题。

2. POST+PATCH组合与单PUT方案哪个更适配该场景？ #

POST+PATCH组合适配度高得多。当前场景99%的操作都是用户点击快捷按钮触发的增量调整，几乎没有全量覆盖总饮水量的需求，单PUT的全量逻辑完全不匹配业务操作模式，还会引入额外的查询开销和并发风险。
甚至可以进一步优化：不需要单独做POST初始化接口，直接给PATCH接口增加upsert逻辑，如果指定用户+日期的记录不存在，就直接用传入的增量值作为初始值创建记录，前端全程只需要调用一个PATCH接口，连是否需要初始化的判断都省了，调用成本更低。

3. 方案c去掉operation字段直接传正负值是否合理？ #

非常合理。正负值本身就可以无歧义地表达增减操作，没有必要额外增加operation字段做冗余判断，不仅简化了参数结构，前端对接的时候也不需要额外处理字段逻辑，直接传正数为加、负数为减即可，开发效率更高。

适配业务场景的优化点 #

正好匹配安卓端的快捷按钮操作逻辑：用户点击100ml、300ml这类按钮，前端不需要查询当前总水量，直接给对应日期的资源接口发PATCH {"amount": 100}即可，后端用原子更新语句（比如SQL的UPDATE table SET amount = amount + ? WHERE userid = ? AND date = ?）执行更新，完全没有并发冲突，前端自己存储操作流水展示即可，完全匹配需求。

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