我们必须要知道的RESTful服务最佳实践

最新推荐文章于 2024-06-20 21:48:49 发布
最新推荐文章于 2024-06-20 21:48:49 发布
阅读量288 收藏
点赞数
文章标签： rest
原文链接：https://blog.csdn.net/kebi007/article/details/80614157?utm_source=blogxgwz7
版权

以下内容转载于https://blog.csdn.net/kebi007/article/details/80614157?utm_source=blogxgwz7

 

看过很多RESTful相关的文章总结，参齐不齐，结合工作中的使用，非常有必要归纳一下关于RESTful架构方式了，RESTful只是一种架构方式的约束，给出一种约定的标准，完全严格遵守RESTful标准并不是很多，也没有必要。但是在实际运用中，有RESTful标准可以参考，是十分有必要的。
实际上在工作中对api接口规范、命名规则、返回值、授权验证等进行一定的约束，一般的项目api只要易测试、足够安全、风格一致可读性强、没有歧义调用方便我觉得已经足够了，接口是给开发人员看的，也不是给普通用户去调用。

回想刚进公司的时候，非常惭愧，并没仔细地了解接口的一些约束，给自己挖坑，给别人挖坑。第一次听说RESTful还是刚工作那会，差不多也有两年了，虽然项目中并没有严格遵守RESTful规范，还是要自我总结反思一下。
我们必须要知道的RESTful服务最佳实践

本章导读：
REST来源
REST是什么，应该知道的6大原则

  1. C-S架构

  2. 无状态

  3. 统一的接口

  4. 一致的数据格式

  5. 自我描述的信息

  6. 超媒体即应用状态引擎（HATEOAS）
    RESTful使用应该注意的问题

  7. 版本（Versioning）

  8. 参数命名规范

  9. url命名规范

  10. 统一返回数据格式

  11. http状态码

  12. 合理使用query parameter

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

  14. API请求授权

1.REST的来源

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

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

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

这位大神牛逼的地方在于2000年那时候发表的论文，应该没被广泛关注，那时候的网页前端后端都是融合在一起，接口服务这些东西即使存在这种概念，都没地方发挥作用，好的东西经得起时间的考验，就像唐诗宋词几千年都会有人读，而什么郭敬明的什么小说我估计00后都不知道什么玩意（我猜的）

随着近几年的移动互联网的爆发、前后端分离的思想，RESTful架构被广泛应用，如
博客园的开发平台：https://developers.douban.com/wiki/?title=api_v2
豆瓣API： https://developers.douban.com/wiki/?title=api_v2
GitHub开放平台： https://developer.github.com/v3/
Roy Fielding的原中英文论文地址如下，可以收藏下载看看，论文一般都比较晦涩难懂。
架构风格与基于网络的软件架构设计.pdf
Architectural_Styles_and_the_Design_of_Network-based_Software_Architectures.pdf
前人栽树，后人乘凉。关于RESTful服务最佳实践 总结的一篇非常好的文章也是外国人写的，原英文下载：RESTful Best Practices-v1 2.pdf
有园友翻译总结后的中文：https://www.cnblogs.com/jaxu/p/7908111.html

  1. REST是什么，应该知道的6大原则

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
** 超媒体即应用状态引擎（HATEOAS）**
　客户端通过body内容、查询串参数、请求头和URI（资源名称）来传送状态。服务端通过body内容，响应码和响应头传送状态给客户端。这项技术被称为超媒体（或超文本链接）。
　　除了上述内容外，HATEOS也意味着，必要的时候链接也可被包含在返回的body（或头部）中，以提供URI来检索对象本身或关联对象。下文将对此进行更详细的阐述。
　　如请求一条微博信息，服务端响应信息应该包含这条微博相关的其他URL，客户端可以进一步利用这些URL发起请求获取感兴趣的信息，再如分页可以从第一页的返回数据中获取下一页的URT也是基于这个原理
4.系统分层
客户端通常无法表明自己是直接还是间接与端服务器进行连接，分层时同样要考虑安全策略。
5.可缓存
　　在万维网上，客户端可以缓存页面的响应内容。因此响应都应隐式或显式的定义为可缓存的，若不可缓存则要避免客户端在多次请求后用旧数据或脏数据来响应。管理得当的缓存会部分地或完全地除去客户端和服务端之间的交互，进一步改善性能和延展性。
6.按需编码、可定制代码（可选）
服务端可选择临时给客户端下发一些功能代码让客户端来执行，从而定制和扩展客户端的某些功能。比如服务端可以返回一些 Javascript 代码让客户端执行，去实现某些特定的功能。
提示：REST架构中的设计准则中，只有按需编码为可选项。如果某个服务违反了其他任意一项准则，严格意思上不能称之为RESTful风格。

3.RESTful使用应该注意的问题

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

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

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

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，冗余没有意义，形式不固定，不同的开发者还需要了解文档才能调用

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动词就可以操作这些资源

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

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

返回成功的响应json格式

{
  "code": 200,
  "message": "success",
  "data": {
    "userName": "123456",
    "age": 16,
    "address": "beijing"
  }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

返回失败的响应json格式

{
  "code": 401,
  "message": "error  message",
  "data": null
}
  • 1
  • 2
  • 3
  • 4
  • 5

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

    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;
    }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44

5. http状态码
在之前开发的xamarin android博客园客户端的时候，patch、delete、post操作时body响应里面没有任何信息，仅仅只有http status code。HTTP状态码本身就有足够的含义，根据http status code就可以知道删除、添加、修改等是否成功。服务段向用户返回这些状态码并不是一个强制性的约束。简单点说你可以指定这些状态，但是不是强制的。常用HTTP状态码对照表
HTTP状态码也是有规律的
1请求未成功
2请求成功、表示成功处理了请求的状态代码。
3请求被重定向、表示要完成请求，需要进一步操作。 通常，这些状态代码用来重定向。
4 请求错误这些状态代码表示请求可能出错，妨碍了服务器的处理。
5**（服务器错误）这些状态代码表示服务器在尝试处理请求时发生内部错误。 这些错误可能是服务器本身的错误，而不是请求出错。

| HTTP Method |详细解释| 返回状态码|
| - | - |
| GET |获取对象或集合|200成功、401没有授权、403访问禁止、404没有资源、参数错误、406请求格式不正确、410资源被删除、500服务器内部错误|
| POST | 新增一条数据 |201创建成功、422新增数据验证错误、（401、403、404、406、500）|
|DELETE | 删除一条数据|204删除成功、（401、403、404、406、500）|
|PATCH | 更新实体部分信息|201更新成功、422验证数据错误（401、403、404、406、500）|
|PUT | 更新实体所有信息除ID外|201更新成功、422（401、403、404、406、500）|

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

  1. 比如设计一个最近登陆的所有用户

https://example.com/api/users?recently_login_day=3

  1. 搜索用户，并按照注册时间降序

https://example.com/api/users?q=key&sort=create_title_desc

  1. 搜索用户，并按照注册时间升序、活跃度降序

https://example.com/api/users?q=key&sort=create_title_asc,liveness_desc

  1. 关于分页，看看博客园开放平台分页获取精华区博文列表

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岁、购买金额降序排列的订单列表

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
[Route(“api/orders/{address}/{month}”)]
Action中的查询参数就只有金额、排序、年龄。减少了查询参数、API的可读性和可维护行增强了。

https://example.com/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

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

请求方式：GET
请求地址：https://api.cnblogs.com/api/blogs/{blogApp}/posts?pageIndex={pageIndex}
blogApp：博客名

7.API请求授权
博客园的开放平台API也是基于OAuth2.0，参见理解OAuth2.0，留存分析

有兴趣的可以关注一下我的微信公众号，分享一些编程相关的经典文章
在这里插入图片描述

ArtisticProgramming
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
RESTful
qq_43389371的博客
10-25 236
REST 是什么 REST 全称 Representational State Transfer ，它不是业界哪个组织规定的规范，它是一种万维网软件架构的风格 ，它是用来创建网路服务的。 Representational ：这里的含义是 数据的表现形式 （JSON、XML…），常用 JSON 数据格式 State ：当前状态或者数据，描述当前处于那种状态（增、删、改、查） Transfer ：数据传输，数据在互联网上传输，（服务器传到客户端） REST 6 个限制 客户-服务器（Client-Serve
restful
qq_47759220的博客
02-04 116
转自：https://blog.csdn.net/qq_27026603/article/details/82012277 概念 一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。 URL定义 资源：互联网所有的事物都可以被抽象为资源 资源操作：使用POST、DELETE、PUT、GET，使用不同方法对资源进行操作。 分别对应 添加、 删除、修改...
RestFul服务介绍
11-21
1. REST介绍 REpresentational State Transfer (REST) 是一种架构原则，其中将 web 服务视为资源，可以由其 URL 唯一标识。 RESTful Web 服务的关键特点是明确使用 HTTP 方法来表示不同的操作的调用。 REST 的基本设计原则对典型 CRUD 操作使用 HTTP 协议方法： POST - 创建资源 GET - 检索资源 PUT – 更新资源 DELETE - 删除资源
jeesz分布式架构-RestFul服务
civtsbiqr522632413的博客
06-06 102
1. REST介绍 REpresentational State Transfer (REST)是一种架构原则，其中将web服务视为资源，可以由其URL唯一标识。 RESTful Web服务的关键...
豆瓣最新能用的api合集总结
最新发布
独行猫a 的沉淀、积累、总结。天天学习，好好向上...c/c++,嵌入式 linux,Android,HarmonyOS)
06-20 1万+
豆瓣网（Douban）作为一个集合了书籍、电影、音乐等多个领域的评论和评分平台，提供了丰富的API接口供开发者使用。通过这些API，开发者可以轻松地获取和处理豆瓣网上的各种数据，实现与豆瓣服务的无缝集成。本文将为您介绍最新的豆瓣API合集及其使用方法。接下来将详细介绍每个类别下的重要接口及其使用示例。
RESTful 最佳实践
weixin_33775572的博客
08-17 209
2019独角兽企业重金招聘Python工程师标准>>> ...
【Restful】三分钟彻底了解Restful最佳实践
guoxinming123的博客
03-24 91
REST是英文representational state transfer(表象性状态转变)或者表述性状态转移;Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计;它是一种设计风格,不是一种标准,是一种思想 Rest架构的主要原则 网络上的所有事物都被抽象为资源 每个资源都有一个...
RESTful API 设计最佳实践
03-20
RESTful API 设计最佳实践是构建可扩展、高效且易于使用的Web服务的关键。遵循REST（Representational State Transfer）原则，可以确保API与Web的核心概念——HTTP协议紧密结合，从而实现资源的透明操作。以下是对...
restful:RESTful的Drupal最佳实践
05-03
RESTful的Drupal最佳实践 该模块允许使用安全性，性能和可用性的最佳实践，通过RESTful HTTP请求来操作Drupal。 概念 以下是RESTful和其他模块（例如RestW和服务实体）之间的区别： RESTful需要明确声明公开的API。...
RESTFUL BEST PRACTICES
08-22
Introduction There are numerous resources on best practices for creating RESTful web services (see the Resources section at the end of this document). Many of the available resources are conflicting, depending on when they were written. Plus, reading and comprehending several books on the subject in order to implement services “tomorrow” is not doable. In order to facilitate the quick uptake and understanding of RESTful concepts, without requiring the reading of at least three to five books on the subject, this guide is meant to speed up the process—condensing REST best practices and conventions into just the high points with not a lot of discussion. REST is more a collection of principles than it is a set of standards. Other than its over-arching six constraints nothing is dictated. There are "best practices" and de-facto standards but those are constantly evolving—with religious battles waging continuously. Designed to be brief, this document provides recommendations and some cookbook-style discussion on many of the common questions around REST and provides some short background information to offer support for effective creation of real-world, production-ready, consistent RESTful services. This document aggregates information available in other sources, adapting it with experience gained through hard knocks. There is still considerable debate as to whether REST is better than SOAP (and vice versa), and perhaps there are still reasons to create SOAP services. While touching on SOAP, this document won't spend a lot of time discussing the relative merits. Instead, because technology and the industry marches on, we will proceed with the assumption that leveraging REST is the current best practice for Web service creation. The first section offers an overview of what REST is, its constraints, and what makes it unique. The second section supplies some quick tips as little reminders of REST service concepts. Later sections go more in depth to provide the Web
Restful服务
c851204293的博客
09-24 225
Http请求主要关注两点： 请求方法POST和GET； 数据格式JSON和www-form-urlencoded； 一、请求方法 GET 方法 请注意，查询字符串（名称/值对）是在 GET 请求的 URL 中发送的： /test/demo_form.asp?name1=value1&name2=value2 有关 GET 请求的其他一些注释： GET 请求可被缓存 GET 请求保留在浏览器历史记录中 GET 请求可被收藏为书签 GET 请求不应在处理敏感数据时使用 GET 请求
分布式软件架构——RESTful服务
四问四不知的博客
06-11 1961
摘抄自极客学院 ——《周志明的软件架构课》
JEESZ RestFul服务介绍
civtsbiqr522632413的博客
08-03 106
摘要: RESTful Web 服务的关键特点是明确使用 HTTP 方法来表示不同的操作的调用。 REST 的基本设计... 1. REST介绍 REpresentational State Tra...
restful介绍_RESTful服务介绍！
weixin_26737625的博客
09-08 412
restful介绍Understanding RESTful Web Services is key for any software engineer today. 对于当今的任何软件工程师而言，了解RESTful Web服务都是关键。 Representational state transfer is a software architectural style that defines ...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值