沉淀的提示詞模板）)
場(chǎng)景一、出現(xiàn)bug解決后我們需要進(jìn)行根因分析歸納總結(jié),沉淀為技術(shù)方案如出現(xiàn)json解析bug要總結(jié)可用提示詞:針對(duì)json解析我所做出的修改出一版技術(shù)方案,從bug日志復(fù)現(xiàn)、問題定位、技術(shù)方案、驗(yàn)證可行性、最后測(cè)試以及修改文件清單這幾個(gè)流程寫一套我做出的優(yōu)化md文檔,命名失敗重試接口json解析優(yōu)化.md,放在導(dǎo)入失敗回滾方案這個(gè)目錄下場(chǎng)景二、單元測(cè)試相關(guān)提示詞1. 針對(duì)我們的類或方法給出單元測(cè)試技術(shù)方案的提示詞:完整版提示詞(僅作為參考,有選擇性的借鑒使用,不推薦,提示詞太長(zhǎng)):單個(gè)類/方法 單元測(cè)試技術(shù)方案生成提示詞后端標(biāo)準(zhǔn) 【通用標(biāo)準(zhǔn)版直接復(fù)制使用】 你現(xiàn)在是資深后端測(cè)試架構(gòu)師請(qǐng)根據(jù)我提供的 Java 類/方法源碼輸出一份完整、專業(yè)、可落地的《單元測(cè)試技術(shù)方案》。 方案需要針對(duì)當(dāng)前類/方法量身定制不要通用套話必須包含以下全部章節(jié) 1. 被測(cè)模塊概述 - 當(dāng)前類/方法職責(zé)、業(yè)務(wù)定位 - 核心輸入、核心輸出 - 依賴的外部服務(wù)、數(shù)據(jù)庫(kù)、第三方接口、緩存、MQ - 當(dāng)前方法核心邏輯鏈路梳理 2. 測(cè)試難點(diǎn)與風(fēng)險(xiǎn)點(diǎn)分析 - 哪些外部依賴需要 Mock - 哪些分支容易漏測(cè) - 存在的邊界場(chǎng)景、異常場(chǎng)景、并發(fā)風(fēng)險(xiǎn) - 事務(wù)、重試、冪等、JSON解析、特殊字符風(fēng)險(xiǎn) 3. 測(cè)試整體設(shè)計(jì)思路 - 采用的測(cè)試策略全量分支覆蓋/場(chǎng)景覆蓋/邊界覆蓋 - Mock 方案哪些依賴使用 MockitoBean / Mockito 模擬 - 數(shù)據(jù)構(gòu)造方案、入?yún)?gòu)造策略 - 不啟動(dòng)完整Spring容器、輕量化單元測(cè)試原則 4. 完整測(cè)試用例設(shè)計(jì)必須全覆蓋 包含三大類場(chǎng)景逐條列出 - 正常場(chǎng)景正常入?yún)?、正常流程、正常返?- 異常場(chǎng)景空參數(shù)、非法參數(shù)、第三方異常、接口超時(shí)、返回空、失敗回調(diào) - 邊界場(chǎng)景極值、空集合、超長(zhǎng)文本、特殊字符、JSON破損、重試觸發(fā)條件 每條用例包含用例名稱、測(cè)試場(chǎng)景、入?yún)?gòu)造、Mock行為、預(yù)期結(jié)果、校驗(yàn)點(diǎn)。 5. 關(guān)鍵邏輯專項(xiàng)測(cè)試方案 根據(jù)當(dāng)前方法自動(dòng)識(shí)別專項(xiàng) - 重試機(jī)制測(cè)試方案 - 事務(wù)回滾測(cè)試方案 - JSON解析容錯(cuò)測(cè)試方案 - 數(shù)據(jù)兜底/默認(rèn)值測(cè)試方案 - 分支條件全覆蓋測(cè)試方案 6. 測(cè)試編碼實(shí)現(xiàn)方案 - 測(cè)試類注解聲明 - 需要Mock的依賴清單 - 核心方法單元測(cè)試代碼結(jié)構(gòu) - 斷言策略返回值、異常、日志、交互次數(shù) 7. 已知問題兼容方案 - 廢棄注解警告兼容MockBean / 過時(shí)API - JSON特殊字符、單引號(hào)、換行符容錯(cuò) - 緩存、上下文、會(huì)話干擾規(guī)避 8. 測(cè)試覆蓋結(jié)論與質(zhì)量保障說明 --- 【強(qiáng)制輸出約束】 1. 禁止套話全部針對(duì)我提供的 具體代碼邏輯 生成 2. 所有用例必須 可落地、可直接編寫代碼 3. 輸出結(jié)構(gòu)正式、技術(shù)化可直接作為技術(shù)方案文檔提測(cè)/評(píng)審 4. 自動(dòng)識(shí)別當(dāng)前方法的重試、異常、JSON、數(shù)據(jù)庫(kù)、向量、文件導(dǎo)入等業(yè)務(wù)特性針對(duì)性設(shè)計(jì)用例。 --- 【你的項(xiàng)目專屬增強(qiáng)后綴固定追加】 本項(xiàng)目為 SpringBoot3.5 JUnit5 Mockito 環(huán)境單元測(cè)試優(yōu)先使用 MockitoBean廢棄API僅做警告不做報(bào)錯(cuò)攔截需要重點(diǎn)覆蓋 JSON 破損容錯(cuò)、重試失敗場(chǎng)景、數(shù)據(jù)庫(kù)向量數(shù)據(jù)占位邏輯、異常數(shù)據(jù)兜底恢復(fù)場(chǎng)景。日常高頻使用提示詞(很短,推薦,能覆蓋我們需要的核心內(nèi)容即可,可自己添加其他需要的內(nèi)容):結(jié)合下方某類某方法的Java 代碼輸出單元測(cè)試方案包含模塊職責(zé)、待測(cè)場(chǎng)景、Mock 策略、測(cè)試用例、落地要點(diǎn)。 注意只生成增量模式的,不需要全量模式。最后,禁止讀取不必要的文件,若要讀取需要經(jīng)過我同意。最后md文檔放在此目錄下: 功能設(shè)計(jì)思路/pgVector批處理策略/增量模式測(cè)試2. 人工審閱確定好單元測(cè)試技術(shù)方案的可行性后,提供提示詞讓ai編寫代碼:嚴(yán)格按照已定單元測(cè)試方案XX單元測(cè)試方案名編寫 JUnit5Mockito 可運(yùn)行單元測(cè)試代碼做好異常斷言、Mock 邏輯。 禁止編寫任何多余的擴(kuò)展代碼,禁止讀取任何不相關(guān)的文件。3. 針對(duì)我們已經(jīng)寫完的單元測(cè)試代碼進(jìn)行歸納總結(jié)的提示詞:請(qǐng)根據(jù)我提供的XX測(cè)試類(替換為你的單元測(cè)試測(cè)試類名稱)的Java 單元測(cè)試代碼生成一份簡(jiǎn)潔規(guī)范的單元測(cè)試技術(shù)文檔。包含測(cè)試模塊說明、技術(shù)棧、測(cè)試設(shè)計(jì)思路、核心用例、異常覆蓋情況、測(cè)試問題總結(jié)、最終測(cè)試結(jié)論。文檔正式、結(jié)構(gòu)化、適合歸檔復(fù)盤。4. 專項(xiàng)增強(qiáng)提示詞適配你的項(xiàng)目場(chǎng)景向量、重試、MQ、單元測(cè)試本次單元測(cè)試為向量知識(shí)庫(kù)業(yè)務(wù)測(cè)試請(qǐng)重點(diǎn)總結(jié)重試機(jī)制測(cè)試、異常熔斷測(cè)試、第三方 Embedding 接口 Mock 測(cè)試、數(shù)據(jù)入庫(kù)占位邏輯、JSON 解析容錯(cuò)、數(shù)據(jù)庫(kù)向量字段處理、異常數(shù)據(jù)兜底邏輯。場(chǎng)景二、單元測(cè)試提示詞自身開發(fā)實(shí)際應(yīng)用總結(jié)1. 極簡(jiǎn)提示詞適合個(gè)人做demo項(xiàng)目,無需復(fù)雜單元測(cè)試方案直接寫代碼為XX類寫出單元測(cè)試 位置: 測(cè)試類在tools包下。 約束: 1. 要求覆蓋邊界、正常、異常、判空等場(chǎng)景。 2. 在單元測(cè)試類上方簡(jiǎn)易列出所有測(cè)試場(chǎng)景表格狀實(shí)際寫出來對(duì)于一些簡(jiǎn)單的類效果還可以尤其這個(gè)表格狀深得我心非常清晰簡(jiǎn)易的描述出當(dāng)前單元測(cè)試類覆蓋的所有情況便于快速查閱有無遺漏情況。所以這個(gè)約束條件我們可以擴(kuò)充到自己的單元測(cè)試提示詞約束庫(kù)中。2. 單元測(cè)試約束條件(個(gè)人實(shí)際使用,不斷擴(kuò)充中)為XX類寫出單元測(cè)試 位置: 測(cè)試類寫在tools包下。 技術(shù)棧: 使用Junit單元測(cè)試框架優(yōu)先使用mock隔離外部網(wǎng)絡(luò)真實(shí)接口僅少量集成測(cè)試。 參考: XX單元測(cè)試類 約束: // 通用約束 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類 3. 要求做最小化讀取只定位并閱讀我點(diǎn)名的參考類 WebSearchTool以及查看 src/main/resources/ToolCalling設(shè)計(jì)方案 目錄下已有的方案文檔格式這是為了后續(xù)方案能對(duì)齊風(fēng)格不涉及全盤掃描 4.單元測(cè)試加上DisplayName類名和每個(gè)測(cè)試方法填寫業(yè)務(wù)場(chǎng)景中文描述方便看測(cè)試報(bào)告。 // 覆蓋場(chǎng)景約束 1. 要求覆蓋邊界、正常、異常、判空、合法性、超時(shí)等場(chǎng)景。要求覆蓋待測(cè)試類中的所有分支。 2. 在單元測(cè)試類上方簡(jiǎn)易列出所有測(cè)試場(chǎng)景表格狀 3. 第三方接口異常如超時(shí)、401鑒權(quán)失敗、限流、無搜索結(jié)果 4. 單元測(cè)試類中每種場(chǎng)景之間用 “// XX場(chǎng)景 ”分隔開,如“// 正常場(chǎng)景 ”3. 目前效果最好的極簡(jiǎn)單元測(cè)試提示詞(不斷更新迭代覆蓋之前版本)為PDFGenerationTool類寫出單元測(cè)試 位置: 測(cè)試類寫在tools包下。 技術(shù)棧: 使用Junit單元測(cè)試框架優(yōu)先使用mock隔離外部網(wǎng)絡(luò)真實(shí)接口僅少量集成測(cè)試。 參考: TerminalOperationToolTest單元測(cè)試類 約束: 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類 3. 要求做最小化讀取只定位并閱讀我點(diǎn)名的參考類這是為了后續(xù)方案能對(duì)齊風(fēng)格不涉及全盤掃描 4. 單元測(cè)試加上DisplayName類名和每個(gè)測(cè)試方法填寫業(yè)務(wù)場(chǎng)景中文描述方便看測(cè)試報(bào)告。 覆蓋場(chǎng)景約束: 1. 要求覆蓋邊界、正常、異常、判空、合法性、超時(shí)等場(chǎng)景。 2. 在單元測(cè)試類上方簡(jiǎn)易列出所有測(cè)試場(chǎng)景表格狀 3. 第三方接口異常若存在則寫,不存在不寫如超時(shí)、401鑒權(quán)失敗、限流、無搜索結(jié)果 4. 單元測(cè)試類中每種場(chǎng)景之間用 “// XX場(chǎng)景 ”分隔開,如“// 正常場(chǎng)景 ”提醒一下只要你VibeCoding開發(fā)完新的功能類后進(jìn)行codereview發(fā)現(xiàn)邏輯分支沒有問題,那么檢查一下你若要進(jìn)行單元測(cè)試需要哪些流程轉(zhuǎn)換的關(guān)鍵步驟信息,來幫助你判斷你這個(gè)結(jié)果的過程是否與你單元測(cè)試當(dāng)前方法想要的測(cè)試關(guān)鍵節(jié)點(diǎn)數(shù)據(jù)一樣最后的結(jié)果是否一樣。說人話就是,你的類中的關(guān)鍵步驟的log日志寫好了,那么我們VibeCoding完單元測(cè)試以后,甚至可以直接相信AI直接按照當(dāng)前方法測(cè)了什么來觀察日志信息,只要關(guān)鍵過程流程轉(zhuǎn)換信息對(duì)的上沒有問題結(jié)果也沒問題,基本測(cè)試不會(huì)出錯(cuò),甚至你不用看代碼。但這個(gè)只適合很著急自己做小demo用,生產(chǎn)開發(fā)環(huán)境在公司還是要最后進(jìn)行一下codereview的。場(chǎng)景三、開發(fā)新功能相關(guān)提示詞VibeCoding 提示詞模板VibeCoding 核心思路寫清楚業(yè)務(wù)背景、需求、約束、技術(shù)棧、已有代碼、輸出規(guī)范讓 AI 直接產(chǎn)出可落地技術(shù)方案 代碼減少來回拉扯。使用小技巧VibeCoding 體驗(yàn)提升先方案后代碼先用模板 1 拿方案你確認(rèn)邏輯沒問題再用模板 2 生成代碼不要一上來直接寫代碼。約束一定要帶上把你踩過的坑寫進(jìn)提示詞比如禁止手動(dòng) new SpringBean、不要 lombok、ConfigurationProperties 規(guī)范避免 AI 產(chǎn)出錯(cuò)誤代碼。貼參考代碼像你的 WebSearchTool可以直接粘貼給 AI 當(dāng)做參考實(shí)現(xiàn)。單元測(cè)試強(qiáng)制要求輸出寫完直接跑減少線上 bug。注意僅作為參考模板主要學(xué)習(xí)格式并根據(jù)自己的實(shí)際項(xiàng)目進(jìn)行潤(rùn)色填充最重要的是AI經(jīng)常理解不清楚漏掉的點(diǎn)一定要寫進(jìn)踩坑提示里面禁止AI犯錯(cuò)來回拉扯提高時(shí)間成本。①生成技術(shù)方案plaintext角色SpringBoot Java后端AI Agent工具開發(fā)。 項(xiàng)目AI Agent工具調(diào)用服務(wù)使用ConfigurationProperties讀取yml配置密鑰走環(huán)境變量Bean交給Spring管理禁止手動(dòng)new帶注解的Bean。 需求【寫你的功能需求】 約束 1.yml橫杠命名Java駝峰密鑰用${ENV_NAME:} 2.工具類加Component禁止手動(dòng)new 3.不用lombok手寫get/set 輸出先輸出技術(shù)方案需求拆解、yml配置、類設(shè)計(jì)、風(fēng)險(xiǎn)點(diǎn)不要直接寫完整代碼。②生成業(yè)務(wù)代碼方案確認(rèn)后用plaintext角色SpringBoot后端輸出可直接復(fù)制運(yùn)行完整代碼。 項(xiàng)目AI Agent工具調(diào)用ConfigurationProperties綁定yml密鑰環(huán)境變量Bean交給Spring禁止手動(dòng)new。 確認(rèn)方案【粘貼方案要點(diǎn)】 參考WebSearchTool聯(lián)網(wǎng)搜索工具類 約束 1.ConfigurationProperties嵌套靜態(tài)內(nèi)部類 2.Component注冊(cè)Bean禁止手動(dòng)new 3.手寫get/set不使用lombok 4.附帶Junit5 SpringBootTest單元測(cè)試關(guān)鍵注釋 輸出完整Java類yml片段。③新增 Tool 工具專用plaintext角色AI Agent工具開發(fā)。 項(xiàng)目SpringBoot Agent工具全部工具為Spring BeanConfigurationProperties讀配置禁止手動(dòng)new。 工具名【XXXTool】 功能【工具能力入?yún)⒊鰠ⅰ?yml配置 tools: xxx-api: api-key: ${XXX_API_KEY:} 參考WebSearchToolComponent、Resource注入配置、PostConstruct初始化、對(duì)外業(yè)務(wù)方法、junit5測(cè)試 輸出配置類追加代碼、yml片段、Tool完整類、單元測(cè)試、踩坑清單。④排錯(cuò)調(diào)試plaintext現(xiàn)象【bug現(xiàn)象】 相關(guān)代碼【貼代碼】 yml【貼yml】 已排查【已經(jīng)確認(rèn)過的點(diǎn)】 輸出根因、修復(fù)完整代碼、驗(yàn)證步驟、規(guī)避坑點(diǎn)。場(chǎng)景三、開發(fā)實(shí)際應(yīng)用測(cè)試個(gè)人實(shí)際開發(fā)使用真實(shí)測(cè)試過1. 開發(fā)提示詞角色SpringBoot Java后端AI Agent工具開發(fā)。 項(xiàng)目AI Agent工具調(diào)用服務(wù)Bean交給Spring管理禁止手動(dòng)new帶注解的Bean。 需求開發(fā)網(wǎng)頁(yè)抓取工具調(diào)用寫在包名tools下,工具類命名為WebScrapingTool。使用jsoup庫(kù)實(shí)現(xiàn)網(wǎng)頁(yè)抓取功能。 約束 1.工具類加Component禁止手動(dòng)new 2.必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及NPE異常報(bào)錯(cuò)。 參考WebSearchTool 輸出先輸出技術(shù)方案需求拆解類設(shè)計(jì)、風(fēng)險(xiǎn)點(diǎn)不要直接寫完整代碼。 技術(shù)方案存儲(chǔ)位置: src/main/resources/ToolCalling設(shè)計(jì)方案。必須我同意后才可以存儲(chǔ)到指定位置。2. 待優(yōu)化約束1. 若有需要,做好超時(shí)、重試邏輯兜底、異常處理 2. 生產(chǎn)環(huán)境下需要的log日志進(jìn)行必要的填充,便于定位錯(cuò)誤,使用Slf4j注解。3. 實(shí)際我們只使用1中的提示詞產(chǎn)生的技術(shù)方案如下(效果尚可):# WebScrapingTool 網(wǎng)頁(yè)抓取工具 — 技術(shù)方案 v2jsoup 版 狀態(tài)已批準(zhǔn) 日期2026-08-18 參考類com.jingdong.ai_super_love_agent.tools.WebSearchTool ## 約束回顧 1. Bean 交給 Spring 管理工具類加 Component禁止手動(dòng) new 帶注解的 Bean 2. 必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及 NPE 異常報(bào)錯(cuò) 3. 使用 jsoup 庫(kù)實(shí)現(xiàn)網(wǎng)頁(yè)抓取功能 ## 一、需求拆解 | # | 子需求 | 說明 | |---|--------|------| | 1 | 引入 jsoup 依賴 | pom.xml 新增 org.jsoup:jsoup:1.23.1 | | 2 | 工具注冊(cè) | Component 交給 Spring 管理方法加 Tool ToolParam返回 String風(fēng)格對(duì)齊 WebSearchTool | | 3 | **入?yún)⑿ｒ?yàn)** | url 判空 協(xié)議校驗(yàn)僅 http/https非法入?yún)?*直接返回錯(cuò)誤提示不發(fā)起請(qǐng)求**防止浪費(fèi)資源 | | 4 | jsoup 抓取 | Jsoup.connect(url) 設(shè)置超時(shí)、UA、maxBodySize解析為 Document | | 5 | **返回值判空** | Document、title()、body()、body().text() 逐級(jí)判空全鏈路防 NPE | | 6 | 異常兜底 | 統(tǒng)一 catch失敗返回 Error scraping url: xxx 字符串不拋異常對(duì)齊 WebSearchTool | | 7 | 單元測(cè)試 | 輕量測(cè)試不啟動(dòng) Spring 容器只驗(yàn)證基本功能 | ## 二、類設(shè)計(jì) tools/WebScrapingTool.java ├── ComponentSpring 管理禁止手動(dòng) new ├── 常量 │ ├── TIMEOUT_MS 10_000 // 連接讀取超時(shí) │ ├── MAX_BODY_SIZE 2MB // jsoup 下載體積上限防超大頁(yè)面 │ ├── MAX_TEXT_LENGTH 5000 // 返回給大模型的文本截?cái)嚅L(zhǎng)度 │ └── USER_AGENT // 常規(guī)瀏覽器 UA降低被反爬概率 │ ├── Tool scrapeWebPage(ToolParam url) : String │ │ 執(zhí)行鏈路校驗(yàn)前置任一失敗立即返回不浪費(fèi)請(qǐng)求 │ ├── ① StringUtils.isEmpty(url) → 空參直接返回錯(cuò)誤提示 │ ├── ② isValidUrl(url) 協(xié)議白名單校驗(yàn) → 非法協(xié)議直接返回錯(cuò)誤提示 │ ├── ③ Jsoup.connect(url).timeout().userAgent().maxBodySize().get() │ ├── ④ document null 判空 → 返回錯(cuò)誤提示 │ ├── ⑤ doc.title() / doc.body() 判空 → body 為空返回頁(yè)面內(nèi)容為空提示 │ ├── ⑥ body.text() 判空 拼接 title → 截?cái)嘀?MAX_TEXT_LENGTH 返回 │ └── ⑦ catch Exception → 返回 Error scraping url: e.getMessage() │ └── private boolean isValidUrl(String url) // 協(xié)議白名單http/https **判空清單對(duì)應(yīng)約束2** | 判空點(diǎn) | 不判空的后果 | |--------|------------| | url 空/非法 | 白白發(fā)起請(qǐng)求、IllegalArgumentException | | Document null | NPE | | doc.title() null | 拼接出 null 臟數(shù)據(jù) | | doc.body() null | .text() 直接 NPE部分頁(yè)面無 body 標(biāo)簽 | | body.text() 空串 | 返回?zé)o意義空內(nèi)容LLM 誤判 | ## 三、風(fēng)險(xiǎn)點(diǎn) | 風(fēng)險(xiǎn) | 影響 | 應(yīng)對(duì) | |------|------|------| | JS 動(dòng)態(tài)渲染頁(yè)面SPA | jsoup 不執(zhí)行 JS只拿到靜態(tài) HTML | 接受限制返回已抓取內(nèi)容不引入瀏覽器內(nèi)核 | | 反爬 403 / 驗(yàn)證碼頁(yè) | 抓取失敗 | 設(shè)置瀏覽器 UAHttpStatusException 單獨(dú)捕獲返回明確狀態(tài)碼提示 | | 超大頁(yè)面 | OOM / token 爆炸 | maxBodySize(2MB) 下載層限流 MAX_TEXT_LENGTH 返回層截?cái)?| | 請(qǐng)求掛起 | 阻塞工具調(diào)用鏈 | timeout(10s) | | 二進(jìn)制內(nèi)容圖片/PDF 鏈接 | 解析出亂碼 | jsoup 默認(rèn)對(duì)非 HTML 拋 UnsupportedMimeTypeException單獨(dú)捕獲返回提示 | | SSRFLLM 被誘導(dǎo)傳內(nèi)網(wǎng)地址 | 探測(cè)內(nèi)網(wǎng) | 本期做協(xié)議白名單內(nèi)網(wǎng) IP 黑名單列入后續(xù)增強(qiáng) | | 編碼亂碼 | 中文亂碼 | jsoup 根據(jù)響應(yīng)頭/meta 自動(dòng)識(shí)別 charset | | 惡意 HTML 注入 | jsoup 僅解析不執(zhí)行腳本且返回純文本 | 風(fēng)險(xiǎn)低body().text() 天然剝離標(biāo)簽 | ## 四、交付物清單 1. pom.xml 新增 jsoup 1.23.1 依賴 2. src/main/java/com/jingdong/ai_super_love_agent/tools/WebScrapingTool.java 3. src/test/java/com/jingdong/ai_super_love_agent/tools/WebScrapingToolTest.java僅基本功能校驗(yàn)類用例不發(fā)真實(shí)網(wǎng)絡(luò)請(qǐng)求 ## 五、參數(shù)默認(rèn)值已確認(rèn) | 參數(shù) | 值 | |------|-----| | 超時(shí) | 10s | | 下載體積上限 | 2MB | | 返回文本截?cái)嚅L(zhǎng)度 | 5000 字符 |然后claude 直接經(jīng)過我同意存儲(chǔ)技術(shù)方案.md后,直接開始寫代碼了,雖然一次過了但是這是不可控的點(diǎn)。故需優(yōu)化提示詞:在1中的提示詞末尾應(yīng)該說明: 經(jīng)過我同意存儲(chǔ)技術(shù)方案后,必須再次詢問我是否允許你開始寫代碼我同意你才可以繼續(xù)。另外,在測(cè)試中也有踩坑點(diǎn),在寫完功能開發(fā)代碼后順手將單元測(cè)試代碼補(bǔ)全了,且沒有事先生成單元測(cè)試技術(shù)方案,不太嚴(yán)謹(jǐn)。最后,寫完單元測(cè)試沒有在類上使用SpringbootTest注解且沒有使用Resource注入網(wǎng)頁(yè)抓取工具類,直接new對(duì)象,這個(gè)我們需要在單元測(cè)試提示詞中增加對(duì)應(yīng)約束,保證我們代碼規(guī)范的統(tǒng)一。故關(guān)于單元測(cè)試的提示詞修復(fù)如下:在1 生成技術(shù)方案 中的提示詞中: 移除關(guān)于單元測(cè)試的要求。 在后續(xù)的單元測(cè)試約束中添加 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類由此可見我們踩的坑都可以作為下次的約束條件,我們的約束條件也是不斷更新并且增加的,有助于減少模型的不確定性。4. 修復(fù)后整體的生成技術(shù)方案的提示詞(暫時(shí)包含單元測(cè)試):角色SpringBoot Java后端AI Agent工具開發(fā)。 項(xiàng)目AI Agent工具調(diào)用服務(wù)Bean交給Spring管理禁止手動(dòng)new帶注解的Bean。 需求開發(fā)網(wǎng)頁(yè)抓取工具調(diào)用寫在包名tools下,工具類命名為WebScrapingTool。使用jsoup庫(kù)實(shí)現(xiàn)網(wǎng)頁(yè)抓取功能。 約束 1.工具類加Component禁止手動(dòng)new 2.必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及NPE異常報(bào)錯(cuò)。 3. 若有需要,做好超時(shí)、重試邏輯兜底、異常處理 4. 生產(chǎn)環(huán)境下需要的log日志進(jìn)行必要的填充,便于定位錯(cuò)誤,使用Slf4j注解。 單元測(cè)試約束 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類 參考WebSearchTool 輸出先輸出技術(shù)方案需求拆解類設(shè)計(jì)、風(fēng)險(xiǎn)點(diǎn)不要直接寫完整代碼。 技術(shù)方案存儲(chǔ)位置: src/main/resources/ToolCalling設(shè)計(jì)方案。必須我同意后才可以存儲(chǔ)到指定位置。 注意: 經(jīng)過我同意存儲(chǔ)技術(shù)方案后,必須再次詢問我是否允許你開始寫代碼我同意你才可以繼續(xù)。場(chǎng)景三、歷史踩坑點(diǎn)全部沉淀到提示詞約束條件中(不斷擴(kuò)充)注意!這個(gè)是我們實(shí)際開發(fā)中踩的坑的歷史積累,有助于讓我們開發(fā)變得越來越精準(zhǔn)明確,符合我們項(xiàng)目架構(gòu)和代碼風(fēng)格,我們應(yīng)把歷史踩坑點(diǎn)全部填入約束條件中,等到實(shí)際使用時(shí)再有選擇的提取部分約束條件貼合我們的實(shí)際需求。1. 生成開發(fā)新需求的技術(shù)方案的約束條件(不斷更新)約束: // 通用約束 1. 必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及NPE異常報(bào)錯(cuò)。判空使用hutool工具類中的Util工具如CollectionUtilhutool沒有則嘗試springframework中的工具類。 2. 若有需要,做好超時(shí)、重試邏輯兜底、異常處理 3. 生產(chǎn)環(huán)境下需要的log日志進(jìn)行必要的填充,便于定位錯(cuò)誤,使用Slf4j注解。 4. 添加必要的注釋便于其他人理解代碼中關(guān)鍵步驟也要進(jìn)行注釋說明分清楚步驟如① 入?yún)⑿ｒ?yàn) ② 構(gòu)建進(jìn)程等 5. 禁止輸出任何與單元測(cè)試相關(guān)的內(nèi)容單元測(cè)試后續(xù)單獨(dú)處理 6. 要求做最小化讀取只定位并閱讀我點(diǎn)名的參考類 WebSearchTool以及查看 src/main/resources/ToolCalling設(shè)計(jì)方案 目錄下已有的方案文檔格式這是為了后續(xù)方案能對(duì)齊風(fēng)格不涉及全盤掃描 // 具體的實(shí)際項(xiàng)目約束 1. 具體需求實(shí)現(xiàn)的固定規(guī)范,如: 工具類加Component禁止手動(dòng)new // 項(xiàng)目規(guī)范 1. 當(dāng)前類中的輔助方法必須用 // helper methods 與主邏輯方法進(jìn)行隔離。 claude code使用命令技巧（四）（開發(fā)沉淀的提示詞模板）
場(chǎng)景一、出現(xiàn)bug解決后我們需要進(jìn)行根因分析歸納總結(jié),沉淀為技術(shù)方案如出現(xiàn)json解析bug要總結(jié)可用提示詞:針對(duì)json解析我所做出的修改出一版技術(shù)方案,從bug日志復(fù)現(xiàn)、問題定位、技術(shù)方案、驗(yàn)證可行性、最后測(cè)試以及修改文件清單這幾個(gè)流程寫一套我做出的優(yōu)化md文檔,命名失敗重試接口json解析優(yōu)化.md,放在導(dǎo)入失敗回滾方案這個(gè)目錄下場(chǎng)景二、單元測(cè)試相關(guān)提示詞1. 針對(duì)我們的類或方法給出單元測(cè)試技術(shù)方案的提示詞:完整版提示詞(僅作為參考,有選擇性的借鑒使用,不推薦,提示詞太長(zhǎng)):單個(gè)類/方法 單元測(cè)試技術(shù)方案生成提示詞后端標(biāo)準(zhǔn) 【通用標(biāo)準(zhǔn)版直接復(fù)制使用】 你現(xiàn)在是資深后端測(cè)試架構(gòu)師請(qǐng)根據(jù)我提供的 Java 類/方法源碼輸出一份完整、專業(yè)、可落地的《單元測(cè)試技術(shù)方案》。 方案需要針對(duì)當(dāng)前類/方法量身定制不要通用套話必須包含以下全部章節(jié) 1. 被測(cè)模塊概述 - 當(dāng)前類/方法職責(zé)、業(yè)務(wù)定位 - 核心輸入、核心輸出 - 依賴的外部服務(wù)、數(shù)據(jù)庫(kù)、第三方接口、緩存、MQ - 當(dāng)前方法核心邏輯鏈路梳理 2. 測(cè)試難點(diǎn)與風(fēng)險(xiǎn)點(diǎn)分析 - 哪些外部依賴需要 Mock - 哪些分支容易漏測(cè) - 存在的邊界場(chǎng)景、異常場(chǎng)景、并發(fā)風(fēng)險(xiǎn) - 事務(wù)、重試、冪等、JSON解析、特殊字符風(fēng)險(xiǎn) 3. 測(cè)試整體設(shè)計(jì)思路 - 采用的測(cè)試策略全量分支覆蓋/場(chǎng)景覆蓋/邊界覆蓋 - Mock 方案哪些依賴使用 MockitoBean / Mockito 模擬 - 數(shù)據(jù)構(gòu)造方案、入?yún)?gòu)造策略 - 不啟動(dòng)完整Spring容器、輕量化單元測(cè)試原則 4. 完整測(cè)試用例設(shè)計(jì)必須全覆蓋 包含三大類場(chǎng)景逐條列出 - 正常場(chǎng)景正常入?yún)?、正常流程、正常返?- 異常場(chǎng)景空參數(shù)、非法參數(shù)、第三方異常、接口超時(shí)、返回空、失敗回調(diào) - 邊界場(chǎng)景極值、空集合、超長(zhǎng)文本、特殊字符、JSON破損、重試觸發(fā)條件 每條用例包含用例名稱、測(cè)試場(chǎng)景、入?yún)?gòu)造、Mock行為、預(yù)期結(jié)果、校驗(yàn)點(diǎn)。 5. 關(guān)鍵邏輯專項(xiàng)測(cè)試方案 根據(jù)當(dāng)前方法自動(dòng)識(shí)別專項(xiàng) - 重試機(jī)制測(cè)試方案 - 事務(wù)回滾測(cè)試方案 - JSON解析容錯(cuò)測(cè)試方案 - 數(shù)據(jù)兜底/默認(rèn)值測(cè)試方案 - 分支條件全覆蓋測(cè)試方案 6. 測(cè)試編碼實(shí)現(xiàn)方案 - 測(cè)試類注解聲明 - 需要Mock的依賴清單 - 核心方法單元測(cè)試代碼結(jié)構(gòu) - 斷言策略返回值、異常、日志、交互次數(shù) 7. 已知問題兼容方案 - 廢棄注解警告兼容MockBean / 過時(shí)API - JSON特殊字符、單引號(hào)、換行符容錯(cuò) - 緩存、上下文、會(huì)話干擾規(guī)避 8. 測(cè)試覆蓋結(jié)論與質(zhì)量保障說明 --- 【強(qiáng)制輸出約束】 1. 禁止套話全部針對(duì)我提供的 具體代碼邏輯 生成 2. 所有用例必須 可落地、可直接編寫代碼 3. 輸出結(jié)構(gòu)正式、技術(shù)化可直接作為技術(shù)方案文檔提測(cè)/評(píng)審 4. 自動(dòng)識(shí)別當(dāng)前方法的重試、異常、JSON、數(shù)據(jù)庫(kù)、向量、文件導(dǎo)入等業(yè)務(wù)特性針對(duì)性設(shè)計(jì)用例。 --- 【你的項(xiàng)目專屬增強(qiáng)后綴固定追加】 本項(xiàng)目為 SpringBoot3.5 JUnit5 Mockito 環(huán)境單元測(cè)試優(yōu)先使用 MockitoBean廢棄API僅做警告不做報(bào)錯(cuò)攔截需要重點(diǎn)覆蓋 JSON 破損容錯(cuò)、重試失敗場(chǎng)景、數(shù)據(jù)庫(kù)向量數(shù)據(jù)占位邏輯、異常數(shù)據(jù)兜底恢復(fù)場(chǎng)景。日常高頻使用提示詞(很短,推薦,能覆蓋我們需要的核心內(nèi)容即可,可自己添加其他需要的內(nèi)容):結(jié)合下方某類某方法的Java 代碼輸出單元測(cè)試方案包含模塊職責(zé)、待測(cè)場(chǎng)景、Mock 策略、測(cè)試用例、落地要點(diǎn)。 注意只生成增量模式的,不需要全量模式。最后,禁止讀取不必要的文件,若要讀取需要經(jīng)過我同意。最后md文檔放在此目錄下: 功能設(shè)計(jì)思路/pgVector批處理策略/增量模式測(cè)試2. 人工審閱確定好單元測(cè)試技術(shù)方案的可行性后,提供提示詞讓ai編寫代碼:嚴(yán)格按照已定單元測(cè)試方案XX單元測(cè)試方案名編寫 JUnit5Mockito 可運(yùn)行單元測(cè)試代碼做好異常斷言、Mock 邏輯。 禁止編寫任何多余的擴(kuò)展代碼,禁止讀取任何不相關(guān)的文件。3. 針對(duì)我們已經(jīng)寫完的單元測(cè)試代碼進(jìn)行歸納總結(jié)的提示詞:請(qǐng)根據(jù)我提供的XX測(cè)試類(替換為你的單元測(cè)試測(cè)試類名稱)的Java 單元測(cè)試代碼生成一份簡(jiǎn)潔規(guī)范的單元測(cè)試技術(shù)文檔。包含測(cè)試模塊說明、技術(shù)棧、測(cè)試設(shè)計(jì)思路、核心用例、異常覆蓋情況、測(cè)試問題總結(jié)、最終測(cè)試結(jié)論。文檔正式、結(jié)構(gòu)化、適合歸檔復(fù)盤。4. 專項(xiàng)增強(qiáng)提示詞適配你的項(xiàng)目場(chǎng)景向量、重試、MQ、單元測(cè)試本次單元測(cè)試為向量知識(shí)庫(kù)業(yè)務(wù)測(cè)試請(qǐng)重點(diǎn)總結(jié)重試機(jī)制測(cè)試、異常熔斷測(cè)試、第三方 Embedding 接口 Mock 測(cè)試、數(shù)據(jù)入庫(kù)占位邏輯、JSON 解析容錯(cuò)、數(shù)據(jù)庫(kù)向量字段處理、異常數(shù)據(jù)兜底邏輯。場(chǎng)景二、單元測(cè)試提示詞自身開發(fā)實(shí)際應(yīng)用總結(jié)1. 極簡(jiǎn)提示詞適合個(gè)人做demo項(xiàng)目,無需復(fù)雜單元測(cè)試方案直接寫代碼為XX類寫出單元測(cè)試 位置: 測(cè)試類在tools包下。 約束: 1. 要求覆蓋邊界、正常、異常、判空等場(chǎng)景。 2. 在單元測(cè)試類上方簡(jiǎn)易列出所有測(cè)試場(chǎng)景表格狀實(shí)際寫出來對(duì)于一些簡(jiǎn)單的類效果還可以尤其這個(gè)表格狀深得我心非常清晰簡(jiǎn)易的描述出當(dāng)前單元測(cè)試類覆蓋的所有情況便于快速查閱有無遺漏情況。所以這個(gè)約束條件我們可以擴(kuò)充到自己的單元測(cè)試提示詞約束庫(kù)中。2. 單元測(cè)試約束條件(個(gè)人實(shí)際使用,不斷擴(kuò)充中)為XX類寫出單元測(cè)試 位置: 測(cè)試類寫在tools包下。 技術(shù)棧: 使用Junit單元測(cè)試框架優(yōu)先使用mock隔離外部網(wǎng)絡(luò)真實(shí)接口僅少量集成測(cè)試。 參考: XX單元測(cè)試類 約束: // 通用約束 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類 3. 要求做最小化讀取只定位并閱讀我點(diǎn)名的參考類 WebSearchTool以及查看 src/main/resources/ToolCalling設(shè)計(jì)方案 目錄下已有的方案文檔格式這是為了后續(xù)方案能對(duì)齊風(fēng)格不涉及全盤掃描 4.單元測(cè)試加上DisplayName類名和每個(gè)測(cè)試方法填寫業(yè)務(wù)場(chǎng)景中文描述方便看測(cè)試報(bào)告。 // 覆蓋場(chǎng)景約束 1. 要求覆蓋邊界、正常、異常、判空、合法性、超時(shí)等場(chǎng)景。要求覆蓋待測(cè)試類中的所有分支。 2. 在單元測(cè)試類上方簡(jiǎn)易列出所有測(cè)試場(chǎng)景表格狀 3. 第三方接口異常如超時(shí)、401鑒權(quán)失敗、限流、無搜索結(jié)果 4. 單元測(cè)試類中每種場(chǎng)景之間用 “// XX場(chǎng)景 ”分隔開,如“// 正常場(chǎng)景 ”3. 目前效果最好的極簡(jiǎn)單元測(cè)試提示詞(不斷更新迭代覆蓋之前版本)為PDFGenerationTool類寫出單元測(cè)試 位置: 測(cè)試類寫在tools包下。 技術(shù)棧: 使用Junit單元測(cè)試框架優(yōu)先使用mock隔離外部網(wǎng)絡(luò)真實(shí)接口僅少量集成測(cè)試。 參考: TerminalOperationToolTest單元測(cè)試類 約束: 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類 3. 要求做最小化讀取只定位并閱讀我點(diǎn)名的參考類這是為了后續(xù)方案能對(duì)齊風(fēng)格不涉及全盤掃描 4. 單元測(cè)試加上DisplayName類名和每個(gè)測(cè)試方法填寫業(yè)務(wù)場(chǎng)景中文描述方便看測(cè)試報(bào)告。 覆蓋場(chǎng)景約束: 1. 要求覆蓋邊界、正常、異常、判空、合法性、超時(shí)等場(chǎng)景。 2. 在單元測(cè)試類上方簡(jiǎn)易列出所有測(cè)試場(chǎng)景表格狀 3. 第三方接口異常若存在則寫,不存在不寫如超時(shí)、401鑒權(quán)失敗、限流、無搜索結(jié)果 4. 單元測(cè)試類中每種場(chǎng)景之間用 “// XX場(chǎng)景 ”分隔開,如“// 正常場(chǎng)景 ”提醒一下只要你VibeCoding開發(fā)完新的功能類后進(jìn)行codereview發(fā)現(xiàn)邏輯分支沒有問題,那么檢查一下你若要進(jìn)行單元測(cè)試需要哪些流程轉(zhuǎn)換的關(guān)鍵步驟信息,來幫助你判斷你這個(gè)結(jié)果的過程是否與你單元測(cè)試當(dāng)前方法想要的測(cè)試關(guān)鍵節(jié)點(diǎn)數(shù)據(jù)一樣最后的結(jié)果是否一樣。說人話就是,你的類中的關(guān)鍵步驟的log日志寫好了,那么我們VibeCoding完單元測(cè)試以后,甚至可以直接相信AI直接按照當(dāng)前方法測(cè)了什么來觀察日志信息,只要關(guān)鍵過程流程轉(zhuǎn)換信息對(duì)的上沒有問題結(jié)果也沒問題,基本測(cè)試不會(huì)出錯(cuò),甚至你不用看代碼。但這個(gè)只適合很著急自己做小demo用,生產(chǎn)開發(fā)環(huán)境在公司還是要最后進(jìn)行一下codereview的。場(chǎng)景三、開發(fā)新功能相關(guān)提示詞VibeCoding 提示詞模板VibeCoding 核心思路寫清楚業(yè)務(wù)背景、需求、約束、技術(shù)棧、已有代碼、輸出規(guī)范讓 AI 直接產(chǎn)出可落地技術(shù)方案 代碼減少來回拉扯。使用小技巧VibeCoding 體驗(yàn)提升先方案后代碼先用模板 1 拿方案你確認(rèn)邏輯沒問題再用模板 2 生成代碼不要一上來直接寫代碼。約束一定要帶上把你踩過的坑寫進(jìn)提示詞比如禁止手動(dòng) new SpringBean、不要 lombok、ConfigurationProperties 規(guī)范避免 AI 產(chǎn)出錯(cuò)誤代碼。貼參考代碼像你的 WebSearchTool可以直接粘貼給 AI 當(dāng)做參考實(shí)現(xiàn)。單元測(cè)試強(qiáng)制要求輸出寫完直接跑減少線上 bug。注意僅作為參考模板主要學(xué)習(xí)格式并根據(jù)自己的實(shí)際項(xiàng)目進(jìn)行潤(rùn)色填充最重要的是AI經(jīng)常理解不清楚漏掉的點(diǎn)一定要寫進(jìn)踩坑提示里面禁止AI犯錯(cuò)來回拉扯提高時(shí)間成本。①生成技術(shù)方案plaintext角色SpringBoot Java后端AI Agent工具開發(fā)。 項(xiàng)目AI Agent工具調(diào)用服務(wù)使用ConfigurationProperties讀取yml配置密鑰走環(huán)境變量Bean交給Spring管理禁止手動(dòng)new帶注解的Bean。 需求【寫你的功能需求】 約束 1.yml橫杠命名Java駝峰密鑰用${ENV_NAME:} 2.工具類加Component禁止手動(dòng)new 3.不用lombok手寫get/set 輸出先輸出技術(shù)方案需求拆解、yml配置、類設(shè)計(jì)、風(fēng)險(xiǎn)點(diǎn)不要直接寫完整代碼。②生成業(yè)務(wù)代碼方案確認(rèn)后用plaintext角色SpringBoot后端輸出可直接復(fù)制運(yùn)行完整代碼。 項(xiàng)目AI Agent工具調(diào)用ConfigurationProperties綁定yml密鑰環(huán)境變量Bean交給Spring禁止手動(dòng)new。 確認(rèn)方案【粘貼方案要點(diǎn)】 參考WebSearchTool聯(lián)網(wǎng)搜索工具類 約束 1.ConfigurationProperties嵌套靜態(tài)內(nèi)部類 2.Component注冊(cè)Bean禁止手動(dòng)new 3.手寫get/set不使用lombok 4.附帶Junit5 SpringBootTest單元測(cè)試關(guān)鍵注釋 輸出完整Java類yml片段。③新增 Tool 工具專用plaintext角色AI Agent工具開發(fā)。 項(xiàng)目SpringBoot Agent工具全部工具為Spring BeanConfigurationProperties讀配置禁止手動(dòng)new。 工具名【XXXTool】 功能【工具能力入?yún)⒊鰠ⅰ?yml配置 tools: xxx-api: api-key: ${XXX_API_KEY:} 參考WebSearchToolComponent、Resource注入配置、PostConstruct初始化、對(duì)外業(yè)務(wù)方法、junit5測(cè)試 輸出配置類追加代碼、yml片段、Tool完整類、單元測(cè)試、踩坑清單。④排錯(cuò)調(diào)試plaintext現(xiàn)象【bug現(xiàn)象】 相關(guān)代碼【貼代碼】 yml【貼yml】 已排查【已經(jīng)確認(rèn)過的點(diǎn)】 輸出根因、修復(fù)完整代碼、驗(yàn)證步驟、規(guī)避坑點(diǎn)。場(chǎng)景三、開發(fā)實(shí)際應(yīng)用測(cè)試個(gè)人實(shí)際開發(fā)使用真實(shí)測(cè)試過1. 開發(fā)提示詞角色SpringBoot Java后端AI Agent工具開發(fā)。 項(xiàng)目AI Agent工具調(diào)用服務(wù)Bean交給Spring管理禁止手動(dòng)new帶注解的Bean。 需求開發(fā)網(wǎng)頁(yè)抓取工具調(diào)用寫在包名tools下,工具類命名為WebScrapingTool。使用jsoup庫(kù)實(shí)現(xiàn)網(wǎng)頁(yè)抓取功能。 約束 1.工具類加Component禁止手動(dòng)new 2.必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及NPE異常報(bào)錯(cuò)。 參考WebSearchTool 輸出先輸出技術(shù)方案需求拆解類設(shè)計(jì)、風(fēng)險(xiǎn)點(diǎn)不要直接寫完整代碼。 技術(shù)方案存儲(chǔ)位置: src/main/resources/ToolCalling設(shè)計(jì)方案。必須我同意后才可以存儲(chǔ)到指定位置。2. 待優(yōu)化約束1. 若有需要,做好超時(shí)、重試邏輯兜底、異常處理 2. 生產(chǎn)環(huán)境下需要的log日志進(jìn)行必要的填充,便于定位錯(cuò)誤,使用Slf4j注解。3. 實(shí)際我們只使用1中的提示詞產(chǎn)生的技術(shù)方案如下(效果尚可):# WebScrapingTool 網(wǎng)頁(yè)抓取工具 — 技術(shù)方案 v2jsoup 版 狀態(tài)已批準(zhǔn) 日期2026-08-18 參考類com.jingdong.ai_super_love_agent.tools.WebSearchTool ## 約束回顧 1. Bean 交給 Spring 管理工具類加 Component禁止手動(dòng) new 帶注解的 Bean 2. 必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及 NPE 異常報(bào)錯(cuò) 3. 使用 jsoup 庫(kù)實(shí)現(xiàn)網(wǎng)頁(yè)抓取功能 ## 一、需求拆解 | # | 子需求 | 說明 | |---|--------|------| | 1 | 引入 jsoup 依賴 | pom.xml 新增 org.jsoup:jsoup:1.23.1 | | 2 | 工具注冊(cè) | Component 交給 Spring 管理方法加 Tool ToolParam返回 String風(fēng)格對(duì)齊 WebSearchTool | | 3 | **入?yún)⑿ｒ?yàn)** | url 判空 協(xié)議校驗(yàn)僅 http/https非法入?yún)?*直接返回錯(cuò)誤提示不發(fā)起請(qǐng)求**防止浪費(fèi)資源 | | 4 | jsoup 抓取 | Jsoup.connect(url) 設(shè)置超時(shí)、UA、maxBodySize解析為 Document | | 5 | **返回值判空** | Document、title()、body()、body().text() 逐級(jí)判空全鏈路防 NPE | | 6 | 異常兜底 | 統(tǒng)一 catch失敗返回 Error scraping url: xxx 字符串不拋異常對(duì)齊 WebSearchTool | | 7 | 單元測(cè)試 | 輕量測(cè)試不啟動(dòng) Spring 容器只驗(yàn)證基本功能 | ## 二、類設(shè)計(jì) tools/WebScrapingTool.java ├── ComponentSpring 管理禁止手動(dòng) new ├── 常量 │ ├── TIMEOUT_MS 10_000 // 連接讀取超時(shí) │ ├── MAX_BODY_SIZE 2MB // jsoup 下載體積上限防超大頁(yè)面 │ ├── MAX_TEXT_LENGTH 5000 // 返回給大模型的文本截?cái)嚅L(zhǎng)度 │ └── USER_AGENT // 常規(guī)瀏覽器 UA降低被反爬概率 │ ├── Tool scrapeWebPage(ToolParam url) : String │ │ 執(zhí)行鏈路校驗(yàn)前置任一失敗立即返回不浪費(fèi)請(qǐng)求 │ ├── ① StringUtils.isEmpty(url) → 空參直接返回錯(cuò)誤提示 │ ├── ② isValidUrl(url) 協(xié)議白名單校驗(yàn) → 非法協(xié)議直接返回錯(cuò)誤提示 │ ├── ③ Jsoup.connect(url).timeout().userAgent().maxBodySize().get() │ ├── ④ document null 判空 → 返回錯(cuò)誤提示 │ ├── ⑤ doc.title() / doc.body() 判空 → body 為空返回頁(yè)面內(nèi)容為空提示 │ ├── ⑥ body.text() 判空 拼接 title → 截?cái)嘀?MAX_TEXT_LENGTH 返回 │ └── ⑦ catch Exception → 返回 Error scraping url: e.getMessage() │ └── private boolean isValidUrl(String url) // 協(xié)議白名單http/https **判空清單對(duì)應(yīng)約束2** | 判空點(diǎn) | 不判空的后果 | |--------|------------| | url 空/非法 | 白白發(fā)起請(qǐng)求、IllegalArgumentException | | Document null | NPE | | doc.title() null | 拼接出 null 臟數(shù)據(jù) | | doc.body() null | .text() 直接 NPE部分頁(yè)面無 body 標(biāo)簽 | | body.text() 空串 | 返回?zé)o意義空內(nèi)容LLM 誤判 | ## 三、風(fēng)險(xiǎn)點(diǎn) | 風(fēng)險(xiǎn) | 影響 | 應(yīng)對(duì) | |------|------|------| | JS 動(dòng)態(tài)渲染頁(yè)面SPA | jsoup 不執(zhí)行 JS只拿到靜態(tài) HTML | 接受限制返回已抓取內(nèi)容不引入瀏覽器內(nèi)核 | | 反爬 403 / 驗(yàn)證碼頁(yè) | 抓取失敗 | 設(shè)置瀏覽器 UAHttpStatusException 單獨(dú)捕獲返回明確狀態(tài)碼提示 | | 超大頁(yè)面 | OOM / token 爆炸 | maxBodySize(2MB) 下載層限流 MAX_TEXT_LENGTH 返回層截?cái)?| | 請(qǐng)求掛起 | 阻塞工具調(diào)用鏈 | timeout(10s) | | 二進(jìn)制內(nèi)容圖片/PDF 鏈接 | 解析出亂碼 | jsoup 默認(rèn)對(duì)非 HTML 拋 UnsupportedMimeTypeException單獨(dú)捕獲返回提示 | | SSRFLLM 被誘導(dǎo)傳內(nèi)網(wǎng)地址 | 探測(cè)內(nèi)網(wǎng) | 本期做協(xié)議白名單內(nèi)網(wǎng) IP 黑名單列入后續(xù)增強(qiáng) | | 編碼亂碼 | 中文亂碼 | jsoup 根據(jù)響應(yīng)頭/meta 自動(dòng)識(shí)別 charset | | 惡意 HTML 注入 | jsoup 僅解析不執(zhí)行腳本且返回純文本 | 風(fēng)險(xiǎn)低body().text() 天然剝離標(biāo)簽 | ## 四、交付物清單 1. pom.xml 新增 jsoup 1.23.1 依賴 2. src/main/java/com/jingdong/ai_super_love_agent/tools/WebScrapingTool.java 3. src/test/java/com/jingdong/ai_super_love_agent/tools/WebScrapingToolTest.java僅基本功能校驗(yàn)類用例不發(fā)真實(shí)網(wǎng)絡(luò)請(qǐng)求 ## 五、參數(shù)默認(rèn)值已確認(rèn) | 參數(shù) | 值 | |------|-----| | 超時(shí) | 10s | | 下載體積上限 | 2MB | | 返回文本截?cái)嚅L(zhǎng)度 | 5000 字符 |然后claude 直接經(jīng)過我同意存儲(chǔ)技術(shù)方案.md后,直接開始寫代碼了,雖然一次過了但是這是不可控的點(diǎn)。故需優(yōu)化提示詞:在1中的提示詞末尾應(yīng)該說明: 經(jīng)過我同意存儲(chǔ)技術(shù)方案后,必須再次詢問我是否允許你開始寫代碼我同意你才可以繼續(xù)。另外,在測(cè)試中也有踩坑點(diǎn),在寫完功能開發(fā)代碼后順手將單元測(cè)試代碼補(bǔ)全了,且沒有事先生成單元測(cè)試技術(shù)方案,不太嚴(yán)謹(jǐn)。最后,寫完單元測(cè)試沒有在類上使用SpringbootTest注解且沒有使用Resource注入網(wǎng)頁(yè)抓取工具類,直接new對(duì)象,這個(gè)我們需要在單元測(cè)試提示詞中增加對(duì)應(yīng)約束,保證我們代碼規(guī)范的統(tǒng)一。故關(guān)于單元測(cè)試的提示詞修復(fù)如下:在1 生成技術(shù)方案 中的提示詞中: 移除關(guān)于單元測(cè)試的要求。 在后續(xù)的單元測(cè)試約束中添加 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類由此可見我們踩的坑都可以作為下次的約束條件,我們的約束條件也是不斷更新并且增加的,有助于減少模型的不確定性。4. 修復(fù)后整體的生成技術(shù)方案的提示詞(暫時(shí)包含單元測(cè)試):角色SpringBoot Java后端AI Agent工具開發(fā)。 項(xiàng)目AI Agent工具調(diào)用服務(wù)Bean交給Spring管理禁止手動(dòng)new帶注解的Bean。 需求開發(fā)網(wǎng)頁(yè)抓取工具調(diào)用寫在包名tools下,工具類命名為WebScrapingTool。使用jsoup庫(kù)實(shí)現(xiàn)網(wǎng)頁(yè)抓取功能。 約束 1.工具類加Component禁止手動(dòng)new 2.必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及NPE異常報(bào)錯(cuò)。 3. 若有需要,做好超時(shí)、重試邏輯兜底、異常處理 4. 生產(chǎn)環(huán)境下需要的log日志進(jìn)行必要的填充,便于定位錯(cuò)誤,使用Slf4j注解。 單元測(cè)試約束 1. 類上均使用SpringbootTest注解 2. 測(cè)試的工具類都要使用Resource進(jìn)行依賴注入禁止手動(dòng)new 工具類 參考WebSearchTool 輸出先輸出技術(shù)方案需求拆解類設(shè)計(jì)、風(fēng)險(xiǎn)點(diǎn)不要直接寫完整代碼。 技術(shù)方案存儲(chǔ)位置: src/main/resources/ToolCalling設(shè)計(jì)方案。必須我同意后才可以存儲(chǔ)到指定位置。 注意: 經(jīng)過我同意存儲(chǔ)技術(shù)方案后,必須再次詢問我是否允許你開始寫代碼我同意你才可以繼續(xù)。場(chǎng)景三、歷史踩坑點(diǎn)全部沉淀到提示詞約束條件中(不斷擴(kuò)充)注意!這個(gè)是我們實(shí)際開發(fā)中踩的坑的歷史積累,有助于讓我們開發(fā)變得越來越精準(zhǔn)明確,符合我們項(xiàng)目架構(gòu)和代碼風(fēng)格,我們應(yīng)把歷史踩坑點(diǎn)全部填入約束條件中,等到實(shí)際使用時(shí)再有選擇的提取部分約束條件貼合我們的實(shí)際需求。1. 生成開發(fā)新需求的技術(shù)方案的約束條件(不斷更新)約束: // 通用約束 1. 必須進(jìn)行入?yún)⑿ｒ?yàn)以及各種返回值的判空校驗(yàn)防止發(fā)起網(wǎng)頁(yè)請(qǐng)求資源浪費(fèi)以及NPE異常報(bào)錯(cuò)。判空使用hutool工具類中的Util工具如CollectionUtilhutool沒有則嘗試springframework中的工具類。 2. 若有需要,做好超時(shí)、重試邏輯兜底、異常處理 3. 生產(chǎn)環(huán)境下需要的log日志進(jìn)行必要的填充,便于定位錯(cuò)誤,使用Slf4j注解。 4. 添加必要的注釋便于其他人理解代碼中關(guān)鍵步驟也要進(jìn)行注釋說明分清楚步驟如① 入?yún)⑿ｒ?yàn) ② 構(gòu)建進(jìn)程等 5. 禁止輸出任何與單元測(cè)試相關(guān)的內(nèi)容單元測(cè)試后續(xù)單獨(dú)處理 6. 要求做最小化讀取只定位并閱讀我點(diǎn)名的參考類 WebSearchTool以及查看 src/main/resources/ToolCalling設(shè)計(jì)方案 目錄下已有的方案文檔格式這是為了后續(xù)方案能對(duì)齊風(fēng)格不涉及全盤掃描 // 具體的實(shí)際項(xiàng)目約束 1. 具體需求實(shí)現(xiàn)的固定規(guī)范,如: 工具類加Component禁止手動(dòng)new // 項(xiàng)目規(guī)范 1. 當(dāng)前類中的輔助方法必須用 // helper methods 與主邏輯方法進(jìn)行隔離。