管理平台接口文档,优化业务流程的灵魂之匙
531
2023-02-10
本文目录一览:
假设实现一个注册用户的功能,在controller 层,他会先进行校验参数,如下:
以上代码有什么问题嘛? 其实没什么问题,就是校验有点辣眼睛 。正常的添加用户业务还没写,参数校验就一大堆啦。假设后来,又接了一个需求:编辑用户信息。实现编辑用户信息前,也是先校验信息,如下:
我们可以使用注解的方式,来进行参数校验,这样代码更加简洁,也方便统一管理。实际上, spring boot 有个 validation 的组件,我们可以拿来即用。引入这个包即可:
引入包后,参数校验就非常简洁啦,如下:
然后在 UserParam 参数对象中,加入 @Validated 注解哈,把错误信息接收到 BindingResult 对象,代码如下:
如果你在你们项目代码中,看到controller 层报文返回结果,有这样的:
也有这样的:
显然,如果接口返回结果不统一,前端处理就不方便,我们代码也不好维护。再比如有的人喜欢用 Result 处理结果, 有点人 喜欢用 Response 处理结果,可以想象一下,这些代码有多乱。
所以作为后端开发,我们项目的响应结果,需要 统一标准的返回格式 。一般一个标准的响应报文对象,都有哪些属性呢?
响应状态码一般用枚举表示哈:
因为返回的数据类型不是确定的,我们可以使用泛型,如下:
有了统一的响应体,我们就可以优化一下controller 层的代码啦:
日常开发中,我们一般都是自定义统一的异常类,如下:
在controller 层,很可能会有类似代码:
这块代码,没什么问题哈,但是如果 try...catch 太多,不是很优雅。
可以借助注解 @RestControllerAdvice ,让代码更优雅。 @RestControllerAdvice 是一个应用于 Controller 层的切面注解,它一般配合 @ExceptionHandler 注解一起使用,作为项目的全局异常处理。我们来看下demo代码哈。
还是原来的 UserController ,和一个会抛出异常的userService的方法,如下:
我们再定义一个全局异常处理器,用 @RestControllerAdvice 注解,如下:
我们有想要拦截的异常类型,比如想拦截 BizException 类型,就新增一个方法,使用 @ExceptionHandler 注解修饰,如下:
API管理最重要的方面包括检测,分析和报告。传统的管理格言是,“无法管理没有指标的东西。”如果企业不仅仅满足于暴露API和服务,而是要管理他们,必须要度量关键指标,并将其应用到决策制定流程里。
度量不仅仅是设置一些阀值,并且在红色警报出现时做出反应。如果没有定期收集数据、分析并且用于决策制度,企业可能能做的更多只是做出反应,而不是真正的管理。要管理API,管理工具要能够完全提供健壮的能够驱动管理决策的数据集。网关管理工具收集使用信息,验证使用在合约限制之内,如果不是,就相应拒绝或者节流该请求。要达到这个目标,指标必须完全基于流量检测。这需要涉及到比如请求数量,相应事件和消息大小。
首先说明下我最近在思考的一个产品规划,即基于ServiceMesh服务网格思路,参考开源的Istio等实现架构来搭建一个完整的微服务治理管控平台。
在前面文章里面我就提到了,在实施微服务架构后,由于微服务将传统的单体应用进行了拆分,颗粒度更细。因此整个集成的复杂度,后续的管控治理复杂度都急剧增加。
当前也出现了类似SpingCLoud主流的微服务开发框架,实现了服务注册和发现,安全,限流熔断,链路监控等各种能力。同时对于服务注册,限流,服务链监控等本身又出现了大量的开源组件,类似服务注册的Nacos,Consul,限流熔断的Sentinel,链接监控的SKyWalking等开源组件。
当我们在思考微服务开发框架和开源组件的时候你会发现。
在SpingCLoud外的各类开源组件本身和微服务开发过程是解耦的,也就是说这些开源组件更加方便地通过配置增加管控能力,或者通过下发一个SDK包或Agent代理组件来实现管控能力。以尽量减少对微服务开发过程的影响。
而对于SpingCLoud微服务框架,在使用中有一个最大的问题就是开发态和治理态的耦合,也就是说一个微服务模块在开发的时候,你会引入很多治理态的内容。类似限流熔断,类似链路监控等能力,都需要你在开发状态增加配置文件,或对接口实现类进行扩展等。
微服务开发本身应该是一个简单的事情。
其核心是实现业务功能和规则逻辑,并暴露轻量的Http Rest API接口实现和前端交互或者实现和其它微服务模块之间的横向交互协同。
也就是说如果不考虑管控治理层面的内容,你采用最小化的SpingBoot来进行微服务开发足够的,或者你仍然可以采用传统的Java架构进行微服务开发,只要确保最终暴露Http API接口即可。
但是如果要考虑治理的内容,你会发现会引入注册中心,限流熔断,安全,服务链监控一系列的管控治理组件,导致整个微服务开发过程,集成过程都复杂化。
因此构建微服务治理平台的初衷即:
在这里还是先简单梳理下业务需求和业务功能场景。
01 服务注册和服务发现
仍然需要实现最基本的当前微服务自注册,自发现能力。这个在开发阶段需要暴露的接口增加注解还是必须的。在ServiceMesh下,由于存在本地Sidecar代理,因此在本地代理和微服务一起容器化部署下去后,会扫描微服务中需要暴露的接口,并完成微服务和API接口服务的注册工作。 也就是传统的应用开发集成中,手工接口API接口服务注册和接入的过程没有了,这个过程应该彻底地自动化掉。
注意这里的注册不仅仅是到微服务粒度,而是可以到微服务API接口粒度。
因此我们需要实现在微服务部署和交付后,微服务注册和微服务中的API接口注册全部自动完成。在微服务集群扩展的时候,相关的注册信息和配置信息也自动更新和扩展。
一个微服务模块在部署和交付后。
进入到微服务治理平台就能够看到当前有哪些微服务已经注册,进入到单个微服务里面,就可以看到当前微服务究竟有哪些细粒度的API接口已经注册。
02 服务安全和双重管理
对于一个微服务暴露的API接口,可以看到部分API接口仅仅是提供给前端微服务使用,但是部分API接口是需要提供给其它横向的微服务模块使用。
一个是前端调用后端API接口,一个是后端各个微服务中心间接口交互。
在安全管理的时候实际需要对这两类API接口分别进行管理。如果仅仅是前端功能使用,那么类似JWT+Token的安全措施即可,同时对于的日志流量并不一定需要完全记录和入库。如果是横向微服务间调用,那么安全要求更高,需要支持Token,用户名密码,IP地址验证等多种安全管控要求。
对于前后端的使用,往往仅授权到微服务层级即可。但是对于横向微服务间调用,那么服务授权必须到API接口服务粒度, 能够针对单个微服务API接口独立授权和管理。
03 服务限流熔断
同样这个功能不应该在微服务开发阶段进行任何配置或代码文件的增加。
在微服务成功的部署和交付上线后,应该能够针对微服务,微服务API接口两个不同的颗粒度进行服务限流设置。当然需要支持类似并发量,时长,错误数,数据量等多种限流熔断策略。
比如一个微服务单点能够支撑的最大并发量是1000TPS,那么这就是最基本的限流条件。我只需要设置单点能量,而不是设置集群能力。管控治理平台要管理的是通过负载均衡分发后到单个节点的流量能够控制到1000TPS。如果你部署了5个微服务节点,那么实际能够支撑的最大流量就是5000TPS。
由于采用Mesh去中心化的架构模式,因此实际微服务间的调用数据流量并不会通过微服务治理平台,微服务治理平台本身并没有太大的性能负荷压力。这个是和传统的ESB或API网关不同的地方,即API网关的限流一方面是保护API网关本身,一个是保护下游的微服务模块。
04 接口调用日志记录
注意这个功能本身也是可以灵活配置的,可以配置单个微服务,也可以配置单个API接口服务是否记录日志,包括日志记录是只记录调用时间和状态,还是需要记录想的接口调用消息报文数据。
在去中心化架构模式下,接口调用日志记录相对来说很容易实现。
即通过Sidecar边车首先对消息和数据流量进行拦截,任何将拦截的数据统一推送到消息中间件,消息中间件再将日志信息存入到分布式文件存储或对象存储中。
对于接口调用日志本身应该区分日志头信息和消息日志信息,对于日志头调用记录信息应该还需要推送到类似ELK组件中,以方便进行关键日志的审计和问题排查。
05 服务链路跟踪和监控
注意,在传统的服务链跟踪中,需要在微服务端配置Agent代理。而采用Mesh化解决方案后,该部分代理能力也移动到了Sidecar边车代理中实现。
服务链路监控不仅仅是微服务和API接口间的调用链路,也包括融入常规APM应用性能监控的能力,能够实现前端界面操作后发起的整个应用链路监控。
应用链路监控一方面是进行日志和错误分析,一方面是进行性能问题排查和优化。
06 和DevOps和容器云的集成
简单来说就是开发人员只需要按照标准规范开发单个微服务模块,然后走DevOps持续集成和交付过程进行部署。
在和DevOps平台进行集成后,DevOps在进行自动化部署前会下发Sidecar代理边车,实现对微服务本身的流量拦截和各种管控治理能力。在整个过程中Sidecar对开发者不可见,满足最基本的服务透明要求。
在通过DevOps部署到容器云平台后,满足基于资源调度策略进行后续微服务集群资源的自动化动态扩展能力。同时微服务在扩展后自动进行相应的集群注册,微服务API接口注册等操作。
在传统的SpingCLoud开发框架中,本身注册中心包括了对微服务模块的心跳检查和节点状态监控能力。在和Kurbernetes集群集成和融合后,完全可以采用Kurbernetes集群本身的心跳监控能力。
简单总结
最后总结下,整个微服务治理平台基于ServiceMesh去中心化架构思路来定制,但是需要实现类似传统ESB总线或API网关的所有管控治理能力。
对于最终的使用者来说并不关心治理能力实现是否是去中心化架构,而更加关心两个点。第一个点是开发阶段不要引入治理要求,第二就是能够实现核心能力的集中化管控和可灵活配置扩展。
也就是你可能上层看到的是一个传统的SOA治理管控平台,但是底层却是采用了去中心化的ServiceMesh架构来实现微服务治理管控能力。
作为一个前后端分离模式开发的团队,我们经常会看到这样的场景:前端开发和后端开发在一起热烈的讨论“你这接口参数怎么又变了?”,“接口怎么又不通了?”,“稍等,我调试下”,“你再试试..."。
那能不能写好接口文档,大家都按文档来开发?很难,因为写文档、维护文档比较麻烦,而且费时,还会经常出现 API 更新了,但文档还是旧的,各种同步不一致的情况,从而耽搁彼此的时间。
之前我们团队也遇到了同样的问题,那么作为研发团队的负责人,我是如何带领团队解决这个问题的呢?
方法其实很简单,如果能做到让写文档/维护文档这件事情的短期收益就能远高于付出的成本,那么所有问题都能迎刃而解,开发人员就会非常乐意去写接口文档。
要做到写文档和及时维护文档的短期收益就能远高于付出的成本,无非两个方向:
鉴于此,我们设想如果有一款工具做到以下这些是不是就非常爽了?
总结下来,我们需要的就是这么一款工具:
为此,我们几乎尝遍了市面上所有相关的工具,但是很遗憾,没有找到合适的。
于是,我们自己实现了一个Postman + Swagger + RAP + JMeter
这个工具就是 Apifox,经常很长一段时间不断更新迭代后,我们基本上完全实现了最初的设想,几乎完美解决了最开始遇到的所有问题,在公司内部大受欢迎。并且也形成了我们自己的最佳实践。
没错,现在我们已经将Apifox产品化对外服务了,你们团队也可以直接使用Apifox了。
官网:www.apifox.cn
Apifox = Postman + Swagger + Mock + JMeter
Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。
通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据 Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确!
节省研发团队的每一分钟!
如果你认为 Apifox 只做了数据打通,来提升研发团队的效率,那就错了。Apifox 还做了非常多的创新,来提升开发人员的效率。
通常一个接口会有多种情况用例,比如 正确用例 参数错误用例 数据为空用例 不同数据状态用例。定义接口的时候定义好这些不同状态的用例,接口调试的时候直接运行,非常高效。
可以独立定义数据模型,接口定义时可以直接引用数据模型,数据模型之间也可以相互引用。同样的数据结构,只需要定义一次即可多处使用;修改的时候只需要修改一处,多处实时更新,避免不一致。
使用 Apifox 调试接口的时候,系统会根据接口文档里的定义,自动校验返回的数据结构是否正确,无需通过肉眼识别,也无需手动写断言脚本检测,非常高效!
Apifox 自动校验数据结构
设置断言:
Apifox 设置断言
运行后,查看断言结果:
先放一张图对比下 Apifox 和其他同类工具 零配置 mock 出来的数据效果:
Apifox Mock 数据结果对比同类工具
可以看出 Apifox 零配置 Mock 出来的数据和真实情况是非常接近的,前端开发可以直接使用,而无需再手动写 mock 规则。
「Apifox 如何做到高效率、零配置生成非常人性化的 mock 数据」
Apifox 项目可“在线分享” API 文档,分享出去的 API 文档可设置为公开或需要密码访问,非常方便与外部团队协作。
体验地址:https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285
根据接口模型定义,自动生成各种语言/框架(如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等)的业务代码(如 Model、Controller、单元测试代码等)和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。
更重要的是:你可以通过自定义代码模板来生成符合自己团队的架构规范的代码,满足各种个性化的需求。
接口调试
Apifox 多种主题色可选
关于后端api接口管理和前端调用api接口的介绍到此就结束了,不知道你从中找到你需要的信息了吗 ?如果你还想了解更多这方面的信息,记得收藏关注本站。 后端api接口管理的介绍就聊到这里吧,感谢你花时间阅读本站内容,更多关于前端调用api接口、后端api接口管理的信息别忘了在本站进行查找喔。版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。
发表评论
暂时没有评论,来抢沙发吧~