资讯频道 → Web前端
阅读更多

9顶
1踩

Web前端

转载新闻 前后端完全分离之API设计

2015-04-28 10:45 by 副主编 mengyidan1988 评论(12) 有17231人浏览
前端开发 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"
  }
}

项目运行截图部分


  • 大小: 247.5 KB
来自: 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的总结(这个好)

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

  • Extjs-表单与输入控件

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

  • 基于S7-300PLC与MCGS6.2的饮料罐装生产线自动化控制系统设计，包含仿真、程序、IO表与电气原理，实现自动操作、灌装报警及瓶数记录功能 ,基于PLC的饮料罐装生产线控制系统设计 S7-30

    基于S7-300PLC与MCGS6.2的饮料罐装生产线自动化控制系统设计，包含仿真、程序、IO表与电气原理，实现自动操作、灌装报警及瓶数记录功能。,基于PLC的饮料罐装生产线控制系统设计。 S7-300PLC MCGS6.2仿真 仿真，程序，IO表，电气原理图，6500字说明。 实现功能有： （1）系统通过开关设定为自动操作模式，一旦启动，则传送带的驱动电机启动并一直保持到停止开关动作或罐装设备下的传感器检测到一个瓶子时停止；瓶子装满饮料后，传送带驱动电机必须自动启动，并保持到又检测到一个瓶子或停止开关动作。 （2）当瓶子定位在灌装设备下时，停顿1秒，罐装设备开始工作，灌装过程为5秒钟，罐装过程应有报警显示，5秒后停止并不再显示报警。 （2）用两个传感器和若干个加法器检测并记录空瓶数和满瓶数，一旦系统启动，必须记录空瓶和满瓶数，设最多不超过99999999瓶。 （4）可以手动对计数器清零（复位）。 ,关键词：S7-300PLC; MCGS6.2仿真; 传送带驱动电机; 传感器检测; 瓶装; 空瓶数; 满瓶数; 报警显示; 自动操作模式; 灌装设备。,基于S7-300PLC的饮料罐装

  • python加密货币时间序列预测源码+数据集-最新出炉.zip

    python加密货币时间序列预测源码+数据集-最新出炉 加密货币分析： 对各种加密货币的数据进行分析和研究。可能会使用到从各种来源收集的数据，包括但不限于加密货币的价格、市值、交易量、交易时间等信息。 探索加密货币市场的趋势和模式，例如价格的波动情况、不同加密货币之间的相关性等。 数据处理与操作： 可能使用 Python 语言（Kaggle 上常用的数据分析语言），并运用一些数据处理和分析的库，如 pandas 用于数据的读取、清洗、整理和转换操作，将原始的加密货币数据转换为更易于分析的格式。 可视化展示： 通过可视化工具，如 matplotlib 或 seaborn 库，将加密货币的信息以图表的形式展示出来，以帮助直观地理解数据中的关系和趋势。 统计分析或预测： 可能会进行一些基本的统计分析，如计算加密货币价格的均值、中位数、标准差等统计量，以描述数据的特征。 或者使用机器学习或时间序列分析的方法对加密货币的价格进行预测，根据历史数据预测未来价格走势。 例如，使用 scikit-learn 进行简单的回归分析： 数据挖掘与特征提取： 挖掘加密货币数据中的特征，如找出影响价格的关键因素，对数据中的特征进行筛选和提取，以帮助更好地理解加密货币的市场行为。

  • 面对程序设计GJava

    类和对象、继承、封装、多态、接口、异常

  • TF_demo1_keras.ipynb

    gee python相关教程

  • 夜间灯光数据 2023年全球_中国夜间灯光数据合集(数据权威)

    夜间灯光强度（平均灯光强度）的高低反映了一个地区城市化发展的水平，平均灯光强度越高，说明该地区城市群越多，城市化程度越高。夜间灯光数据现在越来越广泛地应用于经济增长分析、经济地理、城市经济学、数字经济等众多领域。 本数据包括三套： [1]中国类DMSP-OLS灯光数据1992-202 [2]中国超长序列灯光数据1984-2020 [3]全球类NPP-VIIRS夜间灯光数据2000-2022 包括：全国各省、市、县夜间灯光数据 矫正后夜间灯光数据 细分：标准差、平均值、总值、最大值和最小值

  • 工程项目总监绩效考核表.xls

    工程项目总监绩效考核表

  • (数据权威)各省份一般公共预算转移支付数据（附送地级市转移支付）

    首先解释一下什么叫转移支付。其实，这和养老金的中央调剂是一样的。 每年，地方都要向中央缴纳财政。而中央又要根据各地方的财政实力，给予转移支付。比如一些经济弱省，本身财政收入就不够支出的，还得上交一部分给中央，怎么维持财政运转？由于各省市直接的财政收入能力存在差异，中央为实现各个地方的公共服务水平平等，于是便有了财政转移支付制度。 简单理解就是富省养穷省。 2022年全国一般预算内财政收入203703亿元，给地方转移支付了97144.75亿元，转移支付数额创下新高。

  • 基于门控卷积和堆叠自注意力的离线手写汉字识别算法研究.pdf

    基于门控卷积和堆叠自注意力的离线手写汉字识别算法研究.pdf

  • 逐月中国工业用水空间分布数据集(数据权威)

    【数据介绍】   作为第二大人类部门用水，高质量的工业用水格网数据对于水资源研究和管理至关重要。中国工业用水格网数据（China Industrial Water Withdrawal dataset， CIWW）基于超过 40 万家企业数据、月度工业产品产量数据和连续工业用水统计数据制作得到的一套1965-2020年逐月中国工业用水数据集，其空间分辨率为 0.1°和 0.25°。数据集包括工业用水、企业数量和企业生产总值（辅助数据）等变量，可被用于水文、地理学、环境、可持续发展等方面科学研究。 【数据来源】   数据来源为《中国经济普查年鉴》(省级工业取水量、工业产出)、《中国工业企业数据库》（企业地理位置、产值）、《中国工业产品产量数据库》（工业产品月生产量），以及《中国水资源公报》和(Zhou et al, 2020, PNAS)的工业用水量数据。 【数据处理】 首先通过2008年企业分布数据、经济普查年鉴中分省分部门的工业用水量和工业产值计算得到分省分部门工业用水效率和工业产品产量数据，得到了2008年逐月工业用水数据。然后结合中国水资源公报和相关文献中省级工业用水数据，以2008年工业用水的时空格局作为基础分配工业用水数据，最终得到1965-2020年逐月工业用水的格网数据。详细方法见High-resolution mapping of monthly industrial water withdrawal in China from 1965 to 2020 (Hou et al, 2024, ESSD). 将数据集与统计数据记录和其他数据集进行了验证，结果表示在时间尺度和空间尺度上都与统计数据具有一致性，相比已有工业用水数据有更好的精度。

  • 65 -质量管理部经理绩效考核表1.xlsx

    65 -质量管理部经理绩效考核表1

  • 11 -电脑部经理绩效考核表1.xlsx

    11 -电脑部经理绩效考核表1

  • 大英赛写作必备：实用英语万能句及其应用技巧

    内容概要：本文提供了针对大学生英语竞赛写作准备的重要资源——一系列通用的英文句子模板。这些模板涵盖了现代经济社会的各种话题，从科技进步到环境保护，以及个人品质和社会责任等，并且适用于论述类文章、观点对比和个人见解的表达。文章通过对每一句话的应用环境解释和语法提示，确保使用者可以在实际写作中正确且有效地应用这些表达方式。 适合人群：正在准备参加大学生英语竞赛的学生及其他希望提高书面表达能力的学习者。 使用场景及目标：考生能够在竞赛时间内迅速构建思路完整的文章，增强语言表达的流利性和规范性；帮助学习者积累高级词汇，提升英语写作水平并培养良好的思维逻辑。 阅读建议：结合历年优秀范文进行深入学习，熟悉不同类型话题下的表述方法；练习将提供的句子融入自身创作的文章中，通过不断修订和完善来巩固记忆。同时也可以用于日常的英语写作训练当中。

Global site tag (gtag.js) - Google Analytics