gabriel-glodean/constants_tracker

# Constant Tracker 一个用于使用 **Solr** 对 **Java 字节码常量** 和 **配置文件常量** 进行快速搜索和分析的 Spring Boot (WebFlux) 服务。 该项目始于对 JVM 类文件结构的探索——解析常量池、解析引用，并将它们索引到 Solr 中以供查询和可视化。 项目的重点是 **字节码分析正确性**，同时也支持配置文件分析（YAML、Properties）。 --- ## 🧠 设计重点 该项目分为 **五个模块**，以实现清晰的分离和高可复用性： - **`constant-extractor-api`** 模块定义了共享模型、SPI 接口（`ConstantUsageInterpreter`、`ModelExtractor`）和上下文类型。它不依赖任何框架，是所有提取器实现之间的契约。 - **`constant-extractor-bytecode`** 模块实现了 **JVM ClassFile 解析器**（兼容 class 文件格式版本 69 / JDK 25）以及常量使用提取器。它包含六个语义分类器：日志、SQL、URL/资源、文件路径、错误消息、注解。其测试覆盖率超过 **90%**，验证了所有支持的常量类型，包括 `invokedynamic`、方法句柄和引导方法。 - **`constant-extractor-config-file`** 模块从 YAML（`.yml`/`.yaml`）和 Java 属性（`.properties`）文件中提取常量，并复用 `constant-extractor-api` 中的共享模型。 - **`constant-tracker-app`** 模块提供了一个基于 WebFlux 的响应式 Web 服务。Redis、Solr 和 Postgres 层作为核心分析引擎的集成、缓存和持久化外壳。支持项目版本生命周期管理（开放 → 最终化），并包含 Docker 和 Terraform 部署。 - **`search-ui`** 模块是一个轻量级的 Web UI，用于搜索、浏览、上传和管理已索引的常量与项目版本。它作为一个静态站点提供，并与后端 API 通信。 提取库也可以在需要字节码或配置文件分析能力的任何 Java 项目中 **独立使用**。 此外，**`demo-crud-server`** 模块是一个无框架的 Java 应用程序，用于测试——它尽可能多地执行 SQL、URL、文件路径等语义类型，以验证提取管道。 --- ## 🧩 架构 这是一个 **多模块 Gradle 项目**，关注点分离清晰： ### 模块 1. **`constant-extractor-api`** – 共享模型与 SPI - 模型记录（`UnitConstants`、`UnitConstant`、`UnitDescriptor`、`UsageType`、`SemanticType`） - `ConstantUsageInterpreter` 策略接口 + 上下文类型 - `ModelExtractor` 接口 - 无外部依赖 2. **`constant-extractor-bytecode`** – 核心字节码分析库 - JVM ClassFile 解析器（格式版本 69 / JDK 25） - 常量池提取与解析 - 六个语义分类器：日志、SQL、URL/资源、文件路径、错误消息、注解 - `ConstantUsageInterpreterRegistry` 用于连接分类器 - 依赖 `constant-extractor-api` 和 Guava 3. **`constant-extractor-config-file`** – 配置文件分析库 - YAML 提取器（SnakeYAML） - Java 属性提取器 - 依赖 `constant-extractor-api` 4. **`constant-tracker-app`** – Spring Boot 应用程序 - 响应式 REST API（WebFlux） - Redis 缓存层 + 版本控制 - Solr 索引集成 - 使用 Postgres 的数据库持久化（R2DBC + Flyway 迁移） - 项目版本生命周期管理（开放 → 最终化） - Docker 和 Terraform 部署 - 依赖所有三个提取模块 5. **`search-ui`** – 基于 Web 的搜索界面 - React 19 + TypeScript + Tailwind CSS v4 - 模糊搜索、类查找、文件上传（class/JAR/config）、版本管理 - 位于 `search-ui/` 目录，作为静态站点通过 Nginx 提供服务 6. **`demo-crud-server`** – 测试夹具应用 - 无框架的 Java HTTP 服务器，提供 CRUD 端点 - 执行 SQL、URL、文件路径等常量类型提取测试 ### 数据流 **类/JAR/配置文件上传与索引：** ``` [ .class/.jar/.yml/.properties upload ] │ ▼ [ WebFlux Controller ] (constant-tracker-app) │ ▼ [ Analysis Engine ] (constant-extractor-bytecode / constant-extractor-config-file) │ ▼ [ Redis Cache ] → [ Solr Index + Postgres DB ] (constant-tracker-app) ``` **类与项目查询：** ``` [ class and project query ] │ ▼ [ WebFlux Controller ] (constant-tracker-app) │ ▼ [ Redis Cache ] → [ Postgres DB ] (constant-tracker-app) ``` **模糊搜索常量查询：** ``` [ fuzzy search constant query ] │ ▼ [ WebFlux Controller ] (constant-tracker-app) │ ▼ [ Redis Cache ] → [ Solr Index ] (constant-tracker-app) ``` --- ## 🛠️ 技术栈 **后端：** - Spring Boot 3 / WebFlux – 响应式 REST 接口 - Solr 10 – 常量引用的全文索引 - Postgres 17 – 关系型数据库，用于存储类常量使用的详细元数据和应用状态（R2DBC + Flyway） - Redis 7 – 缓存 - Java 25 – 使用最新特性，包括 ClassFile API **前端（search-ui）：** - React 19 + TypeScript – UI 框架与语言 - Vite 8 – 构建工具与开发服务器 - Tailwind CSS v4 – 实用优先的 CSS 框架 - Lucide React – 图标库 - 原生 fetch API – 与后端通信 - ESLint – 代码检查 - Nginx – 生产环境中的静态文件服务 - Docker – 容器化部署 --- ## 🖥️ 用户界面 该项目包含一个用于浏览、查询、上传和管理已索引常量的搜索 UI。 - **位置：** `search-ui/` 目录（作为静态站点提供） - **功能：** - 跨项目的模糊常量搜索 - 按项目/类/版本查找类常量 - 文件上传（`.class`、`.jar`、`.yml`/`.yaml`、`.properties`） - 版本管理（查找、关闭/最终化、同步删除、删除单元） - **访问方式：** - 使用 Docker Compose 运行时，UI 可通过以下地址访问：[http://localhost:5173](http://localhost:5173) - UI 与后端 API 通信地址：[http://localhost:8080](http://localhost:8080) --- ## 🗄️ 数据库 应用程序使用三个主要数据存储： - **Solr 9/10**：常量引用的全文搜索与索引。 - 默认 URL：[http://localhost:8983/solr/](http://localhost:8983/solr/) - 集合：`Constants` - Schema：`constant-tracker-app/solr/managed-schema.xml` - ⚠️ 启动 Solr 前，请将 schema 文件复制到 Solr 的数据文件夹（详见下文）。 - **Postgres**：用于持久化存储元数据和应用状态的关系型数据库。 - 默认 URL：`jdbc:postgresql://localhost:5432/constants` - ⚠️ 启动 Postgres 前，请确保在环境变量中指定了数据库凭据。 - **Redis 7**：缓存与版本控制。 - 默认 URL：`localhost:6379` 所有服务均可通过 Docker Compose 在本地开发环境中自动启动。 **Solr Schema 设置：** 在启动 Solr 前复制 schema 文件： **Solr 核心设置（必需）：** 在启动 Solr 前，请将以下文件复制到 Solr 核心的配置目录中。此步骤对于正确的索引和搜索功能是必需的： - `constant-tracker-app/solr/managed-schema.xml` → `/conf/managed-schema.xml` - `constant-tracker-app/solr/solrconfig.xml` → `/conf/solrconfig.xml` - `constant-tracker-app/solr/core.properties` → `/core.properties` 将 `` 替换为你的 Solr 核心目录（例如 `constant-tracker-app/solr/data/Constants`）。 **PowerShell（Windows）：** ``` Copy-Item constant-tracker-app/solr/managed-schema.xml /conf/managed-schema.xml -Force Copy-Item constant-tracker-app/solr/solrconfig.xml /conf/solrconfig.xml -Force Copy-Item constant-tracker-app/solr/core.properties /core.properties -Force ``` **Bash（Linux/macOS）：** ``` cp constant-tracker-app/solr/managed-schema.xml /conf/managed-schema.xml cp constant-tracker-app/solr/solrconfig.xml /conf/solrconfig.xml cp constant-tracker-app/solr/core.properties /core.properties ``` 将 `` 替换为你的 Solr 核心目录（例如 `constant-tracker-app/solr/data/Constants/conf` 用于配置文件，`constant-tracker-app/solr/data/Constants` 用于 core.properties）。 --- ## 🐳 使用 Docker Compose 快速启动 要本地启动完整栈（后端、Solr、Postgres、Redis 和 UI），你必须首先构建后端和前端（UI）Docker 镜像： **1. 构建容器：** ``` docker build -f constant-tracker-app/Dockerfile -t constant_tracker:latest . ``` **2. 构建前端（UI）容器：** ``` docker build -f search-ui/Dockerfile -t search_ui:latest ./search-ui ``` **3. 使用 Docker Compose 启动所有服务：** ``` docker compose up -d ``` 这将启动： - **API**：[http://localhost:8080](http://localhost:8080) - **Solr UI**：[http://localhost:8983/solr/#/](http://localhost:8983/solr/#/) - **Postgres**：`localhost:5432` - **Swagger UI**：[http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html) - **搜索 UI**：[http://localhost:5173](http://localhost:5173) - **Redis**：`localhost:6379`（无 Web UI） 你现在可以上传 `.class`、`.jar` 或配置文件，并使用 UI 搜索已索引的常量。 --- ## 🧪 测试 ### 运行所有测试 ``` ./gradlew test # Run tests in all modules ./gradlew testAll # Alternative: run all tests and show summary ./gradlew testReport # Generate combined test report ``` ### 运行重型测试（JRT 文件系统分析） ``` ./gradlew :constant-tracker-app:heavyTest # Run with 16GB heap ``` ### 模块特定测试 - **`constant-extractor-bytecode`**：> 85% 覆盖率（JaCoCo 报告位于 `constant-extractor-bytecode/build/jacocoHtml`） - **`constant-extractor-config-file`**：> 85% 覆盖率（JaCoCo 报告位于 `constant-extractor-config-file/build/jacocoHtml`） - **`constant-tracker-app`**：集成测试，验证上传、缓存和 Solr 索引 ### 测试报告 - 合并报告：`build/reports/allTests/index.html` - 每个模块的 JaCoCo：`{module}/build/jacocoHtml/index.html` --- ## 📦 模拟文件与示例 测试资源中包含示例 `.class` 和 `.java` 文件： - `.class` 文件：`constant-extractor-bytecode/src/test/resources/samples/` 和 `constant-tracker-app/src/test/resources/samples/` - `.java` 文件：`constant-extractor-bytecode/src/test/java/org/glodean/constants/samples/` 它们可用于测试或演示分析过程，而无需编译自己的 Java 源代码。 ``` # 示例：分析提供的模拟类 curl -X POST "http://localhost:8080/class?project=samples" \ -H "Content-Type: application/octet-stream" \ --data-binary @constant-extractor-bytecode/src/test/resources/samples/Greeter.class ``` --- ## 📸 截图 在 Postman 中可以按如下方式保存 Greeter.class 文件：  你可以通过 Postman 检查是否已存储：  或使用 Solr UI：  UI 界面如下所示：  --- ## 🧩 技术亮点 - 自定义 JVM 常量池解析器（字段、方法、字符串、类引用、动态调用） - 支持 `invokedynamic` 和引导方法解析 - 六个语义分类器：日志、SQL、URL/资源、文件路径、错误消息、注解 - 配置文件提取：YAML 和 Java 属性 - 将常量与元数据导出为 Solr 文档 - 项目版本生命周期管理与继承、删除同步 - 响应式且容器就绪（WebFlux + Redis + Solr + Postgres） - 基于 JDK 25 构建与测试（大约可在分配 16GB JVM 内存的 i7-13620 上分析所有 Java 25 运行时，耗时约 2.5 分钟） --- ## 📚 API 文档 - Swagger UI：/swagger-ui.html 或 /swagger-ui/index.html - OpenAPI JSON v3/api-docs --- ## 🛠️ 本地构建与运行 ### 构建所有模块 ``` ./gradlew clean build ``` ### 运行应用程序 ``` # 从根目录 ./gradlew :constant-tracker-app:bootRun # 或者运行已构建的 JAR java -jar constant-tracker-app/build/libs/constant-tracker-app-0.1.0-SNAPSHOT.jar ``` ### 仅构建库 ``` ./gradlew :constant-extractor-api:build ./gradlew :constant-extractor-bytecode:build ./gradlew :constant-extractor-config-file:build ``` 构建后的 JAR 文件将位于每个模块的 `build/libs/` 目录中。 --- ## 📜 许可证 MIT © Gabriel Glodean

标签：API, ClassFile, invokedynamic, JDK25, JVM, Maven, Mutation, PostgreSQL, Properties, Reactive, Redis, SEO, Solr, SPI, Spring Boot, SQL常量, URL资源, WebFlux, WebSocket, YAML, 依赖分析, 可视化, 后台面板检测, 域名枚举, 字节码正确性, 安全库, 常量池, 常量追踪, 引导方法, 搜索引擎, 文件路径, 方法句柄, 日志常量, 模块设计, 注解, 漏洞验证, 类文件解析, 覆盖率测试, 请求拦截, 错误信息, 静态网站