关于设计RestApi的规范建议

文章来源

• URI路径用名词替代动词

  • GET /articles/id: 获取指定文章信息
  • POST /articles/: 保存文章
  • PUT /articles/id 更新指定文章
  • DELETE /articles/id 删除指定文章
    之所以这样设计，是因为我们的HTTP请求方式已经包含了具体的行为（CRUD）

• 字段名用复数形式

  如上所示，路径/articles/ 我们用的是复数形式，这样我们就不必要针对单个查询再新增接口了

• 具有层级关系的数据查询：/articles/id/comments/

  例如我们想查指定文章下的评论情况，其实就应该按照如上建议进行层级分隔，表明评论是文章的子资源；其实对应到数据库中也应该是文章和评论 的1:n关系

• Http状态码和接口响应状态需要有范围内的对应

  • 400 参数异常
  • 401 用户未授权，一般是未登录或者说token无效
  • 403 访问受限，一般是用户身份异常，访问受限；亦或token权限不足
  • 404 文件资源或者接口不存在
  • 500 内部服务异常，一般这种都是兜底的异常捕获方式
    +502 网关异常 可能是ng层出现了问题
  • ……
    通常HttpStatus的状态标记都是为了请求监控，业务异常的判断大多数还是通过响应体内的status或者code等字段值标记，msg字段返回相应的错误信息

• 批量获取的接口需要考虑数据过滤、排序、分页等操作以减小对服务影响和接口响应时间

  例如: /articles?type=NEWS&sort=-time+likes&pageNo=1&pageSize=10，查询文章列表时，可以通过type=NEWS 来做类型过滤，也可以通过sort=-time+likes 表示按时间倒序，按点赞数升序，同时还可以通过pageNo=1&page=10来支持分页查询。当然，也并不是一个接口的限制条件越多越好，当在功能或页面有区分时，我们可以考虑做接口拆分，以免后端代码逻辑过于复杂。

• 控制安全访问

  这里的安全访问不单单指基于HTTPS协议的接口请求，同时还要求我们在做接口设计时需要考虑水平越权等超越用户访问权限的控制。

• 高频或数据变更频率低的接口加上缓存

  可以结合远程缓存+本地缓存，关于缓存一致性的问题又是另外一个话题了

• 如果是对接客户端的接口，需要考虑版本控制

  一般将/v1``/v2之类的前缀放在API开头去做接口版本区分