RESTful设计规范(状态码、幂等性)

RESTful API (​Representational State Transfer​(表述性状态转移))设计规范的核心在于遵循 HTTP 协议的特性,确保接口的简洁性、可预测性和可扩展性。以下是关于状态码和幂等性的关键规范:


一、HTTP 状态码规范

状态码用于表示请求的处理结果,客户端可根据状态码快速判断问题。常用状态码分类:

分类 状态码 场景
2xx 200 OK 通用成功状态(GET/PUT/PATCH)
201 Created 资源创建成功(POST),响应中应包含 Location 头指向新资源
204 No Content 成功但无返回体(DELETE 或 PUT/PATCH 无需返回数据时)
3xx 301 Moved Permanently 资源永久重定向
304 Not Modified 缓存有效(条件请求如 If-Modified-Since
4xx 400 Bad Request 请求格式错误(如参数校验失败)
401 Unauthorized 未认证(需提供身份凭证)
403 Forbidden 无权限访问资源(认证成功但权限不足)
404 Not Found 资源不存在
405 Method Not Allowed 请求方法不支持(如对只读资源发送 POST)
409 Conflict 资源冲突(如重复创建或版本冲突)
5xx 500 Internal Server Error 服务器内部错误(应避免暴露敏感信息)
503 Service Unavailable 服务不可用(如维护或过载)

最佳实践​:

  • 避免滥用 200 OK 返回错误信息(如 { "error": "Not Found" }),应使用正确的状态码。
  • 对客户端错误(4xx)和服务端错误(5xx)严格区分。

二、幂等性(Idempotency)​

幂等性指同一请求多次执行的效果与一次执行相同,是 RESTful 设计的重要原则。

HTTP 方法 幂等性 解释
GET 多次读取同一资源不会改变服务器状态。
PUT 多次更新同一资源会得到相同结果(全量替换)。
DELETE 第一次删除资源后,后续请求返回 404410,但效果不变。
POST 每次调用可能创建新资源(如重复提交订单)。
PATCH 通常否 部分更新可能依赖当前资源状态(如 amount=-10)。若明确全量属性可设计为幂等。

如何保证幂等性​:

  1. 客户端 :对非幂等操作(如 POST)生成唯一请求 ID(X-Request-ID),服务端通过缓存结果避免重复处理。
  2. 服务端
    • 使用条件请求(如 If-Match 头部和 ETag 校验资源版本)。
    • 对更新操作采用 PUT 替代 PATCH(若业务允许)。
    • 实现乐观锁(如版本号或时间戳)。

三、其他关键设计规范

  1. URI 设计​:

    • 使用名词复数形式(如 /users 而非 /user)。
    • 避免动词,通过 HTTP 方法表达操作(如 DELETE /users/123)。
    • 嵌套资源用 / 分隔(如 /users/123/posts)。
  2. 版本控制​:

    • 在 URI 或 Header 中显式声明版本(如 /v1/usersAccept: application/vnd.api.v1+json)。
  3. 过滤与分页​:

    • 使用查询参数:/users?role=admin&page=2&limit=10
  4. HATEOAS​:

    • 在响应中嵌入链接(如 "self": { "href": "/users/1" }),引导客户端发现后续操作。

四、错误响应格式

统一错误格式,包含明确的信息:

复制代码
{
  "error": {
    "code": "invalid_parameter",
    "message": "Email format is invalid",
    "details": {
      "field": "email",
      "expected": "valid email address"
    }
  }
}

通过遵循以上规范,API 可提升可维护性、降低客户端复杂度,并减少因误解导致的错误。

相关推荐
武子康7 分钟前
Java-80 深入浅出 RPC Dubbo 动态服务降级:从雪崩防护到配置中心秒级生效
java·分布式·后端·spring·微服务·rpc·dubbo
舒一笑36 分钟前
我的开源项目-PandaCoder迎来史诗级大更新啦
后端·程序员·intellij idea
@昵称不存在2 小时前
Flask input 和datalist结合
后端·python·flask
zhuyasen2 小时前
Go 分布式任务和定时任务太难?sasynq 让异步任务从未如此简单
后端·go
东林牧之2 小时前
Django+celery异步:拿来即用,可移植性高
后端·python·django
超浪的晨3 小时前
Java UDP 通信详解:从基础到实战,彻底掌握无连接网络编程
java·开发语言·后端·学习·个人开发
AntBlack3 小时前
从小不学好 ,影刀 + ddddocr 实现图片验证码认证自动化
后端·python·计算机视觉
Pomelo_刘金4 小时前
Clean Architecture 整洁架构:借一只闹钟讲明白「整洁架构」的来龙去脉
后端·架构·rust
双力臂4044 小时前
Spring Boot 单元测试进阶:JUnit5 + Mock测试与切片测试实战及覆盖率报告生成
java·spring boot·后端·单元测试
midsummer_woo5 小时前
基于spring boot的医院挂号就诊系统(源码+论文)
java·spring boot·后端