Skip to content

architecture.md

Latest commit

 

History

History
264 lines (205 loc) · 14.7 KB

architecture.md

File metadata and controls

264 lines (205 loc) · 14.7 KB

Druid 架构概览 | Architecture Overview

English | 中文

中文

整体架构

Druid 由四大核心子系统组成，各子系统通过清晰的 API 边界协作：

┌──────────────────────────────────────────────────────────┐
│                     Application Layer                     │
│               (Spring Boot / Direct JDBC)                 │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                   DruidDataSource                         │
│            (JDBC Connection Pool Core)                    │
│  ┌─────────────┐  ┌──────────┐  ┌──────────────────┐    │
│  │ Connection   │  │PoolLock  │  │KeepAlive/Evict   │    │
│  │ Management   │  │& Fairness│  │   Threads        │    │
│  └─────────────┘  └──────────┘  └──────────────────┘    │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                    Filter Chain                           │
│  ┌────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐   │
│  │  Stat  │→│   Wall   │→│   Log    │→│   Custom    │   │
│  │ Filter │ │  Filter  │ │  Filter  │ │   Filter    │   │
│  └────────┘ └──────────┘ └──────────┘ └─────────────┘   │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                   SQL Parser Engine                       │
│  ┌────────┐  ┌────────┐  ┌─────────┐  ┌─────────────┐   │
│  │ Lexer  │→ │ Parser │→ │   AST   │→ │  Visitors   │   │
│  └────────┘  └────────┘  └─────────┘  └─────────────┘   │
│  ┌─────────────────────────────────────────────────────┐ │
│  │         Dialect Registry (30 dialects)               │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

1. 连接池子系统（Connection Pool）

连接池是 Druid 最核心的组件，负责管理物理数据库连接的生命周期。

核心类： DruidDataSource

关键机制：

  • 连接获取（getConnection） — 从池中获取空闲连接，如果池为空则等待或创建新连接
  • 连接归还（recycle） — 连接使用完毕后归还到池中，进行有效性检查后重新入池
  • 创建线程（CreateConnectionThread） — 独立线程异步创建物理连接，避免阻塞业务线程
  • 销毁线程（DestroyConnectionThread） — 定期检测并关闭空闲超时的连接
  • KeepAlive — 对池中空闲连接定期发送心跳，保持连接活跃

连接状态流转：

创建 → 空闲(idle) → 活跃(active) → 空闲(idle) → ... → 销毁
                ↑                      │
                └──────────────────────┘
                      recycle

2. Filter-Chain 子系统

Filter-Chain 是 Druid 的拦截器机制，采用责任链模式，在 JDBC 操作的关键节点（获取连接、执行 SQL、关闭连接等）插入自定义逻辑。

核心接口： Filter

内置 Filter：

Filter 功能
StatFilter 采集 SQL 执行统计（执行次数、耗时、慢 SQL 等）
WallFilter SQL 安全防护，基于 AST 分析拦截危险 SQL
Slf4jLogFilter 通过 SLF4J 输出 SQL 执行日志
Log4jFilter / Log4j2Filter 通过 Log4j/Log4j2 输出日志
CommonsLogFilter 通过 Commons Logging 输出日志
ConfigFilter 支持配置文件加密解密
EncodingConvertFilter 字符编码转换

执行流程：

Application → Filter_1.beforeExecute()
            → Filter_2.beforeExecute()
            → ...
            → JDBC Driver (实际执行)
            → ...
            → Filter_2.afterExecute()
            → Filter_1.afterExecute()
            → Application

3. SQL 解析器子系统

SQL 解析器是 Druid 的另一核心子系统，提供将 SQL 文本解析为结构化 AST 的能力。

处理流水线：

SQL Text → Lexer(词法分析) → Token Stream → Parser(语法分析) → AST → Visitor(遍历/转换)

各阶段说明：

  1. Lexer（词法分析器） — 将 SQL 文本分割为 Token 序列（关键字、标识符、字面量、运算符等）
  2. Parser（语法分析器） — 按 SQL 语法规则将 Token 流组装为 AST
  3. AST（抽象语法树） — 以树形结构表示 SQL 语句的语义，核心基类 SQLStatement、SQLExpr、SQLTableSource
  4. Visitor（访问者） — 通过 Visitor 模式遍历 AST，实现 SQL 输出、Schema 分析、SQL 改写等功能

方言注册机制：

DbType → SQLParserUtils.createParser() → Dialect-specific Parser
       → SQLUtils.createOutputVisitor() → Dialect-specific Visitor

每种方言通过 META-INF/druid/parser/<dialect>/ 下的配置文件注册关键字、数据类型和特性开关。

4. 监控统计子系统

数据采集： StatFilter 在 Filter-Chain 中拦截所有 JDBC 操作，记录：

  • SQL 执行次数、总耗时、最大耗时
  • 慢 SQL 日志（超过阈值的 SQL）
  • 连接池状态（活跃数、空闲数、等待线程数）
  • 事务统计

数据暴露：

  • DruidStatManagerFacade — 编程接口，获取统计数据
  • StatViewServlet — Web 监控页面（/druid/index.html）
  • 自定义接口 — 通过 DruidStatManagerFacade 输出 JSON 对接外部监控

类层次关系

DruidDataSource                        # 连接池核心类
├── CreateConnectionThread (内部类)     # 异步创建连接线程
├── DestroyConnectionThread (内部类)    # 连接回收线程
└── LogStatsThread (内部类)             # 定期日志统计线程

DruidConnectionHolder                  # 连接持有者，包装物理连接
DruidPooledConnection                  # 池化连接，应用层使用

Filter (interface)
└── FilterAdapter                  # Filter 适配器基类
    ├── WallFilter                 # 安全防火墙 Filter
    ├── EncodingConvertFilter      # 字符编码转换 Filter
    ├── ConfigFilter               # 配置加密解密 Filter
    └── FilterEventAdapter         # 事件适配器
        ├── StatFilter             # 统计 Filter
        └── LogFilter (abstract)   # 日志 Filter 基类
            ├── Slf4jLogFilter
            ├── Log4jFilter
            ├── Log4j2Filter
            └── CommonsLogFilter

SQLStatement (AST root)
├── SQLSelectStatement             # SELECT 语句
├── SQLInsertStatement             # INSERT 语句
├── SQLUpdateStatement             # UPDATE 语句
├── SQLDeleteStatement             # DELETE 语句
├── SQLCreateTableStatement        # CREATE TABLE 语句
└── ... (100+ statement types)

English

Overall Architecture

Druid is composed of four core subsystems that collaborate through well-defined API boundaries:

┌──────────────────────────────────────────────────────────┐
│                     Application Layer                     │
│               (Spring Boot / Direct JDBC)                 │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                   DruidDataSource                         │
│            (JDBC Connection Pool Core)                    │
│  ┌─────────────┐  ┌──────────┐  ┌──────────────────┐    │
│  │ Connection   │  │PoolLock  │  │KeepAlive/Evict   │    │
│  │ Management   │  │& Fairness│  │   Threads        │    │
│  └─────────────┘  └──────────┘  └──────────────────┘    │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                    Filter Chain                           │
│  ┌────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐   │
│  │  Stat  │→│   Wall   │→│   Log    │→│   Custom    │   │
│  │ Filter │ │  Filter  │ │  Filter  │ │   Filter    │   │
│  └────────┘ └──────────┘ └──────────┘ └─────────────┘   │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                   SQL Parser Engine                       │
│  ┌────────┐  ┌────────┐  ┌─────────┐  ┌─────────────┐   │
│  │ Lexer  │→ │ Parser │→ │   AST   │→ │  Visitors   │   │
│  └────────┘  └────────┘  └─────────┘  └─────────────┘   │
│  ┌─────────────────────────────────────────────────────┐ │
│  │         Dialect Registry (30 dialects)               │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

1. Connection Pool Subsystem

The connection pool is Druid's core component, managing the lifecycle of physical database connections.

Core class: DruidDataSource

Key mechanisms:

  • getConnection — Acquires an idle connection from the pool; waits or creates new ones if the pool is empty
  • recycle — Returns connections to the pool after validation
  • CreateConnectionThread — Dedicated thread for async physical connection creation
  • DestroyConnectionThread — Periodically detects and closes idle-timeout connections
  • KeepAlive — Periodically sends heartbeats to idle connections

2. Filter-Chain Subsystem

The Filter-Chain implements the Chain of Responsibility pattern, intercepting JDBC operations at key points (connection acquisition, SQL execution, connection close, etc.).

Core interface: Filter

Built-in Filters:

Filter Purpose
StatFilter Collects SQL execution statistics (count, duration, slow SQL)
WallFilter SQL injection protection via AST analysis
Slf4jLogFilter SLF4J-based SQL execution logging
Log4jFilter / Log4j2Filter Log4j/Log4j2-based logging
CommonsLogFilter Commons Logging-based logging
ConfigFilter Configuration encryption/decryption
EncodingConvertFilter Character encoding conversion

3. SQL Parser Subsystem

The SQL parser processes SQL text into a structured AST:

SQL Text → Lexer → Token Stream → Parser → AST → Visitor
  • Lexer — Tokenizes SQL text into keywords, identifiers, literals, operators
  • Parser — Assembles token stream into AST following SQL grammar rules
  • AST — Tree representation of SQL semantics (SQLStatement, SQLExpr, SQLTableSource)
  • Visitor — Traverses AST for SQL output, schema analysis, SQL rewriting

4. Monitoring Subsystem

Collection: StatFilter intercepts all JDBC operations to record execution counts, durations, slow SQL, pool states, and transaction stats.

Exposure: DruidStatManagerFacade (programmatic API), StatViewServlet (Web UI at /druid/index.html), or custom JSON endpoints.