Api设计的一些见解

---

关于API之REST模式(REpresentational State Transfer)

REST是什么?REST只是一种API的一种设计模式，一种前后端约定的开发的通用准则。其主要目的是为了实现API的语义话，通俗的讲，当开发人员看到这个API，就能清晰的得知这个API所需要的资源，动作类型，以及服务层返回的状态。

• 看url就知道要什么

  • url定位资源
  • url中，使用名词表明目的，而不是动词
  • url中，使用路径参数作为关键性参数，而不是查询参数
  • 根据名称的单数/复数来确定返回，提交/返回是的结果集类型

• 看http method就知道干什么(增删改查)

  • get 获取资源，若是获取列表，建议增加分页查询参数，?start_index=0&count=10
  • post 创建，更新，
  • put 更新
  • delete 删除

• 看http status code就知道结果如何

  • 关于http的状态码

  • 通常情况下，Api返回的数据格式为json格式

  • 通常情况下，api返回的数据类型为

    {
        /**
            其中status是server返回的处理状态，
            方案一：0失败,1成功，可能还会有其他状态，内部定义就好
            方案二：直接用http的状态码来定义该code，
            个人还是偏向方案一，或者两者结合起来
        */
    
        status: code,
        data: {
            key: val,
        },
        //请求正确的情况下，可以忽略这个值。但是错误状态下，需要返回处理失败的原因
        msg: 'message',
    }
    

• REST模式的优点

  • 便于前后端分离：前后端分离的大背景下，后端一次开发皆可满足各个端的需求
  • 无状态：客户端的每次请求都需要包含服务端所需要的所有信息
  • 缓存：可缓存的单个请求，减少不必要的交互，提高性能
  • 分层系统：封装服务，引入中间层，限制了系统的复杂性，提高可拓展性
  • 统一性：方便接口的开发和维护

关于Api之网关设计

在API的设计之初，应做好API网关的架构管理。以便更好的开发和维护

• 版本控制：网关统一管理API版本，如*.com/api/v1.0/photos`
• 兼容处理：API版本原则上向下兼容
• 自动降级：当找不到v2.0的API时，server可匹配到其对应的低版本API，如v1.8甚至更低
• 报文包装：网关统一包装返回客户端的code,status，错误信息等报文信息
• 信息验证：网关统一校验token，权限等公用验证性逻辑
• 监控警告：可统计API的调用量，错误率，响应时间，调用方式等信息，辅助优化
• 拓展性：可根据实际业务需求开发更多的中间件，来拓展更多功能

关于API之前端调用

在前端调用方，配置中间层/过滤器来完成对API的监控，比如

• 封装一个API模块，可对API进行统一封装和管理
• 若系统存在权限/token认证，可对API模块配置统一的拦截器，统一加入认证参数或者变量
• 对API返回的报文进行统一过滤，若是没有权限等所需的统一处理，可在拦截器做统一拦截
• 可控制请求队列(比如：小程序重的请求并发不能大于10)