# sqltree

**Repository Path**: he-zhi-heng/sqltree

## Basic Information

- **Project Name**: sqltree
- **Description**: 一个简化的sql分析工具
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-08-19
- **Last Updated**: 2025-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: utils

## README

# SQL Tree Core - Service调用追踪核心模块

## 功能特性

SQL Tree Core 是一个强大的服务调用追踪模块，主要用于追踪和分析服务层方法调用及相关的SQL执行情况。主要功能包括：

- **服务调用追踪**：自动追踪服务层方法调用，记录调用链路和执行时间。
- **SQL执行监控**：监控SQL执行情况，包括执行时间、影响行数、错误信息等。
- **性能分析**：支持慢SQL分析、错误SQL统计、执行时间分布等功能。
- **可视化展示**：提供基于Web的可视化界面，展示调用链路和SQL执行详情。
- **灵活配置**：支持多种配置选项，包括采样率、最大深度、慢SQL阈值等。

## 快速开始

### 1. 引入依赖

在你的Spring Boot项目中，添加以下依赖：

```xml
<dependency>
    <groupId>com.he.sqltree</groupId>
    <artifactId>sqltree-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 基本配置

在`application.yml`中添加以下配置：

```yaml
sql-tree:
  aspect:
    enabled: true
    include-packages:
      - com.he.example.service
    exclude-packages:
      - com.he.example.service.util
    include-classes:
      - com.he.example.service.OrderService
    exclude-classes:
      - com.he.example.service.UserService
  slow-sql-threshold: 1000
  trace-enabled: true
  max-depth: 10
  sampling-rate: 100
  max-sql-length: 1000
```

### 3. 使用示例

#### 场景1：默认配置

默认情况下，SQL Tree Core会自动追踪所有符合命名规范的服务类（如`*Service`, `*ServiceImpl`等），无需额外配置。

#### 场景2：自定义包范围

通过`include-packages`和`exclude-packages`配置项，可以指定需要追踪的服务类所在的包范围。

#### 场景3：自定义类名模式

通过`include-classes`和`exclude-classes`配置项，可以指定需要追踪的具体服务类。

#### 场景4：性能优化

通过调整`max-depth`和`slow-sql-threshold`参数，可以优化性能并减少内存占用。

#### 场景5：完全禁用

将`trace-enabled`设置为`false`，可以完全禁用SQL追踪功能。

## 支持的Service类识别规则

SQL Tree Core支持以下几种Service类识别规则：

1. **注解识别**：通过`@Service`注解识别服务类。
2. **命名约定**：支持常见的命名约定，如`*Service`, `*ServiceImpl`, `*Manager`, `*Provider`, `*Handler`等。
3. **排除规则**：可以通过配置排除特定的类或包。

## 监控统计

SQL Tree Core提供了丰富的监控统计功能，包括：

- **总SQL执行次数**
- **慢SQL次数**
- **错误SQL次数**
- **SQL平均执行时间**
- **最大调用深度**

可以通过`/api/sql-tree/statistics`接口获取当前的统计信息。

## 配置优先级

SQL Tree Core的配置优先级如下：

1. **运行时API配置**：通过`/api/sql-tree/config`接口动态修改的配置具有最高优先级。
2. **配置文件配置**：在`application.yml`中配置的参数次之。
3. **默认配置**：未配置时使用默认值。

## 最佳实践

### 1. 生产环境配置

在生产环境中，建议将`sampling-rate`设置为较低的值（如10-50），以减少性能影响。同时，适当提高`slow-sql-threshold`（如1000ms）以避免过多的慢SQL记录。

### 2. 开发环境配置

在开发环境中，建议将`sampling-rate`设置为100，以便全面监控SQL执行情况。同时，将`slow-sql-threshold`设置为较低的值（如200ms），以便及时发现潜在的性能问题。

### 3. 测试环境配置

在测试环境中，建议启用所有监控功能，并定期导出和分析SQL执行数据，以优化数据库性能。

## 注意事项

- **性能影响**：SQL追踪功能会对性能产生一定影响，建议在生产环境中适当调整采样率和最大深度。
- **内存占用**：大量SQL记录可能会占用较多内存，建议定期清理或导出数据。
- **兼容性**：SQL Tree Core基于Spring AOP和MyBatis拦截器实现，确保你的项目使用了这些技术栈。

## 更新日志

### v1.0.0

- 初始版本，包含核心的SQL追踪和监控功能。
- 提供基于Web的可视化界面。
- 支持多种配置选项和API接口。

## 贡献指南

欢迎贡献代码和文档！请遵循以下步骤：

1. Fork仓库。
2. 创建新分支。
3. 提交代码更改。
4. 创建Pull Request。

## 许可证

本项目使用MIT许可证。详情请参阅[LICENSE](LICENSE)文件。