1.rest是什么
rest的中文意思是表征性状态转移
在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，来得到一个功能强，性能好，适宜通信的架构。REST即是一个架构的约束条件和原则
2.理解rest
rest这种理念，基本都是通过HTTP来实现的，自己平时写web路由层时会参考，所以也使用http相关的例子来加深自己的理解
3. URL设计优化
1.一般来说，URL会使用/来表示层级关系，gin-gonic为一级目录，gin为该目录下的一个仓库
https://github.com/gin-gonic
https://github.com/gin-gonic/gin
2.若其中一个层级的字数较多，则尽量使用_或-来加深URL的可读性
http://www.oschina.net/news/38119/oschina-translate-reward-plan
3.使用.或;来表示同级资源的关系,在git中，比较两个版本的不同会使用如下格式的URL，在对应的web路由层能够解析到这两个参数
4.若API版本变化比较大，那么加上版本是一个很好的做法
5.统一资源接口
这个不难想象，例如，数据库操作一类/db，静态文件一类/static，也可以根据业务区分，例如，用户管理一类/user等等
资源分为单个文档和集合，尽量使用复数来表示资源，单个资源通过添加 id 或者 name 等来表示
http://...../getfile
http://...../getfile?id=1
6.使用正确的method
| method | 描述 |
|---|---|
| HEAD | 只获取某个资源的头部信息，比如只想了解某个文件的部分信息(文件大小，修改时间等) |
| GET | 获取资源 |
| POST | 创建资源 |
| PATCH | 更新部分资源 |
| PUT | 整体替换资源 |
| DELECT | 删除资源 |
7.让数据库查询更加自由
在进行一些数据库sql查询的时候(推荐使用get)，可以通过一些参数来使sql更加灵活自由
- state：open，closed，all
- since：查询指定时间之前或者指定时间之后的记录
- sort：指定排序的字段
- direction：排序的方向，升序ASC，降序DESC
- page：分页查询时指定页数
- pageSize：分页时每页显示的条数
- ....
8.选择合适的状态码，参考https://httpstatuses.com/
| 状态码 | 解释 |
|---|---|
| 200 | 请求成功接收并处理，一般响应中都会有 body |
| 201 | 请求已完成，并导致了一个或者多个资源被创建，最常用在 POST 创建资源的时候 |
| 202 | 请求已经接收并开始处理，但是处理还没有完成。一般用在异步处理的情况，响应 body 中应该告诉客户端去哪里查看任务的状态 |
| 204 | 请求已经处理完成，但是没有信息要返回，经常用在 PUT 更新资源的时候（客户端提供资源的所有属性，因此不需要服务端返回）。如果有重要的 metadata，可以放到头部返回 |
| 400 | 客户端发送的请求有错误（请求语法错误，body 数据格式有误，body 缺少必须的字段等），导致服务端无法处理 |
| 401 | 请求的资源需要认证，客户端没有提供认证信息或者认证信息不正确 |
| 403 | 服务端接收到并理解客户端的请求，但是客户端的权限不足，比如普通用户访问管理员权限的数据 |
| 404 | 客户端想要访问的资源不存在，链接失效或者客户端伪造URL的时候返回 |
| 405 | 服务端接收到请求，资源也存在，但不知道该访问方式 |
| 415 | 服务端不支持的客户端请求资源格式，一般是服务端要求content-type/content-encoding中的格式和客户端传输的不符 |
| 429 | 客户端在规定时间内请求次数过多，在进行访问限制时会用到 |
| 500 | 服务器内部错误，无法完成请求内容 |
| 503 | 服务器负荷过高或者维护，暂时无法提供服务，服务端应该返回Retry-After 头部，告诉客户端过一段时间再来重试 |
9.返回详细的错误信息
例如，客户端请求时发生错误，一般会返回4XX的错误code，但这个结果还是非常模糊，给出错误信息，能够让客户端快速定位问题，解决问题
10.验证和授权
一般接触到的api都涉及一定量的隐私数据，需要一定的权限来访问，例如，登陆后才能查看个人的资产，拥有管理员权限才可以查看后台的所有数据等等
例如用户登陆时，在验证用户名和密码时没有通过验证，则返回401，并相应的返回错误信息
若用户在登录后，查询某部分管理员数据后，出现权限不足的情况，则返回403，并相应的返回权限不足的错误信息
- 需要注意的时，一些特殊的隐私URL，为了防止泄漏，在一些自动化试探用户的私有资源时，应该返回404，而不是返回403，返回403会暴露这些私有的URL资源
11.限流
常见的web服务都会用限流的措施，目的是防止滥用以及DDos攻击，在区块链中较为常见(因区块链处理单笔交易的速度有限，所以很容易造成区块链链上拥堵，引发区块链无法进行正常的业务)
在github中，普遍采用三个相关的头部，来传递限流的具体信息(可在单独一个方法中实现getRateLimit，也可在限流的请求接口中实现)
- X-RateLimit-Limit：用户在指定时间内允许发送请求的最大值
- X-RateLimit-Remaining：当前时间窗口剩下可用的请求数目
- X-RateLimit-Rest：时间窗口重制的时候
对于超过流量的访问，一般返回429状态码too many request
12.Hypermedia API
在返回的结果中提供相关资源的链接
这种做法在前端/app端和后台进行资源交互时，比较常见，后端返回图片的URL，前端/app通过获取到的URL来加载资源，这样，在需要修改图片资源URL时，只需在后台修改即可，不需要前端/app端重新修改，可做到动态修改的目的
13.编写优秀的API文档
API文档非常关键，也非常比较，编写API文档时，需要做到信息的完整展示，API请求数据格式，相应数据格式，会出现的错误，限制条件，前提条件等等
良好的文档可以避免在开发中遇到的很多问题，前后端程序员之间的交流很大程度上也需要依靠api文档，总不能每写一个接口，都跑到你的座位上来问你一堆问题吧
参考自
网友评论