📘 Java 後端開發規範手冊（團隊版）

🎯 目標與原則

• 提升代碼品質與可維護性
• 降低技術債與人為錯誤
• 建立統一的開發流程與技術文化
• 強化安全性與效能保障

🧱 一、項目結構與分層設計

1. 標準分層架構

controller → service → repository → entity

• Controller：只負責接收請求與回應結果，不寫業務邏輯
• Service：承載業務邏輯，禁止直接操作資料庫
• Repository：封裝資料庫操作，使用 MyBatis 或 JPA
• Entity：資料模型，禁止與前端直接對接

2. DTO / VO / BO 使用規範

• DTO：資料傳輸物件，用於 API 輸入輸出
• BO：業務物件，Service 層內部使用

✍️ 二、代碼風格與命名規範

1. 命名規則

2. 代碼格式

• 每行不超過 120 字
• 使用空格縮排（4 個空格）
• 使用 IDE 自動格式化（統一設定）

3. 註解規範

• 公共方法需有 Javadoc
• 關鍵邏輯需加行內註解
• 禁止無意義註解（如 // TODO 無內容）

🔐 三、安全性與穩定性

1. 輸入驗證

• 使用 Hibernate Validator（如 @NotNull, @Length）
• 所有 API 輸入參數必須校驗

2. SQL 安全

• 禁止拼接 SQL，使用 ORM 或預編譯語句
• 禁止使用 select *，明確列出欄位

3. 敏感資訊處理

• 密碼需加密儲存（如 bcrypt）
• 禁止日誌輸出敏感資訊（token、密碼等）

4. 權限控制

• 使用 Spring Security 或自定義 RBAC 模型
• 所有 API 須設計權限驗證機制

🚀 四、效能與可擴展性

1. 快取策略

• 使用 Redis 快取熱點資料
• 設定合理過期時間，避免快取雪崩

2. 異步處理

• 使用 ThreadPoolExecutor 或 Spring Async
• 禁止使用 new Thread()

3. 限流與熔斷

• 接入 Sentinel、Hystrix 等工具
• 所有外部依賴需設計降級策略

🧪 五、測試與部署

1. 單元測試

• 使用 JUnit + Mockito
• 覆蓋率達 80% 以上

2. 集成測試

• 使用 SpringBootTest 模擬真實環境
• 測試資料需隔離，避免污染正式資料庫

3. CI/CD 流程

• 使用 Azure CI
• 每次提交自動構建、測試、部署至測試環境

🤝 六、團隊協作與流程

1. Git 規範

• 遵循 Git Flow 分支策略
• Commit Message 使用英文，格式：

feat: 新增用戶註冊功能
fix: 修復登入錯誤處理
refactor: 重構訂單邏輯

2. Code Review

• 所有 PR 必須經過至少一人審核
• Review 重點：邏輯正確性、命名清晰、是否有測試

3. 文件與知識管理

• 每個模組需有 README 說明架構與使用方式
• 使用 Swagger/OpenAPI 自動生成 API 文件
• 技術決策需記錄於 Confluence 或 Notion

📦 七、導入依賴的規範

1. 依賴管理工具

• 統一使用 Maven 或 Gradle，不混用
• 所有依賴版本需明確指定，禁止使用 LATEST 或 RELEASE

2. 依賴版本控制

• 使用 BOM 管理核心依賴版本
• 定期檢查依賴更新，避免使用過時或有漏洞版本
• 升級依賴需經測試驗證並註明原因

3. 第三方依賴準則

• 僅使用穩定版本，避免 beta、alpha、snapshot
• 優先選擇主流、活躍維護的開源庫
• 禁止導入未經審核的個人或不明來源依賴

4. 依賴精簡原則

• 嚴格控制依賴數量，避免冗餘與重複
• 禁止版本衝突，使用 mvn dependency:tree 檢查

5. 安全與授權

• 所有依賴需符合授權政策（如 Apache 2.0、MIT）
• 禁止使用 GPL 或限制商業授權的依賴
• 修改過的依賴需註明來源與變更內容

📎 八、程式完成後由 Copilot 協助檢核的規範

為了提升程式品質與減少人為疏漏，團隊鼓勵在程式撰寫完成後，透過 Copilot 協助進行初步檢核與優化建議。

檢核流程建議

• 撰寫完成後，主動呼叫 Copilot 進行以下檢查：
• 方法命名是否清晰、語意明確
• 是否有重複邏輯可抽象為共用方法
• 是否有潛在的 NullPointerException 或邏輯漏洞
• 是否符合既定的代碼風格（命名、縮排、註解）
• 是否有未處理的例外或錯誤情境

使用方式建議

• 在 IDE 中（如 VS Code 或 IntelliJ）使用 Copilot 提示功能，於撰寫完成後：
• 加入註解，請 Copilot 解釋邏輯是否合理
• 請 Copilot 優化某段程式碼（如迴圈、條件判斷）
• 請 Copilot 檢查是否有更佳的設計模式可套用

注意事項

• Copilot 提供的是輔助建議，最終決策仍由開發者負責
• 若 Copilot 建議與團隊規範不符，應優先遵守團隊標準
• 建議將 Copilot 的優化建議納入 PR 討論，供 Reviewer 參考

推廣方式

• 鼓勵新進人員在 onboarding 時學習 Copilot 的使用技巧
• 每月技術分享可安排「Copilot 實戰應用」主題
• 可建立 Copilot 使用 FAQ 或範例庫，供團隊參考