RESTful 规范风格

最新推荐文章于 2025-10-11 14:56:27 发布
原创 最新推荐文章于 2025-10-11 14:56:27 发布 · 831 阅读 · 16 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#restful #后端

一、RESTful简介

REST: （Representational State Transfer，表述性状态转移）是一种软件架构风格，由 Roy Fielding 博士在 2000 年提出。是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。
满足REST设计风格的程序或接口我们称之为RESTful。

二、RESTful风格核心特点

1.无状态

每个请求包含处理所需的所有信息。
服务器不能保存客户端的信息， 每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存， 服务器端根据这些状态信息来处理请求。
当客户端可以切换到一个新状态的时候发送请求信息， 当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。 每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

2.统一接口

使用标准 HTTP 方法进行操作。
对资源的操作包括获取、创建、修改和删除，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。换言而知，使用RESTful风格的接口但从接口上你可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下：

HTTP方法描述幂等性安全性
GET从服务器取出资源（一项或多项）是是
POST在服务器新建一个资源否否
PUT在服务器更新完整资源（客户端提供资源数据）是否
PATCH在服务器更新部分资源（客户端提供需要修改的资源数据）否否
DELETE从服务器删除资源是否

幂等性：同样的操作无论执行一次或多次，结果都保持一致且无副作用。

3.以资源为基础

所有内容都被抽象为资源。
资源可以是一个图片、音乐、一个XML格式、HTML格式或者JSON格式等网络上的一个实体，除了一些二进制的资源外，普通的文本资源更多以JSON为载体、面向用户的一组数据(通常从数据库中查询而得到)。

4.可缓存

服务端需回复是否可以缓存以让客户端甄别是否缓存提高效率。

5.URI指向资源

URI： Universal Resource Identifier 统一资源标志符，用来标识抽象或物理资源的一个紧凑字符串。URI包括URL和URN，在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。

三、RESTful API使用

1.URL设计规范

URL为统一资源定位器 ,接口属于服务端资源，首先要通过URL这个定位到资源才能去访问，而通常一个完整的URL组成由以下几个部分构成：

URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]

scheme: 指底层用的协议，如http、https、ftp
host: 服务器的IP地址或者域名
port: 端口，http默认为80端口
path: 访问资源的路径，就是各种web 框架中定义的route路由
query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
fragment: 锚点，定位到页面的资源

通常一个RESTful API的path组成如下：

/{version}/{resources}/{resource_id}

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。
resources：资源，RESTful API推荐用小写英文单词的复数形式。
resource_id：资源的id，访问或操作该资源。

当然，有时候可能资源级别较大，其下还可细分很多子资源也可以灵活设计URL的path，例如：

/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}

此外，有时可能增删改查无法满足业务要求，可以在URL末尾加上action，例如

/{version}/{resources}/{resource_id}/action

其中action就是对资源的操作。

RESTful API的URL具体设计的规范如下：

不用大写字母，所有单词使用英文且小写。
连字符用中杠"-“而不用下杠”_"
正确使用 “/“表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
结尾不要包含正斜杠分隔符”/”
URL中不出现动词，用请求方式表示动作
资源表示用复数不要用单数
不要使用文件扩展名

2.相关注解

注解作用
@RestController由 @Controller + @ResponseBody组成（返回 JSON 数据格式）
@PathVariableURL 中的 {xxx} 占位符可以通过@PathVariable(“xxx“) 绑定到控制器处理方法的形参中
@RequestMapping注解用于请求地址的解析，是最常用的一种注解
@GetMapping查询请求
@PostMapping添加请求
@PutMapping更新请求
@DeleteMapping删除请求
@RequestParam将请求参数绑定到你控制器的方法参数上（是springmvc中接收普通参数的注解）

3.HTTP响应状态码

状态码含义
200 OK - [GET]服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]用户新建或修改数据成功
202 Accepted表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]用户删除数据成功
400 INVALID REQUEST - [POST/PUT/PATCH]用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的
401 Unauthorized - [*]表示用户没有权限（令牌、用户名、密码错误）
403 Forbidden - [*]表示用户得到授权（与401错误相对），但是访问是被禁止的
404 NOT FOUND - [*]用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的
405 Method Not Allowed方法不允许，服务器没有该方法
406 Not Acceptable - [GET]用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）
410 Gone -[GET]用户请求的资源被永久删除，且不会再得到的
422 Unprocesable entity - [POST/PUT/PATCH]当创建一个对象时，发生一个验证错误
500 INTERNAL SERVER ERROR - [*]服务器发生错误，用户将无法判断发出的请求是否成功

4.案例

4.1查询1号用户的A课程详细信息
/api/courses?course_id=A
4.2增删改查一个用户信息

错误的设计：没必要，不用写 create，delete，show

/api/accounts/create

/api/accounts/delete

/api/accounts/show

/api/accounts/update

正确的做法：

post /api/accounts/ 这个是当不知道id是什么时。

delete /api/accouts/1 下面url一样，只是方法不一样。

get /api/accounts/1/ 获取1号用户信息，

put /api/accounts/1/ 修改1号用户信息
4.3从1号用户，转账500，给2号用户

错误设计：

post /api/accounts/1/transfer/500/to/2

正确的设计，当然放在方法体是最好的。

post /api/transaction?from=1&to=2&money=500

参考地址：
https://www.runoob.com/restfulapi/restful-api-tutorial.html
https://zhuanlan.zhihu.com/p/334809573
https://blog.youkuaiyun.com/zzvar/article/details/118164133

RESTful规范
Alex
05-05 601
web服务交互 我们在浏览器中能看到的每个网站，都是一个web服务。 那么我们在提供每个web服务的时候，都需要前后端交互，前后端交互就一定有一些实现方案，我们通常叫web服务交互方案。 目前主流的三种web服务交互方案： -- REST （ Representational State Transfer）表述性状态转移 -- SOAP （Simple Object Access Protocol...
RESTful 规范
梦否
08-29 4640
1. 基本概念     REST全称是Representational State Transfer，中文意思是表征性状态转移。指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。如果后台开发遵守了REST风格便可称为RESTful。 REST本身并没有创造新的技术，是一种软件架构风格，以更好地使用现有Web标准中的一些准则和约束。结构清晰、符合标准、易于理解、扩展方便。     RESTful架构是对MVC架构改进后所形成的一种架构，通过使用事先定义好的
什么是 RESTful API
最新发布
weixin_43346403的博客
10-11 720
a
RESTful风格
expleeve
05-15 1834
英文：Representational State Transfer，简称REST）是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格。 目前在三种主流的Web服务实现方案中，因为REST模式的Web服务与复杂的SOAP和XML-RPC对比来讲明显的更加简洁，越来越多的web服务开始采用REST风格设计和实现。例如，Amazon.com提供接近REST风格的Web服
Restful规范
灰海
11-30 7379
1、关于Restful 随着前后端分离越来越普遍，后端接口规范也就越来越重要了。一套良好的接口规范可以提升工作效率，减少沟通障碍。通常我们都会采用RestfulApi方式来提供接口，使用JSON来传输数据。 Restful是一种软件架构风格，不是标准。既然不是标准，可以遵守，也可以不遵守！！！ 2、Api设计6要素 资源路径(URI) HTTP动词(Method) 过滤信息(query-string) 状态码(Status-code) 错误信息(Error) 返回结果(Result)
RESTFul编程风格
小钟不想敲代码
04-20 2697
RESTFul编程风格
精选资源
RESTful API设计规范.pdf
02-13
RESTful API设计规范是指在软件架构和设计风格中，遵循一组设计原则和约束条件，以降低开发的复杂性，提高系统的可扩展性。RESTful架构的核心是面向资源，每个网址代表一种资源，因此网址中不能有动词，只能有名词。...
RESTful开发风格1：RESTful开发风格初体验一：RESTful开发风格简介；
小枯林的博客
11-09 967
说明： （1） 零：基于传统MVC模式开发web应用的问题； 说明： （1）上面的开发模式是典型的B/S架构（Browser/Server，浏览器/服务器模式）； ● 上面的开发模式很容易理解；也是我们以前经常经常遇到的； ● 在上面的模式中，客户端是支持HTML的浏览器（如谷歌浏览器、IE浏览器等）； （2）但是，还有很多客户端不是【支持HTML的浏览器】； ● 但是，目前互联网发展呈多元化的趋势，除了像谷歌浏览器这种B...
RESTful API风格指南
AI天才研究院
08-06 1781
什么是RESTful API？RESTful API是一种设计风格和开发方式，是一种通过互联网通信的Web服务接口，满足客户端（比如浏览器、移动设备）与服务器端之间信息交换的需求。RESTful API定义了一组规范，旨在使客户端更容易地与服务端通信，屏蔽了底层网络传输协议的复杂性。RESTful API基于HTTP协议，并使用HTTP方法（GET、POST、PUT、DELETE等）、URI和媒体类型（如JSON或XML）。
什么是RESTful接口风格
热门推荐
私聊前往站内信：https://i.youkuaiyun.com/#/msg/chat/weixin_44976692
01-14 2万+
本文将为您介绍RESTful的基本概念、设计原则以及实际应用中的一些技巧。通过本文，我们深入了解了RESTful接口风格的基本概念、设计原则以及一些实际应用的技巧。如果有任何问题或建议，欢迎在评论区留言。RESTful接口应该是统一的，资源的标识、资源的操作方式等都应该符合一致的设计原则。使用HTTP状态码来表示请求的结果，例如200表示成功，404表示未找到资源等。URI应该简洁、直观，使用名词表示资源，使用HTTP方法表示对资源的操作。资源是RESTful设计的核心，每个资源都有一个唯一的标识符。
RESTful规范(建议)
e61015656pub的博客
12-30 479
一、最原始的接口开发 这种方式虽然可以实现接口的开发，但是一个表的处理就需要4个url，当表单多的时候，需要写大量的url，这样不利于开发，并不是接口开发的最好方法 #url路由分配 urlpatterns = [ path('get_order/', views.get_order), path('add_order/', views.add_order), pat...
RESTful 风格详解
weixin_43189971的博客
07-29 9619
@RequsetParam @PathVariable 使用规范
SpringMVC RESTful简介及简单应用
qq_62254095的博客
04-03 216
REST（Representational State Transfer），表现形式状态转换,它是一种软件架构风格传统风格资源描述形式id=1查询id为1的用户信息保存用户信息REST风格描述形式传统方式一般是一个请求url对应一种操作，这样做不仅麻烦，也不安全，因为会程序的人读取了你的请求url地址，就大概知道该url实现的是一个什么样的操作。查看REST风格的描述，你会发现请求地址变的简单了，并且光看请求URL并不是很能猜出来该URL的具体功能。
restful规范
06-13
### RESTful API设计规范与最佳实践 RESTful API 是一种基于资源的架构风格，广泛应用于现代 Web 开发中。以下是关于 RESTful API 的详细设计规范和最佳实践： #### 1. 资源标识 RESTful API 的核心是资源，每个资源都应通过唯一的 URI（Uniform Resource Identifier）进行标识。推荐使用名词而非动词来命名资源，并且以复数形式表示集合资源。例如： - 正确示例：`/users`、`/orders` - 错误示例：`/getUser`、`/placeOrder` 此外，嵌套资源可以通过路径层级表示关联关系。例如，获取用户 `123` 的订单可以使用以下 URL[^1]： ```plaintext /users/123/orders ``` #### 2. HTTP 方法 RESTful API 应严格遵循 HTTP 方法语义，确保操作的语义清晰且一致。常见的 HTTP 方法及其用途如下： - **GET**：用于获取资源，不应产生副作用。 - **POST**：用于创建新资源。 - **PUT**：用于更新或替换整个资源。 - **PATCH**：用于部分更新资源。 - **DELETE**：用于删除资源。 例如，创建一个新用户可以通过以下请求实现： ```http POST /users Content-Type: application/json { "name": "John Doe", "email": "john.doe@example.com" } ``` #### 3. 状态码 HTTP 状态码是客户端理解服务器响应的重要依据。RESTful API 应根据操作结果返回适当的 HTTP 状态码。例如： - 成功创建资源时返回 `201 Created`。 - 成功更新资源时返回 `200 OK` 或 `204 No Content`。 - 资源不存在时返回 `404 Not Found`。 - 客户端请求无效时返回 `400 Bad Request`。 #### 4. 错误处理 清晰的错误处理机制有助于提高 API 的可用性和用户体验。推荐在错误响应中包含详细的错误信息，例如： ```json { "error": { "code": 400, "message": "Invalid request body", "details": "The 'email' field is missing." } } ``` #### 5. 响应格式 RESTful API 通常使用 JSON 格式作为数据交换的标准。响应应结构化且易于解析。例如： ```json { "id": 123, "name": "John Doe", "email": "john.doe@example.com" } ``` #### 6. 分页与过滤 对于大规模数据集，API 应支持分页和过滤功能，以减少不必要的数据传输。例如： ```http GET /users?page=2&size=10&filter=status:active ``` #### 7. HATEOAS HATEOAS（Hypermedia As The Engine Of Application State）是一种增强 API 可发现性的机制。通过在响应中包含链接，客户端可以导航到相关资源。例如： ```json { "id": 123, "name": "John Doe", "email": "john.doe@example.com", "_links": { "self": { "href": "/users/123" }, "orders": { "href": "/users/123/orders" } } } ``` #### 8. 缓存 为了提升性能，RESTful API 应尽可能支持缓存机制。通过设置合适的 HTTP 头部字段（如 `Cache-Control` 和 `ETag`），客户端可以有效利用缓存数据[^4]。 #### 9. 安全性 API 安全性是设计中的关键环节。推荐使用 HTTPS 协议保护数据传输，并结合 OAuth 2.0 等标准实现身份验证和授权。 --- ### 示例代码 以下是一个简单的 Java Spring Boot 实现 RESTful API 的示例： ```java @RestController @RequestMapping("/users") public class UserController { @GetMapping("/{id}") public ResponseEntity<User> getUser(@PathVariable Long id) { User user = userService.findById(id); if (user == null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(user); } @PostMapping public ResponseEntity<Void> createUser(@RequestBody User user) { User savedUser = userService.save(user); return ResponseEntity.created(URI.create("/users/" + savedUser.getId())).build(); } } ```
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值