跳到主要内容

RESTful风格请求规范参考

表现层状态转换（英语：Representational State Transfer，缩写：REST）是一种万维网软件架构风格，目的是便于不同软件/程序在网络（例如互联网）中互相传递信息。表现层状态转换是根基于超文本传输协议（HTTP）之上而确定的一组约束和属性，是一种设计提供万维网络服务的软件构建风格。符合或兼容于这种架构风格（简称为 REST 或 RESTful）的网络服务，允许客户端发出以统一资源标识符访问和操作网络资源的请求，而与预先定义好的无状态操作集一致化。因此表现层状态转换提供了在互联网络的计算系统之间，彼此资源可交互使用的协作性质（interoperability）。

要点及标准​

需要注意的是，REST是设计风格而不是标准。REST通常基于HTTP、URI、XML以及HTML这些现有的广泛流行的协议和标准。

符合REST设计风格的Web API称为RESTful API。它从以下三个方面资源进行定义：

  • 直观简短的资源地址：URI，比如：http://example.com/resources。
  • 传输的资源：Web服务接受与返回的互联网媒体类型，比如：JSON，XML，YAML等。
  • 对资源的操作：Web服务在该资源上所支持的一系列请求方法（比如：POST，GET，PUT或DELETE）。

Spring MVC接收请求的几种方式极其说明​

  • path：参数在URL路径中，如 /api/users/000000，需要与 @PathVariable 配合使用；
  • query：参数直接附到参数后面，可以直接在方法参数中接收，超过2个参数，需要封装成DTO。
  • form：以表单方式提交，可以直接在方法参数中接收，超过2个参数，需要封装成DTO。
  • requestBody：以JSON方式提交，必须以DTO方式接收，无论有多少参数。这种请求方式其实是将请求数据放到请求信息的数据流中，通常可以通过 request.getInputStream() 获取到原始数据。

RESTful API时HTTP请求方法​

常见的HTTP请求方式​

在RESTful架构中，常见的HTTP请求方式包括GET、POST、PUT、DELETE和PATCH。

  • GET：用于从服务器获取资源，通常不应该对服务器状态产生任何影响。GET请求应该是幂等的，即多次请求同一URL的结果应该是一致的。适用场景包括获取资源列表、检索特定资源等。
  • POST：用于向服务器提交数据，通常用于创建新资源。POST请求不是幂等的，即多次提交相同数据可能会产生不同的结果。适用场景包括提交表单、创建新资源等。
  • PUT：用于向服务器更新数据，通常用于更新已有资源的全部内容。PUT请求应该是幂等的，即多次请求同一URL的结果应该是一致的。适用场景包括更新资源的全部内容，例如替换整个对象。
  • DELETE：用于删除服务器上的资源。DELETE请求应该是幂等的，即多次请求同一URL的结果应该是一致的。适用场景包括删除资源。
  • PATCH：用于向服务器部分更新资源，通常用于更新已有资源的部分内容。PATCH请求应该是幂等的，即多次请求同一URL的结果应该是一致的。适用场景包括更新资源的部分内容，例如更改对象的某些属性。

其他HTTP请求方式​

其他的Http请求方式还有：HEAD和OPTIONS。

  • HEAD：用于返回响应中的首部，HEAD方法类似于GET方法，但服务器在响应中只返回首部，不返回实体的主体部分。因此，HEAD请求允许客户端仅获取关于资源的元数据，如响应代码、响应头等，而不获取实际内容。当客户端需要了解关于资源的信息，例如获取响应代码、响应头等，但不需要获取资源的实际内容时，可以使用HEAD请求。这可以用于检查资源的状态、检测资源是否存在等情况。
  • OPTIONS：用于获取关于服务器支持的通信选项，例如服务器支持的HTTP方法、服务器支持的请求头、服务器支持的认证方案等。当客户端需要了解服务器支持的通信选项时，可以使用OPTIONS请求。这可以用于跨域请求中的预检请求（preflight request）以及客户端与服务器之间的交互协商。

这两种请求方法在实际应用中通常用于获取与资源或服务器相关的元数据信息，而不直接获取资源的实际内容。

请求规范说明​

GET请求​

GET请求用于从服务器获取资源，GET请求不应该修改任何数据。而所有获取资源的请求都应当是GET请求。以下是一些请求示例

  • /api/users：批量获取用户信息
  • /api/users/findByKeyword?keyword=xxx：根据关键字查询用户
  • /api/users/000000：获取用户ID为000000的用户信息，这种请求通常与@PathVariable配合使用；

例外情况：

当查询参数中有多层数据嵌套时，如下

{
    "paramA": "a",
    "paramB": {
        "b1": 1,
        "b2": 2
    }
}
json

为简化查询参数的处理。允许使用POST请求代替GET请求。