前后端完全分离之 API 设计

背景

API 就是开发者使用的界面。我的目标不仅是能用,而且好用,跨平台(PC, Android, IOS, etc...)使用。本文将详细介绍 API 的设计及异常处理,并将异常信息进行封装友好地反馈给前端.

上篇文章 前后端完全分离初探 只是讲了些宽泛的概念,接下来的文章将直接上干货,干货的源码会挂在 GitHub 上。

前后端完全分离后,前端和后端如何交互?答:通过双方协商好的API。

接下来我分享我自己设计的 API 接口,欢迎各位朋友指教。

API 设计理念

  1. 将涉及的实体抽象成资源,即按 id 访问资源,在 url 上做文章,以后再也不用为 url 起名字而苦恼了;

  2. 使用 HTTP 动词对资源进行 CRUD(增删改查):

    get -> 查, post -> 增, put -> 改, delete -> 删
  3. URL 命名规则,对于资源无法使用一个单数名词表示的情况,我使用中横线 - 连接

    • 资源采用名词命名,e.g:产品 -> product

    • 新增资源,e.g:新增产品 url -> /product, verb -> POST

    • 修改资源,e.g:修改产品 url -> /products/{id}, verb -> PUT

    • 资源详情,e.g:指定产品详情 url -> /products/{id}, verb -> GET

    • 删除资源,e.g:删除产品 url -> /products/{id}, verb -> DELETE

    • 资源列表,e.g:产品列表 url -> /products, verb -> GET

    • 资源关联关系,e.g:收藏产品 url -> /products/{id}/star, verb -> PUT

    • 资源关联关系,e.g:删除收藏产品 url -> /products/{id}/star, verb -> DELETE

目前我 API 的设计只涉及这两点,至于第三点 HATEOAS(Hypermedia As The Engine Of Application State) 那就由读者自己去选择了,

<!--more-->

项目地址

本文中只涉及了设计的理念,具体的实现请下载源码 rest-api,项目内写了比较详细的注释。

项目实战

实战将从业务场景出发,详细介绍如何使用 HTTP verb 对资源进行操作(状态转移),使用 JSON 返回结果(资源表述),并定义 JSON 的基础结构。

JSON 结构

requestParams:

{
}

responseBody:

{
  "meta": {
  },
  "data": {
  }
}

meta 中封装操作成功或失败的消息,data 中封装返回的具体数据。

当新建商品或更新产品时,相关属性封装在 JSON 中,通过 POST 或 PUT 发送。

{
  "name": "Apple Watch SPORT",
  "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
}

当用户对商品进行操作后,将得到响应结果。GET, POST, PUT 操作成功,返回如下结果

{
  "meta": {
    "code": 201,
    "message": "创建成功"
  },
  "data": {
    "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
    "name": "Apple Watch SPORT",
    "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
  }
}

DELETE 操作成功,返回如下结果

{
  "meta": {
    "code": 204,
    "message": "删除成功"
  }
}

业务场景一

电商网站的管理员对商品进行新增、编辑、删除、浏览的操作,暂时不考虑认证授权,只关注对商品的操作。

为了以后便于做分布式,所有资源 id(表主键)均采用 uuid。

新增商品
  1. url: /api/product

  2. method: POST

  3. requestParams:

    {
      "name": "Apple Watch SPORT",
      "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
    }
  4. responseBody

    {
      "meta": {
        "code": 201,
        "message": "创建成功"
      },
      "data": {
        "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
        "name": "Apple Watch SPORT",
        "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
      }
    }
编辑商品
  1. url: /api/products/{id}

  2. method: PUT

  3. requestParams:

    {
      "name": "iPhone 6",
      "description": "此次苹果发布会发布了iPhone 6与iPhone 6 Plus,搭载iOS 8,尺寸分别是4.7和5.5英寸。外观设计不再棱角分明,表层玻璃边有一个弧度向下延伸,与阳极氧化铝金属机身边框衔接。机身背部采用三段式设计。机身更薄,续航能力更强。"
    }
  4. responseBody

    {
      "meta": {
        "code": 200,
        "message": "修改成功"
      },
      "data": {
        "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
        "name": "iPhone 6",
        "description": "此次苹果发布会发布了iPhone 6与iPhone 6 Plus,搭载iOS 8,尺寸分别是4.7和5.5英寸。外观设计不再棱角分明,表层玻璃边有一个弧度向下延伸,与阳极氧化铝金属机身边框衔接。机身背部采用三段式设计。机身更薄,续航能力更强。"
      }
    }
删除商品
  1. url: /api/products/{id}

  2. method: DELETE

  3. responseBody

    {
      "meta": {
        "code": 204,
        "message": "删除成功"
      },
      "data": {}
    }
获取商品详情
  1. url: /api/products/{id}

  2. method: GET

  3. responseBody:

    //删除前
    
    {
      "meta": {
        "code": 200,
        "message": "查询成功"
      },
      "data": {
        "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
        "name": "Apple Watch SPORT",
        "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
      }
    }
    
    //删除后
    {
      "meta": {
        "code": 404,
        "message": "指定产品不存在"
      }
    }
获取商品列表(未分页)
  1. url: /api/products

  2. method: GET

  3. responseBody

    {
      "meta": {
        "code": 200,
        "message": "获取全部商品成功"
      },
      "data": [
        {
          "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
          "name": "Apple Watch SPORT",
          "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
        },
        {
          "id": "9db1992a-c342-4ff0-a2a4-aeb3dbfd93f6",
          "name": "Apple Watch SPORT",
          "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
        },
        {
          "id": "4481619b-45c5-4729-9539-f93bb01f10d8",
          "name": "Apple Watch SPORT",
          "description": "Sport 系列的表壳材料为轻巧的银色及深空灰色阳极氧化铝金属,强化 Ion-X 玻璃材质为显示屏提供保护。搭配高性能 Fluoroelastomer 表带,共有 5 款缤纷色彩。"
        }
      ]
    }

业务场景二

业务场景一中只涉及了单个资源的操作,但实际场景中还有些关联操作;如用户去电商网站浏览商品,并收藏了一些商品,之后又取消收藏了部分商品。

暂时不考虑用户认证授权,以后加了token后,用户信息可以从中获取。

收藏商品
  1. url: /api/products/{id}/star

  2. method: PUT

  3. responseBody

    {
      "meta": {
        "code": 200,
        "message": "收藏商品[5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9]成功"
      },
      "data": [
        {
          "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
          "name": "iPhone 6",
          "description": "此次苹果发布会发布了iPhone 6与iPhone 6 Plus,搭载iOS 8,尺寸分别是4.7和5.5英寸。外观设计不再棱角分明,表层玻璃边有一个弧度向下延伸,与阳极氧化铝金属机身边框衔接。机身背部采用三段式设计。机身更薄,续航能力更强。"
        }
      ]
    }
取消收藏商品
  1. url: /api/products/{id}/star

  2. method: DELETE

  3. responseBody

    {
      "meta": {
        "code": 200,
        "message": "删除收藏商品[5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9]成功"
      },
      "data": []
    }

自定义异常和异常处理

所有自定义异常继承 RuntimeException,在业务层抛出,统一在 Controller 层进行处理。

异常分为全局异常和局部异常,例如 http method unsupported (405),unauthorized (401),accessDenied (403),not found (404) 等属于全局异常。针对对独立业务的一些异常属于局部异常,例如产品编辑出错。

异常在 Controller 中进行处理,并封装成 json 返回给前端,封装后的数据如下,相关实现见源码

{
  "meta": {
    "code": 404,
    "message": "指定产品不存在"
  }
}
{
  "meta": {
    "code": 405,
    "message": "Request method 'POST' not supported"
  }
}

项目运行截图部分

本系列文章

  • 前后端完全分离初探

  • 前后端完全分离之API设计

  • 前后端完全分离之安全认证与授权-上

  • 前后端完全分离之安全认证与授权-下

  • 前后端完全分离之前端模块化开发

  • 前后端完全分离之前端路由系统

  • 前后端完全分离之后端面向服务的模块化开发

原文出自 前后端完全分离之API设计,欢迎转载,转载请注明出处。

阅读 22.8k

推荐阅读
arccode
用户专栏

积累技术,努力工作,坚持学习,认真生活。

55 人关注
3 篇文章
专栏主页