API Design

发表于 分类于 阅读次数： 本文字数： 1.9k 阅读时长 ≈ 2 分钟

目前业界常用的API风格

  • RESTful
  • RPC
  • GraphQL

RESTful API

Representational State Transfer - 表现层状态转移
REST是一种软件架构风格，是一组架构约束条件和原则
REST规范把所有内容都视为资源
REST是一种规范，而RESTful API则是满足这种规范的API接口

  • HTTP动词与REST风格CRUD对应关系

    HTTP方法 行为 URI 示例说明 是否安全 是否幂等
    GET 获取资源列表 /users 获取用户列表 是 是
    GET 获取一个具体资源 /users/admin 获取admin用户的详细信息 是 是
    POST 创建一个新的资源 /users 创建一个新用户 否 否
    PUT 以整体的方式更新一个资源 /users/admin 更新user为admin的用户 否 是
    DELETE 删除服务器上的一个资源 /users/admin 删除user为admin的用户 否 是 
    1
    2
    1. GET,PUT,POST操作的资源属性一致
    2. 资源进行状态/属性变更，要用PUT方法，POST方法用来创建或者批量删除

    • 核心特点

      1. 以资源resource为中心, 所有的东西都抽象称资源，所有的行为都应该是在资源上的CRUD操作
      2. 资源是有状态的，使用JSON/XML等在HTTP Body里表征资源的状态
      3. 客户端通过四个HTTP动词，对服务器资源进行操作, 实现“表现层状态转化”
      4. 无状态, 对于服务端的弹性扩容是很重要的

    • RESTful API 设计原则

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      # URI设计
        1. 资源名使用名词而不是动词,并且用名词复数表示
        2. URI结尾不包含/
        3. URI中不能出现下划线,必须使用中杠代替
        4. URI路径shying小写，不使用大写
        5. 避免层级过深的URI，超过2层的资源嵌套会很乱,建议其他资源转换为?参数

      # 安全性: 不会改变资源状态
      # 幂等性: 执行1次和执行N次，对资源状态改变的效果是等价的

      # API版本管理
        1. URL中 /v1/users
        2. HTTP Header中, Accept: version=1.0
        3. Form参数中, /users?version=v1

      # API命名:
        1. 驼峰命名法 serverAddress
        2. 蛇形命名法 server_address
        3. 脊柱命名法 server-address -- GitHub API 使用的脊柱命名

      # 统一分页/过滤/排序/搜索功能
        1. 分页: /users?offset=0&limit20
        2. 过滤: /users?fields=email,username,address
        3. 排序: /users?sort=age,desc
        4. 搜索:

      # 域名
        1. https://chyidl.com/api : 这种方式适合API不会有进一步扩展的情况
        2. https://storage.api.chyidl.com : chyidl.com域名下会新增另一个系统API

RPC API

RPC (Remote Procedure Call) 远程过程调用

  • RPC调用流程

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    1. Client 通过本地调用Client Stub --
    2. Client Stub将参数打包称一个消息，然后发送这个消息
    3. Client所在的OS将消息发送给Server
    4. Server端接收到消息后，将消息传递给Server Stub
    5. Server Stub将消息解包，得到参数
    6. Server Stub调用服务端的子程序，处理完后，最终结果按照相反的步骤返回给Client

    Stub: 负责调用参数和返回值的流化serialization、参数的打包和解包、以及网络层的通信.

    google gRPC
    Facebook Thrift

  • RESTful VS gRPC

    对比项 RESTful gRPC
    优点 1. REST更规范、更标准、更通用 无论那种语言都支持HTTP协议，可以对接外部很多系统 1. 屏蔽网络细节，调用远程接口像调用本地方法一样，调用简单、方便
    2. RESTful接口采用JSON作为数据通信格式，JSON格式可读性强 2. gRPC采用Protocol Buffer作为数据传输格式，效率高
    3. 客户端和服务端松耦合 3.gRPC基于HTTP/2协议标准，性能更高
    缺点 1.扩展性差，随着需求变化 1.Protobuf数据格式可读性差
    2.性能相对于gRPC偏低 2.gRPC不支持浏览器调用,调试不方便
    使用场景 1. 接口对外，需要接口规范易懂 1.消息密集型、对系统性能和延时要求比较高
    2.系统能要求不高 2.偏向内部的API
    3.提供API天生围绕资源、对象、管理展开 3.提供API很难进行资源、对象抽象