fast-api 一款快速将spring的bean发布成接口并生产对应swagger文档调试的轻量级工具

简介

fast-api 一款快速将spring的bean(service)发布成接口并生产对应swagger文档的轻量级工具

背景

开发痛点:

在开发阶段自测,或者排查生产测试环境bug, 需要调试具体一段业务逻辑,如XxxService.doSomething(param1, param2,…), 发现没有项目里没有controller接口对应
接口直接调用去验证。这个时候一般两个做法

• 找到最终会调用这个业务逻辑的controller方法. 通过该接口去请求. 但是中间可能经过很多业务,查库计算,必须分析用什么数据合适,导致入口http接口造数据特别麻烦.
• 还有一种方式写单元测试,直接调用该业务逻辑.但是还要写代码,多次调试还要,重新运行。项目大的启动费时费力

可能上面两种操作都是程序员的基本操作,但是笔者是一个“超级懒人”。执行一次可以,写多次就真的不能忍了。

分析需求

1. 不写代码:需要一个"0"开发,实现任意service接口方法,发布web api机制,才能够通过http直接请求需要"诊断"方法。

2. 极速测试:发布的快速接口需要有uri规则,能够通过http测试工具方便构造请求地址, 请求参数也要,能够与service接口方法参数绑定. 得知道项目有那些接口发布了,请求最好有示例.

根据需求分析,发现没有现成技术实现上面的能力, 因此开发实现了fast-api组件的初版

实战fast-api

快速上手

使用技术

• spring-boot.version 2.3.2.RELEASE
• springfox-swagger.version 2.10.5

推荐接入项目使用接近版本,保证兼容性.

1. 引入依赖

springboot引入fast-api-spring-boot-starter的maven

        <dependency><groupId>io.github.easycode8</groupId><artifactId>fast-api-spring-boot-starter</artifactId><version>1.1.0</version></dependency>

2. @FastApiMapping标记service对象

fast-api默认扫描@FastApiMapping标记Bean的所有公开方法,发布成web接口

@FastApiMapping
@Service
public class HelloService {//请求json: {"name": "李四"}public String sayHello(String name) {return "hello " + name;}//请求json: {"name": "李四", age: 18}private  String sayHello2(String name, int age) {return "name:" + name + " age:" + age;}//请求json: {"account":[{"username":"张三"}], "name": "李四"}private  List<Account> sayHello3(List<Account> account, String name) {System.out.println(name);return account;}
}

• 请求说明
  • 请求method: POST
  • 请求uri格式: /fast-api/ServiceName/methodName/参数名
  • 请求方式: json 根据bean方法key:value构造json请求请求体.
• 请求示例
  • curl -X POST “http://127.0.0.1:8080/fast-api/HelloService/sayHello/name” -H “Content-Type:application/json” -d “{“name”:“zhangsan”}”

3. swagger2/knife4j 在线测试

框架已经通过springfox-swagger2整合swagger2/knife4j 可以通过在线接口文档测试Service方法的接口.

接入项目只要集成swagger2/knife4j可以自动识别fast-api接口.springfox-swagger.version版本基于2.10.5

效果:

请求测试

进阶使用

开启调试模式

fast-api默认扫描@FastApiMapping类注释的所有公开方法. 但是还是要写一个注解标记. 能不能再偷懒点? 没问题,开启service-debug模式,@Service标记的bean的public方法自动发布成http接口,无需注解@FastApiMapping

spring:fast-api:service-debug: true #默认false

适合场景: 开发阶段,调试所有service方法,“指哪打哪”,简直不要太快乐

支持指定类或包目录发布

• service-debug 模式虽然很强大,但是范围太大了. 不仅自己service发布接口,可能第三方的包也可能发布.
• @FastApiMapping 虽然可以指定,但是写很麻烦,而且第三方别人的包,导入进来,别人代码写不了.

没关系,这些问题框架也想到了, 框架提供includes模式,可以指定类或者包通配发布fast-api接口

spring:fast-api:includes:- com.demo.service.impl.HelloServiceImpl #按类名匹配- com.demo.service.impl.* #按包路径匹配# - 可以配置多行

incloudes模式是不限制@Service标记的bean对象. 只要是bean对象(除controller外), 都可以发布

适合场景: 不管是本项目的代码还是其他业务maven导入的代码,都可以包的维度来控制发布fast-api.

如何关闭fast-api

如果测试/生产环境需要临时开启和关闭fast-api能力,框架也提供了支持.

spring:fast-api:enabled: false #默认true

自定义fast-api的前缀

spring:fast-api:prefix: you_prefix #默认 fast-api

写在最后

fast-api诞生于,研发"偷懒思维", 提升工作效率. 它看起来是"Service层的controller"或是"service层的restful.“, 是不是破坏了mvc的三层结构呢. 前后端分离大行其道背景下, controller接口越来越成为接口发布能力,弱化了视图的能力.这样场景下, controller写起来多少有点嫌弃 但是它依然是重要的. 毕竟设计模式或分层结构.都是为了团队协作下代码的可读性服务. controller该写还是要写. 但是"偷懒是第一生产力”,希望fast-api提升研发调试友好性能够提供一些帮助.

• 使用场景不限于
  • 日常service业务逻辑直连快速调试
  • service发布web接口, 可用于外部自动化系统http测试业务
  • 新老项目过度, 调用旧项目能力,免写controller层,提供接口发布能力

最后,欢迎收藏点赞评论,留下你宝贵的意见或者建议.