前后端完全分离之API设计

标签: Java Javascript Rest 架构 | 发表时间:2015-04-18 09:46 | 作者:
出处:http://arccode.net/

背景

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)那就由读者自己去选择了.

项目地址

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

项目实战

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

JSON结构

requestParams:

1     
2
{     
}

responseBody:

1     
2
3
4
5
6
{     
"meta": {
},
"data": {
}
}

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

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

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

当用户对商品进行操作后, 将得到响应结果,

GET, POST, PUT操作成功, 返回如下结果

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

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

1     
2
3
4
5
6
{     
"meta": {
"code": 204,
"message": "删除成功"
}
}

业务场景一

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

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

新增商品

1, url: /api/product

2, method: POST

3, requestParams:

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

4, responseBody

1     
2
3
4
5
6
7
8
9
10
11
{     
"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:

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

4, responseBody

1     
2
3
4
5
6
7
8
9
10
11
{     
"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

1     
2
3
4
5
6
7
{     
"meta": {
"code": 204,
"message": "删除成功"
},
"data": {}
}

获取商品详情

1, url: /api/products/{id}

2, method: GET

3, responseBody

删除前

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

删除后

1     
2
3
4
5
6
{     
"meta": {
"code": 404,
"message": "指定产品不存在"
}
}

获取商品列表(未分页)

1, url: /api/products

2, method: GET

3, responseBody

1     
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{     
"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

1     
2
3
4
5
6
7
8
9
10
11
12
13
{     
"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

1     
2
3
4
5
6
7
{     
"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返回给前端, 封装后的数据如下, 相关实现见 源码;

1     
2
3
4
5
6
{     
"meta": {
"code": 404,
"message": "指定产品不存在"
}
}
1     
2
3
4
5
6
{     
"meta": {
"code": 405,
"message": "Request method 'POST' not supported"
}
}

项目运行截图部分

本系列文章

  • 前后端完全分离初探
  • 前后端完全分离之API设计
  • 前后端完全分离之安全认证与授权-上
  • 前后端完全分离之安全认证与授权-下
  • 前后端完全分离之前端模块化开发
  • 前后端完全分离之前端路由系统
  • 前后端完全分离之后端面向服务的模块化开发

相关 [完全 api 设计] 推荐:

前后端完全分离之API设计

- - ITeye资讯频道
API就是开发者使用的界面. 我的目标不仅是能用,而且好用, 跨平台(PC, Android, IOS, etc…)使用:本文将详细介绍API的设计及异常处理,并将异常信息进行封装友好地反馈给前端. 上篇文章前后端完全分离初探只是讲了些宽泛的概念,接下来的文章将直接上干货,干货的源码会挂在github上.

Java API 设计清单 « 友好的API

- - 东西
在设计Java API的时候总是有很多不同的规范和考量. 与任何复杂的事物一样,这项工作往往就是在考验我们思考的缜密程度. 就像飞行员起飞前的检查清单,这张清单将帮助软件设计者在设计Java API的过程中回忆起那些明确的或者不明确的规范. 本文也可以看作为“ API设计指南”这篇文章的附录. 我们还准备了一些前后比对的例子来展示这个列表如何帮助你理清设计需求,找出错误,识别糟糕的设计实践以及如何寻找改进的时机.

API 设计二三事

- 烙饼 - 岁月如歌
所有程序员都是 API 设计者. 很认可 Dan Webb 的这句话. 近期刚好也有一些思考,总结分享下. jQuery 很优秀,原由之一就是其 API 具有很强的可预测性. 这样,不用详细阅读文档,根据直觉,就可以推测出 API 的一些高级用法,并且记忆深刻(因为是自己探索发现出来的). 我们可能会好奇,是什么让我们拥有这个“直觉”.

RESTful API 设计指南

- - 阮一峰的网络日志
网络应用程序,分为前端和后端两个部分. 当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信. 这导致API构架的流行,甚至出现 "API First"的设计思想. RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.

Web API 设计摘要

- - CSDN博客架构设计推荐文章
最近读了一本微电子书 Brian Mulloy 所著《Web API Design》感觉颇多收获,特对其内容做了个整理摘要以便回顾其观点精华以指导日常工作中的设计思路. 本文主要讲述 Web API 设计,追求一种更务实的 REST 风格. 正如作者所说 REST 是一种架构风格,而非严格的标准,没必要在形式定义上去做过多真论,到底什么才是真正的 REST.

Web API设计方法论

- - 博客园_知识库
  英文原文: A Web API Design Methodology.    为 Web 设计、实现和维护 API 不仅仅是一项挑战;对很多公司来说,这是一项势在必行的任务. 本系列 将带领读者走过一段旅程,从为 API 确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在 Web 上维护公共 API.

文章: Spring Data —— 完全统一的API?

- - InfoQ cn
Spring Data 作为SpringSource的其中一个父项目, 旨在统一和简化对各类型持久化存储, 而不拘泥于是关系型数据库还是NoSQL 数据存储. 白皮书下载:JBoss Enterprise Application Platform 6迁移指南. 白皮书下载:从虚拟化到云:在云中优化和自动化IT.

思考系统API设计的问题

- edware_love - C++博客-首页原创精华区
最近正好在思考系统API设计中考量的一些问题,. 我现在的理解是这样的,假设有巨大的真实内存. windows首先将高2G的内存自己占了,用作各种内核对象. 这2G内存共享给每个进程,但进程不能直接访问,只能通过windows给定的函数访问. : 然后每个进程都给他2G内存,进程如果创建自己的对象就放到自己那2G内存里面,如果要建立内核对象就放到共享的那高2G里面去.

如何设计一个优秀的API

- - 标点符
到目前为止,已经负责API接近两年了,这两年中发现现有的API存在的问题越来越多,但很多API一旦发布后就不再能修改了,即时升级和维护是必须的. 一旦API发生变化,就可能对相关的调用者带来巨大的代价,用户需要排查所有调用的代码,需要调整所有与之相关的部分,这些工作对他们来说都是额外的. 如果辛辛苦苦完成这些以后,还发现了相关的bug,那对用户的打击就更大.