Loading [MathJax]/jax/output/CommonHTML/config.js
首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >专栏 >面试官:你连RESTful都不知道我怎么敢要你?

面试官:你连RESTful都不知道我怎么敢要你?

作者头像
云爬虫技术研究笔记
发布于 2019-11-14 10:07:11
发布于 2019-11-14 10:07:11
1.2K00
代码可运行
举报
运行总次数:0
代码可运行

01 前言

看过很多RESTful相关的文章总结,参齐不齐,结合工作中的使用,非常有必要归纳一下关于RESTful架构方式了,RESTful只是一种架构方式的约束,给出一种约定的标准,完全严格遵守RESTful标准并不是很多,也没有必要。但是在实际运用中,有RESTful标准可以参考,是十分有必要的。

实际上在工作中对api接口规范、命名规则、返回值、授权验证等进行一定的约束,一般的项目api只要易测试、足够安全、风格一致可读性强、没有歧义调用方便我觉得已经足够了,接口是给开发人员看的,也不是给普通用户去调用。

02 RESTful的来源

REST:Representational State Transfer(表象层状态转变),如果没听说过REST,你一定以为是rest这个单词,刚开始我也是这样认为的,后来发现是这三个单词的缩写,即使知道了这三个单词理解起来仍然非常晦涩难懂。如何理解RESTful架构,最好的办法就是深刻理解消化Representational State Transfer这三个单词到底意味着什么。

1.每一个URI代表一种资源; 2.客户端和服务器之间,传递这种资源的某种表现层; 3.客户端通过四个HTTP动词(get、post、put、delete),对服务器端资源进行操作,实现”表现层状态转化”。

是由美国计算机科学家Roy Fielding(百度百科没有介绍,真是尴尬了)。Adobe首席科学家、Http协议的首要作者之一、Apache项目联合创始人。

03 RESTful6大原则

REST之父Roy Fielding在论文中阐述REST架构的6大原则。

1. C-S架构

数据的存储在Server端,Client端只需使用就行。两端彻底分离的好处使client端代码的可移植性变强,Server端的拓展性变强。两端单独开发,互不干扰。

2. 无状态

http请求本身就是无状态的,基于C-S架构,客户端的每一次请求带有充分的信息能够让服务端识别。请求所需的一些信息都包含在URL的查询参数、header、body,服务端能够根据请求的各种参数,无需保存客户端的状态,将响应正确返回给客户端。无状态的特征大大提高的服务端的健壮性和可拓展性。

当然这总无状态性的约束也是有缺点的,客户端的每一次请求都必须带上相同重复的信息确定自己的身份和状态(这也是必须的),造成传输数据的冗余性,但这种确定对于性能和使用来说,几乎是忽略不计的。

3.统一的接口

这个才是REST架构的核心,统一的接口对于RESTful服务非常重要。客户端只需要关注实现接口就可以,接口的可读性加强,使用人员方便调用。

4.一致的数据格式

服务端返回的数据格式要么是XML,要么是Json(获取数据),或者直接返回状态码,有兴趣的可以看看博客园的开放平台的操作数据的api,post、put、patch都是返回的一个状态码 。

自我描述的信息,每项数据应该是可以自我描述的,方便代码去处理和解析其中的内容。比如通过HTTP返回的数据里面有 [MIME type ]信息,我们从MIME type里面可以知道数据的具体格式,是图片,视频还是JSON,客户端通过body内容、查询串参数、请求头和URI(资源名称)来传送状态。服务端通过body内容,响应码和响应头传送状态给客户端。这项技术被称为超媒体(或超文本链接)。

除了上述内容外,HATEOS也意味着,必要的时候链接也可被包含在返回的body(或头部)中,以提供URI来检索对象本身或关联对象。下文将对此进行更详细的阐述。

如请求一条微博信息,服务端响应信息应该包含这条微博相关的其他URL,客户端可以进一步利用这些URL发起请求获取感兴趣的信息,再如分页可以从第一页的返回数据中获取下一页的URT也是基于这个原理。

4.系统分层

客户端通常无法表明自己是直接还是间接与端服务器进行连接,分层时同样要考虑安全策略。

5.可缓存

在万维网上,客户端可以缓存页面的响应内容。因此响应都应隐式或显式的定义为可缓存的,若不可缓存则要避免客户端在多次请求后用旧数据或脏数据来响应。管理得当的缓存会部分地或完全地除去客户端和服务端之间的交互,进一步改善性能和延展性。

6.按需编码、可定制代码(可选)

服务端可选择临时给客户端下发一些功能代码让客户端来执行,从而定制和扩展客户端的某些功能。比如服务端可以返回一些 Javascript 代码让客户端执行,去实现某些特定的功能。提示:REST架构中的设计准则中,只有按需编码为可选项。如果某个服务违反了其他任意一项准则,严格意思上不能称之为RESTful风格。

03 RESTful的7个最佳实践

1. 版本

如github开放平台 https://developer.github.com/v3/ 就是将版本放在url,简洁明了,这个只有用了才知道,一般的项目加版本v1,v2,v3?好吧,这个加版本估计只有大公司大项目才会去使用,说出来不怕尴尬,我真没用过。有的会将版本号放在header里面,但是不如url直接了当。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://example.com/api/v1/

2.参数命名规范

query parameter可以采用驼峰命名法,也可以采用下划线命名的方式,推荐采用下划线命名的方式,据说后者比前者的识别度要高,可能是用的人多了吧,因人而异,因团队规范而异吧

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://example.com/api/users/today_login 获取今天登陆的用户
https://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列

3.url命名规范

API 命名应该采用约定俗成的方式,保持简洁明了。在RESTful架构中,每个url代表一种资源所以url中不能有动词,只能有名词,并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可

不规范的的url,冗余没有意义,形式不固定,不同的开发者还需要了解文档才能调用。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://example.com/api/getallUsers GET 获取所有用户
https://example.com/api/getuser/1 GET 获取标识为1用户信息
https://example.com/api/user/delete/1 GET/POST 删除标识为1用户信息
https://example.com/api/updateUser/1 POST 更新标识为1用户信息
https://example.com/api/User/add POST 添加新的用户

规范后的RESTful风格的url,形式固定,可读性强,根据users名词和http动词就可以操作这些资源

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://example.com/api/users GET 获取所有用户信息
https://example.com/api/users/1 GET 获取标识为1用户信息
https://example.com/api/users/1 DELETE 删除标识为1用户信息
https://example.com/api/users/1 Patch 更新标识为1用户部分信息,包含在body中
https://example.com/api/users POST 添加新的用户

4. 统一返回数据格式

对于合法的请求应该统一返回数据格式,这里演示的是json

  • code——包含一个整数类型的HTTP响应状态码。
  • status——包含文本:”success”,”fail”或”error”。HTTP状态响应码在500-599之间为”fail”,在400-499之间为”error”,其它均为”success”(例如:响应状态码为1XX、2XX和3XX)。这个根据实际情况其实是可要可不要的。
  • message——当状态值为”fail”和”error”时有效,用于显示错误信息。参照国际化(il8n)标准,它可以包含信息号或者编码,可以只包含其中一个,或者同时包含并用分隔符隔开。
  • data——包含响应的body。当状态值为”fail”或”error”时,data仅包含错误原因或异常名称、或者null也是可以的

返回成功的响应json格式

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
{
  "code": 200,
  "message": "success",
  "data": {
    "userName": "123456",
    "age": 16,
    "address": "beijing"
  }
}

返回失败的响应json格式

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
{
  "code": 401,
  "message": "error  message",
  "data": null
}

下面这个ApiResult的泛型类是在项目中用到的,拓展性强,使用方便。返回值使用统一的 ApiResult 或 ApiResult 错误返回 使用 ApiResult.Error 进行返回;成功返回,要求使用 ApiResult.Ok 进行返回

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
public class ApiResult: ApiResult
    {
        public new static ApiResult<T> Error(string message)
        {
            return new ApiResult<T>
            {
                Code = 1,
                Message = message,
            };
        }
        [JsonProperty("data")]
        public T Data { get; set; }
    }
    public class ApiResult
    {
        public static ApiResult Error(string message)
        {
            return new ApiResult
            {
                Code = 1,
                Message = message,
            };
        }

        public static ApiResult<T> Ok<T>(T data)
        {
            return new ApiResult<T>()
            {
                Code = 0,
                Message = "",
                Data = data
            };
        }
        /// <summary>
        /// 0 是 正常 1 是有错误
        /// </summary>
        [JsonProperty("code")]
        public int Code { get; set; }
        [JsonProperty("msg")]
        public string Message { get; set; }

        [JsonIgnore]
        public bool IsSuccess => Code == 0;
    }

5. http状态码

在之前开发的xamarin android博客园客户端的时候,patch、delete、post操作时body响应里面没有任何信息,仅仅只有http status code。HTTP状态码本身就有足够的含义,根据http status code就可以知道删除、添加、修改等是否成功。(ps:有点linux设计的味道哦,没有返回消息就是最好的消息,表示已经成功了)服务段向用户返回这些状态码并不是一个强制性的约束。简单点说你可以指定这些状态,但是不是强制的。常用HTTP状态码对照表 HTTP状态码也是有规律的

  • 1**请求未成功
  • 2**请求成功、表示成功处理了请求的状态代码。
  • 3**请求被重定向、表示要完成请求,需要进一步操作。通常,这些状态代码用来重定向。
  • 4** 请求错误这些状态代码表示请求可能出错,妨碍了服务器的处理。
  • 5**(服务器错误)这些状态代码表示服务器在尝试处理请求时发生内部错误。这些错误可能是服务器本身的错误,而不是请求出错。

6. 合理使用query parameter

在请求数据时,客户端经常会对数据进行过滤和分页等要求,而这些参数推荐采用HTTP Query Parameter的方式实现

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
比如设计一个最近登陆的所有用户
https://example.com/api/users?recently_login_day=3
代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
搜索用户,并按照注册时间降序
https://example.com/api/users?recently_login_day=3
代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
搜索用户,并按照注册时间升序、活跃度降序
https://example.com/api/users?q=key&sort=create_title_asc,liveness_desc
代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
关于分页,看看博客园开放平台分页获取精华区博文列表
https://api.cnblogs.com/api/blogposts/@picked?pageIndex={pageIndex}&pageSize={pageSize}
返回示例:
[ 
{
“Id”: 1,
“Title”: “sample string 2,
“Url”: “sample string 3,
“Description”: “sample string 4,
“Author”: “sample string 5,
“BlogApp”: “sample string 6,
“Avatar”: “sample string 7,
“PostDate”:2017-06-25T20:13:38.892135+08:00,
“ViewCount”: 9,
“CommentCount”: 10,
“DiggCount”: 11
},
{
“Id”: 1,
“Title”: “sample string 2,
“Url”: “sample string 3,
“Description”: “sample string 4,
“Author”: “sample string 5,
“BlogApp”: “sample string 6,
“Avatar”: “sample string 7,
“PostDate”:2017-06-25T20:13:38.892135+08:00,
“ViewCount”: 9,
“CommentCount”: 10,
“DiggCount”: 11
}
]

7. 多表、多参数连接查询如何设计URL

这是一个比较头痛的问题,在做单个实体的查询比较容易和规范操作,但是在实际的API并不是这么简单而已,这其中常常会设计到多表连接、多条件筛选、排序等。比如我想查询一个获取在6月份的订单中大于500元的且用户地址是北京,用户年龄在22岁到40岁、购买金额降序排列的订单列表

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://example.com/api/orders?order_month=6&order_amount_greater=500&address_city=北京&sort=order_amount_desc&age_min=22&age_max=40

从这个URL上看,参数众多、调用起来还得一个一个仔细对着,而且API本身非常不容易维护,命名看起来不是很容易,不能太长,也不能太随意。

在.net WebAPI总我们可以使用属性路由,属性路由就是讲路由附加到特定的控制器或操作方法上装饰Controll及其使用[Route]属性定义路由的方法称为属性路由。

这种好处就是可以精准地控制URL,而不是基于约定的路由,简直就是为这种多表查询量身定制似的的。从webapi 2开发,现在是RESTful API开发中最推荐的路由类型。我们可以在Controll中标记Route

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
[Route(“api/orders/{address}/{month})]

Action中的查询参数就只有金额、排序、年龄。减少了查询参数、API的可读性和可维护行增强了。

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
https://example.com/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

这种属性路由比如在博客园开放的API也有这方面的应用,如获取个人博客随笔列表

代码语言:javascript
代码运行次数:0
运行
AI代码解释
复制
请求方式:GET
请求地址:https://api.cnblogs.com/api/blogs/{blogApp}/posts?pageIndex={pageIndex}
(ps:blogApp:博客名)
本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2019-11-13,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 云爬虫技术研究笔记 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
暂无评论
推荐阅读
编辑精选文章
换一批
RESTful规范Api最佳设计实践
RESTful是目前比较流行的接口路径设计规范,基于HTTP,一般使用JSON方式定义,通过不同HttpMethod来定义对应接口的资源动作,如:新增(POST)、删除(DELETE)、更新(PUT、PATCH)、查询(GET)等。
恒宇少年
2019/10/10
1K0
Restful 规范
Restful 规范 REST Representational State Transfer(表象层状态转变) RESTful原则 RESTful就是对对接口的约束规范,有六大原则 C-S架构:数
JuneBao
2022/10/26
4570
【RESTful】RESTful API 接口设计规范 | 示例
参考官方文档:https://tools.ietf.org/html/rfc2616
前端修罗场
2023/10/07
2.1K0
【RESTful】RESTful API 接口设计规范 | 示例
【全栈修炼】RESTful架构及实践修炼宝典
REST:(Representational State Transfer)即表现层状态转换,定义了资源的通用访问格式,是一种网络应用程序的设计风格和开发方式。
pingan8787
2019/11/26
1.2K0
RESTful设计方法和规范
REST 全称是 Representational State Transfer,中文意思是表述性状态转移(注:通常译为表征性状态转移)。它首次出现在 2000 年 Roy Fielding 的博士论文中,Roy Fielding 是 HTTP 规范的主要编写者之一。
Tinywan
2024/08/12
2660
RESTful设计方法和规范
Restful API 设计指北
近期学习了Go语言,跟着七米在学习,学习过程中了解到了 API 的一个设计规范,也就是本文要讲的 Restful API 设计模式,现在互联网处在前后端分离的阶段,API 的书写及规范化是非常重要的,针对于 API 中 Restful API 中设计比较规范的是 Github API,可以直接访问他们的 https://api.github.com 直接查看 Github 针对与公共接口的链接及使用方法。
Meng小羽
2020/03/12
8090
使用 swagger 生成规范化的RESTful API 代码
REST(英文:Representational State Transfer,又称具象状态传输)是Roy Thomas Fielding博士于2000年在他的博士论文[1] 中提出来的一种万维网软件架构风格,目的是便于不同软件/程序在网络(例如互联网)中互相传递信息。
goodspeed
2020/12/25
6.5K0
使用 swagger 生成规范化的RESTful API 代码
RESETful API 设计规范
如果你的应用很庞大或者你预计它将会变的很庞大,那 应该 将 API 放到子域下(api.example.com)。这种做法可以保持某些规模化上的灵活性。
全栈程序员站长
2022/06/29
1.8K0
RESTful API
网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......)。
用户1214487
2022/03/26
1.8K0
RESTful API
深入解析 RESTful API:从设计到实践的完整指南
在当今的互联网世界中,不同系统之间的数据交互和通信是构建现代应用的核心需求。无论是移动应用、Web 平台,还是微服务架构,RESTful API 都扮演着桥梁的角色。它以其简洁性、灵活性和可扩展性,成为开发者构建分布式系统的首选方案。本文将从基础概念到实际应用,一步步拆解 RESTful API 的设计与实现,助你掌握这一关键技术。
DevKevin
2025/02/16
8170
浅谈 RESTful API
全称:REST,全称是Resource Representational State Transfer,即:URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作。
Spark学习技巧
2021/02/12
1.1K0
浅谈 RESTful API
什么是RESETful API 设计规范?
现在在开发中前后端都是分离开发,后端提供接口给前台,RESTful 架构,就是目前最流行的一种互联网软件架构,也相当于是接口规范
沈唁
2018/08/21
3.5K0
什么是RESETful API 设计规范?
RESTful API 最佳实践
在参考了GitHub API设计和大量博客文章后总结了一下RESTful API的设计,分享如下。想要更好的理解RESTful API首先需要理解如下概念:
哲洛不闹
2018/09/14
2K0
RESTful API 最佳实践
细说RESTful API之入门介绍
REST(英文:Representational State Transfer,又称具象状态传输)是Roy Thomas Fielding博士于2000年在他的博士论文中提出来的一种万维网软件架构风格,目的是便于不同软件/程序在网络(例如互联网)中互相传递信息。目前在三种主流的Web服务实现方案中,因为REST模式与复杂的SOAP和XML-RPC相比更加简洁,越来越多的web服务开始采用REST风格设计和实现。
编程随笔
2019/09/11
7110
细说RESTful API之入门介绍
RESTful 接口
REST 将资源的状态以适合客户端的形式从服务端发送到客户端(或相反方向)。在 REST 中,通过 URL 进行资源定位,用 HTTP 动作(GET、POST、DELETE、PUT等)描述进行操作,完成功能。
Jimmy_is_jimmy
2023/07/31
1.1K0
RESTful 接口
Restful 架构 API 接口经典设计误区
目前微服务架构盛行,在了解了很多的实际微服务项目中,发现很多同事在设计业务 API 接口时,写法五花八门,现总结下目前项目上设计业务 API 接口的一些比较经典误区写法。
猿芯
2021/05/27
8710
RESTful API 设计最佳实践
Web API 近几年变得越来越火,而简洁的 API 设计在多后端系统交互应用中也变得尤为重要。通常,会使用 RESTful API 来作为我们的 Web API 。本文介绍了几种简洁 RESTful API 设计的最佳实践。
用户7657330
2020/08/14
7200
10个有关RESTful API良好设计的最佳实践
  Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的。
物流IT圈
2019/07/16
7210
浅谈RESTful
RESTful 是一种系统开发设计风格、原则,可视情况调整。以下内容参考RFC5789。
老猫-Leo
2023/12/11
2450
Koa2+MongoDB+JWT实战--Restful API最佳实践
Web API 已经在最近几年变成重要的话题,一个干净的 API 设计对于后端系统是非常重要的。
前端森林
2020/04/23
10K0
Koa2+MongoDB+JWT实战--Restful API最佳实践
相关推荐
RESTful规范Api最佳设计实践
更多 >
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档
本文部分代码块支持一键运行,欢迎体验
本文部分代码块支持一键运行,欢迎体验