当前位置: 首页 > news >正文

Java后端通用接口设计

1、接口的响应要明确表示接口的处理结果

为了将接口设计得更合理,我们需要考虑如下两个原则:

  • 对外隐藏内部实现。即服务A调用服务B,如果服务B异常,但是我们不要直接把服务B的状态码、错误描述直接暴露给用户;

  • 设计接口结构时,明确每个字段的含义,以及客户端的处理方式。

比如下面这个是我们设计的接口的响应:

@Data
public class APIResponse<T> {private boolean success;private T data;private int code;private String message;
}

接口的设计逻辑:

  • 如果出现非 200 的 HTTP 响应状态码,就代表请求没有到服务,可能是网络出问题、网络超时,或者网络配置的问题。这时,肯定无法拿到服务端的响应体,客户端可以给予友好提示,比如让用户重试,不需要继续解析响应结构体。

  • 如果 HTTP 响应码是 200,解析响应体查看 success,为 false 代表下单请求处理失败,可能是因为服务参数验证错误,也可能是因为服务操作失败。这时,根据服务定义的错误码表和 code,做不同处理。比如友好提示,或是让用户重新填写相关信息,其中友好提示的文字内容可以从 message 中获取。

  • success 为 true 的情况下,才需要继续解析响应体中的 data 结构体。data 结构体代表了业务数据。

1.1、通过ResponseBodyAdvice完成自动包装响应体

为了代码会更简洁,我们的业务逻辑中可以通过ResponseBodyAdvice完成响应体的包装。

@RestControllerAdvice
@Slf4j
public class APIResponseAdvice implements ResponseBodyAdvice<Object> {//自动处理APIException,包装为APIResponse@ExceptionHandler(APIException.class)public APIResponse handleApiException(HttpServletRequest request, APIException ex) {log.error("process url {} failed", request.getRequestURL().toString(), ex);APIResponse apiResponse = new APIResponse();apiResponse.setSuccess(false);apiResponse.setCode(ex.getErrorCode());apiResponse.setMessage(ex.getErrorMessage());return apiResponse;}//仅当方法或类没有标记@NoAPIResponse才自动包装@Overridepublic boolean supports(MethodParameter returnType, Class converterType) {return returnType.getParameterType() != APIResponse.class&& AnnotationUtils.findAnnotation(returnType.getMethod(), NoAPIResponse.class) == null&& AnnotationUtils.findAnnotation(returnType.getDeclaringClass(), NoAPIResponse.class) == null;}//自动包装外层APIResposne响应@Overridepublic Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {APIResponse apiResponse = new APIResponse();apiResponse.setSuccess(true);apiResponse.setMessage("OK");apiResponse.setCode(2000);apiResponse.setData(body);return apiResponse;}
}

实现了 @NoAPIResponse 自定义注解。如果某些 @RestController 的接口不希望实现自动包装的话,可以标记这个注解:

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface NoAPIResponse {
}

在 ResponseBodyAdvice 的 support 方法中,我们排除了标记有这个注解的方法或类的自动响应体包装。比如,对于刚才我们实现的测试客户端 client 方法不需要包装为 APIResponse,就可以标记上这个注解:

@GetMapping("client")
@NoAPIResponse
public String client(@RequestParam(value = "error", defaultValue = "0") int error){}

这样我们在代码中,就统一了响应体的处理,不用担心有些程序员别出心裁自己搞一套。

2、要考虑接口变迁的版本控制策略

接口不可能一成不变,需要根据业务需求不断增加内部逻辑。如果做大的功能调整或重构,涉及参数定义的变化或是参数废弃,导致接口无法向前兼容,这时接口就需要有版本的概念。在考虑接口版本策略设计时,我们需要注意的是,最好一开始就明确版本策略,并考虑在整个服务端统一版本策略。

  • 第一,版本策略最好一开始就考虑。
  • 第二,版本实现方式要统一。

为了实现上面的目的,我们可以通过注解的方式为接口增加基于 URL 的版本号:首先,创建一个注解来定义接口的版本。@APIVersion 自定义注解可以应用于方法或 Controller 上:

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface APIVersion {String[] value();
}

然后,定义一个 APIVersionHandlerMapping 类继承 RequestMappingHandlerMapping。

public class APIVersionHandlerMapping extends RequestMappingHandlerMapping {@Overrideprotected boolean isHandler(Class<?> beanType) {return AnnotatedElementUtils.hasAnnotation(beanType, Controller.class);}@Overrideprotected void registerHandlerMethod(Object handler, Method method, RequestMappingInfo mapping) {Class<?> controllerClass = method.getDeclaringClass();//类上的APIVersion注解APIVersion apiVersion = AnnotationUtils.findAnnotation(controllerClass, APIVersion.class);//方法上的APIVersion注解APIVersion methodAnnotation = AnnotationUtils.findAnnotation(method, APIVersion.class);//以方法上的注解优先if (methodAnnotation != null) {apiVersion = methodAnnotation;}String[] urlPatterns = apiVersion == null ? new String[0] : apiVersion.value();PatternsRequestCondition apiPattern = new PatternsRequestCondition(urlPatterns);PatternsRequestCondition oldPattern = mapping.getPatternsCondition();PatternsRequestCondition updatedFinalPattern = apiPattern.combine(oldPattern);//重新构建RequestMappingInfomapping = new RequestMappingInfo(mapping.getName(), updatedFinalPattern, mapping.getMethodsCondition(),mapping.getParamsCondition(), mapping.getHeadersCondition(), mapping.getConsumesCondition(),mapping.getProducesCondition(), mapping.getCustomCondition());super.registerHandlerMethod(handler, method, mapping);}
}

RequestMappingHandlerMapping 的作用,是根据类或方法上的 @RequestMapping 来生成 RequestMappingInfo 的实例。我们覆盖 registerHandlerMethod 方法的实现,从 @APIVersion 自定义注解中读取版本信息,拼接上原有的、不带版本号的 URL Pattern,构成新的 RequestMappingInfo,来通过注解的方式为接口增加基于 URL 的版本号。

最后,要通过实现 WebMvcRegistrations 接口,来生效自定义的 APIVersionHandlerMapping

@SpringBootApplication
public class CommonMistakesApplication implements WebMvcRegistrations {@Overridepublic RequestMappingHandlerMapping getRequestMappingHandlerMapping() {return new APIVersionHandlerMapping();}
}

这样,就实现了在 Controller 上或接口方法上通过注解,来实现以统一的 Pattern 进行版本号控制,使用时:

@GetMapping(value = "/api/user")
@APIVersion("v4")
public int right4() {return 4;
}

访问url为 http://localhost:8080/v4/api/user

使用框架来明确 API 版本的指定策略,不仅实现了标准化,更实现了强制的 API 版本控制。假如我们的接口强制要求必须要有版本号,可以改动APIVersionHandlerMapping代码,在获取不到@APIVersion注解时,就给予报错提示。

相关文章:

Java后端通用接口设计

1、接口的响应要明确表示接口的处理结果 为了将接口设计得更合理&#xff0c;我们需要考虑如下两个原则&#xff1a; 对外隐藏内部实现。即服务A调用服务B&#xff0c;如果服务B异常&#xff0c;但是我们不要直接把服务B的状态码、错误描述直接暴露给用户&#xff1b; 设计接…...

万字长文带你走进MySql优化(系统层面优化、软件层面优化、SQL层面优化)

文章目录系统层面优化采用分布式架构使用缓存使用搜索引擎软件层面优化调整 MySQL 参数配置定期清理无用数据创建索引创建索引普通索引唯一索引全文索引组合索引空间索引主键索引外键索引索引前缀适合创建索引的场景不适合创建索引的场景优化表结构分库分表SQL优化explain执行计…...

云原生安全2.X 进化论系列|云原生安全2.X未来展望(4)

随着云计算技术的蓬勃发展&#xff0c;传统上云实践中的应用升级缓慢、架构臃肿、无法快速迭代等“痛点”日益明显。能够有效解决这些“痛点”的云原生技术正蓬勃发展&#xff0c;成为赋能业务创新的重要推动力&#xff0c;并已经应用到企业核心业务。然而&#xff0c;云原生技…...

认识进程 -了解进程调度

前言 本篇通过介绍操作系统OS的重要功能&#xff0c;了解并发并行, 了解操作系统的一项重要功能 “进程管理” , 通过了解进程管理认识进程是操作系统资源分配的基本单位 ,如有错误&#xff0c;请在评论区指正&#xff0c;让我们一起交流&#xff0c;共同进步&#xff01; 文章…...

第十届省赛——7外卖店优先级

题目&#xff1a;“饱了么”外卖系统中维护着N 家外卖店&#xff0c;编号1~N。每家外卖店都有一个优先级&#xff0c;初始时(0 时刻) 优先级都为0。每经过1 个时间单位&#xff0c;如果外卖店没有订单&#xff0c;则优先级会减少1&#xff0c;最低减到0&#xff1b;而如果外卖店…...

做自动化测试选择Python还是Java?

今天&#xff0c;我们来聊一聊测试人员想要进阶&#xff0c;想要做自动化测试&#xff0c;甚至测试开发&#xff0c;如何选择编程语言 前言 自动化测试&#xff0c;这几年行业内的热词&#xff0c;也是测试人员进阶的必备技能&#xff0c;更是软件测试未来发展的趋势。特别是…...

C#基础之基础语法(一)

总目录 文章目录总目录前言一、C#简述1 C#是什么&#xff1f;2 .Net平台3. C# 和.Net的关系4. 集成开发环境&#xff08;IDE&#xff09;二、控制台应用程序1. 常用代码2.注意事项三、基础语法1.编写C#代码注意事项2.C#注释2. 变量&标识符&关键字4. 变量&#xff0c;字…...

【JVM篇1】认识JVM,内存区域划分,类加载机制

目录 一、JVM内存区域划分 ①程序计数器(每个线程都有一个) ②栈&#xff1a;保存了局部变量和方法调用的信息(每一个线程都有一个栈) 如果不停地调用方法却没有返回值&#xff0c;会产生什么结果 ③堆(每一个进程都有一个堆&#xff0c;线程共享一个堆) 如何区分一个变量是…...

CHAPTER 5 文件共享 - FTP

文件共享 - FTP1 FTP1.1 传输方式1. ASCII传输方式2. 二进制传输模式3. 两种传输方式的区别1.2 支持的模式1. 主动模式(PORT)2. 被动模式(PASV)3. 如何选择4. 为什么绝大部分互联网应用都是被动模式&#xff1f;1.3 搭建FTP服务器&#xff08;使用vsftpd&#xff09;1. 安装软件…...

【MySQL】将 CSV文件快速导入 MySQL 中

【MySQL】将 CSV文件快速导入 MySQL 中方法一&#xff1a;使用navicat等软件的导入向导如果出现中文乱码方法二&#xff1a;命令行导入&#xff08;LOAD DATA INFILE SQL&#xff09;一般来说&#xff0c;将csv文件导入mysql数据库有两种办法&#xff1a; 使用 navicat、workbe…...

Ngnix安装教程(2023.3.8)

Nginx安装教程&#xff08;2023.3.8&#xff09;引言1、Nginx简介2、Nginx安装2.1 下载Nginx安装包2.2 免安装启动Nginx&#xff08;切记解压后将nginx-1.23.3文件夹需要放在英文路径下&#xff0c;实测中文路径不识别且启动不成功&#xff09;2.3 熟悉Nginx文件夹目录结构2.4 …...

【C语言】每日刷题 —— 牛客(2)

前言 大家好&#xff0c;继续更新专栏c_牛客&#xff0c;不出意外的话每天更新十道题&#xff0c;难度也是从易到难&#xff0c;自己复习的同时也希望能帮助到大家&#xff0c;题目答案会根据我所学到的知识提供最优解。 &#x1f3e1;个人主页&#xff1a;悲伤的猪大肠9的博客…...

关于算法的一些简单了解

文章目录ALGORITHMBASIC INFORMATIONBasic algorithm design technology穷举法分治法减治法动态规划法贪心法Algorithm design technology based on search回溯法分支限界法PRACTICECONCEPTCALATION*CODEprim&dijkstra&kruskal分治法Q&AT(n)T(n)T(n) 是渐进时间复杂…...

mysql无法启动服务及其他问题总结

文章目录1.安装后关于配置的问题显示【发生系统错误&#xff0c;拒绝访问】命令行Command Line Client闪退2.显示【MySQL服务无法启动】问题检查端口被占用删除data文件并初始化配置my.ini/.conf文件重新安装MySQL1.安装后关于配置的问题 显示【发生系统错误&#xff0c;拒绝访…...

数据库表字段命名规范

因为近期笔者在数据库命名规范上产生了一些疑问&#xff0c;故特此记录下来了一些开发规范&#xff0c;望做参考。 摘要&#xff1a; 当前研发工作中经常出现因数据库表、数据库表字段格式不规则而影响开发进度的问题&#xff0c;在后续开发使用原来数据库表时&#xff0c;也会…...

23种设计模式-命令模式(android应用场景介绍)

命令模式是一种行为设计模式&#xff0c;它允许将请求封装成一个独立的对象&#xff0c;并将请求的不同参数化。通过这种方式&#xff0c;命令模式可以在不同的请求间切换&#xff0c;或者将请求放入队列中等待执行。 在Java中&#xff0c;命令模式通常由一个抽象命令类和具体…...

vector你得知道的知识

vector的基本使用和模拟实现 一、std::vector基本介绍 1.1 常用接口说明 std::vector是STL中的一个动态数组容器&#xff0c;它可以自动调整大小&#xff0c;支持在数组末尾快速添加和删除元素&#xff0c;还支持随机访问元素。 以下是std::vector常用的接口及其说明&#xf…...

【C++进阶】四、AVL树(二)

目录 前言 一、AVL树的概念 二、AVL树节点的定义 三、AVL树的插入 四、AVL树的旋转 4.1 左单旋 4.2 右单旋 4.3 左右双旋 4.4 右左双旋 五、AVL树的验证 六、AVL树的性能 七、完整代码 前言 前面对 map/multimap/set/multiset 进行了简单的介绍&#xff0c;在其文…...

React 服务端渲染

React 服务器端渲染概念回顾什么是客户端渲染CSR(Client Side Rendering)服务器端只返回json数据&#xff0c;Data和Html的拼接在客户端进行&#xff08;渲染&#xff09;。什么是服务器端渲染SSR(Server Side Rendering)服务器端返回数据拼接过后的HTML&#xff0c;Data和Html…...

【算法设计-搜索】回溯法应用举例(1)

文章目录0. 回溯模板1. 走楼梯2. 机器走格子&#xff0c;但限定方向3. 中国象棋&#xff0c;马走日字4. 走迷宫5. 积木覆盖0. 回溯模板 搜索算法中的回溯策略&#xff0c;也是深度优先搜索的一种策略&#xff0c;比较接近早期的人工智能。毕竟&#xff0c;搜索是人工智能技术中…...

XML Group端口详解

在XML数据映射过程中&#xff0c;经常需要对数据进行分组聚合操作。例如&#xff0c;当处理包含多个物料明细的XML文件时&#xff0c;可能需要将相同物料号的明细归为一组&#xff0c;或对相同物料号的数量进行求和计算。传统实现方式通常需要编写脚本代码&#xff0c;增加了开…...

[2025CVPR]DeepVideo-R1:基于难度感知回归GRPO的视频强化微调框架详解

突破视频大语言模型推理瓶颈,在多个视频基准上实现SOTA性能 一、核心问题与创新亮点 1.1 GRPO在视频任务中的两大挑战 ​安全措施依赖问题​ GRPO使用min和clip函数限制策略更新幅度,导致: 梯度抑制:当新旧策略差异过大时梯度消失收敛困难:策略无法充分优化# 传统GRPO的梯…...

rknn优化教程(二)

文章目录 1. 前述2. 三方库的封装2.1 xrepo中的库2.2 xrepo之外的库2.2.1 opencv2.2.2 rknnrt2.2.3 spdlog 3. rknn_engine库 1. 前述 OK&#xff0c;开始写第二篇的内容了。这篇博客主要能写一下&#xff1a; 如何给一些三方库按照xmake方式进行封装&#xff0c;供调用如何按…...

系统设计 --- MongoDB亿级数据查询优化策略

系统设计 --- MongoDB亿级数据查询分表策略 背景Solution --- 分表 背景 使用audit log实现Audi Trail功能 Audit Trail范围: 六个月数据量: 每秒5-7条audi log&#xff0c;共计7千万 – 1亿条数据需要实现全文检索按照时间倒序因为license问题&#xff0c;不能使用ELK只能使用…...

Golang dig框架与GraphQL的完美结合

将 Go 的 Dig 依赖注入框架与 GraphQL 结合使用&#xff0c;可以显著提升应用程序的可维护性、可测试性以及灵活性。 Dig 是一个强大的依赖注入容器&#xff0c;能够帮助开发者更好地管理复杂的依赖关系&#xff0c;而 GraphQL 则是一种用于 API 的查询语言&#xff0c;能够提…...

CocosCreator 之 JavaScript/TypeScript和Java的相互交互

引擎版本&#xff1a; 3.8.1 语言&#xff1a; JavaScript/TypeScript、C、Java 环境&#xff1a;Window 参考&#xff1a;Java原生反射机制 您好&#xff0c;我是鹤九日&#xff01; 回顾 在上篇文章中&#xff1a;CocosCreator Android项目接入UnityAds 广告SDK。 我们简单讲…...

从零开始打造 OpenSTLinux 6.6 Yocto 系统(基于STM32CubeMX)(九)

设备树移植 和uboot设备树修改的内容同步到kernel将设备树stm32mp157d-stm32mp157daa1-mx.dts复制到内核源码目录下 源码修改及编译 修改arch/arm/boot/dts/st/Makefile&#xff0c;新增设备树编译 stm32mp157f-ev1-m4-examples.dtb \stm32mp157d-stm32mp157daa1-mx.dtb修改…...

在鸿蒙HarmonyOS 5中使用DevEco Studio实现录音机应用

1. 项目配置与权限设置 1.1 配置module.json5 {"module": {"requestPermissions": [{"name": "ohos.permission.MICROPHONE","reason": "录音需要麦克风权限"},{"name": "ohos.permission.WRITE…...

AI+无人机如何守护濒危物种?YOLOv8实现95%精准识别

【导读】 野生动物监测在理解和保护生态系统中发挥着至关重要的作用。然而&#xff0c;传统的野生动物观察方法往往耗时耗力、成本高昂且范围有限。无人机的出现为野生动物监测提供了有前景的替代方案&#xff0c;能够实现大范围覆盖并远程采集数据。尽管具备这些优势&#xf…...

第7篇:中间件全链路监控与 SQL 性能分析实践

7.1 章节导读 在构建数据库中间件的过程中&#xff0c;可观测性 和 性能分析 是保障系统稳定性与可维护性的核心能力。 特别是在复杂分布式场景中&#xff0c;必须做到&#xff1a; &#x1f50d; 追踪每一条 SQL 的生命周期&#xff08;从入口到数据库执行&#xff09;&#…...