我们制定的 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的更多相关文章

  1. 一个完整的Node.js RESTful API

    前言 这篇文章算是对Building APIs with Node.js这本书的一个总结.用Node.js写接口对我来说是很有用的,比如在项目初始阶段,可以快速的模拟网络请求.正因为它用js写的,跟i ...

  2. 人人都是 API 设计师:我对 RESTful API、GraphQL、RPC API 的思考

    原文地址:梁桂钊的博客 博客地址:http://blog.720ui.com 欢迎关注公众号:「服务端思维」.一群同频者,一起成长,一起精进,打破认知的局限性. 有一段时间没怎么写文章了,今天提笔写一 ...

  3. PHPer的项目RESTful API设计规范是怎样的?

    RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 什么是RESTful RESTful是一种软件设计风格, 主要用于客户端与服务端交互的软件. 一般来说RESTful ...

  4. 基于轻量型Web服务器Raspkate的RESTful API的实现

    在上一篇文章中,我们已经了解了Raspkate这一轻量型Web服务器,今天,我们再一起了解下如何基于Raspkate实现简单的RESTful API. 模块 首先让我们了解一下"模块&quo ...

  5. Web服务器Raspkate的RESTful API

    基于轻量型Web服务器Raspkate的RESTful API的实现 在上一篇文章中,我们已经了解了Raspkate这一轻量型Web服务器,今天,我们再一起了解下如何基于Raspkate实现简单的RE ...

  6. Swagger RESTful API文档规范

    *注意编写的关键词:“必须”.“不能”.“需要”.“应当”,“不得”.“应该”.“不应该”,“推荐”.“可能”和“可选的” 原文链接:http://swagger.io/specification/ ...

  7. Spring Boot中使用Swagger2构建强大的RESTful API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  8. 什么是RESTful API?

    要弄清楚什么是RESTful API,首先要弄清楚什么是REST.REST -- REpresentational State Transfer,英语的直译就是"表现层状态转移". ...

  9. Java 调用Restful API接口的几种方式--HTTPS

    摘要:最近有一个需求,为客户提供一些Restful API 接口,QA使用postman进行测试,但是postman的测试接口与java调用的相似但并不相同,于是想自己写一个程序去测试Restful ...

随机推荐

  1. web安全之跨站脚本漏洞(XSS)

    XSS(跨站脚本)概述以及pikachu上的实验操作 Cross-Site Scripting 简称为“CSS”,为避免与前端叠成样式表的缩写"CSS"冲突,故又称XSS. XSS ...

  2. 为什么 group by后面 必须跟selecte 后面的除了聚集函数外的所有字段

    如:SELECT store_name, SUM(Sales) FROM Store_Information GROUP BY store_name 可以而SELECT store_name, add ...

  3. Nginx使用upstream实现负载均衡

    如果Nginx没有仅仅只能代理一台服务器的话,那它也不可能像今天这么火,Nginx可以配置代理多台服务器,当一台服务器宕机之后,仍能保持系统可用.具体配置过程如下: 1. 在http节点下,添加ups ...

  4. spring bean post processor

    相关文章 Spring 整体架构 编译Spring5.2.0源码 Spring-资源加载 Spring 容器的初始化 Spring-AliasRegistry Spring 获取单例流程(一) Spr ...

  5. 浅谈bfs

    广搜(bfs) 定义 广度优先算法,简称BFS.是一种图形搜索演算法,简单的说,BFS是从根节点开始,沿着树的宽度遍历树的节点,如果发现目标,终止. 与dfs的相似之处与不同 结合深搜理解 相同点:都 ...

  6. PDF无法复制/打印/编辑怎么办?

    PDF的内容不能复制/打印/编辑,主要有两种原因: 1.PDF文件设置了权限保护 2.PDF内容是图片 第一种,PDF被设置了权限保护 这种的特点是可以选中PDF里的文字,但无法复制 PDF格式标准内 ...

  7. String为什么要设置成Final类型

    ---今天面试碰到个这样的问题:String在设计的时候为什么要设计成final的  当时回答的是String功能已经很丰富了,不需要对其进行扩展,所有巴拉巴拉. 现在来正确看看为什么定义成final ...

  8. css伪选择器使用总结——css中关于伪类和伪元素的知识总汇

    CSS 伪类用于向某些选择器添加特殊的效果,而CSS引入伪类和伪元素的概念是为了实现基于文档树之外的信息的格式化.这里讲总结关于css伪类和伪元素的相关使用 伪元素 :before/:before 在 ...

  9. 前端老司机常用的方法CSS如何清除浮动?清除浮动的几种方式

    在前端开发过程中,我们经常会使用到浮动(float),这个我们即爱又恨的属性.爱,是因为通过浮动,我们能很方便地进行布局:恨,是因为浮动之后遗留下来太多的问题需要解决.下面本篇文章给大家介绍CSS清除 ...

  10. 理解并使用CSS3中的单位rem vh vw vmin vmax

    rem vh vw vmin vmax做为CSS3中的新单位,其实都出来挺久的了,这篇文章将总结并理解下它们. rem 如果你给body设置了font-size字体大小,那么body的任何子元素的1e ...