Restful设计风格

最新推荐文章于 2025-04-02 21:27:54 发布

ammmao

最新推荐文章于 2025-04-02 21:27:54 发布

阅读量316

点赞数

CC 4.0 BY-SA版权

分类专栏： Web开发文章标签： restful

本文链接：https://blog.csdn.net/ammmao/article/details/96155077

Web开发专栏收录该内容

1 篇文章

订阅专栏

RESTful设计风格强调使用HTTP协议，通过名词表示资源，利用HTTP方法执行操作。资源的URL应避免动词，统一使用名词的复数形式。正确使用HTTP状态码表示操作结果，错误处理需提供详细信息。此外，推荐实现版本控制，并统一返回JSON格式的数据。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

文章目录

RESTFUL

RESTFUL

RESTful(Representational State Transfer),表现层状态转义。通俗来讲就是：资源在网络中以某种表现形式进行状态转移。分解开来

它首次出现在2000年ROY Fielding的博士论文中，Roy Fielding是HTTP规范的编写者之一。

表现层是资源的表现层，对于网络中的资源就需要URL来指向。

1.协议

使用HTTP或者HTTPs。对外若有安全性要求，可以使用HTTPS，但是内部服务间调用可以使用HTTP或者HTTPS。

2.HTTP方法

HTTP请求中的方法表示执行的动作

常用方法(动词)	说明
GET	获取资源
POST	创建新的资源
PUT	更细资源
PATCH	部分更新资源
DELETE	删除资源

3.使用名词

URL指向资源,在URL路径的描述中,只需要出现名词。动词由HTTP方法提供。
不要单复数混用，建议名词使用复数。
Reatful的核心是资源，URL应该指向资源，所以应该是使用名称表达，而不是动词表达。

示例

方法	路径	说明
GET	/posts/返回所有文章
GET	/posts/10	返回id为10的文章
POST	/posts	创建新的文章
PUT	/posts/10	更细id为10的文章
DELETE	/posts/10	删除id为10的文章
PATCH	/posts/10	部分更新id为10的文章数据

不要出现下面的访问资源的路径

/getALLposts
/addposts
/updateposts
/delposts

GET方法只是获取资源,而不是改变资源状态。改变资源状态请使用POST、PUT、DELETE等方法。

例如，使用GET /posts/10就可以获取资源了,但是却使用GET /posts/10/del或 GET /posts/10?v=del,本意是想删除,但这样不好,GET方法请求只是为了获取资源,不要改变资源状态。

方法	路径	说明
GET	/posts/10/authors	返回id为10的文章的所有作者
GET	/posts/10/authors/8	返回id为10的文章的作者中id为4的

4.集合功能

过滤 Filtering
指定过滤条件 GET /posts?tag=python

排序 Sorting
指定排序条件。有很多种设计风格，例如使用+表示asc， -表示desc。
GET /posts?sort=+tile,-id
GET /posts?sort=title_asc,id_desc

分页 Pagination
一般情况下,查询返回的记录数非常的多,必须分页。
GET /posts?page=5&size=20

5.状态码

使用HTTP响应的状态码表示动作的成功与否

Status code	说明	Method	说明
200	OK	GET	成功获取资源
201	CREATED	POST、PUT、PATCH	成功创建或修改
204	NO CONTENT	DELETE	成功删除资源
400	Bad Request	ALL	请求中错误,例如GET时参数有问题,PUT是提交的数据错误等
401	Unauthorized	ALL	权限未通过认证
403	Forbidden	ALL	有无权限都进制访问该资源
404	Not Found	ALL	请求的资源不存在
500	Internal Server Error	ALL	服务器端错误

详细状态码参考https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

6.错误处理

在Restfil API设计中,错误处理也非常重要,单单从状态码中无法详尽描述错误的信息。

1.返回信息

{
    error:"user Not Found"
}

2.从错误消息中了解到错误号、错误信息、错误描述等信息。甚至更详细的信息可以通过code查阅文档。

{
    "code":10056,
    "message":"Invalid ID",
    "description":"More Details"
}

7.版本

强烈要求使用版本,版本号可以使用简单数字,例如v2

2种风格

http://api.baidu.com/v1/posts/10 这种风格会跨域,适合较大的项目
http://www.magedu.com/api/v1/posts/10

8.返回结果

方法	路径	说明
GET	/posts	返回所有文章的列表
GET	/posts/10	返回id为10的文章对象
POST	/posts	创建新的文章并返回这个对象
PUT	/posts/10	更新id为10的文章并返回这个对象
DELETE	/posts/10	删除id为10的文章并返回一个空对象
PATCH	/posts/10	部分更新id为10的文章数据并返回这个对象

返回数据一律采用JSON格式