RESTfulAPI写了五年，这几个设计原则我一直没搞懂

写了五年RESTful API自认为已经轻车熟路直到最近带新人时被几个问题问住才发现有些设计原则我从来就没真正搞懂过。今天把这些困惑摊开聊聊或许你也有同感。一、幂等性到底谁说了算我一直以为GET、PUT、DELETE是幂等的POST不是背得滚瓜烂熟。可实际项目里我用PUT做“追加备注”接口每次调用都会在数组末尾加一条新记录——这还幂等吗后来才明白幂等指的是“多次请求对资源状态的影响相同”而不是“响应相同”。PUT的语义是“用请求体替换目标资源”如果你用它做追加那就是滥用。真正幂等的PUT应该是无论调用多少次资源最终都等于你传过去的那份表示。同理DELETE第一次返回204第二次返回404状态变了但资源已删除的状态没变所以仍是幂等。这个“语义与效果”的区分我花了三年才真正吃透。二、状态码200走天下刚工作时不管什么情况我都返回200然后在响应体里塞{code: 500, msg: 错误}。理由是“前端好处理”。直到一次对接外部系统对方看到我所有接口都回200直接问“你们是没有错误处理吗”我才意识到状态码是HTTP协议的一部分不是装饰。201 Created、204 No Content、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、409 Conflict、422 Unprocessable Entity每一个都有明确语义。尤其409和422一个表示资源冲突一个表示语法正确但语义错误我至今还在努力分清。三、PUT和PATCH混用多年很长一段时间我用PUT做局部更新传什么字段就改什么字段。直到有人问我“那你和PATCH有什么区别”我哑口无言。PUT的语义是全量替换没传的字段应该被置空或删除PATCH才是局部更新。可现实是很多框架对PATCH支持不好前端也懒得区分于是PUT成了万能更新。但严格来说这违背了REST的语义。我现在会在文档里明确写“本接口用PUT实现部分更新不符合严格REST语义”算是一种妥协。四、资源命名动词还是名词/getUserById、/createOrder、/deleteComment这些我写了无数个。REST的原则是“用名词表示资源用HTTP方法表示动作”。正确写法是GET /users/{id}、POST /orders、DELETE /comments/{id}。可遇到复杂业务动作怎么办比如“用户点赞文章”没有天然的HTTP方法对应。后来学会设计成子资源POST /articles/{id}/likes或者用动作资源POST /articles/{id}/like。虽然不够纯粹但比/likeArticle强得多。五、无状态真的不能有Session吗REST要求无状态我一度以为不能用Session所有请求必须带Token。后来才理解无状态指的是“服务端不保存客户端会话状态”Token本身可以是有状态的比如JWT里带用户信息或者Redis里存Token映射。关键是每个请求必须自包含服务端不依赖上一次请求的上下文。分页、排序、过滤参数放Query String认证信息放Header这才是无状态的正确姿势。六、HATEOAS最熟悉的陌生人这个原则我背了五年定义却从没在项目里用过。它要求响应里包含超媒体链接客户端通过链接发现可用操作而不是硬编码URL。比如获取订单后响应里带_links: { cancel: /orders/1/cancel }。理念很美好但实际开发中前端更愿意直接拼URL后端也懒得维护链接。我至今没搞懂在真实业务里到底该怎么落地。也许它更适合开放平台而不是内部系统。写了五年依然在学。RESTful不是教条而是一套需要权衡的约束。搞不懂没关系怕的是以为自己都懂了。