7.优化前后端交互的秘诀

注释规约

  1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用/*内容/格式,不得使用

// xxx 方式。

说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE

中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。

  1. 【强制】所有的抽象方法(包括接口中的方法)必须要用 Javadoc 注释、除了返回值、参数、

异常说明外,还必须指出该方法做什么事情,实现什么功能。

说明:对子类的实现要求,或者调用注意事项,请一并说明。 \

  1. 【强制】所有的类都必须添加创建者和创建日期。

说明:在设置模板时,注意 IDEA 的@author 为${USER},而 eclipse 的@author 为${user},大小写有

区别,而日期的设置统一为 yyyy/MM/dd 的格式。

正例:

 /** @author yangguanbao @date 2016/10/31 */ 
  1. 【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使

用/* */注释,注意与代码对齐。

  1. 【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。
  1. 【推荐】与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持 英文原文即可。反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。
  1. 【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑

等的修改。

说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了

导航的意义。

  1. 【推荐】在类中删除未使用的任何字段、方法、内部类;在方法中删除未使用的任何参数声明

与内部变量。

  1. 【参考】谨慎注释掉代码。在上方详细说明,而不是简单地注释掉。如果无用,则删除。

说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没有备注信息,

难以知晓注释动机。后者建议直接删掉即可,假如需要查阅历史代码,登录代码仓库即可。

10.【参考】对于注释的要求:第一、能够准确反映设计思想和代码逻辑;第二、能够描述业务含

义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同

天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看

的,使其能够快速接替自己的工作。

11.【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的一

个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释又是相当大的负担。

12.【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,

经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

1) 待办事宜(TODO):(标记人,标记时间,[预计处理时间])

表示需要实现,但目前还未实现的功能。这实际上是一个 Javadoc 的标签,目前的 Javadoc 还没

有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个 Javadoc 标签)。

2) 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间])

在注释中用 FIXME 标记某代码是错误的,而且不能工作,需要及时纠正的情况

前后端规约

1.【强制】前后端交互的 API,需要明确协议、域名、路径、请求方法、请求内容、状态码、响

应体。

说明:

1) 协议:生产环境必须使用 HTTPS。

2) 路径:每一个 API 需对应一个路径,表示 API 具体的请求地址:

a) 代表一种资源,只能为名词,推荐使用复数,不能为动词,请求方法已经表达动作意义。

b) URL 路径不能使用大写,单词如果需要分隔,统一使用下划线。

c) 路径禁止携带表示请求内容类型的后缀,比如".json",“.xml”,通过 accept 头表达即可。

3) 请求方法:对具体操作的定义,常见的请求方法如下:

a) GET:从服务器取出资源。

b) POST:在服务器新建一个资源。

c) PUT:在服务器更新资源。

d) DELETE:从服务器删除资源。

4) 请求内容:URL 带的参数必须无敏感信息或符合安全要求;body 里带参数时必须设置 Content-Type。

5) 响应体:响应体 body 可放置多种数据类型,由 Content-Type 头来确定。Java 开发手册

2.【强制】前后端数据列表相关的接口返回,如果为空,则返回空数组[]或空集合{}。

说明:此条约定有利于数据层面上的协作更加高效,减少前端很多琐碎的 null 判断。

3.【强制】服务端发生错误时,返回给前端的响应信息必须包含 HTTP 状态码,errorCode、

errorMessage、用户提示信息四个部分。

说明:四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息

要求:简短清晰、提示友好,引导用户进行下一步操作或解释错误原因,提示信息可以包括错误原因、上

下文环境、推荐操作等。errorMessage:简要描述后端出错原因,便于错误排

查人员快速定位问题,注意不要包含敏感数据信息。

正例:常见的 HTTP 状态码如下

1) 200 OK: 表明该请求被成功地完成,所请求的资源发送到客户端。

2) 401 Unauthorized: 请求要求身份验证,常见对于需要登录而用户未登录的情况。

3) 403 Forbidden:服务器拒绝请求,常见于机密信息或复制其它登录用户链接访问服务器的情况。

4) 404 Not Found: 服务器无法取得所请求的网页,请求资源不存在。

5) 500 Internal Server Error: 服务器内部错误。

4.【强制】在前后端交互的 JSON 格式数据中,所有的 key 必须为小写字母开始的

lowerCamelCase 风格,符合英文表达习惯,且表意完整。

正例:errorCode / errorMessage / assetStatus / menuList / orderList / configFlag

反例:ERRORCODE / ERROR_CODE / error_message / error-message / errormessage /

ErrorMessage / msg

5.【强制】errorMessage 是前后端错误追踪机制的体现,可以在前端输出到 type=“hidden”

文字类控件中,或者用户端的日志中,帮助我们快速地定位出问题。

6.【强制】对于需要使用超大整数的场景,服务端一律使用 String 字符串类型返回,禁止使用

Long 类型。

说明:Java 服务端如果直接返回 Long 整型数据给前端,JS 会自动转换为 Number 类型(注:此类型为双

精度浮点数,表示原理与取值范围等同于 Java 中的 Double)。Long 类型能表示的最大值是 2 的 63 次方

-1,在取值范围之内,超过 2 的 53 次方 (9007199254740992)的数值转化为 JS 的 Number 时,有些数

值会有精度损失。扩展说明,在 Long 取值范围内,任何 2 的指数次整数都是绝对不会存在精度损失的,所

以说精度损失是一个概率问题。若浮点数尾数位与指数位空间不限,则可以精确表示任何整数,但很不幸,

双精度浮点数的尾数位只有 52 位。

反例:通常在订单号或交易号大于等于 16 位,大概率会出现前后端单据不一致的情况,比如,“orderId”:

362909601374617692,前端拿到的值却是: 362909601374617660。

7.【强制】HTTP 请求通过 URL 传递参数时,不能超过 2048 字节。

说明:不同浏览器对于 URL 的最大长度限制略有不同,并且对超出最大长度的处理逻辑也有差异,2048

字节是取所有浏览器的最小值。

反例:某业务将退货的商品 id 列表放在 URL 中作为参数传递,当一次退货商品数量过多时,URL 参数超长,

传递到后端的参数被截断,导致部分商品未能正确退货。

8.【强制】HTTP 请求通过 body 传递内容时,必须控制长度,超出最大长度后,后端解析会出

错。

说明:nginx 默认限制是 1MB,tomcat 默认限制为 2MB,当确实有业务需要传较大内容时,可以通过调

大服务器端的限制。

9.【强制】在翻页场景中,用户输入参数的小于 1,则前端返回第一页参数给后端;后端发现用

户输入的参数大于总页数,直接返回最后一页。

10.【强制】服务器内部重定向必须使用 forward;外部重定向地址必须使用 URL 统一代理模块

生成,否则会因线上采用 HTTPS 协议而导致浏览器提示“不安全”,并且还会带来 URL 维护

不一致的问题。

  1. 【推荐】服务器返回信息必须被标记是否可以缓存,如果缓存,客户端可能会重用之前的请求

结果。

说明:缓存有利于减少交互次数,减少交互的平均延迟。

正例:http 1.1 中,s-maxage 告诉服务器进行缓存,时间单位为秒,用法如下,

response.setHeader("Cache-Control", "s-maxage=" + cacheSeconds); 
  1. 【推荐】服务端返回的数据,使用 JSON 格式而非 XML。
  1. 【推荐】前后端的时间格式统一为"yyyy-MM-dd HH:mm:ss",统一为 GMT。

14.【参考】在接口路径中不要加入版本号,版本控制在 HTTP 头信息中体现,有利于向前兼容。

说明:当用户在低版本与高版本之间反复切换工作时,会导致迁移复杂度升高,存在数据错乱风险。

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

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

c++_09_继承

1 继承 C的继承是弱继承 继承的语法: class 子类 : 继承方式1 基类1, 继承方式2 基类2, ... { ... }; 继承方式: 共有继承 public 保护继承 protected 私有继承 private 2 继承的基本属性(3种继承方式均有) 继承所…

Javaweb之JDBC的详细解析

2. JDBC介绍(了解) 2.1 介绍 通过Mybatis的快速入门,我们明白了,通过Mybatis可以很方便的进行数据库的访问操作。但是大家要明白,其实java语言操作数据库呢,只能通过一种方式:使用sun公司提供的 JDBC 规范。 Mybatis…

从 MySQL 的事务 到 锁机制 再到 MVCC

其他系列文章导航 Java基础合集数据结构与算法合集 设计模式合集 多线程合集 分布式合集 ES合集 文章目录 其他系列文章导航 文章目录 前言 一、事务 1.1 含义 1.2 ACID 二、锁机制 2.1 锁分类 2.2 隔离级别 三、MVCC 3.1 介绍 3.2 隔离级别 3.3 原理 四、总结 前…

Impala中kudu基础理论详解(超详细)

文章目录 前言一、概述1. Impala简介2. kudu简介3. kudu架构(1) Master节点(2) Tablet服务器(TServer)(3) 表(Table)(4) 数据模型 4. kudu特性与优势(1) 快速随机访问(2) 列式存储与压缩(3) 数据一致性保证 5. kudu应用场景6. Kud…

鸟瞰uml(中)

21.依赖和关联之间的区别 依赖(Dependency): 依赖关系是一种较弱的关系,它表示一个类在某些条件下使用了另一个类。一个类的变化可以影响到依赖它的类,但不必须反过来,即依赖关系是一个单向的。依赖关系通…

【2023年度总结】 何其有幸 年岁并进 一元复始 万象更新

🌙 新年将至,万物更新,旧疾当愈。 今年极度焦虑。发生太多事情,做出很多改变。 自律。早起、拍照、运动、读书、学习、认识了很多厉害的朋友,尝试影响周围的人。这是我生活正向能量的来源。 学习。今年依然是把大量…

C#上位机与欧姆龙PLC的通信06---- HostLink协议(FINS版)

1、介绍 对于上位机开发来说,欧姆龙PLC支持的主要的协议有Hostlink协议,FinsTcp/Udp协议,EtherNetIP协议,本项目使用Hostlink协议。 Hostlink协议是欧姆龙PLC与上位机链接的公开协议。上位机通过发送Hostlink命令,可…

golang的大杀器协程goroutine

在Golang中,协程(Goroutine)是轻量级的执行单元,用于实现并发编程。它是Golang语言的重要组成部分,提供了简洁、高效的方式来处理并发任务。 特点: 1)轻量级:Go语言的协程是轻量级…

Golang leetcode206 翻转链表 迭代 递归 双指针

文章目录 翻转链表 leetcode206题解第一版 直接建立新的链表双指针迭代递归法 翻转链表 leetcode206 至此走到这里,我们对于链表的结构应当已经比较熟悉,下面的就是敢于操作 题解第一版 直接建立新的链表 时间复杂度太高 // 初始方法,建立…

简单搭建 SSM 项目实现登录

目录 项目简介项目层级介绍,导入依赖添加配置业务逻辑实现前端 JSP 页面实现 项目简介 SSM(Spring、Spring MVC、MyBatis)框架,是一种 Java Web 应用程序开发框架的集合,可以帮助开发者快速搭建 Java Web 应用程序。想…

React16源码: Suspense与lazy源码实现

Suspense 与 lazy 1 &#xff09;概述 Suspense 是在 react16.6 提供的新 feature用于加载的缓冲的内置组件 2 &#xff09;示例程序 lazy.js // lazy.js import React from react export default () > <p>Lazy Comp</p>主程序 import React, { Suspense, …

ARM AArch64的虚拟化(virtualization)详解(上)

目录 一、概述 开始之前 二、虚拟化介绍 为什么虚拟化很重要

用队列实现栈(JAVA)

仅使用两个队列实现一个后入先出&#xff08;LIFO&#xff09;的栈&#xff0c;并支持普通栈的全部四种操作&#xff08;push、top、pop 和 empty&#xff09;。 实现 MyStack 类&#xff1a; void push(int x) 将元素 x 压入栈顶。int pop() 移除并返回栈顶元素。int top() …

【MySQL】查看表的信息相关命令

文章目录 【MySQL】查看表的信息相关命令查看表的信息相关命令例 【免责声明】文章仅供学习交流&#xff0c;观点代表个人&#xff0c;与任何公司无关。 编辑|SQL和数据库技术(ID:SQLplusDB) 【MySQL】查看表的信息相关命令 在MySQL中&#xff0c;可以使用以下语句来查看表的信…

python实现Ethernet/IP协议的客户端(二)

Ethernet/IP是一种工业自动化领域中常用的网络通信协议&#xff0c;它是基于标准以太网技术的应用层协议。作为工业领域的通信协议之一&#xff0c;Ethernet/IP 提供了一种在工业自动化设备之间实现通信和数据交换的标准化方法。python要实现Ethernet/IP的客户端&#xff0c;可…

【Linux】socket基础API

目录 1. 创建socket&#xff08;TCP/UDP&#xff0c;客户端服务器&#xff09; 1.1 第一个参数——domain 1.2 第二个参数——type 1.3 第三个参数——protocol 2. 绑定socket地址&#xff08;TCP/UDP&#xff0c;服务器&#xff09; 2.1 字节序及转换函数 2.2 IP地址及…

消融实验(ablation study)——全网最全解读

消融实验&#xff08;ablation study&#xff09; 是什么优势与劣势案例总结 是什么 消融实验是一种科学研究方法&#xff0c;用于确定一个条件或参数对结果的影响程度。当研究者提出了一个新的方案或方法时&#xff0c;消融实验通过逐一控制一个条件或参数&#xff0c;来观察…

6个火爆全网的AI开源项目,用上月10万+

标题月10万可能说的有点夸张和含糊&#xff0c;10万具体指的是你可以利用这些开源项目实现&#xff1a; 访问量10万 收入10万 用户10万 …… 开源项目只是免费的工具&#xff0c;具体怎么实现还需要你根据自己需求去深入运营。这里只是给你推荐一些比较热门的开源项目&…

基于QT开发的温室气体数据记录软件

1、概述 温室气体分析仪数据记录软件用于实现温室气体分析仪数据的获取与存储&#xff0c;阀箱数据的获取与存储、冷阱数据的获取与存储、采样单元数据的获取与存储、阀箱和采样单元的远程操作以及系统功能的管理。其主操作界面如下&#xff1a; 上述软件界面分为2各区域&…

用html,js和layui写一个简单的点击打怪小游戏

介绍&#xff1a; 一个简单的打怪小游戏&#xff0c;点击开始游戏后&#xff0c;出现攻击按钮&#xff0c;击败怪物后可以选择继续下一关和结束游戏。 继续下一个怪兽的血量会增加5点&#xff0c;攻击按钮会随机变色。 效果图&#xff1a; html代码&#xff1a; <!DOCTYPE…