REST开发规范

REST开发规范

REST（Representational State Transfer，表述性状态转移）是一种用于构建网络应用的架构风格，通常用于设计基于HTTP协议的分布式系统。REST开发规范主要包含以下几个方面：

1. 资源（Resources）

  • 资源的表示：资源通过URI（Uniform Resource Identifier）标识，例如：/users/1 表示用户ID为1的资源。
  • 资源表示形式：资源可以以不同的格式表示，如JSON、XML、HTML等。

2. HTTP动词（HTTP Verbs）

REST使用标准的HTTP动词来操作资源：

  • GET：获取资源。
  • POST：创建资源。
  • PUT：更新资源。
  • DELETE：删除资源。
  • PATCH：部分更新资源。
  1. 传统URL风格
1
2
3
4
http://localhost:8080/user/getById?id=1     GET：查询id为1的用户
http://localhost:8080/user/saveUser         POST：新增用户
http://localhost:8080/user/updateUser       POST：修改用户
http://localhost:8080/user/deleteUser?id=1  GET：删除id为1的用户
  1. 基于REST风格URL
1
2
3
4
http://localhost:8080/users/1  GET：查询id为1的用户
http://localhost:8080/users    POST：新增用户
http://localhost:8080/users    PUT：修改用户
http://localhost:8080/users/1  DELETE：删除id为1的用户

3. 状态转移（State Transfer）

  • 无状态性：每个请求都是独立的，服务器不会保存客户端的状态。每个请求必须包含所有必要的信息。
  • 状态转移的表现：客户端可以通过HTTP响应中的链接（HATEOAS：Hypermedia As The Engine Of Application State）来发现和操作其他资源。

4. URL设计（URL Design）

  • 资源路径：使用名词而非动词，反映资源的层级关系。例如：/users/{userId}/orders。
  • 简洁明了：路径应当简单、易读且具备自解释性。

5. 数据格式（Data Formats）

  • 媒体类型：使用HTTP头中的Content-Type和Accept字段指定数据格式，例如application/json。
  • 统一数据格式：确保客户端和服务器之间的数据格式一致。

6. 安全性（Security）

  • 认证与授权：使用如OAuth、JWT等机制进行用户认证和授权。
  • 数据加密：通过HTTPS确保数据传输的安全性。

7. 错误处理（Error Handling）

  • HTTP状态码：使用合适的HTTP状态码表示请求的结果。例如，200 OK表示请求成功，404 Not Found表示资源未找到，500 Internal Server Error表示服务器内部错误。
  • 错误信息：提供详细的错误信息和解决方案提示。例如，返回JSON格式的错误描述。

8. 版本控制（Versioning）

  • URI版本控制：通过在URI中包含版本信息，例如：/api/v1/users。
  • HTTP头版本控制：通过HTTP头中的自定义字段指定版本信息。

9. 缓存（Caching）

  • 缓存控制：使用HTTP头中的Cache-Control、Expires等字段控制缓存行为。
  • ETag和Last-Modified：使用ETag和Last-Modified头进行缓存验证。