RESTful API设计与实现指南

原创已于 2025-07-19 21:15:15 修改 · 877 阅读

21 ·

CC 4.0 BY-SA版权

文章标签：

#spring #mvc #java #restful #后端

于 2025-07-19 21:14:55 首次发布

SSM框架专栏收录该内容

7 篇文章

订阅专栏

1 什么是RESTful特征的API

每一个URI代表一种资源

客户端和服务器端之间传递着资源的某种表现

客户端通过HTTP的几个动作对资源进行操作，发生状态转化

2 如何设计符合RESTful 特征的API

2.1 关于URL

协议 - http/https

域名

域名中体现出api字样，如

https://api.example.com
版本

https://api.example.com/v1/

路径

路径中避免使用动词，资源用名词表示，案例如下

<span style="background-color:#f8f8f8"><span style="color:#000000">https</span>:<span style="color:#981a1a">//</span><span style="color:#000000">api</span>.<span style="color:#000000">example</span>.<span style="color:#000000">com</span><span style="color:#981a1a">/</span><span style="color:#000000">v1</span><span style="color:#981a1a">/</span><span style="color:#000000">users</span>
<span style="color:#000000">https</span>:<span style="color:#981a1a">//</span><span style="color:#000000">api</span>.<span style="color:#000000">example</span>.<span style="color:#000000">com</span><span style="color:#981a1a">/</span><span style="color:#000000">v1</span><span style="color:#981a1a">/</span><span style="color:#000000">animals</span></span>

2.2 HTTP动词语义

2.2.1 说明

HTTP动词语义

请求动词	说明
GET（SELECT）	从服务器取出资源（一项或多项）
POST（CREATE）	在服务器新建一个资源
PUT（UPDATE）	在服务器更新资源
DELETE（DELETE）	从服务器删除资源

具体案例如下：

请求动作	请求资源	说明
GET	/zoos	列出所有动物园
POST	/zoos	新建一个动物园
GET	/zoos/ID	获取某个指定动物园的信息
PUT	/zoos/ID	更新某个指定动物园的信息
DELETE	/zoos/ID	删除某个动物园
GET	/zoos/ID/animals	列出某个指定动物园的所有动物
DELETE	/zoos/ID/animals/ID	删除某个指定动物园的指定动物

3.3 查询参数

巧用查询参数

<span style="background-color:#f8f8f8"><span style="color:#333333"><span style="color:red">?</span><span style="color:#000000">type_id</span>=<span style="color:#116644">1</span><span style="color:#000000">：指定筛选条件</span>
<span style="color:red">?</span><span style="color:#000000">limit</span>=<span style="color:#116644">10</span><span style="color:#000000">：指定返回记录的数量</span>
<span style="color:red">?</span><span style="color:#000000">offset</span>=<span style="color:#116644">10</span><span style="color:#000000">：指定返回记录的开始位置。</span></span></span>

3.4 HTTP状态码

用HTTP响应码表达此次请求结果，例如

响应码	说明
200 OK - [GET]	服务器成功返回用户请求的数据
404 NOT FOUND - [*]	用户发出的请求针对的是不存在的记录
500 INTERNAL SERVER ERROR - [*]	服务器发生错误

3 常用注解

1) `@RequestMapping` 注解

@RequestMapping 用于指定处理请求的 URL，它可以标注在类和方法上；

可以通过 method 参数限定处理 GET、POST、PUT、DELETE 等HTTP的请求方法，比如：

处理 GET 请求

@RequestMapping(value = "/v1/users", method = RequestMethod.GET)
处理 POST 请求

@RequestMapping(value = "/v1/users", method = RequestMethod.POST)

处理 PUT DELETE 方式的HTTP请求同理。

2) 限定请求方式的注解

2.1`@GetMapping` 注解

@GetMapping 只会处理 HTTP GET 请求；

是 @RequestMapping(method = RequestMethod.GET) 的缩写。

如果限定为处理GET请求，则发送其他方式请求时HTTP状态码为 405

2.2 `@PostMapping` 注解

@PostMapping 只会处理 HTTP POST 请求；

是 @RequestMapping(method = RequestMethod.POST) 的缩写。

如果限定为处理POST请求，则发送其他方式请求时HTTP状态码为 405

2.3 `@PutMapping` 注解

@PutMapping 只会处理 HTTP PUT 请求；

是 @RequestMapping(method = RequestMethod.PUT) 的缩写。

如果限定为处理PUT请求，则发送其他方式请求时HTTP状态码为 405

2.4 `@DeleteMapping` 注解

@DeleteMapping 只会处理 HTTP DELETE 请求；

是 @RequestMapping(method = RequestMethod.DELETE) 的缩写。

如果限定为处理DELETE请求，则发送其他方式请求时HTTP状态码为 405

3)`@PathVariable` 注解

@PathVariable 注解用于接受 RESTful API 中的 URL 中的变量；

通常与请求注解一起使用，可以将 URL 中的变量映射到 Controller 中的方法参数上。

3.1 用法

假如有一个 RESTful API：/v1/users/{id}，

其中 {id} 是一个变量，表示用户 ID。

可以这样定义一个处理该请求的控制器方法

<span style="background-color:#f8f8f8"><span style="color:#333333"><span style="color:#555555">@GetMapping</span>(<span style="color:#aa1111">"/v1/users/{id}"</span>)
<span style="color:#770088">public</span> <span style="color:#008855">String</span> <span style="color:#0000ff">getUserById</span>(<span style="color:#555555">@PathVariable</span> <span style="color:#008855">Integer</span> <span style="color:#000000">id</span>) {
    <span style="color:#aa5500">// 根据 ID 查询用户，并返回用户信息</span>
}</span></span>

3.2 使用示例

根据 id 查询用户，并返回该用户信息

地址：/v1/users/{id} id为用户id
请求方法：GET
查询参数：无
响应类型：用户对象user

实现

使用 _05mvcboot02 工程

根据 id 查询用户，并返回该用户信息（GET请求：/v1/users/{id}）

<span style="background-color:#f8f8f8"><span style="color:#555555">@GetMapping</span>(<span style="color:#aa1111">"{id}"</span>)
<span style="color:#770088">public</span> <span style="color:#000000">User</span> <span style="color:#0000ff">selectById</span>(<span style="color:#555555">@PathVariable</span> <span style="color:#008855">int</span> <span style="color:#000000">id</span>){
    <span style="color:#aa5500">// 自己定义相对应的接口方法</span>
    <span style="color:#770088">return</span> <span style="color:#000000">userMapper</span>.<span style="color:#000000">selectById</span>(<span style="color:#000000">id</span>);
}</span>