服务 API 设计之 ——API 参数规范

【强制】字段名称用小驼峰风格

【强制】Service API 返回值必须使用 Response 包装

  • Service API 返回值强制要求进行通用包装,例如:Response。
  • Response 的作用:
  1. 统一方法表示 API 调用是否成功
  2. API 调用失败时,统一格式反馈错误 Code,错误 Message
  3. 统一的 Response 易于调用方经验复用,框架集成
  • 作为 API 调用方,其编码诉求很简单:
  1. API 调用是否成功;
  2. 调用不成功时,提示文案是什么;
  • 调用方几不想:
  1. 不想关心 API 内部有多牛逼
  2. 不想关心 API 可能会抛的各种 Exception,以及因此不得不做各种异常处理
  • 关于当前不统一的 Response
  • 【新业务】【强制】使用架构组定义的统一 Response:ZCY Response
  • 目前业务方有自定义 Result/Response,风格和作用大同小异。有更好的设计可以自荐给架构组集成,杜绝各自开辟重复的新定义。

【强制】杜绝完全不规范的缩写,避免望文不知义。(国际通用缩写除外)

  • 错误实践
  • AbstractClass “缩写” 命名成 AbsClass;
  • condition “缩写” 命名成 condi;
  • 此类随意缩写严重降低了代码的可阅读性。

【强制】禁止使用 Map 作为参数类型

Map<K,V> 机制非常灵活,但这样的灵活却是负作用巨大。

  1. Map 的数据说明是晦涩的,调用方、实现方之间需要具有隐式的契约解释支持哪些 Key,每个 Key 的 Value 是什么类型。增加了双方的使用复杂度。
  2. Map<K,V> 不可被校验。加之第 1 条的使用复杂度,导致使用上非常容易出错。
  3. 用 Map 类型字段做预留扩展性的设计都是不优雅的设计。

注:参数中的调用方自定义数据部分允许使用 Map。API 提供方不关系、不解析、只透传。

【强制】业务对象 / 查询条件用 DTO 封装,禁止以入参方式平铺字段。

  • 正确实践

分页查询,将查询条件以 DTO 方式包装。

Dubbo 序列化特点:

  • Dubbo API 的 POJO 类中,UID 不一致:没关系。
  • Dubbo API 的 POJO 类中,字段数量不一致:没关系,只要字段名和类型一致,数据能反序列化成功。
  • 发送方比接收方的字段多:没关系。
  • 发送方比接收方的字段少:没关系。
1
Response<Page<T>> pagingXXX(QueryDTO q)
  • 错误实践
1
Response<Page<T>> pagingXXX(String name, String code, Long orgId, Long creatorId, Integer pageNo, Integer PageSize)

以上错误实践缺点:
1、对于调用方来说,无论以什么条件查询,都需要逐个条件传参。
2、API 对扩展不友好,一旦想增加查询条件,API 就不兼容。

【推荐】DTO 字段设置 JSR303 Annotation 进行基础校验

  • 正确实践
1
2
3
public interface ZcyPayFacade {
    Result<Boolean> validTradePay(@NotNull @Valid TradePayPO tradePayPO);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
public class TradePayPO implements Serializable {

    @NotBlank
    @Length(max = 15)
    /** 业务交易编号(订单编号) */
    private String businessTradeNo;

    /**
     * 业务渠道:1-订阅,2-CA
     * @see BusinessTypeEnum
     *
     * */
    @NotNull
    @Range(min = 1, max = 2)
    private Integer businessType;

    ......
    
    /** 商户名称(商家) */
    @NotBlank
    @Length(max = 50)
    private String merchantName;

    /** 订单标题(即商品名称),粗略描述用户的支付目的。如“喜士多(浦东店)消费”*/
    @NotBlank
    @Length(max = 256)
    private String orderSubject;

    /** 订单描述(即商品描述),可以对交易或商品进行一个详细地描述,比如填写"购买商品2件共15.00元"*/
    @NotBlank
    @Length(max = 128)
    private String orderBody;

    ......
}

【推荐】在客户端完成基础字段校验

  • 方式 1:【推荐】自定义 Dubbo Filter 实现通用拦截、校验。
  • 方式 2:【推荐】通过 Builder 模式构建入参对象。
  • 方式 3:【不推荐】Dubbo 客户端参数校验,要求 consumer 方设置 validation=”true”,Dubbo 客户端参数校验。缺点:以抛异常方式处理校验失败,需要业务方额外处理 Exception。而且,IDE 并不会提示 consumer 方需要处理 ConstraintViolationException。
  • 方式 4:Dubbo 方式,local-stub 特性。实现较复杂,校验代码通用性低。Dubbo local-stub

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

如若内容造成侵权/违法违规/事实不符,请联系我们进行投诉反馈qq邮箱809451989@qq.com,一经查实,立即删除!

相关文章

vue实现轨迹回放(很详细)

效果 功能 时间搜索查询轨迹并生成&#xff08;默认是当前的一天的时间&#xff09; 图标能跟随路径方向移动 删除了百度logo和版权信息&#xff08;业务需要&#xff0c;不建议删除&#xff09; Vue Baidu Map npm install vue-baidu-map --save main.js import Vue from vu…

关于h5跳转app的坑

需求&#xff1a;h5点击按钮跳转app&#xff0c;有下载app的直接打开&#xff0c;无下载就跳转下载的链接&#xff08;安卓跟ios的下载链接不一样&#xff09; 1、用超链接的方式打开app <a href"xxxx"></a> 弊端&#xff1a;这种方式只能控制有下载ap…

基于电子商务平台客户管理系统的设计与实现_kaic

摘要 本论文旨在设计和实现一个基于电子商务平台的客户关系管理系统&#xff0c;以提高企业与客户之间的互动和关系维护效率。本文首先介绍了客户关系管理系统的相关理论和技术&#xff0c;并分析了其在电子商务平台中的应用价值。接着&#xff0c;进行了电子商务平台客户关系管…

【计算机组成原理笔记】

【计算机组成原理笔记】 1.1 计算机系统简介 计算机系统由软件和硬件组成。软件又可分为系统软件和应用软件。 计算机体系结构指的是&#xff08;机器语言&#xff09;程序员所看到的计算机系统属性概念性的结构与功能特性。&#xff08;研究有无乘法指令&#xff09; 计算机…

【ROS服务通信如果先启动客户端,那么会请求异常需求,如何解决?最全】

问题: 如果在启动 ROS 服务的客户端之前启动了 ROS 服务&#xff0c;客户端可能会因为缺少服务而发出异常请求。这可能会导致服务端不知道如何处理请求&#xff0c;从而导致通信失败。要解决这个问题&#xff0c;有以下几种方法&#xff1a; 等待服务启动&#xff1a;在启动客…

C语言爱心代码大全集—会Ctrl+C就可以表白了

一、C语言爱心代码大全&#xff0c;会CtrlC就可以表白了&#xff01; 博主整理了一个C语言爱心代码大全&#xff0c;里面有C语言爱心代码会动的动态效果和C语言爱心代码大全静态效果&#xff0c;只需复制粘贴就可以用啦&#xff01; 1、动态C语言爱心代码效果图如下&#xff…

如何优雅地使用 Markdown?

程序员宝藏库&#xff1a;https://gitee.com/sharetech_lee/CS-Books-Store 要想优雅&#xff0c;首先得有一个丝滑、好用的Markdown编辑器。 我用typora做笔记三年多&#xff0c;收费之后我开始找替代品&#xff0c;尝试了很多&#xff0c;总是有这样那样的问题不满意&#x…

QT设置图标

可执行文件图标 把.ico文件放到工程目录中&#xff0c;于.pro文件同级&#xff0c;然后在.pro文件中加上 RC_ICONSxxx.ico窗口左上角图标和任务栏图标 在mainwindows的ui文件中 选择文件或选择资源。资源的话就是从QT resources中找。百度关键字QT resources。

软件测试面试复盘:技术面没有难倒我,hr面被虐的体无完肤

一般提到面试&#xff0c;肯定都会想问一下面试结果&#xff0c;我就大概的说一下面试结果&#xff0c;哈哈&#xff0c;其实不太想说&#xff0c;因为挺惨的&#xff0c;并没有像很多大佬一样 ”已拿字节阿里腾讯各大厂offer”&#xff0c;但是毕竟是自己的经历&#xff0c;无…

【JavaWeb】7—会话控制

⭐⭐⭐⭐⭐⭐ Github主页&#x1f449;https://github.com/A-BigTree 笔记链接&#x1f449;https://github.com/A-BigTree/Code_Learning ⭐⭐⭐⭐⭐⭐ 如果可以&#xff0c;麻烦各位看官顺手点个star~&#x1f60a; 如果文章对你有所帮助&#xff0c;可以点赞&#x1f44d;…

7.redis-集群

一.概念 1.分片 集群中的每个redis实例都被认为是整个数据的一个分片&#xff0c;官方建议是最大1000个 2.槽位 redis集群有16384个哈希槽&#xff0c;每个key通过CRC16校验后通过总分片数量,对16384取模来决定放哪个槽&#xff0c;集群的每个节点负责一部分hash槽位。 3.槽位…

springboot+vue+java高速公路收费管理系统的设计

.第一&#xff0c;友好界面。高速公路收费管理系统开发设计&#xff0c;界面的友好性比较重要&#xff0c;满足这一要求才能体现出人性化设计特征&#xff0c;和用户应用系统便捷性相适应&#xff0c;动态的人机交互设计&#xff0c;用户应用系统的时候能感受到操作的便利&…

Maven核心概念

一、Maven基础知识 Apache Maven是一个项目管理和构建工具&#xff0c;它基于项目对象模型&#xff08;POM&#xff09;的概念&#xff0c;通过一小段描述信息来管理项目的构建、报告和文档。 1、Maven模型 2、仓库分类 本地仓库&#xff1a;自己计算机上的一个目录中央仓库&a…

【vite+vue3】 多页面应用模式

需要注意到的点&#xff1a; 1. 项目文件结构 2. vite.config.js 的配置 3. 访问地址的路径 假设你有下面这样的项目文件结构 ├── package.json ├── vite.config.js ├── index.html ├── main.ts └── src├── project&#xff5c;————projectA&#xf…

1669_MIT 6.828 xv6代码的获取以及编译启动

全部学习汇总&#xff1a; GreyZhang/g_unix: some basic learning about unix operating system. (github.com) 6.828的学习的资料从开始基本信息的讲解&#xff0c;逐步往unix的一个特殊版本xv6过度了。这样&#xff0c;先得熟悉一下这个OS的基本代码以及环境。 在课程中其实…

Python工具库安装

1、Python工具库下载 &#xff08;1&#xff09;查询安装Python的版本信息。 按键 WinR&#xff0c;在弹出的“运行”对话框中输入cmd&#xff0c;在弹出的Dos系统中&#xff0c;输入python&#xff0c;即可查询得到Python的版本信息。本次所安装的python版本为3.8.10。 &…

后端开发之Swagger API开发工具

最近刚入职公司&#xff0c;做Java后端。当下对于新手程序员来说&#xff0c;的确并不友好&#xff0c;不仅是经济低迷&#xff0c;而且这次chatgpt的大火也极大地冲击了软件开发行业&#xff0c;所以小白必须抓紧时间卷&#xff0c;哪怕自己写出来的东西把自己搞失业……也要尽…

【Python从入门到进阶】14、字典高级应用

接上篇《13、元组高级应用及常见切片操作》 上两篇我们学习了Python中元组的高级应用&#xff0c;以及字符串、列表和元祖的切片操作。本篇我们来学习字典的高级应用&#xff0c;包括字典的查询、修改、添加、删除及遍历操作。 一、字典高级简介 我们通过前面的学习知道&…

ORACLE创建表空间、用户、授权和Navicat创建序列和触发器及解决ORA-00942、ORA-01219错误

问题描述&#xff1a;因为每次Oracle删除数据库的时候磁盘文件还没删除&#xff0c;然后自己手动停止Oracle&#xff0c;删除磁盘里的.DBF文件导致数据库重启后无法连接。 cmd sqlplus sys as sysdba执行alter database open;查看你报错的数据文件&#xff08;就是你停止Orac…

Git 基础知识总结

Git 基础知识总结 1. Git 简介 Git 是什么 Git是一款分布式版本控制系统&#xff0c;可以有效地管理代码的版本和变更。Git可以在本地进行版本控制&#xff0c;也可以在多人协作开发时进行远程版本控制。Git的设计目标是速度快、数据完整性高、支持分布式、非线性开发流程。…
最新文章