啟動與資料庫連線

Q1：啟動時出現 Communications link failure

原因：連不上 MySQL。
排查順序：

MySQL 有沒有在跑？（或）
連接埠對不對？預設 3306，若有更改需同步調整連線字串。
帳號密碼與是否一致？
在 Docker 容器內跑 API 時，不能是 —— 請改用，或 Compose 的服務名稱（見第 7 章）。

Q2：Port 8080 was already in use

原因：8080 被其他程式佔用。
解法：找出並關閉佔用程式（macOS：），或修改的。

Q3：Access denied for user ’root’@’localhost’

原因：資料庫密碼錯誤。
解法：確認密碼；用環境變數覆寫：。

Q4：中文存進資料庫變成問號或亂碼

解法：確認連線字串含，且資料庫使用字元集（第 3 章的建庫指令）。

JWT 與權限

Q5：所有請求都回 401

排查順序：

Header 格式必須是 —— 注意後面有一個空格。
token 是否過期？（預設 1 小時，重新登入即可）
伺服器重啟後若換了，舊 token 全部失效。
Postman 中確認變數有值（滑鼠移到變數上可預覽）。

Q6：登入成功，但呼叫 DELETE 回 403

原因：403 表示「已認證但權限不足」——你用的是的 token。
解法：改用 admin 帳號登入取得的 token（Postman 中是）。

Q7：The specified key byte array is 248 bits which is not secure enough

原因：JWT 密鑰太短，HS256 要求至少 256 bits（32 字元）。
解法：把改成 32 字元以上的字串。

Maven 與 Docker

Q8：mvn 指令找不到（command not found）

解法：安裝 Maven（第 1 章），或使用專案附的 Maven Wrapper：。

Q9：Cannot connect to the Docker daemon

原因：Docker Desktop 沒有啟動。
解法：開啟 Docker Desktop 應用程式，等狀態變成執行中再重試。

Q10：docker compose up 後 app 一直重啟

排查：看錯誤訊息。最常見是 MySQL 還沒就緒——本專案已用 healthcheck 處理；若自行修改過 compose 檔，確認的還在。

指令速查表

Maven

lP7cm 指令 & 用途
& 啟動開發伺服器
& 清除並打包成 JAR
& 打包但跳過測試
& 執行測試
& 查看相依套件樹（排查版本衝突）

MySQL

-- 進入 MySQL（Docker 版）：
--   docker exec -it bookstore-mysql mysql -uroot -proot1234

SHOW DATABASES;              -- 列出所有資料庫
USE bookstore_db;            -- 切換資料庫
SHOW TABLES;                 -- 列出資料表
DESCRIBE books;              -- 查看資料表結構
SELECT * FROM books;         -- 查詢資料
SELECT * FROM users;         -- 查看使用者（密碼是 BCrypt 雜湊值）

curl 測試 API

# GET（-i 顯示狀態列與 Header）
curl -i "http://localhost:8080/api/books?page=0&size=5"

# POST（-X 指定方法、-H 加 Header、-d 附上 JSON 本文）
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "Admin@123"}'

# 帶 JWT 的請求
curl -X DELETE http://localhost:8080/api/books/1 \
  -H "Authorization: Bearer $TOKEN"

延伸學習方向

完成本教材後，建議依序探索以下主題，逐步補齊業界實務的完整拼圖：

API 文件自動化：springdoc-openapi——加一個相依套件，自動產生 Swagger UI 互動式 API 文件。
資料庫版本控管：Flyway 或 Liquibase—— 用版本化的 SQL 腳本管理資料表結構（取代）。
自動化測試：JUnit 5 ＋ MockMvc（Controller 測試）、 Testcontainers（在測試中啟動真實 MySQL 容器）。
Refresh Token：Access Token 短效期＋Refresh Token 換發機制，兼顧安全性與使用者體驗。
關聯對映進階：／、 LAZY 載入與 N+1 查詢問題。
快取與效能：Spring Cache ＋ Redis。
CI/CD：GitHub Actions——push 後自動測試、建置映像檔、部署。
雲端部署：把 Docker 映像檔部署到 AWS／GCP／Azure 或 Zeabur、Railway 等平台。

學習愉快，程式路上一帆風順！

常見問題排除（FAQ）