MySQL 關鍵字衝突導致寫入失敗：保留字完整表與轉義最佳實踐

MySQL 關鍵字衝突導致寫入失敗：保留字完整表與轉義最佳實踐

開發中常遇到「SQL 語法正確卻報錯」的離奇現象，多因表名/列名與 MySQL 保留關鍵字衝突。本文提供 MySQL 5.5/5.7/8.0 保留字完整對照、衝突診斷流程、反引號轉義規範、命名規範建議。

一、現象還原

GENERAL, IGNORE_SERVER_IDS, MASTER_HEARTBEAT_PERIOD, MAXVALUE, RESIGNAL, SIGNAL, SLOW

四、可作為標識符的保留字 (需反引號)

以下詞彙雖為保留字，但 MySQL 允許加 反引號 ` 作為標識符使用：

ACTION, BIT, DATE, ENUM, NO, TEXT, TIME, TIMESTAMP

五、衝突解決三板斧

1. 方案 A：改名（推薦，治本）

   CREATE TABLE `order` (
         `id` INT PRIMARY KEY,
         `desc` VARCHAR(255),
         `key` VARCHAR(64)
     );
     SELECT `id`, `desc` FROM `order` WHERE `key` = 'abc';

   缺點：所有 SQL 必須帶反引號，ORM/代碼生成器易遺漏，跨庫遷移麻煩。
2. 方案 C：前綴隔離（折中）

   #!/bin/bash
   # check_keywords.sh: 掃描 SQL 文件中的潛在關鍵字衝突
   # 使用: ./check_keywords.sh schema.sql
   
   KEYWORDS_FILE="/usr/share/mysql/keywords.txt"  # 需自行維護或從官方文檔導出
   SQL_FILE="$1"
   
   grep -oE '\b[a-zA-Z_][a-zA-Z0-9_]*\b' "$SQL_FILE" | sort -u |
   while read word; do
       if grep -qi "^${word}$" "$KEYWORDS_FILE"; then
           echo "⚠️  疑似關鍵字衝突: $word"
       fi
   done

   七、命名規範建議 (阿里巴巴 Java 開發手冊衍生版)

   對象	規範	示例
   表名	業務前綴 + 名詞單數 + _t 後綴	biz_order_t, sys_user_t
   列名	名詞/動詞組合，避免單一保留字	user_name, order_status, create_time
   索引名	idx_ + 表縮寫 + 列名	idx_bo_user_id
   外鍵	fk_ + 子表縮寫 + 父表縮寫	fk_bo_usr
   布爾列	is_/has_/can_ 前綴	is_deleted, has_permission

   八、版本差異提醒

   • MySQL 8.0：新增 GROUPS、RANGE、ROWS (窗口函數)、MEMBER OF (JSON) 等保留字。
   • MariaDB：部分保留字集合不同，遷移前必跑兼容性檢查。
   • SHOW KEYWORDS / SELECT * FROM INFORMATION_SCHEMA.KEYWORDS (8.0+) 可查詢當前版本保留字。

   總結

   「寧可名字長一點，不可踩保留字坑」。方案 A（語義化改名）為最佳實踐，配合團隊統一命名規範、Code Review 關鍵字掃描、CI 集成自動檢測，從源頭杜絕關鍵字衝突。遷移存量項目時，短期用方案 B（反引號）過渡，制定時間表逐步重構為方案 A。