本文档为 SpringBoot-API-Scanne使用手册，旨在帮助用户快速理解工具框架、核心原理、关键技术，并掌握完整的使用流程。本工具是一款专为 SpringBoot 项目设计的自动化接口扫描工具，可实现接口信息提取、注解解析、标准化 Excel 报告生成。

一、工具框架

SpringBoot-API-Scanner 采用分层架构设计，核心目标是实现“输入-解析-处理-输出”的全流程自动化，各层职责清晰、解耦性强，便于扩展与维护。整体框架分为 4 层，自上而下依次为：

1.1 命令行接口层（CLI Layer）

核心职责：接收用户输入参数，完成任务调度与流程启动。

核心组件：基于 Picocli 框架开发，提供简洁的命令行交互能力，支持用户通过参数指定扫描路径、输出路径、配置文件等核心信息。该层是工具与用户的交互入口，负责参数合法性校验、任务初始化与结果反馈。

1.2 核心扫描引擎层（Core Scanner Layer）

核心职责：完成 Java 源码遍历、接口信息提取与注解解析，是工具的核心业务层。

核心模块：

• 目录遍历模块：递归扫描指定路径下的 .java 源码文件，过滤非源码文件（如编译后的 .class 文件、配置文件等）；

• 双重解析模块：集成 AST 解析与文本降级解析两种模式，实现注解与接口信息的精准提取；

• 接口识别模块：识别控制器类（@RestController/@Controller）与接口方法（@GetMapping/@PostMapping 等），构建完整接口路径（类路径 + 方法路径）。

1.3 数据模型层（Data Model Layer）

核心职责：标准化存储扫描提取的接口信息，为后续报告生成提供结构化数据支撑。

核心模型：

• ApiInfo：存储单个接口的完整信息，包括控制器类名、方法名、HTTP 方法、接口路径、参数列表、返回类型、注解详情等；

• ParamInfo：存储接口参数信息，包括参数名称、类型、关联注解（如 @RequestParam/@PathVariable）等；

• AnnotationDetail：存储注解的键值对信息，支持嵌套注解、单值注解、标记注解的标准化存储。

1.4 输出层（Export Layer）

核心职责：将结构化的接口信息转换为标准化的输出文件（当前默认支持 Excel，可扩展其他格式）。

核心组件：基于 Apache POI 框架开发，实现多工作表 Excel 生成，包括接口概览表、权限配置详情表、控制器分组表，支持 24+ 维度信息的完整展示与统计数据计算。

二、核心原理

工具的核心逻辑是“源码解析-信息提取-数据聚合-报告生成”，其中最关键的是“双重解析机制”与“接口信息构建流程”，确保扫描的准确性与兼容性。

2.1 双重解析机制原理

为解决单一解析模式的局限性，工具采用“AST 解析为主、文本解析为辅”的双重策略，最大化提升解析成功率：

2.1.1 AST 抽象语法树解析（精准模式）

原理：基于 JavaParser 库将 Java 源码解析为抽象语法树（AST），通过遍历语法树的 ClassDeclaration（类声明）、MethodDeclaration（方法声明）、AnnotationExpr（注解表达式）节点，精准提取类/方法上的注解信息与结构信息。

优势：可准确识别嵌套注解（如 @PreAuthorize("hasRole('ADMIN') and hasPermission('/user','edit')")）、枚举值、注解属性键值对等复杂结构，解析误差极低。

适用场景：标准 SpringBoot 项目、语法规范的 Java 源码。

2.1.2 文本降级解析（兼容模式）

原理：当 AST 解析失败（如遇到非标准语法糖、复杂泛型、损坏的源码文件）时，自动触发文本解析模式。通过逐行读取源码文本，利用正则表达式匹配关键注解（如 @RestController、@GetMapping）、接口路径、参数定义等特征字符串，实现信息提取。

优势：容错性极强，可处理非标准代码或 AST 解析不支持的特殊场景，避免因单个文件解析失败导致整个扫描任务中断。

适用场景：非标准源码、存在语法糖的复杂代码、AST 解析失败的异常场景。

2.2 接口信息构建流程

1. 目录遍历：根据用户指定的代码路径，递归遍历所有 .java 文件；

2. 文件筛选：过滤非控制器相关文件（仅保留包含 @RestController/@Controller 注解的类文件）；

3. 注解解析：通过双重解析机制，提取类级别注解（如 @RequestMapping 类路径）与方法级别注解（如 @GetMapping 方法路径、@RamCheck 安全注解）；

4. 接口路径构建：拼接类级别路径与方法级别路径，处理斜杠重复/缺失问题（如类路径 "/user" + 方法路径 "/list" → 完整路径 "/user/list"）；

5. 参数与返回值提取：解析方法参数的类型、名称、关联注解（如 @RequestParam），以及方法返回类型；

6. 数据聚合：将提取的信息封装为 ApiInfo 与 ParamInfo 对象，汇总为 List<ApiInfo> 结构化数据；

7. 报告生成：将结构化数据写入 Excel 多工作表，计算统计信息（接口总数、需权限接口数等）并添加时间戳。

三、关键技术

工具核心功能的实现依赖以下关键技术，覆盖解析、交互、输出等核心环节：

3.1 JavaParser 语法解析技术

核心作用：实现 AST 抽象语法树解析，是精准提取接口信息的核心技术。通过 JavaParser 的 ParserConfiguration 配置解析规则，利用 Visitor 模式（访问者模式）遍历语法树节点，高效提取类、方法、注解的关键信息。

3.2 Picocli 命令行交互技术

核心作用：构建轻量级命令行交互能力，支持用户通过参数指定扫描路径、输出路径、配置文件等。通过注解式参数定义（如 @Option(names = {"-s", "--source"}, required = true, description = "源码路径")），简化参数解析逻辑，提升用户使用便捷性。

3.3 Apache POI Excel 生成技术

核心作用：实现多工作表 Excel 报告的生成与格式化。通过 XSSFWorkbook 构建 Excel 工作簿，利用 CellStyle 统一单元格格式，支持批量数据写入与统计信息计算，确保报告的标准化与可读性。

四、使用指导

本工具为可执行 JAR 包，无需额外部署，直接通过命令行运行即可完成扫描任务。以下是完整的使用流程与参数说明：

4.1 前置条件

• 环境要求：JDK 8 及以上版本（需配置 JAVA_HOME 环境变量，确保 java 命令可正常执行）；

• 工具准备：获取 springboot-api-scanner-2.0.0.jar 包（可通过 Maven/Gradle 构建或直接下载官方发布包）；

• 权限要求：对指定的 SpringBoot 项目源码路径拥有读取权限，对输出路径拥有写入权限。

4.2 核心命令格式

基础命令（核心参数：源码路径）：

java -jar springboot-api-scanner-2.0.0.jar 【你的 SpringBoot 项目源码路径】

注意：打包jar环境是jdk17，所以运行jar需要jdk>=17

4.3 完整参数说明

工具支持多个可选参数，用于定制扫描范围、输出格式等，参数说明如下：

参数名称	简写	是否必选	描述	示例
--output	-o	否	Excel 报告输出路径（默认输出到当前目录，文件名：api-scan-report-{时间戳}.xlsx）	-o D:\reports\api-scan
--help	-h	否	查看帮助信息（输出所有参数说明）	-h
--version	-v	否	查看工具版本	-v

4.4 实操步骤示例

步骤 1：准备源码与工具

假设：

• SpringBoot 项目源码路径：D:\projects\springboot-demo\src\main\java

• 工具 JAR 包路径：D:\tools\springboot-api-scanner-2.0.0.jar

下载：【免费】SpringBoot-API-Scanne工具是一款专为SpringBoot项目设计的自动化接口扫描工具，可实现接口信息提取、注解解析、标准化Excel报告生成资源-CSDN下载

• 计划输出报告路径：D:\reports

步骤 2：执行扫描命令

打开命令提示符（CMD）或终端，进入工具 JAR 包所在目录，执行以下命令：

cd D:\tools java -jar springboot-api-scanner-2.0.0.jar D:\projects\springboot-demo\src\main\java -o D:\reports

步骤 3：查看执行结果

• 成功执行：命令行输出“扫描完成，报告路径：D:\reports\api-scan-report-20260108153020.xlsx”（时间戳为实际执行时间）；

• 失败排查：若执行失败，查看命令行输出的日志信息（如“源码路径不存在”“权限不足”“解析异常”等），根据日志提示修正问题后重新执行。

步骤 4：解读扫描报告

打开生成的 Excel 报告，包含 3 个核心工作表：

• 接口概览：展示所有接口的核心信息（接口路径、HTTP 方法、控制器类名、是否需权限等），并统计接口总数、需权限接口数等核心数据；

• 权限配置详情：聚焦安全注解（@RamCheck、@PreAuthorize 等），详细列出每个接口的权限要求，用于安全审计；

• 控制器分组：按控制器类名聚合接口信息，便于按业务模块查看接口分布。

五、总结

SpringBoot-API-Scanner 2.0.0 是一款聚焦 SpringBoot 项目接口治理的轻量化自动化工具，通过“双重解析机制”实现接口信息的精准提取与兼容扫描，以标准化 Excel 报告为输出载体，为接口管理、安全审计、API 文档整理提供高效支撑。

适用人群：SpringBoot 项目开发人员、测试人员、安全审计人员、架构治理人员。通过本工具，可大幅降低接口信息整理的人工成本，提升接口治理的效率与准确性，是 SpringBoot 微服务项目全生命周期管理的得力工具。