简介

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

背景

开发痛点:

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

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

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

分析需求

不写代码:需要一个"0"开发,实现任意service接口方法,发布web api机制,才能够通过http直接请求需要"诊断"方法。
极速测试:发布的快速接口需要有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提升研发调试友好性能够提供一些帮助.