前后端完全分离之API设计

9顶
1踩

2015-04-28 10:45 by 副主编 mengyidan1988 评论(12) 有17119人浏览

前端开发 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)那就由读者自己去选择了。
项目地址

本文中只涉及了设计的理念，具体的实现请下载源码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"
  }
}

项目运行截图部分

查看图片附件

来自: Arccode's blog

分享到：

9
顶

1
踩

评论共 12 条请登录后发表评论

12 楼 zbm2001 2015-07-12 13:52

web原来就应该是这样的架构风格（rest）,对于断层的人你解释了也不一定理解，主要靠自省

11 楼 mangguo 2015-04-30 09:39

挺不错的好东西。

==（⊙o⊙）来自汇智网至尊客户端！世界辣莫大，你还不会编程。

10 楼 Fatyu 2015-04-29 22:59

dxbj1010 写道

如果用spring的话，如何识别这些method了?requestMethod?

指定method方式

9 楼 zhangchengtest 2015-04-29 14:42

跟我的想法竟然这么的一致

8 楼 nicegege 2015-04-29 11:38

github的地址有没？

7 楼 nicegege 2015-04-29 11:36

干货好东西谢谢分享！

6 楼 Tyrion 2015-04-29 10:41

这篇文章是个系列，建议编辑把前后都发上来吧。

5 楼 QuarterLifeForJava 2015-04-29 09:09

Angular+bootstamp+spring restfull
数据库层用起来都不大爽，求大家推荐个

4 楼 dxbj1010 2015-04-28 21:10

如果用spring的话，如何识别这些method了?requestMethod?

3 楼西南吹风 2015-04-28 16:36

restfull相当好用。企业应用分层架构模式下，restfull+json是个不二的选择。

2 楼 mangguo 2015-04-28 13:49

木有看懂是什么意思

1 楼 jinyanhui2008 2015-04-28 11:34

你要说明什么？

发表评论

您还没有登录,请您登录后再发表评论

相关推荐

ExtJs 3 自定义combotree

ExtJs 3 自定义combotree /** * 自定义下拉树，支持初始化值时自动定位树节点。 * 还没有考虑性能问题。继承自Ext.form.ComboBox也很浪费。 * 代码中的cu.get()是自定义的异步请求方法。 * @author ...

Coolite之ComboTree控件附加与实际引用、取值

看了N遍还没有明白那位老兄是怎么调用这个ComBoTree　控件。说明：以上是comboTree.js 与ComboTree.cs的存放位置。 Code1usingSystem;2usingSystem.Collections.Generic;3usingSystem.Component...

【转载】Coolite之ComboTree控件附加与实际引用、取值

Coolite之ComboTree控件附加与实际引用、取值在发这个贴子之前，我想说几句话。强烈笔视～～那些只发代码不写怎么调用的XXX人。看了N遍还没有明白那位老兄是怎么调用这个ComBoTree　控件。说明：以上是...

combotree的总结

1：最近有这个需求，就是ext下的combo下拉是树，网上的例子很多，封装的也很好，基本都可以满足下拉框下出现想要的树，但是我的使用情况是比如在用户编辑的时候，要把用户已经选择过的数值自动再赋值到下拉框内，...

extjs tree checkbox 复选框实现取值显示

原来做EXTTREE的复选其实很简单！数据： [{id:'55',text:'节点11',leaf:false,checked:true} checked属性就是控制复选框是否出现，true出现复选框 false 不出现。获取tree的选中值方法：...

combotree的总结(这个好)

Extjs-表单与输入控件

var editForm = new Ext.form.FormPanel({ labelWidth : 120, labelAlign : 'right', border : false, frame : true, trackResetOnLoad : true, anchor : '100%', bodyStyle : 'padding:5p

安卓桌面应用EyeRoom.zip

android 源码学习. 资料部分来源于合法的互联网渠道收集和整理，供大家学习参考与交流。本人不对所涉及的版权问题或内容负法律责任。如有侵权，请通知本人删除。感谢CSDN官方提供大家交流的平台

仿随手记的炫酷饼图.zip

webview重载使用&自定义网址.zip

C语言学习工程和C语言项目.zip

C语言诞生于美国的贝尔实验室，由丹尼斯·里奇（Dennis MacAlistair Ritchie）以肯尼斯·蓝·汤普森（Kenneth Lane Thompson）设计的B语言为基础发展而来，在它的主体设计完成后，汤普森和里奇用它完全重写了UNIX，且随着UNIX的发展，c语言也得到了不断的完善。为了利于C语言的全面推广，许多专家学者和硬件厂商联合组成了C语言标准委员会，并在之后的1989年，诞生了第一个完备的C标准，简称“C89”，也就是“ANSI C”，截至2020年，最新的C语言标准为2018年6月发布的“C18”。 [5] C语言之所以命名为C，是因为C语言源自Ken Thompson发明的B语言，而B语言则源自BCPL语言。 1967年，剑桥大学的Martin Richards对CPL语言进行了简化，于是产生了BCPL（Basic Combined Programming Language）语言。

带暂停功能倒计时TimeCountDown盒子适用.zip

Google翻译.txt

汽车车灯检测机械臂设计.doc

网络购物中心项目源码.rar

网络购物中心项目源码.rar是一个压缩文件包，包含了一个基于Web技术的电子商务平台的全部源代码和相关资源。这个源码包旨在提供一个功能全面、界面友好的在线购物体验，它集成了商品浏览、搜索、购买、支付以及用户管理等核心电商功能。该项目采用了当下流行的开发框架和编程语言，比如使用HTML5, CSS3, JavaScript, PHP和MySQL数据库等技术，确保了网站的响应速度和跨浏览器兼容性。对于即将毕业的学生或者正在寻找实践项目的课程设计者来说，这个源码包是一个宝贵的资源。它不仅提供了一个实际应用的平台以供学习和研究，还允许用户根据需求进行定制和扩展，如添加新的功能模块或优化现有的代码结构。此外，项目文档详细记录了系统架构、功能实现和部署流程，为初学者提供了清晰的指引。通过分析和修改这份源码，学生可以深化对Web开发的理解，提高编程能力，并且有机会将理论知识转化为实际操作技能。此源码包适合作为计算机科学与技术、软件工程、信息技术等相关专业的毕业设计或课程设计项目，能够帮助学生在完成学业的同时，积累实战经验，增强就业竞争力。无论是作为学习的起点，还是作为未来职业生涯的一个跳板，网络购物

C语言仓库,存储的是C语言代码.zip

Sora AI Videos的案例站点

这是Sora AI Videos的案例站点，使用此项目可以帮助你快速构建Sora AI的演示项目。

2015园林业务齐发展，区域拓展加速（20页）.zip

机械臂的物体识别与抓取技术研究.pdf

使用不同的超导间隙模型拟合从穿透深度获得的超流体密度数据matlab代码.zip

1.版本：matlab2014/2019a/2021a 2.附赠案例数据可直接运行matlab程序。 3.代码特点：参数化编程、参数可方便更改、代码编程思路清晰、注释明细。 4.适用对象：计算机，电子信息工程、数学等专业的大学生课程设计、期末大作业和毕业设计。

9顶1踩