新手指南：如何避免 Django 遷移衝突問題

更新日期： 2024 年 12 月 26 日

在使用 Django 開發應用程式時，遷移（Migration）系統能夠幫助我們，有效管理資料庫結構的變更。

然而，當多人協作或處理不當時，遷移可能引發一些棘手的衝突問題，例如欄位重複定義或資料庫與遷移文件不匹配。

這篇文章將帶您了解常見的遷移問題原因，以及提供清晰的解決建議，幫助新手開發者在團隊協作中避免遷移衝突。

常見的遷移問題原因

多人協作問題

在多人協作的環境中，不同開發者可能同時對同一模型進行修改，導致遷移文件之間的衝突。

範例情境：

• 開發者 A 創建了初始遷移 0001，新增了 freelancer_verified 欄位。
• 開發者 B 不知情，後續又新增該欄位，並生成了另一個遷移（如 0004）。

當這些遷移被同時執行時，資料庫可能因欄位重複而報錯。

遷移文件未正確同步

當遷移文件沒有妥善處理並正確合併至版本控制系統（如 Git），可能會導致衝突。

範例情境：

• 開發者 A 的遷移文件已被合併至主分支。
• 開發者 B 的分支基於舊的模型版本，生成了新的遷移，忽略了主分支中的更新。

結果是資料庫執行遷移時，試圖再次新增已存在的欄位。

模型的手動修改與遷移文件不匹配

直接修改模型定義或資料庫結構，而未通過 Django 的遷移系統管理，也會導致問題。

範例情境：

• 在模型中手動添加了 freelancer_verified 欄位，但未同步更新遷移文件。
• 使用 SQL 手動修改資料庫表結構，遷移文件並不知情。

自動生成的遷移邏輯錯誤

Django 根據模型變更自動生成遷移，但某些情況下可能產生多餘或衝突的遷移。

範例情境：

• 在未執行現有遷移的情況下執行 makemigrations，導致重複定義欄位。
• 模型定義多次手動修改，未與遷移文件保持一致。

資料庫與遷移文件的狀態不一致

當資料庫中的實際結構與遷移文件記錄的狀態不一致時，也可能導致問題。

範例情境：

• 遷移文件記錄需新增欄位，但資料庫中該欄位已存在。
• 可能是因遷移執行中斷後，手動修復資料庫造成。

解決與預防建議

確保版本控制一致性

• 在生成遷移前，始終拉取主分支的最新代碼，以確保模型版本一致。
• 若多位開發人員需要修改同一模型，應進行協作處理，避免各自生成衝突的遷移文件。

運行檢查與最佳實踐

• 執行檢查： 在生成新遷移前，執行以下命令檢查現有遷移狀態：

 python manage.py showmigrations

• 避免手動修改： 不建議直接修改資料庫結構或跳過遷移執行，應始終通過 Django 的遷移系統管理變更。

審查與合併遷移文件

• 在代碼合併時，仔細檢查遷移文件是否有衝突。
• 若發現遷移衝突，應重新生成一個新的整合遷移，並刪除或合併重複的遷移。

使用自動化工具

• 在團隊中實施 CI/CD 自動化檢查，確保代碼合併前進行遷移測試。
• 可以使用工具自動檢測潛在的遷移衝突或資料庫錯誤。

小結

遷移問題常見於多人協作或操作不當時，但可以透過良好的版本控制、清晰的團隊協作流程，以及自動化工具的輔助來預防。

對於新手開發者，務必理解 Django 的遷移機制，並遵循本文提供的最佳實踐，這將大大減少遷移衝突的發生。

如果您的團隊需要更深入的解決方案或工具建議，請隨時查閱相關資源或諮詢專家！