开发实践：一份复杂业务系统的 RESTFul 接口规范

news2024/11/17 3:23:37

1. 从需求入手

  • 对象：增删改查

  • 对象列表：获取

  • 对象的复杂处理：挖掘、整理、汇总

2. 资源分类

  • 对象型：**/project/1

  • 列表型：**/projects

  • 算法型：**/project/search?input=**

3. 设计 URI

3.1. URI 命名

  • 有意义的单词，全部小写

  • 多个单词时，使用下划线分隔，设计良好的 URI 通常会避免多个单词

  • 不推荐使用缩写

3.2. URI 结构

几点：

  • 路径变量：表示层次结构

  • 路径标点：表示非层次结构

3.2.1. 路径变量

id为8的deal的评论列表：

  • /deal/8/comments

id为8的商家下第88条评论：

  • /merchant/8/comment/88

上述通过实体关联关系进行路径导航，一般是 id 导航；如果实体之间关联层级过深，则，使用查询参数，替代路径层级导航。

  • 路径层级：GET /zoo/1/area/2/animal/3

  • 查询参数：GET /zoo/1?area=2&animal=3

组合实体的访问：必须通过父实体的 id导航访问。组合实体不是first-class的实体，它的生命周期完全依赖父实体，无法独立存在，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。

3.2.2. 路径标点

”.”表达不同的representation，约定 Response 返回的数据格式

  • /deal/6.json

  • /deal/8.xml

3.3. URI 对外暴露的方法

GET，获取服务器的资源：

  • 安全性：服务器端响应 GET 请求并不会对服务器造成副作用

  • 不要使用 GET 方法来修改服务器端的状态信息

POST，创建资源：

  • 创建从属资源

  • 客户端无法确定对应 URI

  • POST 请求，不安全，也不是幂等的，因此，发布 POST 请求需要小心

备注：幂等，多次操作与只进行一次的效果相同。

PUT，创建资源和更新资源：

  • 与 POST 创建资源的区别：客户端知道 URI，具有幂等性

  • 在网络环境差的情况下，可将 POST 创建资源重构成 PUT 创建资源

DELETE，删除资源：

  • 资源划分粒度要使得，删除资源不用带参数

  • 具备幂等性

HTTP 请求返回码：

  • 建议：HTTP 头部的返回码统一用200（OK），具体状态在 body 中使用参数标识

  • body 中返回码的值，与 HTTP 协议中返回码的值保持一致，便于大家统一理解

HTTP 常见状态码：

  • 操作成功，2xx：200，ok；201，created

  • Client Error，4xx：400，bad request；401，未授权；404，not found

  • Server Error，5xx：500，internal server error

小结

REST，Representational States Transfer，表现层状态转化 & 有状态传输，本质上：REST 关注于资源，将所有的内容看做一个资源：图片、文本、计算，为每一个资源分配唯一的地址，并对这些资源进行规范的操作。

几个方面：

  • 资源的地址：URI，URL（URI 是抽象，URL 是具体实现）

  • 资源的形式：实体文件如：图片，文本，html，json。甚至一些算法及服务

  • 对资源的操作：GET\POST\PUT\DELETE

4. URL 补充

避免层级过深的 URL，/ 在 URL 中表示层级，按实体关联关系进行对象导航，通常是 id 导航。

过深的 URL 层级导航，容易造成 URL 迅速膨胀，例如：GET /zoo/1/area/2/animal/3，推荐使用查询参数，替代路径中的实体导航，例如：GET /zoo/1?area=2&animal=3

5. 请求及返回内容的规范

几点：

  • json和xml对象的属性，必须 使用驼峰法命名：一个单词时全部小写，多个单词时第一个单词小写，后续的单词首字母大写；

  • 单个对象：对象包含在 data 元素中{}；

  • 多个对象：data 是一个 list[{},{},…]，paging 包含分页信息{offset,limit,total}

  • 错误与异常：error 元素中，包含{code, type, message}

1.  `//  单个对象`
2.  `{`
3.  `"data"  :  {`
4.  `"bdId"  :  8,`
5.  `"bdName":  "Rongjun",`
6.  `"commission"  :  1200.00,`
7.  `...`
8.  `}`
9.  `}`

11.  `// 多个对象`
12.  `{`
13.  `"data"  :  [`
14.  `{`
15.  `"code"  :  "1234567890",`
16.  `"status":  0,`
17.  `},`
18.  `{`
19.  `"code"  :  "234578901",`
20.  `"status":  128,`
21.  `}`
22.  `...`
23.  `]`
24.  `"paging"  :  {`
25.  `"offset"  :  0,`
26.  `"limit"  :  20,`
27.  `"total"  :  100`
28.  `}`
29.  `}`

31.  `// 错误信息`
32.  `{`
33.  `"error"  :  {`
34.  `"code"  :  401,  /* code 仅用于表示有错误，相同的 code 可能有不同的 type 和 message */`
35.  `"type"  :  "PermissionDenied",  /* type表示真正的错误类型，错误类型的唯一标示 */`
36.  `"message"  :  "抱歉，你没有足够的权限"  /* 错误对应的详细说明，和type成对。可以理解type是title，message是body */`
37.  `}`
38.  `}`

POST/PUT 提交的请求数据：

  • 当请求方法为POST或PUT时，通常需要在Request Body中传递数据。

  • Request数据格式（Incoming Representation）可以根据需要采用url form或json格式。

  • 建议优先考虑采用json格式，此时，HTTP Header的“Content-Type”设置为”application/json”。

  • 相比于Response的格式定义，考虑到Request body中传递的都是业务数据，不需要用data来和其他信息做区别，建议采用 {x:1, y:2} 的格式。

疑问：Request 通过 POST 方式传递数据时，如何定义数据的编码格式？

6. 猫眼演出接口约定

整体上遵循技术文档-前后端约定，补充一些：

  • B 端 API 接口，/api/admin 开头，.json 结尾

  • C 端 API 接口，/api开头，.json 结尾

  • C 端 Web 接口，实际对象实体开头

7. 异常处理

出现异常时，要满足两种场景：

  1. 开发调试时，方便看到完整的异常信息，方便调试

  2. 线上服务时，屏蔽异常细节信息，只需向用户显示提示信息

技术上，两种情况：

  1. 请求 Web 页面，出现异常，或者 model 中属性异常

  2. 调用 API 端口，出现异常，通常是 Ajax 请求对应的 JSON 数据

从业务与非业务角度，异常分为两类：

  1. 业务异常：自己的业务代码抛出，表示一个用例的前置条件不满足、业务规则冲突等，比如参数校验不通过、权限校验失败。抛出异常，好处：终止业务逻辑的继续执行。

  2. 非业务异常：表示不在预期内的问题，通常由类库、框架抛出，或由于自己的代码逻辑错误导致，比如数据库连接失败、空指针异常、除0错误等等。

技术细节实现上，所有异常，返回给用户时，都需要两类信息：

  1. 异常对应的HTTP响应码

  2. 异常的文本描述信息

Spring MVC 下，具体技术解决方案：在Controller 层使用统一的异常拦截器：

  • 设置 HTTP 响应的状态码：业务类异常，使用它指定的 HTTP code；非业务类异常，统一使用500

  • Response Body 的错误码：异常类名

  • Response Body 的错误描述：业务类异常，使用它指定的错误文本；

8. 其他

常用命名方法：

  • DAO 层，方法命名：insert、update、getBy*、delete

  • Service 层，方法的命名：add、update*、getBy*、remove

  • Controller 层，方法命名：create、update、getBy*、实际操作的语意：on、off、publish、delete、sync

出错信息：

1.  `// 错误信息`
2.  `{`
3.  `"success":  false,`
4.  `"data"  :  {`
5.  `"reason"  :  "没有权限",`
6.  `"message":  "详细信息..."`
7.  `}`
8.  `}`

PUT vs. POST:

  • POST：Ajax 中，对 post 方法提供了封装，能够快捷调用，http://stackoverflow.com/q/2153917

  • PUT：通常要求更新操作具备幂等性

     

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/164370.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

游戏盾如何防护

游戏盾如何防护

什么是游戏盾呢游戏盾是DDoS高防IP产品系列中针对游戏行业的安全解决方案。 游戏盾专为游戏行业定制，针对性解决游戏行业中复杂的DDoS攻击、游戏CC攻击等问题。目前以对抗的形式存在的高防产品形态，也就是防御带宽要大于攻击者的流量。如果你是做运营商商…
阅读更多...
设计模式学习（六）：Template Method模板方法模式

设计模式学习（六）：Template Method模板方法模式

一、什么是Template Method模式 模板的原意是指带有镂空文字的薄薄的塑料板。只要用笔在模板的镂空处进行临摹，即使是手写也能写出整齐的文字，但是具体写出的文字是什么感觉则依赖于所用的笔。如果使用签字笔来临摹，则可以写出签字似的文字&a…
阅读更多...
【ROS2入门】ROS 2 services 概述

【ROS2入门】ROS 2 services 概述

大家好，我是虎哥，从今天开始，我将花一段时间，开始将自己从ROS1切换到ROS2，在上一篇中，我们一起了解ROS 2中Topic， 这一篇，我们主要会围绕ROS中另外一个重要的概念“Services ”&…
阅读更多...
excel图表技巧：如何在折线图上标注极值

excel图表技巧：如何在折线图上标注极值

折线图是大家日常工作中经常使用的一类基础图表，作用是体现数据的变化趋势。例如将每月的销售额通过折线图展示出来，数值变化就会很直观：抛开图表的美化，基本上大家做出来的折线图都是上图中的样子，而老菜鸟做出来的折…
阅读更多...
＜Linux＞进度条小程序和git使用详解

＜Linux＞进度条小程序和git使用详解

进度条小程序和git使用详解 文章目录进度条小程序和git使用详解一、Linux第一个小程序 - 进度条1.\r && \n2.行缓冲3.进度条二、git使用详解1.git概述1.1.历史背景1.2.版本控制1.3.集中式与分布式的区别2.Gitee仓库创建2.1.新建仓库2.2.复制仓库链接2.3.克隆仓库2.4.扩…
阅读更多...
Redis基础命令操作四之集合类型HASH

Redis基础命令操作四之集合类型HASH

HASH命令 命令举例说明HSETHSET [OUTKEY] [INKEY][INVALUE]集合添加键值对[INKEY][INVALUE]HGETHGET [OUTKEY] [INKEY]获取集合中inkey对应的valueHGETALLHGETALL [OUTKEY]获取集合中所有key,value信息HDELHDEL [OUTKEY] [INKEY]从集合中删除inkey键值对HLENHLEN [OUTKEY]获…
阅读更多...
linux部署KubeSphere和k8s集群（二）

linux部署KubeSphere和k8s集群（二）

上一篇文章讲述了在单个节点上安装 KubeSphere和k8s，这节主要讲解k8s多节点集群部署 第一步：设置主机名称hostname--(3台机器都设置) hostnamectl set-hostname k8s-master hostnamectl set-hostname k8s-node1 hostnamectl set-hostname k8s-node2 第二…
阅读更多...
_Linux多线程--生产者消费者模型篇

_Linux多线程--生产者消费者模型篇

文章目录1. 为何要使用生产者消费者模型2. 基于BlockingQueue的生产者消费者模型3. C queue模拟阻塞队列的生产消费模型条件变量使用规范简单测试1. BlockQueue (缓存--超市)2. ConProd.cc3. 结果展示升级版测试&&设计与RAII风格的加锁方式1. BlockQueue.hpp2. Task.hp…
阅读更多...
MATLAB 实现路由算法详细教程（完整代码+数据）

MATLAB 实现路由算法详细教程（完整代码+数据）

问题描述：鉴于我们小组成员都来自计通学院，我们对专业知识计算机网络内的路由器进行研究。我们知道在整个互联网中，有着很多个小的无法互相连通的小网络，早在上世纪六十年代，针对不同网络无法互联的问题，路…
阅读更多...
IC芯片类元件创建

IC芯片类元件创建

--摘自凡亿教育 一、VS1003音频芯片 首先，先创建新的元器件库 按箭头所指的即可。 然后，我们右击箭头所指的键，选择第六个矩形。 然后，依次放置管脚 点击箭头所指，既可放置管脚。 由于我们放置管脚的时候&#xff…
阅读更多...
python的webdriver应用

python的webdriver应用

本文总结如何使用python的webdriver插件，应用自动化测试以及爬虫抓取数据。工具选择谷歌版本下载：https://www.iplaysoft.com/tools/chrome/webdriver版本：http://npm.taobao.org/mirrors/chromedriver/ 或https://chromedriver.storage.goog…
阅读更多...
顺序表学习指南，请查收~

顺序表学习指南，请查收~

作者：爱塔居的博客_CSDN博客-JavaSE,数据结构领域博主 专栏：数据结构 作者简介：大三学生，希望一起进步！ 文章目录 目录 文章目录 一、顺序表基本概念 二、练习 一、顺序表基本概念 🌺顺序表是用一段物理地…
阅读更多...
常用工具的常用操作

常用工具的常用操作

写在前面 记录可能用到的各种工具常见技巧。 1：sublime 1.1：操作多列 首先选中要操作的列所在的行： 然后点击selection，spit lines： 接下来移动左右键就可以操作了，删除或者批量添加内容： 1…
阅读更多...
创客匠人助力机构招生获客转化

创客匠人助力机构招生获客转化

后疫情时代，各行各业部署线上化成为一门必修课。 创客匠人作为一家专注教育培训行业的知识付费技术服务商，为了更好的帮助教培机构、教育企业立足于内容传播需求，打通线上线下资源通道，将线下资源向"线上核心平台"靠拢…
阅读更多...
无极低码：100套大屏可视化源码，包含多个行业

无极低码：100套大屏可视化源码，包含多个行业

随着互联网的发展，各项技术的不断成熟，数据可视化在新的时代，人们对数据的呈现方式开始有了新的要求。科技感、美观、直观、动感等等都成为现代软件系统新的设计和思考方向，特别是硬件的发展和数据的发展，数据分析的需…
阅读更多...
Vue3商店后台管理系统设计文稿篇（一）

Vue3商店后台管理系统设计文稿篇（一）

记录使用vscode构建Vue3商店后台管理系统，这是第一篇，主要记录Vue3项目创建过程，以及数据的挂载 文章目录一、Vue3项目创建二、取消代码规范检查三、数据简单挂载正文内容： 一、Vue3项目创建 使用如下命令全局安装yarn npm i -g …
阅读更多...
Java开发 - Mybatis框架初体验

Java开发 - Mybatis框架初体验

前言 在前文中，我们已经学习了Spring框架，Spring MVC框架，相信大家对这些基础的内容已经熟练使用了，今天，我们继续来学习Mybatis框架。就目前而言，Mybatis框架依然是比较实用的框架，这篇博客&a…
阅读更多...
SpringMVC知识点记录

SpringMVC知识点记录

SpringMVC知识点记录1. SpringMVC简介2. 入门案例3. RequestMapping注解4. SpringMVC获取请求参数5. 域对象共享数据6.SpringMVC的视图7. RESTful8. RESTful 案例9. SpringMVC处理ajax请求10. 文件上传和下载11. 拦截器12. 异常处理器13. 注解配置SpringMVC14. SpringMVC执行流…
阅读更多...
hgame2023 week1 writeup

hgame2023 week1 writeup

#WEEK1 RE 1、re-test_your_IDA ida打开可见flag： int __cdecl main(int argc, const char **argv, const char **envp) {char Str1[24]; // [rsp20h] [rbp-18h] BYREFsub_140001064("%10s");if ( !strcmp(Str1, "r3ver5e") )sub_140001010…
阅读更多...
移动端 - 搜索组件(search-input篇)

移动端 - 搜索组件(search-input篇)

我们先来看一下最终效果 这样的搜索组件在移动端是很常见的, 大部分需求都是: 1. 搜索框进行搜索关键字 2. 热门搜索 3. 搜索历史 4. 搜索结果(提供上拉加载效果) 上述的基本需求也是我们现在需要去实现的, 先来说一下大致的方向: 1. search 一般都是一个路由组件, 所以先…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023