RESTful API 接口设计规范:资源导向、HTTP 语义、统一返回格式、避坑指南

RESTful 是 Web API 主流架构风格,核心思想是以资源为中心,使用 HTTP 方法表达动作。很多项目伪 REST,URL 写大量动词,方法滥用 GET/POST。本文系统讲解 REST 核心原则、URL 命名、HTTP 方法语义、状态码使用、统一返回体、分页、排序、嵌套资源、版本控制,附带正反案例、开发踩坑清单,适合团队接口规范制定、复习。

前言

REST 全称 Representational State Transfer(表述性状态转移),由 Roy Fielding 提出。REST 不是一个协议,是一套架构设计风格 ,基于 HTTP 协议特性。 REST 核心思想:一切皆资源,URL 代表资源,HTTP 方法代表对资源的操作动作。

反模式:/getUser、/deleteOrder,URL 里面带动词,这不是 REST 风格。

一、REST 核心设计原则

  1. 资源使用名词,推荐复数 URL 描述资源集合,不要描述动作。

    推荐
    GET /users 获取用户列表
    GET /users/100 获取id=100单个用户
    POST /users 创建用户
    PUT /users/100 全量更新用户
    PATCH /users/100 局部更新用户字段
    DELETE /users/100 删除用户

    错误示范
    GET /getUserList
    POST /createUser
    DELETE /deleteUser

  2. 正确使用 HTTP 方法,遵守语义、幂等、安全特性

    方法 含义 幂等 安全 适用场景
    GET 查询资源 是 是 只读查询,不修改数据
    POST 新建资源 否 否 新增记录
    PUT 全量替换资源 是 否 完整覆盖更新,不存在则新建
    PATCH 局部更新 否 否 只更新部分字段
    DELETE 删除资源 是 否 删除资源
  3. 无状态 每个请求包含全部信息,服务端不保存客户端会话状态;认证信息(Token)放在请求头。

  4. 资源可以嵌套(父子资源)

    GET /users/100/orders 获取用户100的订单列表
    POST /users/100/orders 为用户100创建订单

嵌套层级建议最多 2 层,不要无限嵌套。

二、URL 规范细节

  1. 全部小写,横线-分隔单词,禁止下划线、驼峰; /user-address 而不是 /userAddress、/user_address

  2. 根路径增加 api 前缀区分业务接口:/api/users

  3. 查询参数放 queryString,用于过滤、分页、排序

    GET /api/users?page=1&size=10&status=1&sort=createTime,desc

三、HTTP 状态码合理使用

不要全部接口统一返回 200,业务错误放在 code 字段,这是很多项目的伪 REST。

  • 查询成功:200 OK
  • 创建资源成功:201 Created,响应头 Location 返回资源地址
  • 删除成功无返回体:204 No Content
  • 参数错误:400 Bad Request
  • 未登录 / Token 无效:401 Unauthorized
  • 权限不足:403 Forbidden
  • 资源不存在:404 Not Found
  • 请求方法不支持:405 Method Not Allowed
  • 参数校验失败:422 Unprocessable Entity
  • 服务异常:500 Internal Server Error

现实开发折中方案:很多团队仍然统一返回 200,业务自定义 code。面试时区分标准 REST 和企业落地折中方案。

四、统一返回体设计(企业落地最常用)

标准 REST 推荐直接返回资源实体;国内项目为方便前端,一般封装统一 JSON 结构。

复制代码
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 100,
    "name": "张三"
  }
}
  • code:业务码,200 成功;4xxx 客户端业务错误;5xxx 服务异常
  • msg:可读提示信息
  • data:业务数据,查询返回实体 / 数组;删除成功可以为 null

分页返回示例:

复制代码
{
  "code":200,
  "msg":"success",
  "data":{
    "records":[],
    "total":100,
    "current":1,
    "size":10
  }
}

五、附加规范:版本控制、排序、过滤、搜索

  1. API 版本控制 (推荐路径版本) /api/v1/users,新增不兼容接口升级 v2。不推荐 Header 放版本。
  2. 过滤:query 参数,?status=1&gender=0
  3. 排序:?sort=field,asc ?sort=createTime,desc
  4. 字段裁剪:按需返回字段 ?fields=id,name

六、REST 常见误区 & 踩坑

  1. 所有接口只用 GET 和 POST,PUT/DELETE 不使用;
  2. URL 大量动词,/api/updateUser;
  3. GET 请求做数据修改操作(违反安全原则,缓存会误触发);
  4. 幂等接口没有保证幂等,重试产生脏数据;
  5. 状态码滥用,全部返回 200,业务异常全部用自定义 code;
  6. 嵌套层级太深,可读性变差。

七、问答

Q1:RESTful 是什么?核心原则?

A:REST 是基于 HTTP 的资源导向架构风格。核心:一切是资源,URL 标识资源,HTTP 方法代表动作,无状态,合理使用状态码。

Q2:PUT 和 PATCH 区别?

A:PUT 全量替换资源;PATCH 局部更新部分字段。

Q3:幂等性是什么?哪些 HTTP 方法天然幂等?

A:多次请求,服务端结果和一次请求相同。GET、PUT、DELETE 天然幂等;POST 非幂等。

Q4:如何做 API 版本管理?

A:路径版本/api/v1/users,Header 版本,参数版本;项目推荐路径版本,简单直观。

结语

RESTful 接口设计的本质,是充分利用 HTTP 原生语义,让接口语义自描述。实际开发不必追求完全严格 REST(Richardson 成熟度模型 Level3),优先保证团队统一、前后端沟通简单。合理的接口规范,降低对接成本,方便使用 Apifox/Postman 调试。

相关推荐
芜名氏1 天前
API 文档生成工具——SpringDoc
java·spring boot·ci/cd·设计规范
我不会插花弄玉2 天前
5.应⽤层协议HTTP【由浅入深-网络】
http
如夏倾城3 天前
QUIC——HTTP/3 的唯一底层传输协议 及 0-RTT恢复
网络·网络协议·tcp/ip·安全·http
Thanks_ks4 天前
HTTPS:浏览器地址栏那把锁的工作原理
http·网络安全·https·tls·加密算法·数字证书·中间人攻击
杨凯凡4 天前
Spring Boot 大文件下载如何实现断点续传?HTTP Range、206 与 416 实战
spring boot·后端·http
FungLeo5 天前
成为全栈·Vue 管理后台篇·用 fetch 建一层可控的请求内核
前端·javascript·vue.js·http·fetch·formdata·接口封装
wuyk5555 天前
Spider-第03讲-HTTP速通与读懂响应
网络·爬虫·网络协议·http
杨凯凡6 天前
Spring Framework 7 HTTP Interface 实战:声明式 RestClient、超时与测试
java·spring·http
CodeYp20196 天前
第11讲:应用层协议 HTTP
linux·http
Thanks_ks7 天前
HTTP 请求方法与 RESTful 接口设计:GET 和 POST 到底怎么用
http·api·restful·状态码·get·post·接口设计