我们制定的 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. Springboot在包含有参构造方法的类中使用@Value注解取值

    我们在Springboot中经常使用@Value注解来获取配置文件中的值,像下面这样 @Component class A { @Value("${user.value}") pr ...

  2. Java内置定时器Timer

    Timer是Java内置的一个定时任务,类似于JavaScript里面的setTimeout()和setInterval()方法,可以延迟一定的时间执行任务,也可以按时间间隔重复执行任务. Timer ...

  3. 【Xamarin.Forms 1】App的创建与运行

    引言 本篇文章将从介绍Xamarin.Forms创建开始. 开发环境 Visual Studio 2019 16.6.2 Xamarin.Forms 4.6.0.726 Android 5.0 (AP ...

  4. 一.2.序列化使用之用户资源功能app

    1.环境准备:(1).新建功能app: (python36env) [vagrant@CentOS7 devops]$ python manage.py startapp users ---建议以后用 ...

  5. 宿主机ping不通虚拟机,虚拟机能ping通宿主机问题

    打开虚拟机管理器,点开设置=>网络,网络选的是NAT,所以宿主机不能直接ping能虚拟机!!! 问题描述 查看虚拟机ip,  #ifconfig如下图: 宿主机ping虚拟机ip,无法通信,如下 ...

  6. For setting NODE_ENV you can use any of these methods.

    method 1: set NODE_ENV for all node apps Windows: set NODE_ENV=production Linux or other Unix based ...

  7. 每日一题 - 剑指 Offer 48. 最长不含重复字符的子字符串

    题目信息 时间: 2019-07-02 题目链接:Leetcode tag: 动态规划 哈希表 难易程度:中等 题目描述: 请从字符串中找出一个最长的不包含重复字符的子字符串,计算该最长子字符串的长度 ...

  8. linux新用户(组)的那些事

    linux新用户(组)的那些事   创建新用户 groupadd bigdata //添加新用户组bigdata useradd -g bigdata es //-g:为用户组添加新用户 passwd ...

  9. 「疫期集训day13」雾天

    我们千里迢迢赶来这里支援协约国----与德军正面交锋的美国士兵 今天考试签到题都没A,失误重大,T1几周前做过的拓扑排序板子都没写,T2失误在没敢调试,对自己信心不足,30分钟写了个DP,几分钟没调出 ...

  10. python入门008

    目录 一.for循环 作用:for循环是因为在循环取值(即遍历值)时for循环比while循环的使用更为简洁 1.for循环语法: 2.应用案例: 注意:break 与 continue也可以用于fo ...