借鉴一个比较标准的后端RESTful API
我们制定的 API 规范,使用了微服务架构所以做了一些改进,我们更偏向使用 http code 标识,不然需要自己处理成功或失败的逻辑,在 200 内再包一层显得啰嗦;并且微服务系列都不支持,Feign,监控等都需要自己改造。
当逻辑错误时,返回 http code 400,body 体内是具体的错误原因,也可以加上自定义的状态码,解决了 http code 不能满足业务状态的需求
### 接口命名规范
**前端对接时如果发现后端提供的接口不符合规范有权拒接(包括后端对接爬虫),如接入了不符合规范的接口,需要及时整改**
为了便于管理接口,我们将接口分为三类:
1. `public`: 不用登录即可访问的资源,举例:登录接口 `https://api.buffdj.com/public/quick_login`
2. `api`: 需要用户登录才能进行访问的接口,举例:获取用户详细信息接口: `https://api.buffdj.com/api/user/info?id=666`
3. `rpc`: 微服务之间相互调用才能用的,外部不允许访问.举例: 调用pay 微服务的 pay 接口:`https://api.buffdj.com/rpc/service-pay/pay?param=666`
### Restful 风格的 API
1. `get`:用于获取资源
2. `post`:用于提交新增一个资源
3. `put`:用于修改一个资源
4. `delete`:用于删除一个资源
**所有 API 返回值都必须是 application/json 形式,不允许字符串格式的返回值**
详细可参考 :[如何向其他人解释Restful](http://www.jianshu.com/p/e77d2f60aa5d)
我们的接口规范如下:
1. 获取书籍列表: `GET /api/book?size=10&page=1` size 和 page为分页参数
2. 获取书籍详情: `GET /api/book/info?id=666` id 为要查询的资源`主键`
3. 修改书籍信息: `PUT /api/book ` body里边放更新依据`主键 id`,以及其他参数
4. 新增数据资源: `POST /api/book ` body里放主键之外的参数
5. 删除书籍资源: `DELETE /api/book?id=666` id 为要删除的资源`主键`
不使用 PathVariable 的原因是由于 Spring Could 系列的监控、追踪等软件还不兼容,会认为 GET /api/book/1, GET /api/book/2 是不同的 URL,所以我们不使用它
ps:
1. 不要在路径里使用动词如: getXXX,queryXXX,findXXX,只需资源的名字即可,比如:获取书籍封面`GET /api/book/cover`,因为请求方法`GET` 就已经表明当前是获取资源而不是增加或者删除
2. 路径统一使用小写字母,多个单词使用`_`分割
### Response Body 状态码规范
便于交流和协作,我们统一使用 HTTP 标准的状态码
* 200:本次请求成功,服务器已返回正确的数据在 body 里
* 4XX:出现业务逻辑异常或错误,包括:路径错误,参数错误,具体信息会在response body 中展示
* 5XX:这个是服务器出现了一些意料之外的错误
**找不到数据,查询数据结果为空的时候,需要返回404**
状态码4xx,具体的Response Body 数据结构
```
{
"timestamp": 1512611487539,
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.web.bind.MethodArgumentNotValidException",
"message": "Validation failed for object='person'. Error count: 1"
}
```
### 关于控制前端弹出信息相关规范
控制前端弹出信息统一放在 Response Header 中
```
X-dialog-message: \u6d88\u606f\u63d0\u793a
X-dialog-type: warning
```
`X-dialog-message` 这个message 是后端根据该用户的语言返回对应的提示信息的 **Unicode 编码** ,因为 header 中不能存放中文
`X-dialog-type` 目前只有warning 和 error 类型,纯展示,后续根据产品需要可以扩充更多类型
### 网关与其他微服务之间一些约定
#### Header 中存放了一些用户的基本信息
`X-user-id` 根据前端传递的 token 解析出来的 userId 放在 header中的这个字段里传递给其他微服务,其他微服务通过 HttpServletRequest.header 来获取
`X-user-nickname` 获取用户昵称
`X-user-phone` 获取用户手机号码,如果有的话
`X-user-photo` 获取用户头像
`X-user-account` 获取用户账号,手机号码或者邮箱
ps: Java 可直接通过 duiker 提供的 **HttpUtils** 中提供的方法获取用户基本信息
借鉴一个比较标准的后端RESTful API的更多相关文章
- 一个完整的Node.js RESTful API
前言 这篇文章算是对Building APIs with Node.js这本书的一个总结.用Node.js写接口对我来说是很有用的,比如在项目初始阶段,可以快速的模拟网络请求.正因为它用js写的,跟i ...
- 人人都是 API 设计师:我对 RESTful API、GraphQL、RPC API 的思考
原文地址:梁桂钊的博客 博客地址:http://blog.720ui.com 欢迎关注公众号:「服务端思维」.一群同频者,一起成长,一起精进,打破认知的局限性. 有一段时间没怎么写文章了,今天提笔写一 ...
- PHPer的项目RESTful API设计规范是怎样的?
RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 什么是RESTful RESTful是一种软件设计风格, 主要用于客户端与服务端交互的软件. 一般来说RESTful ...
- 基于轻量型Web服务器Raspkate的RESTful API的实现
在上一篇文章中,我们已经了解了Raspkate这一轻量型Web服务器,今天,我们再一起了解下如何基于Raspkate实现简单的RESTful API. 模块 首先让我们了解一下"模块&quo ...
- Web服务器Raspkate的RESTful API
基于轻量型Web服务器Raspkate的RESTful API的实现 在上一篇文章中,我们已经了解了Raspkate这一轻量型Web服务器,今天,我们再一起了解下如何基于Raspkate实现简单的RE ...
- Swagger RESTful API文档规范
*注意编写的关键词:“必须”.“不能”.“需要”.“应当”,“不得”.“应该”.“不应该”,“推荐”.“可能”和“可选的” 原文链接:http://swagger.io/specification/ ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- 什么是RESTful API?
要弄清楚什么是RESTful API,首先要弄清楚什么是REST.REST -- REpresentational State Transfer,英语的直译就是"表现层状态转移". ...
- Java 调用Restful API接口的几种方式--HTTPS
摘要:最近有一个需求,为客户提供一些Restful API 接口,QA使用postman进行测试,但是postman的测试接口与java调用的相似但并不相同,于是想自己写一个程序去测试Restful ...
随机推荐
- CentOS 7 Nacos 集群搭建
环境 CentOS 7.4 MySQL 5.7 nacos-server-1.1.2 本次安装的软件全部在 /home/javateam 目录下. MySQL 安装 首先下载 rpm 安装包,地址:h ...
- Flutter开发初探
目前跨端开发比较热门的就是 React Native 和 Flutter 了,到底该选哪门技术似乎也快成了大前端圈的一个热门话题.对于web前端来说,基于web生态的 React Native 应该是 ...
- 前端开发神器Charles从入门到卸载
前言 本文将带大家学习使用前端开发神器-charles,从基本的下载安装到常见配置使用,为大家一一讲解. 一.花式夸奖Charles 截取 Http 和 Https 网络封包. 支持重发网络请求,方便 ...
- Spring Boot — 运行应用程序5种方式
1. 从IDE中的Run 按钮运行 你可以从IDE中运行Spring Boot应用, 就像一个简单的Java应用, 但是, 你首先需要导入项目. 导入步骤跟你的IDE和构建系统有关. 大多数IDEs能 ...
- STL初步学习(queue,deque)
4.queue queue就是队列,平时用得非常多.栈的操作是只能是先进先出,与栈不同,是先进后出,与之后的deque也有区别.个人感觉手写队列有点麻烦,有什么head和tail什么的,所以说 STL ...
- web前端开发入门全套学习方法路径,兼职在家做网站也能月入上万!
前端学习路径 1.WEB前端快速入门 在本阶段,我们需要掌握 HTML 与 CSS 基础,当然,也包含 H5 和 C3 的新特性.这个部分内容非常简单,而且非常容易掌握.相信你也更愿意学习这个部分,毕 ...
- Windows使用VNC远程连接Linux桌面系统
sudo yum -y install tigervnc-server #安装 su - your_user #切换用户 vncpasswd #设置密码 sudo cp /lib/systemd/s ...
- SELinux已经允许,为什么日志显示的仍然是denied?
从日志可以看到,SELinux的Mode已经修改位了permissive = 1,也就是允许模式,但它前面的日志仍然显示的是“denied".本来我还以为是自己哪里没弄好导致的这个问题,但访 ...
- vscode 配置 c++ 环境
vscode 配置 c++ 环境 参考的这篇bloghttps://blog.csdn.net/bat67/article/details/81268581 1.安装编译器.这里安装 codebloc ...
- Scrapy模拟登录赶集网
1.打开赶集网登录界面,先模拟登录并抓包,获得post请求的request参数 2. 我们只需构造出上面的参数传入formdata即可 参数分析: setcookie:为自动登录所传的值,不勾选时默认 ...