路径前加什么动词


前言

在学习RESTful风格接口之前,你可能对其能解决的问题和应用场景感到好奇。听我给你解释一下:在互联网的早期,页面请求和并发量不高,那时的接口要求并不严格,一些动态页面就可以满足大多数需求。但随着互联网和移动设备的发展,人们对Web应用的需求增加,传统的动态页面因效率低下而被前后端分离的HTML+JavaScript(Ajax)所取代。现在,移动端、小程序等客户端种类多元化,它们需要与服务端进行通信,这时,接口的重要性就凸显出来了。

而RESTful风格的接口(RESTful API)因其结构清晰、符合标准、易于理解和扩展方便等特点,逐渐被广泛应用。现在,它是最流行的接口设计规范,在很多公司有着广泛的应用。

但在开发实践中,很多人可能仍使用传统API进行请求交互,对RESTful API的认知可能仅停留在表面。其实,RESTful API的精髓远不止于此。

一、REST概述

REST涉及一些概念性的东西可能比较多。在实战RESTful API之前,我们需要对REST相关的知识有个系统的认知。

REST的诞生:REST是一种软件架构风格和设计风格,而不是标准。它主要用于客户端和服务器交互类的软件。基于这种风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。

需要注意的是,REST并没有一个明确的标准,而更像是一种设计的风格。所以满足这种设计风格的程序或接口我们称之为RESTful。Fielding博士提出的REST架构在很长时间内并没有受到太多关注,近些年才在国内变得流行起来。

二、RESTful API设计规范

了解了RESTful的一些规则和特性后,我们该如何设计RESTful API呢?这需要我们从URL路径、HTTP请求动词、状态码和返回结果等方面详细考虑。

URL设计规范:URL为统一资源,API的path设计需要认真考虑。RESTful对path的设计有一些规范,如版本号、资源、资源id等。

HTTP动词:在RESTful API中,不同的HTTP请求方法有各自的含义。我们需要正确使用GET、POST、PUT、DELETE等请求方法,以表示不同的操作。

状态码和返回数据:服务端处理完成后,需要返回状态码和返回数据给客户端。我们需要正确使用各类状态码来表示请求的处理结果,同时返回数据给客户端。

三、一个RESTful API案例

上面讲了那么多理论知识,下面我们动手实现一个小案例吧!

在这个案例中,我们将访问的RESTful接口都是对数据库的真实操作。我们需要新建数据库和表。

案例的POJO是Dog.java实体对象。我们将实现对dog资源的增删改查操作。这里我们简单演示了如何使用SpringBoot实现这个接口,并没有完全遵循RESTful API规范。在使用postman发送请求时,我们介绍了三种常见的文件类型传递到后端的方式。

在数字化世界中,文本上传是我们不可或缺的需求。你可以轻松上传任意格式的文本,无论是简单的Text格式还是复杂的JSON或XML格式数据。当我们需要后端接收JSON格式数据进行处理时,这种方式尤为方便,可以用于测试各种场景。

在处理HTTP请求时,我们通常会使用不同的请求方法来向后端传递数据。GET请求常用于查询参数,这些参数直接附加在URL后面。不同浏览器对GET请求的参数长度有一定的限制,这对于长文本传输可能存在问题。当前场景中,我们设计了两个基于GET请求的API接口。一个是GET /dogs,用于返回dog资源的列表;另一个是GET /dogs/{dogid},用于查询特定ID的单个dog资源。

当我们要新增一个资源时,我们使用POST请求。就像数据库中插入新记录的操作一样,POST请求会创建新的内容。其请求参数通常包含在请求体中,没有特定的长度限制。在我们的案例中,POST /dogs接口用于在服务器端新增一个dog资源。

还有DELETE请求,它的作用就是删除资源,与数据库中的删除操作相对应。我们的案例中,DELETE /dogs/{dogid}接口用于删除特定ID的单个dog资源。

对应的Mapper文件和controller文件是这些API接口的核心组成部分。经过测试,这些API接口运行正常。

RESTful风格的API具有其独特的优点和规范性。在实际应用中,大多数互联网公司并不会完全遵循RESTful的规则。REST更像是一种设计风格,而不是严格的规则或约束。过于理想的RESTful API可能会增加不必要的成本。例如,RESTful API的操作方式相对繁琐,且某些浏览器对除GET和POST之外的请求支持不够友好。对于复杂的业务需求,单纯的增删改查可能无法满足需求。在设计API时,我们应结合实际情况,如果REST风格与业务场景相匹配则可采用,否则可以根据实际需求进行选择或借鉴其他设计风格。无论如何,设计的目标始终是方便团队开发、沟通和项目管理。