对接同事说接口是 restful 的，自己发出去的却是普通 POST，参数还往地址里塞。跑是能跑，被说风格不对。这两个词老被摆在一起比，其实一个说协议，一个说设计风格。

先分清它们不在同一层

http 接口说的是走 HTTP 协议通信的接口，重点在用什么传输；restful 说的是按 REST 风格设计的一套约定，重点在怎么组织资源和动作。所以 restful 接口一定是 http 接口，反过来不成立。混着比，怎么比都别扭。

restful 的几条硬约定

  • 用名词表示资源：地址写 users、orders，不写 getUser、deleteUser 这类带动词的路径。
  • 用方法表动作：GET 查、POST 建、PUT 全量改、PATCH 局部改、DELETE 删，动作交给 HTTP 方法。
  • 用状态码表结果：200 成功、201 已创建、400 参数错、401 未登录、404 不存在、500 服务端异常。
  • 无状态：每次请求自带身份信息，服务端不在会话里存上下文。

普通 http 接口长什么样

传统写法常是一个统一入口，靠参数里的 action 或 method 区分要干什么，返回体里塞 code 和 message，HTTP 状态码一律给 200。这种风格在早期系统和内部接口里很普遍，前端不用记一堆地址，调试也直白。

实际项目怎么取舍

对外开放、要长期维护的接口，按 restful 来更规范，别人看地址就能推出资源关系。内部小工具、历史系统，沿用原来那套反而省事，硬改还得同步前后端和文档。返回体两种都能包一层 code，并不冲突。

返回体的差异

restful 倾向让 HTTP 状态码承担结果语义，成功就是 200 或 201，失败用 4xx 和 5xx。传统接口习惯无论成败都返回 200，再靠 body 里的 code 区分。对接第三方时先问清这一点，否则前端判断条件写错，错误提示永远不弹出来。

  • 判断提醒：别为了整洁把老接口全改成 restful，投入产出不成正比；新项目起手就按 restful 设计，后期扩展和对接都省心。