# 架構

本頁以一張概覽圖說明 `MySQLPool` 由哪些層組成，以及各層之間的關係。

```mermaid
graph TB
    App[應用程式] --> Init["init()"]
    Init --> Cfg[設定解析<br/>設定物件 / 環境變數]
    Cfg --> RP[(讀取連線池)]
    Cfg --> WP[(寫入連線池)]
    App --> QB[鏈式查詢建構器<br/>static 狀態]
    App --> Raw["read() / write()"]
    QB --> Exec["query() 執行器<br/>慢查詢記錄"]
    Raw --> Exec
    Exec --> RP
    Exec --> WP
```

## 分層

| 層 | 位置 | 職責 |
|---|---|---|
| 設定解析 | `init()`、`correctConfig()`（`src/MySQLPool.ts:40-97`） | 依優先序挑選讀寫設定、補預設值、建立 `mysql2/promise` 連線池並驗證 |
| 查詢建構器 | `table()` 到 `increase()`（`src/MySQLPool.ts:117-227`） | 把欄位、條件、JOIN、排序、分頁累積在 static 欄位 |
| SQL 組合 | `get()`、`insert()`、`update()`、`upsert()`（`src/MySQLPool.ts:229-360`） | 依累積狀態組出 SQL 與綁定值 |
| 執行器 | `query()`（`src/MySQLPool.ts:362-392`） | 選擇連線池、取連線、執行、計時、釋放連線 |
| 原生入口 | `read()`、`write()`（`src/MySQLPool.ts:394-406`） | 以固定連線池執行手寫 SQL |
| 生命週期 | `close()`（`src/MySQLPool.ts:99-115`） | 關閉連線池 |

## 跨層原則

| 原則 | 說明 |
|---|---|
| 單一資料庫出口 | 所有 SQL 都經過 `query()`，慢查詢記錄與連線釋放只在一處實作 |
| 全域單例 | `MySQLPool` 只有 static 成員，建構子為 private，整個行程共用一組連線池與一份建構器狀態 |

## 延伸閱讀

- 各模組詳細圖、資料流與狀態機：[doc/architecture.zh.md](https://github.com/pardnio/node-mysql-pool/blob/main/doc/architecture.zh.md)
- [讀寫連線池](/zh/read-write-pools)、[建構器狀態](/zh/builder-state)