MySQL Error 1064 排查實戰：從異常堆棧到 SQL 語法陷阱的 30 分鐘血淚教訓

MySQL Error 1064 排查實戰：從異常堆棧到 SQL 語法陷阱的 30 分鐘血淚教訓

一條看似正常的 UPDATE 在 iBatis 執行時拋出 Error 1064: You have an error in your SQL syntax near 'WHERE id = 12'。本文完整復盤從異常堆棧分析、錯誤碼誤導、動態 SQL 多餘逗號定位、到最終修復的全過程，揭示「錯誤碼不靠譜，動態 SQL 需防多餘逗號」的核心教訓。

一、 現場還原：異常堆棧信息

### Error updating database. Cause: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException:
You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'WHERE id = 12' at line 1

關鍵提示：near 'WHERE id = 12' —— 語法錯誤發生在 WHERE 關鍵字前，說明 SET 子句結構有問題。

二、 誤入歧途：錯誤碼 1064 的百度誤導

搜索「MySQL 1064」多數結果稱「列名與關鍵字衝突需加反引號」。
嘗試給 name 加反引號 \`name\`，重跑單測 —— 依然報 1064。
教訓：錯誤碼僅提示「語法錯誤」，具體原因需具體分析，切勿盲目套用網上方案。

三、 關鍵突破：打印 iBatis 真實執行 SQL

配置 log4j 打印 iBatis 執行的最終 SQL，但單測無輸出（可能事務回滾導致日志未刷出）。
無奈只能肉眼審閱動態 SQL 模板。

四、 真兇現形：動態 導致的多餘逗號

原始映射文件

<update id="updateById" parameterClass="Org">
    UPDATE org SET name = #name:VARCHAR#,
    <isNotNull property="tree_level">tree_level = #tree_level#, </isNotNull>
    <isNotNull property="yn">yn = #yn#, </isNotNull>
    <isNotNull property="route">route = #route:VARCHAR#, </isNotNull>
    `version` = `version` + 1,
    <isNotNull property="editor">editor = #editor:VARCHAR# </isNotNull>
    WHERE id = #id#
</update>

場景復現

當 editor 為 null 時，最後一個 isNotNull 不輸出內容，但前面 version = version + 1, 留下的逗號變成：

UPDATE org SET name = ?, version = version + 1,  WHERE id = ?

多餘逗號導致語法錯誤，MySQL 報錯位置指向 WHERE。

五、 修復方案：調整逗號位置，統一前置

<update id="updateById" parameterClass="Org">
    UPDATE org SET 
    <isNotNull property="name">`name` = #name:VARCHAR#, </isNotNull>
    <isNotNull property="tree_level">tree_level = #tree_level#, </isNotNull>
    <isNotNull property="yn">yn = #yn#, </isNotNull>
    <isNotNull property="route">route = #route:VARCHAR#, </isNotNull>
    <isNotNull property="editor">editor = #editor:VARCHAR#, </isNotNull>
    `version` = `version` + 1
    WHERE id = #id#
</update>

• 所有動態欄位統一輸出「欄位 = 值,」（含逗號）。
• 最後一個固定欄位 version = version + 1 不加逗號。
• 若所有動態欄位均為 null，固定欄位直接銜接 SET，語法合法。

驗證

單測通過。去掉反引號 \`name\`、\`version\` 亦正常運行，證實關鍵字衝突非本次根因。

六、 總結與最佳實踐

1. Error 1064 只意味著「語法錯誤」，具體原因需看報錯位置上下文，切勿迷信「關鍵字衝突」說法。
2. 動態 SQL 模板中，逗號策略統一前置：每個可能出現的片段自帶尾隨逗號，最後一個固定片段不加逗號。
3. 單元測試必須覆蓋「所有動態條件為 null」的邊界場景。
4. 打印真實執行 SQL 是排查動態 SQL 問題的金標準，配置 MyBatis/iBatis STDOUT_LOGGING 或 P6Spy。
5. 代碼評審重點檢查動態 SQL 模板的逗號、AND/OR 拼接邏輯。

這 30 分鐘的排查，換來的是對動態 SQL 模板編寫的肌肉記憶：逗號前置，邊界測試，真實 SQL 可見。