微服务开发系列:设计一个统一的 http 接口内容形式

源码地址

微服务开发系列:开篇
微服务开发系列:为什么选择 kotlin
微服务开发系列:为什么用 gradle 构建
微服务开发系列:目录结构,保持整洁的文件环境
微服务开发系列:服务发现,nacos 的小补充
微服务开发系列:怎样在框架中选择开源工具
微服务开发系列:数据库 orm 使用
微服务开发系列:如何打印好日志
微服务开发系列:鉴权
微服务开发系列:认识到序列化的重要性
微服务开发系列:设计一个统一的 http 接口内容形式
微服务开发系列:利用异常特性,把异常纳入框架管理之中
微服务开发系列:利用 knife4j,生成最适合微服务的文档

1 统一接口格式

所有有关于接口返回的数据格式,都定义在 framework:cn/framework/common/http 包路径下。

1.1 MessageType

系统中为了方便直观的使用,对所有 HTTP code 做了拦截,除了网络错误的请求,前端不再需要判断 404、500 等错误,只需要根据 MessageType 判断是否成功。

定义返回的消息类型,直接确定下来前端根据这个消息类型去打印不同的信息。

目前只定义了 WARNING、SUCCESS、ERROR 三种消息类型,并且定义了相应的消息内容,可以根据业务场景的增加扩展。

1.2 RequestResult

所有返回到前端的数据格式,都必须为此格式。

关键字段:

  1. MessageType type,信息类型,默认为成功
  2. String message,消息内容,如果为空使用 MessageType 中自带的消息内容
  3. String reason,错误消息,用于在发生异常时,携带异常信息,不能用于展示给客户端
  4. Long code,行动码,用于与前端交互,改变行为,没有可不设置,使用 type 代替就可以
  5. LocalDateTime time,变量生成时间,用于协助判断问题
  6. Object value,真正返回的业务数据,可以是任何可被序列化的数据

拥有统一的数据格式,前端才能更好统一的处理信息。

1.3 InnerExp

内部异常,用于方便返回结果到前端。

对于内部异常,和其它异常的分析,放在下一篇《利用异常特性,把异常纳入框架管理之中》单独讲述。

2 http status code

http 的协议中,定义了很多状态码。

但是我认为在一般的前后端的业务交互上,我们不需要这么多状态码,这些状态码,更多的是给还未到达后端的请求准备的。

例如有些请求在 nginx 这一层就出现异常,此时 nginx 就可以根据一些情况返回对应的状态码,因为像 nginx 这种中间件,它要满足更加标准化的情况。

对此,框架中设计的消息返回状态码,只要是到达了后端,一律返回 200,消息只分为成功、失败、警告三种。

如果有更加复杂的场景,需要前端针对不同的异常类型,作为不同的反应,例如登录失败的原因是密码错误还是密码到期,上面的返回消息体中,也可以自定义 code。

这样不仅简化了后端的处理方式,也大大降低了前端的处理难度。

前端获取的 response 只要是非 200 的,证明肯定不是后端出现了问题,将错误信息统一处理。

针对 200 消息可以做统一的拦截处理,针对错误、警告消息做出回应,成功消息放行。

我们不需要对没有使用正统的 http code 这件事耿耿于怀,任何能够简化我们开发的方式,都是一种好方式,以当下的事实环境来设计开发方式,如果未来不满足,再重新设计。


微服务开发系列
一个使用 kotlin,开发独创的,搭配完整源码,完整介绍微服务框架理解的系列
2.8k 声望
2.7k 粉丝
0 条评论
推荐阅读
java/kotlin 生成 echarts 图片最优解
一. 方法探索后台生成图片的方法不多,根据我在网上的查找,有如下几种方法:前台服务提供接口,结合图表提供的生成图片,请求后返回图片数据。搭建服务,与第一点类似,同样是发送数据。若有配合的前端服务,可...

zxdposter1阅读 893

从零搭建 Node.js 企业级 Web 服务器(十五):总结与展望
总结截止到本章 “从零搭建 Node.js 企业级 Web 服务器” 主题共计 16 章内容就更新完毕了,回顾第零章曾写道:搭建一个 Node.js 企业级 Web 服务器并非难事,只是必须做好几个关键事项这几件必须做好的关键事项就...

乌柏木66阅读 6.2k评论 16

从零搭建 Node.js 企业级 Web 服务器(一):接口与分层
分层规范从本章起,正式进入企业级 Web 服务器核心内容。通常,一块完整的业务逻辑是由视图层、控制层、服务层、模型层共同定义与实现的,如下图:从上至下,抽象层次逐渐加深。从下至上,业务细节逐渐清晰。视图...

乌柏木44阅读 7.4k评论 6

从零搭建 Node.js 企业级 Web 服务器(二):校验
校验就是对输入条件的约束,避免无效的输入引起异常。Web 系统的用户输入主要为编辑与提交各类表单,一方面校验要做在编辑表单字段与提交的时候,另一方面接收表单的接口也要做足校验行为,通过前后端共同控制输...

乌柏木33阅读 6.2k评论 9

从零搭建 Node.js 企业级 Web 服务器(五):数据库访问
回顾 从零搭建 Node.js 企业级 Web 服务器(一):接口与分层,一块完整的业务逻辑是由视图层、控制层、服务层、模型层共同定义与实现的,控制层与服务层实现了业务处理过程,模型层定义了业务实体并以 对象-关系...

乌柏木34阅读 4.6k评论 9

从零搭建 Node.js 企业级 Web 服务器(十三):断点调试与性能分析
Node.js 官方提供了断点调试机制,出于安全性考虑默认为关闭状态,可以通过 node 参数 --inspect 或 --inspect-brk 开启,配合 IDE 能够非常方便地调试代码,本章就上一章已完成的项目 licg9999/nodejs-server-ex...

乌柏木31阅读 3.9k评论 9

从零搭建 Node.js 企业级 Web 服务器(八):网络安全
计算机网络依据 TCP/IP 协议栈分为了物理层、网络层、传输层、应用层,通常基础设施供应商会解决好前三层的网络安全问题,需要开发者自行解决应用层的网络安全问题,本章将着重表述应用层常见的网络安全问题及处...

乌柏木33阅读 5.8k评论 1

2.8k 声望
2.7k 粉丝
宣传栏