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

9顶
1踩

Web前端

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

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

  • DeepSeek与AI幻觉-清华大学团队制作

    DeepSeek与AI幻觉-清华大学团队制作 一、什么是AI幻觉 （定义与基础概念） 二、DeepSeek为什么会产生幻觉 （聚焦特定AI模型的幻觉成因分析） 三、AI幻觉评测 （评估AI幻觉的频率、类型与影响的方法） 四、如何减缓AI幻觉 （解决方案与技术优化方向） 五、AI幻觉的创造力价值 （探讨幻觉在创新场景中的潜在益处，如艺术生成、灵感激发等）

  • 协同过滤算法商品推荐系统(源码+数据库+论文+ppt)java开发springboot框架javaweb，可做计算机毕业设计或课程设计

    协同过滤算法商品推荐系统(源码+数据库+论文+ppt)java开发springboot框架javaweb，可做计算机毕业设计或课程设计 【功能需求】 前台用户可以实现注册登录、商品浏览，在线客服，加入购物车，加入收藏，下单购买，个人信息管理，收货信息管理，收藏管理，评论功能。 后台管理员可以进行用户管理、商品分类管理、商品信息管理、订单评价管理、系统管理、订单管理。 【环境需要】 1.运行环境：最好是java jdk 1.8，我们在这个平台上运行的。其他版本理论上也可以。 2.IDE环境：IDEA，Eclipse,Myeclipse都可以。 3.tomcat环境：Tomcat 7.x,8.x,9.x版本均可 4.数据库：MySql 5.7/8.0等版本均可； 【购买须知】 本源码项目经过严格的调试，项目已确保无误，可直接用于课程实训或毕业设计提交。里面都有配套的运行环境软件，讲解视频，部署视频教程，一应俱全，可以自己按照教程导入运行。附有论文参考，使学习者能够快速掌握系统设计和实现的核心技术。

  • MES系统数字化工厂解决方案.pptx

    MES系统数字化工厂解决方案.pptx

  • MUI调用照片以及裁剪和图库照片上传到服务器

    MUI调用照片以及裁剪和图库照片上传到服务器

  • ChatGPT付费创作系统V3.1.3独立版 WEB端+H5端+小程序端 （新增DeepSeek高级通道+新的推理输出格式）

    GPT付费体验系统最新版系统是一款基于ThinkPHP框架开发的AI问答小程序， 是基于国外很火的ChatGPT进行开发的Ai智能问答小程序。这是一种基于人工智能技术的问答系统， 可以实现智能回答用户提出的问题。相比传统的问答系统，ChatGPT可以更加准确地理解用户的意图， 提供更加精准的答案。同时系统采用了最新的GPT3.5接口与GPT4模型，同时还支持型，文心一言，腾讯混元， 讯飞星火，通义千问，DeepSeeK，智普等等国内各种大模型，可以更好地适应不同的应用场景，支持站点无限多开， 可以说ChatGPT付费创作系统目前国内相对体验比较好的一款的ChatGPT及多接口软件系统。 新增接入DeepSeek-R1、DeepSeek-V3（Ollama自部署和第三方均支持）、高级通道增加DeepSeek、 支持AI接口输出的reasoning_content字段（新的推理输出格式）、更新模型库、修复导出Excel的bug等功能， 优化了云灵Midjourney接口，出图更快更稳定。小程序端变化不大该系统版本测试下来比较完美， 老版本升级时数据库结构同步下，同时把原来

  • 基于java的美食点餐管理平台设计的详细项目实例（含完整的程序，GUI设计和代码详解）

    内容概要：本文档详细介绍了一款基于Java技术的美食点餐管理平台的设计与实现。该平台旨在优化传统餐饮行业的服务流程，通过智能化的点餐系统、高效的订单处理、智能库存管理和数据分析等功能，为用户提供便捷高效的点餐体验，并提升餐厅管理效率和服务质量。系统涵盖了前端设计、后端开发、数据库设计等方面，采用了成熟的Java技术和现代Web开发框架，如Spring Boot、Vue.js或React，确保系统的高效性和稳定性。此外，文档还包括详细的用户界面设计、模块实现以及系统部署指南，帮助开发者理解和搭建该平台。 适合人群：具备一定的Java编程基础和技术经验的研发人员、IT从业者以及有意开发类似系统的企业和个人。 使用场景及目标：①为餐厅提供一个集点餐、订单处理、库存管理于一体的高效平台；②优化传统餐饮服务流程，提升客户服务体验；③利用大数据分析辅助决策，助力餐饮企业精细化运营；④通过集成多种支付方式和其他外部系统，满足多样化的商业需求。 其他说明：本项目不仅提供了完整的技术方案和支持文档，还针对实际应用场景提出了多个扩展方向和技术优化思路，旨在引导用户不断迭代和完善该平台的功能和性能。

  • 相场模拟与激光制造技术：选择性激光烧结、激光融覆中的凝固与枝晶生长研究,相场模拟与激光制造技术：选择性激光烧结、激光融覆及凝固过程中的枝晶生长研究,相场模拟 选择性激光烧结 激光融覆 凝固 枝晶生长

    相场模拟与激光制造技术：选择性激光烧结、激光融覆中的凝固与枝晶生长研究,相场模拟与激光制造技术：选择性激光烧结、激光融覆及凝固过程中的枝晶生长研究,相场模拟 选择性激光烧结 激光融覆 凝固 枝晶生长 ,相场模拟; 选择性激光烧结; 激光融覆; 凝固; 枝晶生长,相场模拟与激光工艺：枝晶生长的凝固过程研究

  • 基于ssh框架开发的厂区管理系统，集成增删改查功能。.zip

    项目工程资源经过严格测试运行并且功能上ok，可实现复现复刻，拿到资料包后可实现复现出一样的项目，本人系统开发经验充足（全栈全领域），有任何使用问题欢迎随时与我联系，我会抽时间努力为您解惑，提供帮助 【资源内容】：包含源码+工程文件+说明等。答辩评审平均分达到96分，放心下载使用！可实现复现；设计报告也可借鉴此项目；该资源内项目代码都经过测试运行；功能ok 【项目价值】：可用在相关项目设计中，皆可应用在项目、毕业设计、课程设计、期末/期中/大作业、工程实训、大创等学科竞赛比赛、初期项目立项、学习/练手等方面，可借鉴此优质项目实现复刻，设计报告也可借鉴此项目，也可基于此项目来扩展开发出更多功能 【提供帮助】：有任何使用上的问题欢迎随时与我联系，抽时间努力解答解惑，提供帮助 【附带帮助】：若还需要相关开发工具、学习资料等，我会提供帮助，提供资料，鼓励学习进步 下载后请首先打开说明文件（如有）;整理时不同项目所包含资源内容不同;项目工程可实现复现复刻，如果基础还行，也可在此程序基础上进行修改，以实现其它功能。供开源学习/技术交流/学习参考，勿用于商业用途。质量优质，放心下载使用

  • 关于加强新能源汽车安全管理涉及的法规标准分析.pptx

    关于加强新能源汽车安全管理涉及的法规标准分析.pptx

  • 基于SSM的校园二手交易平台.zip(毕设&课设&实训&大作业&竞赛&项目)

    项目工程资源经过严格测试运行并且功能上ok，可实现复现复刻，拿到资料包后可实现复现出一样的项目，本人系统开发经验充足（全栈全领域），有任何使用问题欢迎随时与我联系，我会抽时间努力为您解惑，提供帮助 【资源内容】：包含源码+工程文件+说明等。答辩评审平均分达到96分，放心下载使用！可实现复现；设计报告也可借鉴此项目；该资源内项目代码都经过测试运行，功能ok 【项目价值】：可用在相关项目设计中，皆可应用在项目、毕业设计、课程设计、期末/期中/大作业、工程实训、大创等学科竞赛比赛、初期项目立项、学习/练手等方面，可借鉴此优质项目实现复刻，设计报告也可借鉴此项目，也可基于此项目来扩展开发出更多功能 【提供帮助】：有任何使用上的问题欢迎随时与我联系，抽时间努力解答解惑，提供帮助 【附带帮助】：若还需要相关开发工具、学习资料等，我会提供帮助，提供资料，鼓励学习进步 下载后请首先打开说明文件（如有）;整理时不同项目所包含资源内容不同;项目工程可实现复现复刻，如果基础还行，也可在此程序基础上进行修改，以实现其它功能。供开源学习/技术交流/学习参考，勿用于商业用途。质量优质，放心下载使用

  • 机器学习课程设计——基于AdaBoost的银行用户逾期行为检测.zip

    项目工程资源经过严格测试运行并且功能上ok，可实现复现复刻，拿到资料包后可实现复现出一样的项目，本人系统开发经验充足（全栈全领域），有任何使用问题欢迎随时与我联系，我会抽时间努力为您解惑，提供帮助 【资源内容】：包含源码+工程文件+说明等。答辩评审平均分达到96分，放心下载使用！可实现复现；设计报告也可借鉴此项目；该资源内项目代码都经过测试运行；功能ok 【项目价值】：可用在相关项目设计中，皆可应用在项目、毕业设计、课程设计、期末/期中/大作业、工程实训、大创等学科竞赛比赛、初期项目立项、学习/练手等方面，可借鉴此优质项目实现复刻，设计报告也可借鉴此项目，也可基于此项目来扩展开发出更多功能 【提供帮助】：有任何使用上的问题欢迎随时与我联系，抽时间努力解答解惑，提供帮助 【附带帮助】：若还需要相关开发工具、学习资料等，我会提供帮助，提供资料，鼓励学习进步 下载后请首先打开说明文件（如有）;整理时不同项目所包含资源内容不同;项目工程可实现复现复刻，如果基础还行，也可在此程序基础上进行修改，以实现其它功能。供开源学习/技术交流/学习参考，勿用于商业用途。质量优质，放心下载使用

  • UI+svg+规范设置打包

    UI+svg格式

  • 关于乘用车燃料消耗量评价方法及指标强制性国家标准的分析.pptx

    关于乘用车燃料消耗量评价方法及指标强制性国家标准的分析.pptx

Global site tag (gtag.js) - Google Analytics