API接口开发

HTTP方法选择策略与常见误区

API接口开发
HTTP方法选择策略与常见误区

HTTP方法选择看似简单,实际项目中却频繁出现误用。不少团队的API无论增删改查全部用POST,美其名曰统一接口。这种做法放弃了HTTP协议的语义能力,导致接口自描述性差、缓存失效、幂等问题难处理。本文梳理每种HTTP方法的使用场景和注意事项。

GET的正确用法

GET用于查询资源,是幂等的、安全的,可以被缓存。GET请求不应该改变服务端状态。常见误区是在GET请求中使用请求体传递参数,这违反了HTTP规范。GET参数应该通过URL查询字符串传递。对于复杂查询,参数过多导致URL过长时,可以考虑将参数编码后放在查询字符串中,或者改用POST查询端点。GET请求的响应内容可以被CDN和浏览器缓存,适合数据变化不频繁的查询接口。

POST的使用边界

POST用于创建资源或触发非幂等的操作。POST不是万能的替代品,只在需要创建新资源或执行不确定结果的操作时使用。常见误区是用POST实现更新、删除和查询操作。正确做法是创建资源用POST,更新用PUT或PATCH,删除用DELETE。POST请求的响应状态码为201,并在响应头Location中返回新建资源的URL。对于批量操作,POST也是合适的选择,但需要在接口文档中明确说明幂等性。

PUT与PATCH的区别

PUT是全量更新,PATCH是局部更新。这是很多开发者容易混淆的地方。PUT要求请求体中包含资源的所有字段,缺少的字段会被置为默认值。PATCH只包含需要修改的字段,其他字段保持不变。选择原则是:如果客户端获取完整资源后只修改部分字段,用PATCH更合适。如果客户端直接提交完整资源,用PUT更合适。PATCH还可以使用JSON Patch标准格式来表达更复杂的修改操作。

DELETE的安全考量

DELETE用于删除资源,是幂等的,但非安全。多次删除同一资源应该返回相同结果。删除操作需要考虑级联影响,如删除用户时是否同时删除其订单。建议DELETE操作使用软删除,标记资源为已删除状态而不是物理删除。在响应上,删除成功返回204无内容,资源不存在也返回204保持幂等一致性。DELETE请求不应该有请求体,参数通过URL路径传递。

聊聊你的项目

有架构或成本优化的烦恼?

把你的业务场景告诉我们,专家会给出一份务实的改造与降本建议。


电话咨询 微信咨询 在线咨询 返回顶部
xycx202108

微信扫码咨询

×