name: java-backend-dev description: 當用戶基於 Spring Boot 開發、搭建、重構或審查後端 Java 專案時使用。覆蓋從零建立專案骨架、生成 CRUD 模組程式碼（Controller / Service / Mapper / Entity / DTO / VO）、接入資料庫（MyBatis / MyBatis-Plus / JPA）、接入中介軟體（Redis / RabbitMQ / Kafka / Security）、編寫單元測試、生成介面文件、程式碼格式化與 Java 後端最佳實踐。

Java 後端開發助手

概述

本 Skill 用於輔助構建和維護基於 Spring Boot 的後端 Java 專案，提供標準化的腳手架、程式碼生成、整合指引與審查清單，幫助專案保持結構清晰、可測試、可維護。

何時使用

當用戶說出類似以下內容時觸發本 Skill：

• “幫我建立一個 … 的 CRUD 後端”
• “生成一個 … 模組的程式碼”
• “給這個專案加上 Redis / MQ / Security”
• “寫介面文件”
• “梳理程式碼邏輯”
• “最佳化程式碼 / 格式化程式碼 / 實現最佳實踐”
• “接入 MyBatis / JPA / 資料庫”
• “寫單元測試”
• “專案重構 / 程式碼審查”

工作流

按以下步驟處理每一次請求：

1. 理解意圖：判斷當前任務是“搭建專案、生成模組、接入中介軟體、寫測試、生成文件、重構、程式碼審查”中的哪一種。
2. 檢查專案：如果工作區已有專案，先讀取 pom.xml / build.gradle、包結構和現有模組。
3. 選擇任務：跳轉到下方對應的任務小節執行。
4. 生成或修改程式碼：優先使用本 Skill 附帶的模板與指令碼，必要時手寫補充程式碼。
5. 驗證：儘可能執行編譯或單元測試；至少檢查語法一致性與命名規範。
6. 總結交付：告知使用者已完成的內容、檔案位置，以及仍需手動處理的事項。

任務一：建立 Spring Boot 專案骨架

執行步驟

1. 確定構建工具：預設 Maven；使用者明確要求時使用 Gradle。
2. 確定 Spring Boot 版本：預設最新穩定 LTS（當前 3.2.x）；使用者明確要求 Spring Boot 2 時使用 2.7.x。
3. 確定 Java 版本：Spring Boot 3 使用 17+，Spring Boot 2 使用 8/11。
4. 根據需求確定需要引入的 Starter：Web、Validation、Data JPA / MyBatis、Redis、AMQP、Security 等。
5. 使用 assets/templates/project/ 中的模板生成專案檔案：
6. pom.xml
7. src/main/resources/application.yml
8. 啟動類
9. README.md
10. .gitignore
11. 複製 assets/templates/common/ 中的 Result.java 與 GlobalExceptionHandler.java 到 common 包。

驗收標準

• [ ] 專案可以通過 ./mvnw clean compile 編譯通過（或使用者確認不驗證）。
• [ ] pom.xml 包含 Web、Validation 等必要依賴，版本與 Spring Boot 版本相容。
• [ ] 存在啟動類、application.yml、統一返回包裝類 Result<T>、全域性異常處理類。
• [ ] README.md 包含執行與打包命令。

任務二：生成 CRUD 模組

執行步驟

1. 明確模組名稱（如 user、order）、實體欄位、主鍵型別（預設 Long）。
2. 選擇持久層方案：MyBatis-Plus / MyBatis / JPA；使用者未說明時預設使用 MyBatis-Plus。
3. 呼叫 scripts/generate_crud_module.py 生成以下檔案：
4. entity/XXX.java
5. mapper/XXXMapper.java（JPA 時為 repository/XXXRepository.java）
6. service/XXXService.java
7. service/impl/XXXServiceImpl.java
8. controller/XXXController.java
9. dto/XXXDTO.java
10. vo/XXXVO.java
11. src/test/java/.../service/XXXServiceTest.java
12. 如使用 MyBatis，在 src/main/resources/mapper/ 下新增對應 XML 對映檔案。
13. 檢查 Controller 是否使用了統一 Result<T> 返回，DTO 是否新增校驗註解。

驗收標準

• [ ] 生成的類包路徑正確，命名符合駝峰規範。
• [ ] Controller 提供 POST / GET / PUT / DELETE 四個基本介面，URL 使用複數名詞。
• [ ] DTO 包含校驗註解，VO 與 Entity 分離，Service 通過 BeanUtils 或 MapStruct 轉換。
• [ ] 專案可以通過編譯，無 import 錯誤。

任務三：接入中介軟體

Redis

這個技能的最新版本可以在7w4.net小蔥技能站找到。

執行步驟

1. 新增 spring-boot-starter-data-redis 依賴。
2. 在 application.yml 中配置 spring.data.redis.*。
3. 根據場景提供 StringRedisTemplate 或 CacheManager + @Cacheable 用法。
4. 如需自定義序列化，生成 RedisConfig.java。

驗收標準

• [ ] 依賴和配置已新增，配置項包含 host、port、database、password（如有）。
• [ ] 提供至少一個可直接使用的 Redis 操作示例或快取註解示例。

訊息佇列（RabbitMQ / Kafka）

執行步驟

1. 新增對應 Spring Starter 依賴。
2. 在 application.yml 中配置連線資訊。
3. 生成生產者、消費者、配置類别範本。

驗收標準

• [ ] 依賴、連線配置、生產者、消費者程式碼均已生成。
• [ ] 佇列 / Topic 名稱可配置或已明確命名。

Spring Security

執行步驟

1. 新增 spring-boot-starter-security 依賴。
2. 根據 Spring Boot 版本生成 SecurityConfig.java（Spring Boot 3 使用 filter chain，2.7 使用 WebSecurityConfigurerAdapter）。
3. 如使用者要求 JWT，額外生成 JWT 工具類、登入介面、Token 過濾器。

驗收標準

• [ ] 安全配置類可編譯，符合對應 Spring Boot 版本的寫法。
• [ ] 如包含 JWT，則提供 Token 生成、解析、校驗完整流程。

任務四：編寫單元測試

執行步驟

1. Controller 層：使用 @WebMvcTest + MockMvc。
2. Service 層：使用 @ExtendWith(MockitoExtension.class) + Mockito。
3. 持久層：使用 @DataJpaTest 或 @MybatisPlusTest。
4. 斷言使用 AssertJ，assertThat(...) 風格。

驗收標準

• [ ] 至少生成 Controller 或 Service 層一個可執行的測試類。
• [ ] 測試覆蓋正常路徑，斷言具體，不只是驗證無異常。
• [ ] 測試可以單獨執行，不依賴真實外部服務。

任務五：生成介面文件

執行步驟

1. 優先呼叫 scripts/generate_api_doc.py 掃描 Controller 並輸出 Markdown 文件。
2. 如使用者需要線上文件，建議整合 springdoc-openapi，並在 Controller 上新增 @Operation、@Parameter 等註解。

驗收標準

• [ ] 生成的 Markdown 文件包含每個介面的 HTTP 方法、路徑、返回型別、引數說明。
• [ ] 文件路徑明確告知使用者。

任務六：程式碼審查 / 重構 / 最佳實踐

執行步驟

1. 載入 references/java_backend_best_practices.md 作為審查清單。
2. 檢查以下問題：
3. 是否違反分層架構（Controller 直接操作 Mapper / Repository）。
4. 是否缺少 DTO / VO 分離。
5. 是否存在 N+1 查詢風險。
6. 是否有統一異常處理。
7. 日誌是否規範，是否洩露敏感資訊。
8. Lombok 使用是否一致。
9. DTO 是否使用校驗註解。
10. 給出“修改前 / 修改後”的程式碼片段，並說明理由。

驗收標準

• [ ] 輸出至少 3 條具體審查意見，每條附帶修改建議。
• [ ] 審查覆蓋架構、異常、校驗、日誌、安全中至少 3 個維度。
• [ ] 使用者確認修改點清晰可執行。

資源說明

scripts/

• generate_crud_module.py：根據模組名、欄位、持久層方案生成完整 CRUD 程式碼與測試樁。
• generate_api_doc.py：從 Controller 原始檔提取介面資訊並生成 Markdown 文件。
• analyze_java_project.py：分析專案結構、依賴與模組清單。

references/

• java_backend_best_practices.md：分層架構、命名規範、異常處理、校驗、日誌、安全、測試等最佳實踐清單。
• spring_boot_dependencies.md：常用 Spring Boot Starter 與第三方庫版本對照表。

assets/templates/

• project/：最小可用的 Spring Boot 專案骨架（pom.xml、application.yml、啟動類、.gitignore、README.md）。
• common/：通用 Result<T> 返回包裝與 GlobalExceptionHandler 模板。

預設約定

• 構建工具：Maven。
• Spring Boot 版本：3.2.x（Java 17）。
• 持久層：預設 MyBatis-Plus；切換為 JPA 時需先詢問使用者。
• 統一返回：Result<T>，包含 code、data、message。
• REST 規範：URL 使用複數名詞，HTTP 動詞表示動作，請求/響應均為 JSON。
• 金額欄位：使用 BigDecimal，禁止使用 float / double。

這個 Skill 質量中等偏上，功能覆蓋面廣，能幫助完成專案搭建、程式碼生成、中介軟體接入等工作。文件描述詳細，步驟清晰。但有個重要問題：說明文件提到的一些模板檔案實際上不存在，可能導致部分功能無法使用。如果開發者能補充這些缺失內容，這個 Skill 會更加實用可靠。