需留存请求记录的距离查询REST API接口HTTP方法选型问题

需求背景：接口提供两点间距离查询能力，同时需保存每一次请求用于后续公开请求历史。
面试官提到的「存储请求数据就不具备幂等性」的说法不符合RFC 7231对HTTP方法语义的定义：HTTP方法的安全、幂等特性仅针对请求URI对应的目标资源，服务器内部的审计、日志、附属资源写入操作不影响目标资源的语义判定。

方案一：单GET接口（绝大多数场景的最优选择） #

• 接口示例：GET /api/distance?origin={起点坐标}&destination={终点坐标}
• 逻辑说明：
  • 目标资源为「两点间的距离计算结果」，属于只读资源，多次请求返回的结果完全一致，天然符合GET的安全、幂等语义
  • 请求历史存储作为后台异步附属操作执行，不影响主请求响应，也不改变距离资源本身的状态
• 优势：
  • 支持HTTP原生缓存，相同的两点查询无需重复计算，大幅提升接口性能
  • 支持直接通过URL寻址、书签保存、浏览器直接调用等特性，易用性更高
  • 实现成本最低，符合绝大多数业务的常规设计逻辑

方案二：双接口拆分（请求历史为一等公开资源时适用） #

如果业务需要对请求历史做独立的查询、编辑、分享等管理操作，可将能力拆分为两个独立接口：

• 提交距离查询请求：POST /api/distance-queries
  请求体携带起点、终点参数，返回结果同时包含距离计算值，以及本次请求生成的历史记录唯一ID
• 公开请求历史查询：GET /api/distance-queries（查询全量历史）或 GET /api/distance-queries/{recordId}（查询单条历史详情）
• 适用场景：需要对查询记录本身做生命周期管理的业务，比如用户查询历史回溯、热门查询路线统计等需求

核心误区澄清 #

• 服务器内部产生新数据不违反GET语义：几乎所有Web服务都会在处理GET请求时写入访问日志、统计数据，这类附属操作从未被判定为违反GET的幂等性
• 不要滥用POST处理只读查询：如果核心诉求是获取只读资源，强行使用POST会丢失缓存、可寻址等HTTP原生优势，属于不必要的过度设计

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