MySQL 內置幫助文檔層級化導出腳本：從 help contents 到結構化知識樹

MySQL 內置幫助文檔層級化導出腳本：從 help contents 到結構化知識樹

離線環境無法搜索官網文檔時，MySQL 內置 HELP CONTENTS 是救命稻草。但原始輸出扁平化、層級不清，查找語法極其低效。本文提供一鍵 Shell 腳本，將幫助文檔遞歸解析為樹狀結構（Category → Subcategory → Topic），並解決 PLUGINS、Numeric Functions 等特殊節點的解析邊界條件。

核心邏輯：遞歸下探 + 格式化輸出

#!/bin/bash
# 輸出：/tmp/help_tree.txt
mkdir -p /tmp/mysql_help && cd /tmp/mysql_help

# 1. 獲取一級目錄
mysql -uroot -p'YOUR_PASS' -e "HELP CONTENTS" > categories.txt
sed -i '1d;$d' categories.txt  # 去除表頭尾

# 2. 遞歸函數：解析分類/主題
recursive() {
  local file=$1 level=$2
  while read -r line; do
    local name=$(echo "$line" | tr -d '[:space:]')  # 文件名去空格
    mysql -uroot -p'YOUR_PASS' -e "HELP '$line'" > "$name"
    local first=$(head -1 "$name")
    
    # 判斷是否為葉子節點
    if [[ "$first" == "Name: '$line'" ]] || [[ "$first" == "Name: 'SHOW PLUGINS'" ]]; then
      # 輸出 Topic
      printf '%*s├── %s\n' $((level*4)) '' "$line"
    else
      # 輸出 Category 並遞歸
      printf '%*s├── %s\n' $((level*4)) '' "$line"
      sed -i '1d;$d' "$name"
      if [[ "$line" == "Numeric Functions" ]]; then
        # 特殊處理：直接列出運算符主題
        while read -r fn; do
          printf '%*s├── %s\n' $(((level+1)*4)) '' "$fn"
        done < "$name"
      else
        recursive "$name" $((level+1))
      fi
    fi
  done < "$file"
}

recursive categories.txt 0
# 重定向輸出：bash export_help.sh > help_tree.txt

關鍵邊界條件處理

輸出樣例（節選）

├── Account Management
│   ├── ALTER USER
│   ├── CREATE USER
│   └── GRANT
├── Administration
│   ├── BINLOG
│   ├── FLUSH
│   └── SHOW VARIABLES
├── Functions
│   ├── Date and Time Functions
│   │   ├── ADDDATE
│   │   └── NOW
│   └── Numeric Functions
│       ├── +
│       ├── /
│       └── SQRT
└── Transactions
    ├── START TRANSACTION
    └── COMMIT

進階擴展：HTML/Markdown 渲染

# 輸出 Markdown
recursive() {
  ...
  if [[ leaf ]]; then
    echo "$(printf '  %.0s' $(seq $level))- \`$line\`"
  else
    echo "$(printf '  %.0s' $(seq $level))- **$line**"
    recursive ...
  fi
}
# 執行：bash export_help.sh > help_tree.md

實戰價值

• 離線環境快速定位語法：grep -A 5 'ALTER USER' help_tree.txt
• 新人培訓教材：結構化目錄對應知識體系
• 版本對比：不同 MySQL 版本導出樹結構 diff，發現新增/廢棄命令
• CI 集成：構建鏡像時自動導出，隨容器發布供運行時查詢

將隱性知識（內置幫助）顯性化（結構化文檔），是提升團隊離線作戰能力的低成本高回報實踐。建議將腳本納入自動化構建流水線，每次 MySQL 升級自動產出最新幫助樹。