API Design

所有接口都用 POST,不是最佳实践,但可能是组织选择

“所有接口都用 POST”听起来很不 REST。GET、POST、PUT、DELETE 各有语义,缓存、浏览器、网关、监控工具也都围绕这些语义工作。所以如果一个团队说所有接口统一 POST,第一反应不该是立刻叫好,也不该只是骂不规范,而是看它到底解决了什么问题,又付出了什么代价。

GET 不是形式主义

GET 的好处很实际:安全读取、天然可缓存、URL 可分享、日志容易看、CDN 和监控工具容易理解。公开查询、资源读取、文档化 API,很多时候都应该保留 GET。把这些接口全改成 POST,会让系统失去一部分 HTTP 本来就提供的能力。

POST 统一也不是一定偷懒

有些内部系统确实会选择统一 POST。原因可能是业务动作太复杂,很难映射成资源;也可能是网关要统一签名、防重、鉴权、染色、审计;还可能是客户端很多,统一 body 格式能降低 SDK 和多端实现成本。

如果这些理由讲得清楚,POST 统一就是组织层面的取舍,而不是单纯反 REST。

失去语义后要补纪律

问题在于,HTTP method 的语义被弱化后,系统必须用别的方式补回来。action 名要清楚,幂等性要写明,重试规则要固定,错误码要稳定,审计日志要能看出谁对什么对象做了什么。

  • 读接口要说明没有副作用。
  • 写接口要说明能不能重复提交。
  • 网关日志要记录 action、resource、user 和 requestId。
  • 文档要比普通 REST API 更明确。

API 风格不是宗教。GET/POST 用得好,能降低系统成本;统一 POST 用得好,也能减少组织复杂度。最差的是没有理由、没有约束、没有文档,只是因为方便就都写成 POST。