[case20]聊聊rest api设计

序

本文主要研究下rest api的设计。

设计准则

• easy to use & hard to misuse

易用不易误用，也就是api设计不要太复杂，要简单易用，并且还不能容易用错。

• least astonishment

简单就好，不要试图提供其余花哨、华丽的额外功能，好比对于时间相似的字符串参数，规定好一个输入格式便可，不要试图同时兼容多种格式输入。

• use case & document story

api文档要围绕story或者use case来进行，在一个业务场景下提供完整的闭环操做。

输入规范

• url中的路径

避免驼峰，避免下划线，优先采用横杠

• request method

post表示新增( url中没有id)，delete表示删除，get表示查询，put表示全量更新( 幂等操做)，post url中携带id也可用于表示更新。

• 分页

好比page及size，或者limit及offset

• 排序

好比sort=+field2,-field2，用逗号分隔多个排序字段，用+表示升序，用-表示降序

• 字段过滤

好比fields=field1,field2,field3

• 复杂查询

简单的好比用eq表明等，lt表明小于，lte表明小于等于，gt表明大于，gte表明大于等于，like表明模糊查询；更复杂的话，能够参考rsql规范。

• 版本

不建议版本化，建议采用新的领域命名才与原有的api区分开来

输出规范

• 返回码

遵循http的返回码规范，4xx表示客户端错误，5xx表示服务端错误。

• 返回jsonObject而不是jsonArray

顶层结构返回jsonArray的话，就不容易扩展了。通常返回jsonObject，一般会携带code，error之类的

• 返回jsonObject的字段

success表示请求是否成功，data表示数据，msg表示消息描述，error描述错误信息详情。

• 错误信息格式

type表示错误异常类型，code表示错误编号用于个性化错误提示，msg用于错误信息描述，link提供该错误信息的具体描述页面

安全相关

• 调用方鉴权

对于api的消费者，要求调用的时候强制提供appId及appKey，用于最基本的调用源的鉴权

• 细粒度鉴权

对于更细粒度的数据权限控制，要细化到url及requestMethod基本

• 参数校验

对于查询、修改等参数要作基本校验，对参数内容进行非法参数过滤。

• 屏蔽错误堆栈

不要暴露后端的错误堆栈，若是是要方便排查问题，能够设置一个开关，来设置是否屏蔽错误堆栈

• 敏感数据脱敏

对于敏感的数据，要适当作一些脱敏处理，好比身份证号，手机号等。在真正须要真实数据的话，须要额外进行请求。

• 帐号密码须要加密

登录接口必须走https，并且必需要有图形验证码，并且还必须防暴力破解，有错误锁定机制，对于密码的传递，必须加密处理

• 防止id遍历问题

对于url的参数，若是id是递增的，则须要处理遍历问题，要么对外暴露通过处理后的id，要么作数据权限控制

• 防止token replay

对于token要有必定的失效机制，另外建议token对url参数进行签名

• 防止文件下载目录遍历

对于提供文件下载的接口，必定要避免目录遍历问题

服务质量保障

• 提供SLA
• 提供流量管理、熔断、限流
• 提供服务扩容机制
• 提供故障演练
• 提供审计功能
• 监控异常流量
• 提供调用方间的隔离

小结

rest api的设计牵扯的方面比较多，本文暂时只是先列了一些，后续有待补充。

doc

• API设计要点
• 聊聊jpa的动态查询
• 使用RSQL实现端到端的动态查询