微服务RESTful 接口设计规范
1、RESTful发展背景及简介
网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......)。因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。
REST(Representational State Transfer)表述性状态转换,REST指的是一组架构约束条件和原则。 如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。REST本身并没有创造新的技术、组件或服务,而隐藏在RESTful背后的理念就是使用Web的现有特征和能力, 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深, 但是理论上REST架构风格并不是绑定在HTTP上,只不过目前HTTP是唯一与REST相关的实例。
2、RESTful设计风格
2.1、推荐格式
1)url格式:
http(s)://server.com/api-name/{version}/{domain}/{rest-convention}{version}代表api的版本信息。{domain}是一个你可以用来定义任何技术的区域(例如:安全-允许指定的用户可以访问这个区域。)或者业务上的区域(例如:同样的功能在同一个前缀之下)。{rest-convention} 代表这个域(domain)下,约定的rest接口集合。
2)参数格式:
GET采用两种常见格式:
① URL参数(更推荐),如:
https://www.example.com/v1.1?name=‘lk-abc%’&age=’lt-10’
②路径参数,如:
https://www.example.com/v1.1/employees/{id}
POST采用两种常见格式:
①Json格式包装参数提交
POST https://www.example.com/v1.1Content-Type: application/json;charset=utf-8{"title":"test","sub":[1,2,3]}
②form表单参数提交
POST https://www.example.com/v1.1Content-Type: application/x-www-form-urlencoded;charset=utf-8title=test&sub%5B%5D=1&sub%5B%5D=2&sub%5B%5D=3
3)返回体格式:
{ "status": 200, "message":"用户查询返回成功","document":”https://www.example.com/doc#userinfo","data": {"className": "com.fiberhome.smartas.pricecloud.User","id":"1b434wtert564564sdffey32","name": "lilei","age": 18,"job": {"className”:"com.fiberhome.smartas.pricecloud.Job","id": "1b434wtert564564sdffeyey","name": "微服务架构师"}}}
2.2、协议
考虑到服务的安全性,建议使用https作为API的通信协议,当然http也是可以的。
2.3、域名
建议将API部署在专有域名下,以此屏蔽消费者对服务提供方的部署细节(可借助于平台的反向代理+路由网关),在服务地图丰富起来之后可以考虑多级域名。
https://api.example.com https://example.org/api/
2.4、版本
考虑到微服务的平滑升级,可以将API的版本号放入URL,也可以将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。
https://api.example.com/v1/
2.5、复数名词路径
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
https://api.example.com/v1/employees
2.6、http协议类型表达资源操作
HTTP协议里的8种方法,及其他衍生方法,常用的Get、post可以间接的实现其余所有的操作,根据框架和浏览器的兼容性选择性使用。
1) GET(SELECT) :从服务器取出资源(一项或多项)。 2) POST(CREATE) :在服务器新建一个资源。 3) PUT(UPDATE) :在服务器更新资源(客户端提供改变后的完整资源)。 4) PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。 5) DELETE(DELETE):从服务器删除资源 6) HEAD:获取资源的元数据。 7) OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。 8) TRACE:回显服务器收到的请求,主要用于测试或诊断。 9) CONNECT:HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。 10) MOVE: 请求服务器将指定的页面移至另一个网络地址。 11) COPY: 请求服务器将指定的页面拷贝至另一个网络地址。 12) LINK: 请求服务器建立链接关系。 13) UNLINK: 断开链接关系。 14) WRAPPED: 允许客户端发送经过封装的请求。 15) Extension-mothed:在不改动协议的前提下,可增加另外的方法。 例:
GET https://api.example.com/v1/employees/ 获取所有雇员
2.7、过滤信息
请求信息应该为集合提供过滤、排序、选择和分页等功能
1)Filtering过滤:
使用唯一的查询参数进行过滤:
GET /cars?color=red 返回红色的cars
2)Sorting排序:
允许针对多个字段排序
GET /cars?sort=-manufactorer,+model #这是返回根据生产者降序和模型升序排列的car集合
3)Fieldselection
移动端能够显示其中一些字段,它们其实不需要一个资源的所有字段,给API消费者一个选择字段的能力,这会降低网络流量,提高API可用性。
GET /cars?fields=manufacturer,model,id,color
4)Paging分页
使用 limit 和offset.实现分页,缺省limit=20 和offset=0;
GET /cars?offset=10&limit=5
为了将总数发给客户端,使用订制的HTTP头:X-Total-Count.
链接到下一页或上一页可以在HTTP头的link规定,遵循Link规定:
Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>;rel="next",<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>;rel="last",<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>;rel="first",<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>;rel="prev",
2.8、返回结果为统一的json格式
一方面,出于平台标准化的API管理,另一方面,遵循微服务的宽进严出设计理念,建议RESTful采用标准的Json格式。
返回结构体:
{ "className": "com.fiberhome.smartas.pricecloud.User","id":"1b434wtert564564sdffey32","name": "lilei","age": 18,"job": {"className":"com.fiberhome.smartas.pricecloud.Job","id": "1b434wtert564564sdffeyey","name": "微服务架构师"}}
2.9、返回结果应该包含状态码
常见状态码,Http1.1协议完整状态码定义参考地址:
1) 200 OK [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)2) 201 CREATED [POST/PUT/PATCH]:用户新建或修改数据成功3) 202 Accepted [*]:表示一个请求已经进入后台排队(异步任务)4) 204 NO CONTENT [DELETE]:用户删除数据成功5) 400 INVALID REQUEST [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的6) 401 Unauthorized [*]:表示用户没有权限(令牌、用户名、密码错误)7) 403 Forbidden [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的8) 404 NOT FOUND [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的9) 406 Not Acceptable [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)10) 410Gone [GET]:用户请求的资源被永久删除,且不会再得到的11) 422Unprocesable entity [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误12) 500INTERNAL SERVER ERROR [*]:服务器发生错误,用户将无法判断发出的请求是否成功
2.10、返回结果中提供帮助链接
RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。注:Github就是这么做的
返回体结构:
{"link": {"document":" https://www.example.com/docs#zoos","href":"https://api.example.com/zoos","title":"List of zoos","type":"application/vnd.yourformat+json"}}
2.11、API扩展事项
1)RESTful API依托PaaS平台治理,需要对API进行认证、授权、参数加密等操作,可考虑在HTTP头部加认证token、调用链指令、状态信息等系列信息。
2)如PPT所言,API分层,会有内部API和外部API之分,两种API的设计或有不同(甚至是不同协议)。
3)对于API设计的状态选择,建议为无状态、N次幂等,但后续或存在性能优化问题,http2.0待评测。
转载于:https://www.cnblogs.com/mzhaox/p/11212568.html
微服务RESTful 接口设计规范相关推荐
- RESTful接口设计规范
RESTful接口设计规范 个人博客:RESTful接口设计规范 协议:API与用户的通信协议,尽量使用HTTPS 域名:尽量将API部署在专用域名下,如https://api.example.com ...
- Day210.服务端渲染技术NUXT、整合前台主页面、名师、课程静态页面、首页整合banner数据后端部分【创建banner微服务、接口、banner后台前端实现】 -谷粒学院
谷粒学院 服务端渲染技术NUXT 一.服务端渲染技术NUXT 1.什么是服务端渲染 服务端渲染又称SSR (Server Side Render)是在服务端完成页面的内容,而不是在客户端通过AJAX获 ...
- 多个微服务的接口依赖如何测试_微服务测试之接口测试和契约测试
日常开发过程中,项目的接口通常由服务提供方约定和提供,微服务模式下接口被多个消费者调用更是常态,那么提供方接口的变更如何快速.高效.无遗漏的通知给消费者呢?另外,当一个service同时被多个使用者调 ...
- restful接口设计规范学习
1.接口编程 1 背景 随着互联网的发展, 尤其是移动互联为代表的Web3.0时代. 客户端层出不穷, 以APP.微信.PC浏览器为代表, 服务端业务逻辑是基本一致的.那么有没有一种方式可以做到&qu ...
- 微服务架构 接口交互问题_架构师的故事:设计微服务架构
架构师在软件项目中的作用是提供待解决问题的工作模型.架构师的工作是提供脚手架,开发人员将根据这些脚手架构建他们的代码,使应用程序所有部件都组合在一起. 在构建微服务架构时,项目的架构师主要关注以下3个 ...
- 微服务(接口)设计原则
文章目录 1.前言 2.高可用 2.1 降级兜底 2.2 过载保护(保护自己) 2.3 流量控制(保护下游) 2.4 快速失败 2.5 无状态服务 2.6 最少依赖 2.7 简单可靠 2.8 分散原则 ...
- 如何使用增强版swagger(通过网关端口看对应各个微服务的接口文档)
文章目录 配置 网关配置 SwaggerHandler.class SwaggerResourceConfig.class 公共配置 SwaggerConfig.class 使用 演示 增强版swag ...
- feignclient注解使用_从 Feign 使用注意点到 RESTFUL 接口设计规范
最近项目中大量使用了Spring Cloud Feign来对接http接口,踩了不少坑,也产生了一些对RESTFUL接口设计的想法,特此一篇记录下. SpringMVC的请求参数绑定机制 了解Feig ...
- 基于工程经验的『RESTful接口设计规范』
前言 这篇文章,主要想总结自己在设计RESTful API的一系列经验于思考. 有些规范可能与标准规范有所出入,但是所有的考量都是基于『减少重复工作,增加可读性可维护性』而出发的.话说回来,我一直觉得 ...
最新文章
- 奇葩错误 -- modelsim波形显示no data(全X)
- linux proc
- virtualBox 创建新虚拟机
- c语言字符串替换有大小写,(C语言)字符串大小写无关查找替换
- MFC中CString.Format的用法
- 百度免费开放长语音识别功能
- VC++动态链接库(DLL)编程(六)――DLL***
- lf 前后端分离 (5) 优惠券
- 维护通讯录的方法及群组通讯录 管理平台
- TextBox显示提示信息
- 【无标题】半导体器件特性曲线测试方法的研究
- 微信公众号H5开发——JSSDK调用微信接口
- Microsoft Office XP 中为开发人员新增的功能
- 爬虫:获取OLD的Oxford 3000 and 5000
- 小,大:使用CSS fit-content
- 两个不同包里有相同的类
- 直播预告更新 | 火爆全网的ChatGPT为什么这么强?
- JavaScript面试精讲(六)——说说你经常使用到的array方法
- 单总线编程介绍(用于DS18B20)
- oracle 数据转换不报错,oracle数据库与hibernate方言转型异常