用結(jié)構(gòu)樣本：AI生成代碼不跑偏的關(guān)鍵)
先說一個(gè)我踩過的坑。幾個(gè)月前我用人工智能編程工具寫一個(gè)待辦任務(wù)模塊需求描述寫得很清楚創(chuàng)建待辦、列表查詢、標(biāo)記完成、刪除。生成出來的代碼單看每個(gè)方法都沒問題真跑起來卻發(fā)現(xiàn)一堆結(jié)構(gòu)性問題——Controller里塞了狀態(tài)判斷Service直接寫SQLRepository上方憑空多出一個(gè)“查詢所有任務(wù)后在內(nèi)存里排序”的邏輯。后來我換了輸入方式先給AI一份方法調(diào)用結(jié)構(gòu)樣本再讓它按樣本生成。代碼質(zhì)量立刻提升了一個(gè)檔次。這件事讓我意識(shí)到一個(gè)關(guān)鍵點(diǎn)——所謂的人工智能編程真正決定產(chǎn)出上限的往往不是提示詞寫得多花哨而是你有沒有給AI提供一份清晰的方法調(diào)用結(jié)構(gòu)樣本。這篇文章就圍繞這個(gè)主題展開方法調(diào)用結(jié)構(gòu)樣本到底是什么、待辦任務(wù)場景下怎么設(shè)計(jì)、按什么姿勢(shì)喂給AI、實(shí)際踩過哪些坑。適合正在用AI寫業(yè)務(wù)代碼的開發(fā)者也適合想在團(tuán)隊(duì)里統(tǒng)一AI生成代碼風(fēng)格的讀者參考。1. 為什么AI編程離不開方法調(diào)用結(jié)構(gòu)樣本1.1 一次待辦任務(wù)代碼的“翻車現(xiàn)場”我最初用的提示詞大概是這樣的“幫我寫一個(gè)待辦任務(wù)模塊包含創(chuàng)建、列表、完成、刪除功能用Spring Boot實(shí)現(xiàn)。”需求不可謂不清楚AI也不負(fù)眾望地生成了一大堆代碼。但你把構(gòu)造函數(shù)一拉開問題全出來了Controller里的createTodo方法寫了完整的參數(shù)校驗(yàn)和狀態(tài)判斷業(yè)務(wù)規(guī)則盤踞在HTTP層ApplicationService里沒有業(yè)務(wù)編排反而出現(xiàn)了JdbcTemplate直接寫SQLRepository層被繞開部分查詢邏輯散落在Service和Controller里標(biāo)記完成時(shí)直接setStatus(COMPLETED)沒有校驗(yàn)當(dāng)前狀態(tài)是否允許流轉(zhuǎn)。單看每個(gè)方法語法都沒問題但組合在一起就是典型的“能跑但沒法維護(hù)”的結(jié)構(gòu)災(zāi)難。我當(dāng)時(shí)的第一反應(yīng)是“AI不行”但冷靜下來復(fù)盤發(fā)現(xiàn)問題出在我自己身上——我沒告訴AI這個(gè)項(xiàng)目的方法調(diào)用結(jié)構(gòu)是怎么組織的。1.2 AI編程工具的真實(shí)工作方式它是模式補(bǔ)全器不是架構(gòu)師市面上主流的AI編程工具本質(zhì)上是基于海量代碼訓(xùn)練出來的模式補(bǔ)全器。你給它一個(gè)指令它根據(jù)訓(xùn)練數(shù)據(jù)里的統(tǒng)計(jì)規(guī)律預(yù)測“最有可能的下一段代碼是什么”。注意是最有可能不是最正確更不是最符合你項(xiàng)目架構(gòu)。這意味著什么AI對(duì)“正確結(jié)構(gòu)”的理解來自它見過的通用代碼而不是你項(xiàng)目的特定約定。你的項(xiàng)目是Controller → ApplicationService → DomainService → Repository的四層結(jié)構(gòu)AI腦子里卻是五花八門的Controller直接操作DAO、Service既是事務(wù)邊界又是業(yè)務(wù)邏輯集合的混亂模式。所以它生成的代碼“看起來像那么回事”但細(xì)節(jié)全是結(jié)構(gòu)硬傷。方法調(diào)用結(jié)構(gòu)樣本就是用來解決這個(gè)上下文缺失問題的。你提前把“這個(gè)項(xiàng)目里方法之間應(yīng)該怎么調(diào)用、每層該干什么、不該干什么”寫清楚AI才有依據(jù)生成符合架構(gòu)的代碼。沒有樣本AI在猜有了樣本AI在按圖施工。1.3 待辦任務(wù)最適合當(dāng)樣本的業(yè)務(wù)場景有人可能會(huì)問為什么要拿待辦任務(wù)做樣本因?yàn)樗堑湫偷摹奥槿鸽m小五臟俱全”的業(yè)務(wù)場景。待辦任務(wù)的功能不多但覆蓋了完整的后端調(diào)用鏈路創(chuàng)建涉及參數(shù)校驗(yàn)和持久化列表涉及過濾排序分頁標(biāo)記完成涉及狀態(tài)機(jī)和權(quán)限校驗(yàn)刪除涉及存在性檢查和級(jí)聯(lián)約束。這四個(gè)操作放在一起基本把Controller、ApplicationService、DomainService、Repository四層能遇到的問題全暴露了一遍。更關(guān)鍵的是待辦任務(wù)的業(yè)務(wù)規(guī)則足夠簡單容易把“調(diào)用鏈本身”和“復(fù)雜業(yè)務(wù)”剝離開讓讀者看清楚結(jié)構(gòu)長什么樣。你拿一個(gè)訂單系統(tǒng)當(dāng)樣本光狀態(tài)機(jī)就夠?qū)懸黄L文反而沖淡了方法調(diào)用結(jié)構(gòu)這個(gè)主題。所以待辦任務(wù)是我推薦的首選樣本場景學(xué)會(huì)了這里的調(diào)用關(guān)系換到訂單、庫存、任務(wù)流思路完全一致。2. 待辦任務(wù)調(diào)用鏈的骨架設(shè)計(jì)先定邊界再寫代碼2.1 一個(gè)用例對(duì)應(yīng)一個(gè)方法而不是按CRUD劃分設(shè)計(jì)方法調(diào)用結(jié)構(gòu)樣本的第一步不是打開IDE寫代碼而是先把用例邊界劃清楚。待辦任務(wù)的標(biāo)準(zhǔn)用例至少有五個(gè)創(chuàng)建待辦、查詢待辦列表、查詢待辦詳情、標(biāo)記待辦完成、刪除待辦。這里最常見的錯(cuò)誤是“按CRUD劃分方法”。很多AI生成代碼時(shí)天然喜歡把“創(chuàng)建”對(duì)應(yīng)insert“列表”對(duì)應(yīng)select“刪除”對(duì)應(yīng)delete一套數(shù)據(jù)操作四板斧。結(jié)果是標(biāo)記完成這種典型的“狀態(tài)變更用例”被硬生生拆成了“先把記錄查出來再改個(gè)狀態(tài)字段再存回去”的散裝代碼。按用例劃分的意思是讓ApplicationService的每個(gè)方法完整表達(dá)一個(gè)業(yè)務(wù)用戶故事。createTodo就是“創(chuàng)建一個(gè)待辦”從校驗(yàn)參數(shù)到落庫到返回VO一氣呵成。completeTodo就是“把一個(gè)待辦標(biāo)記完成”從查存在性到校驗(yàn)狀態(tài)到變更到落庫同樣一氣呵成。一個(gè)方法對(duì)應(yīng)一個(gè)完整用例調(diào)用鏈清晰AI也好模仿人也好review。2.2 調(diào)用鏈四層職責(zé)拆分待辦任務(wù)的方法調(diào)用結(jié)構(gòu)我用四層來定義這也是我在團(tuán)隊(duì)里推薦的標(biāo)準(zhǔn)形態(tài)層職責(zé)允許做的事禁止做的事ControllerHTTP入口適配參數(shù)解析、調(diào)用ApplicationService、返回VO寫業(yè)務(wù)判斷、直接操作實(shí)體、訪問RepositoryApplicationService用例編排調(diào)度DomainService和Repository開啟事務(wù)寫SQL、拼業(yè)務(wù)規(guī)則、直接操作實(shí)體內(nèi)部狀態(tài)DomainService領(lǐng)域規(guī)則校驗(yàn)狀態(tài)流轉(zhuǎn)校驗(yàn)、權(quán)限校驗(yàn)、業(yè)務(wù)不變量校驗(yàn)做持久化、編排多個(gè)用例、返回值里塞DTORepository持久化適配保存、查詢、刪除、分頁過濾寫業(yè)務(wù)規(guī)則、返回組裝好的VO這套劃分不是銀彈但勝在簡單可執(zhí)行AI照著樣本不容易跑偏。核心思想是每一層只做一件事層與層之間單向依賴不允許往回調(diào)用。拿DomainService舉例它很容易和ApplicationService混淆。我的判據(jù)很簡單ApplicationService管的是“這個(gè)用例要經(jīng)過哪些步驟”DomainService管的是“這個(gè)領(lǐng)域規(guī)則允不允許”。前者是流程編排者后者是規(guī)則裁判員。裁判員只做判斷不做操作所以DomainService的方法最好返回void校驗(yàn)不過就拋異常校驗(yàn)通過就靜靜返回。2.3 方法命名、返回值和異常的硬性約定骨架設(shè)計(jì)里最容易被忽略但恰恰是AI最需要明確指示的三件事方法怎么命名、返回值給什么、異常怎么拋。方法命名我要求“動(dòng)詞開頭、表達(dá)業(yè)務(wù)意圖”。創(chuàng)建待辦就叫createTodo不叫insertTodo標(biāo)記完成就叫completeTodo不叫updateStatus。命名是調(diào)用鏈的第一層語言命名爛了整個(gè)結(jié)構(gòu)就開始松動(dòng)。AI在這方面的能力比人更差因?yàn)樗鼉A向從數(shù)據(jù)視角命名你必須在樣本里替它立好規(guī)矩。返回值方面我的約定是“永不出實(shí)體一律出VO”。Controller返回給前端的必須是TodoVO不直接返回Todo實(shí)體。貧血模型還是充血模型之爭先放一邊至少對(duì)外輸出要保持穩(wěn)定。如果讓AI放飛自我它會(huì)在三個(gè)不同的方法里分別返回實(shí)體、DTO、Mapreview到懷疑人生。異常處理更是一個(gè)坑。我要求領(lǐng)域規(guī)則校驗(yàn)統(tǒng)一拋InvalidTodoException、狀態(tài)沖突拋TodoStateConflictException、未授權(quán)拋TodoPermissionException由全局異常處理器統(tǒng)一映射成HTTP狀態(tài)碼。一切為了不讓AI在Controller里寫try-catch。3. 一份可以直接復(fù)用的方法調(diào)用結(jié)構(gòu)樣本3.1 創(chuàng)建待辦任務(wù)的調(diào)用鏈樣本這部分我把實(shí)際在項(xiàng)目里用的樣本貼出來代碼用Java演示換成TypeScript或Golang只是語法差異調(diào)用結(jié)構(gòu)完全一樣。同時(shí)也是這段內(nèi)容的核心——先看完整調(diào)用鏈再怎么拆// #SAMPLE:CREATE_TODO // // 調(diào)用鏈TodoController.createTodo // → TodoApplicationService.createTodo // → TodoDomainService.validateNewTodo // → TodoRepository.save // 約束 // - Controller 只做 HTTP 參數(shù)解析不寫業(yè)務(wù)判斷 // - ApplicationService 內(nèi)部不出現(xiàn) if 和校驗(yàn)邏輯 // - 領(lǐng)域校驗(yàn)統(tǒng)一放 DomainService // RestController RequestMapping(/api/v1/todos) public class TodoController { private final TodoApplicationService todoApplicationService; public TodoController(TodoApplicationService todoApplicationService) { this.todoApplicationService todoApplicationService; } PostMapping public ResponseEntityTodoVO createTodo(RequestBody TodoCreateRequest request) { TodoCreateCommand command request.toCommand(CurrentUser.id()); TodoVO vo todoApplicationService.createTodo(command); return ResponseEntity.ok(vo); } }Service public class TodoApplicationService { private final TodoDomainService todoDomainService; private final TodoRepository todoRepository; public TodoApplicationService(TodoDomainService todoDomainService, TodoRepository todoRepository) { this.todoDomainService todoDomainService; this.todoRepository todoRepository; } Transactional public TodoVO createTodo(TodoCreateCommand cmd) { Todo todo cmd.toEntity(); todoDomainService.validateNewTodo(todo); todoRepository.save(todo); return TodoVO.from(todo); } }Component public class TodoDomainService { private static final int MAX_TITLE_LENGTH 50; public void validateNewTodo(Todo todo) { if (todo.getTitle() null || todo.getTitle().trim().isEmpty()) { throw new InvalidTodoException(待辦標(biāo)題不能為空); } if (todo.getTitle().length() MAX_TITLE_LENGTH) { throw new InvalidTodoException(標(biāo)題長度不能超過50個(gè)字符); } if (todo.getDeadline() ! null todo.getDeadline().isBefore(LocalDateTime.now())) { throw new InvalidTodoException(截止時(shí)間不能早于當(dāng)前時(shí)間); } } }public interface TodoRepository { void save(Todo todo); OptionalTodo findById(Long id); ListTodo findByUserId(Long userId, Pageable pageable); ListTodo findByUserIdAndStatus(Long userId, TodoStatus status, Pageable pageable); void delete(Todo todo); }這段樣本覆蓋了完整鏈路。留意幾個(gè)細(xì)節(jié)Controller連命令對(duì)象都不自己組裝而是讓Request的toCommand方法完成ApplicationService里沒有任何if校驗(yàn)完全委托給DomainServiceRepository接口在樣本里一并寫好為的是堵住AI“發(fā)明新方法”的嘴。3.2 標(biāo)記完成與刪除的調(diào)用鏈樣本創(chuàng)建是新增相對(duì)簡單。標(biāo)記完成是狀態(tài)變更調(diào)用鏈要復(fù)雜一截因?yàn)樗嗔艘粋€(gè)“先查后改”的過程// #SAMPLE:COMPLETE_TODO // 調(diào)用鏈TodoController.completeTodo // → TodoApplicationService.completeTodo // → TodoRepository.findById先查存在性 // → TodoDomainService.validateCompletion再校驗(yàn)規(guī)則 // → todo.markCompleted()執(zhí)行狀態(tài)變更 // → TodoRepository.save最后落庫 PatchMapping(/{id}/complete) public ResponseEntityTodoVO completeTodo(PathVariable Long id, RequestBody TodoCompleteRequest request) { TodoCompleteCommand command new TodoCompleteCommand( id, CurrentUser.id(), request.getCompletedAt()); TodoVO vo todoApplicationService.completeTodo(command); return ResponseEntity.ok(vo); }Transactional public TodoVO completeTodo(TodoCompleteCommand cmd) { Todo todo todoRepository.findById(cmd.getTodoId()) .orElseThrow(() - new TodoNotFoundException(cmd.getTodoId())); todoDomainService.validateCompletion(todo, cmd.getUserId()); todo.markCompleted(cmd.getCompletedAt()); todoRepository.save(todo); return TodoVO.from(todo); }public void validateCompletion(Todo todo, Long userId) { if (!todo.belongsTo(userId)) { throw new TodoPermissionException(無權(quán)操作他人的待辦任務(wù)); } if (todo.getStatus() TodoStatus.COMPLETED) { throw new TodoStateConflictException(該待辦已完成不能重復(fù)操作); } if (todo.getStatus() TodoStatus.CANCELLED) { throw new TodoStateConflictException(已取消的待辦不能標(biāo)記完成); } }刪除操作的調(diào)用鏈和完成操作很接近deleteTodo同樣先findById查存在性再做歸屬和狀態(tài)校驗(yàn)最后調(diào)TodoRepository.delete(todo)。沒必要整段貼出來但要注意刪除也要走“先查后刪”不能讓AI直接寫deleteById(id)了事否則把別人的待辦刪了都沒人知道。3.3 列表查詢鏈路與狀態(tài)流轉(zhuǎn)約束查詢鏈路和寫入鏈路不一樣寫入是“實(shí)例方法調(diào)用序列”查詢更接近“參數(shù)傳遞鏈”。但同樣有結(jié)構(gòu)約束// #SAMPLE:LIST_TODOS // 查詢鏈路TodoController.listTodos // → TodoApplicationService.listTodos // → TodoRepository.findByUserIdAndStatus // → 組裝 TodoVO // 約束排序、分頁、過濾全部在 Repository 完成 // 禁止把全量數(shù)據(jù)拉到內(nèi)存再過濾 GetMapping public ResponseEntityPageResultTodoVO listTodos( RequestParam(required false) TodoStatus status, RequestParam(defaultValue 0) int page, RequestParam(defaultValue 20) int size) { PageResultTodoVO result todoApplicationService.listTodos( CurrentUser.id(), status, page, size); return ResponseEntity.ok(result); }public PageResultTodoVO listTodos(Long userId, TodoStatus status, int page, int size) { Pageable pageable PageRequest.of(page, size, Sort.by(Sort.Direction.DESC, createdAt)); ListTodo todos; if (status null) { todos todoRepository.findByUserId(userId, pageable); } else { todos todoRepository.findByUserIdAndStatus(userId, status, pageable); } return PageResult.from(todos.stream().map(TodoVO::from).toList()); }查詢鏈路樣本里最重要的一條約束是“不要在內(nèi)存里過濾和排序”。AI特別容易在Repository沒有提供對(duì)應(yīng)方法時(shí)直接findByUserId拿到全量列表再在Service里用Stream做過濾排序。數(shù)據(jù)量小的時(shí)候沒問題一旦單用戶待辦破千這種寫法就是性能事故。所以樣本里必須寫死過濾排序分頁是Repository的職責(zé)。狀態(tài)流轉(zhuǎn)約束是待辦任務(wù)里最容易丟的一環(huán)。我把這張狀態(tài)機(jī)表也放進(jìn)樣本當(dāng)前狀態(tài)允許到達(dá)狀態(tài)觸發(fā)操作NEWIN_PROGRESS開始任務(wù)NEWCOMPLETED直接完成NEWCANCELLED取消任務(wù)IN_PROGRESSCOMPLETED標(biāo)記完成IN_PROGRESSCANCELLED取消任務(wù)COMPLETED無終態(tài)CANCELLED無終態(tài)4. 把樣本正確喂給AI的三種姿勢(shì)4.1 對(duì)話式AI樣本前置 明確指令很多人用對(duì)話式AI編程的習(xí)慣是直接說需求這其實(shí)是把AI當(dāng)成了“懂項(xiàng)目背景的老同事”。正確姿勢(shì)是把需求描述和項(xiàng)目約定分開先給項(xiàng)目約定再給需求。我實(shí)際用的提示詞結(jié)構(gòu)是這樣的你是一位熟悉分層架構(gòu)的Java工程師。項(xiàng)目使用 Controller → ApplicationService → DomainService → Repository 四層結(jié)構(gòu)方法調(diào)用約束如下 [此處粘貼上文的方法調(diào)用結(jié)構(gòu)樣本包括三個(gè)樣本代碼反例約定] 請(qǐng)按照以上調(diào)用鏈結(jié)構(gòu)實(shí)現(xiàn)“編輯待辦標(biāo)題”功能。 編輯規(guī)則標(biāo)題不能為空長度不超過50字符只能編輯自己的待辦。注意順序樣本在前需求在后。這份提示詞還有一個(gè)隱藏作用——當(dāng)需求描述和樣本矛盾時(shí)AI會(huì)優(yōu)先遵守約束更強(qiáng)的指令而不是放飛想象力。4.2 IDE輔助編程樣本目錄與符號(hào)標(biāo)記在Cursor、Copilot這類IDE工具里把全部樣本堆在提示詞里不現(xiàn)實(shí)更推薦的方式是把樣本做成項(xiàng)目里的“可檢索文檔”。我在項(xiàng)目根目錄維護(hù)了一個(gè)docs/ai-patterns/目錄里面放method-call-patterns.md核心代碼塊統(tǒng)一用#SAMPLE:CREATE_TODO、#SAMPLE:COMPLETE_TODO這類大寫標(biāo)簽開頭。這樣做有兩個(gè)好處。第一編輯器里的AI補(bǔ)全能通過注釋感知項(xiàng)目約定你在寫createTodo時(shí)它會(huì)從歷史代碼和樣本注釋里領(lǐng)悟調(diào)用風(fēng)格。第二用Cursor的對(duì)話功能時(shí)可以直接這個(gè)文件告訴AI“先讀這個(gè)文件再干活”。4.3 輸入輸出對(duì)和反例標(biāo)注只給“正向樣本”還不夠AI會(huì)把正向樣本當(dāng)成“參考風(fēng)格”但它并不知道哪些做法是紅線。所以我的樣本文件里專門有一節(jié)叫“反例約定”明文禁止四種寫法// 反例約定以下代碼模式禁止出現(xiàn)在本項(xiàng)目中 // 1. Controller 里出現(xiàn) if 判斷業(yè)務(wù)狀態(tài) // 2. ApplicationService 里出現(xiàn) SQL/JdbcTemplate // 3. Service 之間互相調(diào)用內(nèi)部方法繞過 ApplicationService // 4. Repository 返回 List 后在 Service 內(nèi)存中做過濾/排序/分頁經(jīng)驗(yàn)是AI對(duì)“禁止做什么”的遵守度遠(yuǎn)高于“應(yīng)該做什么”。人也一樣給一個(gè)明確禁止清單比對(duì)著一堆代碼猜隱含規(guī)則要高效得多。4.4 樣本也要納入版本管理樣本文件不是一次性產(chǎn)物它必須跟著項(xiàng)目架構(gòu)演進(jìn)。我見過最典型的場景是項(xiàng)目把Repository從MyBatis換成了Spring Data JPA但樣本文件沒更新AI繼續(xù)按老接口生成代碼編譯都過不了。所以凡是涉及調(diào)用鏈調(diào)整的PR都要同步改method-call-patterns.md。這和我把樣本當(dāng)“團(tuán)隊(duì)編碼憲法”的理念是一致的——它是活的約定不是存檔的筆記。我在提交記錄里甚至?xí)憽癲oc: 更新方法調(diào)用結(jié)構(gòu)樣本新增軟刪除鏈路”讓整個(gè)團(tuán)隊(duì)都能追溯架構(gòu)約定的變化。5. AI按樣本生成代碼時(shí)的典型偏差與修正5.1 偏差一方法拆分粒度不對(duì)即使給了樣本AI還是會(huì)在細(xì)節(jié)上跑偏。最常見的是方法拆分粒度問題要么把ApplicationService的多個(gè)用例塞進(jìn)一個(gè)方法要么把一個(gè)用例拆得支離破碎比如把校驗(yàn)寫成一個(gè)私有方法、把VO轉(zhuǎn)換寫成另一個(gè)私有方法、真正的業(yè)務(wù)邏輯只剩兩三行。識(shí)別方法很清楚看方法體里是不是超過30行、方法參數(shù)是不是超過4個(gè)、方法命名是不是變成了processTodoData之類。修正方法也很簡單讓AI“分步驟生成不要一次性輸出完整文件”。我通常讓它先輸出ApplicationService方法骨架再補(bǔ)DomainService校驗(yàn)規(guī)則最后寫Repository方法每步之間人工看一眼。5.2 偏差二AI自己“發(fā)明”Repository方法這是最隱蔽的一個(gè)坑。AI需要“按標(biāo)題模糊搜索待辦”時(shí)如果樣本里沒有findByTitleContaining它會(huì)很自然地在Repository接口里新增這個(gè)方法而不是復(fù)用已有的findByUserId。如果項(xiàng)目用的是JPAAI甚至?xí)l(fā)明一個(gè)映射關(guān)系完全不存在的查詢方法編譯期才發(fā)現(xiàn)錯(cuò)誤。更嚴(yán)重的是它會(huì)引入findAll()然后把過濾邏輯寫在Service里。剛才說了這是查詢鏈路的紅線。我的處理方式是樣本里加一句硬約束“Repository接口方法以樣本為準(zhǔn)AI不得新增必須新增時(shí)先詢問用戶?！边@句話看著簡單實(shí)戰(zhàn)里能省下大半review時(shí)間。5.3 偏差三事務(wù)邊界跑偏事務(wù)是AI最理解不了的機(jī)制之一。它經(jīng)常把Transactional加到DomainService上或者加到ApplicationService里一個(gè)被同類的其他方法調(diào)用的私有方法上事務(wù)直接失效。我吃過一次大虧讓AI生成“批量完成待辦”功能時(shí)AI在TodoApplicationService.batchComplete里調(diào)用了completeTodo方法但因?yàn)閮蓚€(gè)方法都在同一個(gè)類里completeTodo被同類內(nèi)部調(diào)用時(shí)繞過了代理對(duì)象事務(wù)注解根本沒生效。數(shù)據(jù)寫了一半。所以樣本里我固定了一條鐵律事務(wù)只標(biāo)注在ApplicationService的公開用例方法上DomainService和Repository一律不標(biāo)注。內(nèi)部方法調(diào)用一律通過注入的獨(dú)立Bean進(jìn)行。5.4 偏差四繞過領(lǐng)域方法直接改狀態(tài)這個(gè)偏差最隱蔽也最致命。AI生成了todo.setStatus(TodoStatus.COMPLETED)就直接落庫了完全跳過了todo.markCompleted()里的狀態(tài)機(jī)校驗(yàn)邏輯。結(jié)果就是一個(gè)CANCELLED狀態(tài)的任務(wù)可以被直接標(biāo)記成COMPLETED業(yè)務(wù)上毫無意義還污染數(shù)據(jù)。我會(huì)在樣本的實(shí)體示例代碼里明確寫出實(shí)體的內(nèi)部狀態(tài)變更方法public void markCompleted(LocalDateTime completedAt) { // 狀態(tài)流轉(zhuǎn)只在這里做 if (this.status ! TodoStatus.NEW this.status ! TodoStatus.IN_PROGRESS) { throw new TodoStateConflictException(當(dāng)前狀態(tài)不能標(biāo)記完成); } this.status TodoStatus.COMPLETED; this.completedAt completedAt; }配合“Repository保存的必須是狀態(tài)變更完成后的實(shí)體”這條約定AI基本不會(huì)再來硬改實(shí)體內(nèi)部字段。5.5 實(shí)測下來最有效的修正口訣經(jīng)過一段時(shí)間磨合我形成了一套最有效的修正檢查每次AI生成完代碼我都會(huì)跑一遍快速掃描搜索setStatus和setTitle這種直接setter確認(rèn)沒有繞過實(shí)體方法搜索new JdbcTemplate和jdbcTemplate確認(rèn)Service層沒寫SQL數(shù)一數(shù)Controller里有沒有if關(guān)鍵字有就多半是業(yè)務(wù)邏輯泄漏確認(rèn)所有Transactional都在ApplicationService的方法上?？谠E就四句先查后改校驗(yàn)在前倉儲(chǔ)接口不新增事務(wù)只寫在用例方法上。這十六個(gè)字基本上把AI在方法調(diào)用結(jié)構(gòu)上90%的偏差都堵住了。最后再分享一個(gè)我個(gè)人的使用習(xí)慣在項(xiàng)目的README里加一行鏈接指向docs/ai-patterns/method-call-patterns.md讓任何新加入項(xiàng)目的人以及任何AI編程工具都第一眼能看到這份樣本。每當(dāng)架構(gòu)有變動(dòng)先改樣本再讓AI生成代碼。這個(gè)順序一旦固定下來AI生成代碼的返工率會(huì)肉眼可見地下降。希望這篇關(guān)于方法調(diào)用結(jié)構(gòu)樣本的拆解能讓你在下次用AI寫待辦任務(wù)或者任何類似業(yè)務(wù)模塊時(shí)少踩幾個(gè)我已經(jīng)替你踩過的坑。 方法調(diào)用結(jié)構(gòu)樣本：AI生成代碼不跑偏的關(guān)鍵
先說一個(gè)我踩過的坑。幾個(gè)月前我用人工智能編程工具寫一個(gè)待辦任務(wù)模塊需求描述寫得很清楚創(chuàng)建待辦、列表查詢、標(biāo)記完成、刪除。生成出來的代碼單看每個(gè)方法都沒問題真跑起來卻發(fā)現(xiàn)一堆結(jié)構(gòu)性問題——Controller里塞了狀態(tài)判斷Service直接寫SQLRepository上方憑空多出一個(gè)“查詢所有任務(wù)后在內(nèi)存里排序”的邏輯。后來我換了輸入方式先給AI一份方法調(diào)用結(jié)構(gòu)樣本再讓它按樣本生成。代碼質(zhì)量立刻提升了一個(gè)檔次。這件事讓我意識(shí)到一個(gè)關(guān)鍵點(diǎn)——所謂的人工智能編程真正決定產(chǎn)出上限的往往不是提示詞寫得多花哨而是你有沒有給AI提供一份清晰的方法調(diào)用結(jié)構(gòu)樣本。這篇文章就圍繞這個(gè)主題展開方法調(diào)用結(jié)構(gòu)樣本到底是什么、待辦任務(wù)場景下怎么設(shè)計(jì)、按什么姿勢(shì)喂給AI、實(shí)際踩過哪些坑。適合正在用AI寫業(yè)務(wù)代碼的開發(fā)者也適合想在團(tuán)隊(duì)里統(tǒng)一AI生成代碼風(fēng)格的讀者參考。1. 為什么AI編程離不開方法調(diào)用結(jié)構(gòu)樣本1.1 一次待辦任務(wù)代碼的“翻車現(xiàn)場”我最初用的提示詞大概是這樣的“幫我寫一個(gè)待辦任務(wù)模塊包含創(chuàng)建、列表、完成、刪除功能用Spring Boot實(shí)現(xiàn)。”需求不可謂不清楚AI也不負(fù)眾望地生成了一大堆代碼。但你把構(gòu)造函數(shù)一拉開問題全出來了Controller里的createTodo方法寫了完整的參數(shù)校驗(yàn)和狀態(tài)判斷業(yè)務(wù)規(guī)則盤踞在HTTP層ApplicationService里沒有業(yè)務(wù)編排反而出現(xiàn)了JdbcTemplate直接寫SQLRepository層被繞開部分查詢邏輯散落在Service和Controller里標(biāo)記完成時(shí)直接setStatus(COMPLETED)沒有校驗(yàn)當(dāng)前狀態(tài)是否允許流轉(zhuǎn)。單看每個(gè)方法語法都沒問題但組合在一起就是典型的“能跑但沒法維護(hù)”的結(jié)構(gòu)災(zāi)難。我當(dāng)時(shí)的第一反應(yīng)是“AI不行”但冷靜下來復(fù)盤發(fā)現(xiàn)問題出在我自己身上——我沒告訴AI這個(gè)項(xiàng)目的方法調(diào)用結(jié)構(gòu)是怎么組織的。1.2 AI編程工具的真實(shí)工作方式它是模式補(bǔ)全器不是架構(gòu)師市面上主流的AI編程工具本質(zhì)上是基于海量代碼訓(xùn)練出來的模式補(bǔ)全器。你給它一個(gè)指令它根據(jù)訓(xùn)練數(shù)據(jù)里的統(tǒng)計(jì)規(guī)律預(yù)測“最有可能的下一段代碼是什么”。注意是最有可能不是最正確更不是最符合你項(xiàng)目架構(gòu)。這意味著什么AI對(duì)“正確結(jié)構(gòu)”的理解來自它見過的通用代碼而不是你項(xiàng)目的特定約定。你的項(xiàng)目是Controller → ApplicationService → DomainService → Repository的四層結(jié)構(gòu)AI腦子里卻是五花八門的Controller直接操作DAO、Service既是事務(wù)邊界又是業(yè)務(wù)邏輯集合的混亂模式。所以它生成的代碼“看起來像那么回事”但細(xì)節(jié)全是結(jié)構(gòu)硬傷。方法調(diào)用結(jié)構(gòu)樣本就是用來解決這個(gè)上下文缺失問題的。你提前把“這個(gè)項(xiàng)目里方法之間應(yīng)該怎么調(diào)用、每層該干什么、不該干什么”寫清楚AI才有依據(jù)生成符合架構(gòu)的代碼。沒有樣本AI在猜有了樣本AI在按圖施工。1.3 待辦任務(wù)最適合當(dāng)樣本的業(yè)務(wù)場景有人可能會(huì)問為什么要拿待辦任務(wù)做樣本因?yàn)樗堑湫偷摹奥槿鸽m小五臟俱全”的業(yè)務(wù)場景。待辦任務(wù)的功能不多但覆蓋了完整的后端調(diào)用鏈路創(chuàng)建涉及參數(shù)校驗(yàn)和持久化列表涉及過濾排序分頁標(biāo)記完成涉及狀態(tài)機(jī)和權(quán)限校驗(yàn)刪除涉及存在性檢查和級(jí)聯(lián)約束。這四個(gè)操作放在一起基本把Controller、ApplicationService、DomainService、Repository四層能遇到的問題全暴露了一遍。更關(guān)鍵的是待辦任務(wù)的業(yè)務(wù)規(guī)則足夠簡單容易把“調(diào)用鏈本身”和“復(fù)雜業(yè)務(wù)”剝離開讓讀者看清楚結(jié)構(gòu)長什么樣。你拿一個(gè)訂單系統(tǒng)當(dāng)樣本光狀態(tài)機(jī)就夠?qū)懸黄L文反而沖淡了方法調(diào)用結(jié)構(gòu)這個(gè)主題。所以待辦任務(wù)是我推薦的首選樣本場景學(xué)會(huì)了這里的調(diào)用關(guān)系換到訂單、庫存、任務(wù)流思路完全一致。2. 待辦任務(wù)調(diào)用鏈的骨架設(shè)計(jì)先定邊界再寫代碼2.1 一個(gè)用例對(duì)應(yīng)一個(gè)方法而不是按CRUD劃分設(shè)計(jì)方法調(diào)用結(jié)構(gòu)樣本的第一步不是打開IDE寫代碼而是先把用例邊界劃清楚。待辦任務(wù)的標(biāo)準(zhǔn)用例至少有五個(gè)創(chuàng)建待辦、查詢待辦列表、查詢待辦詳情、標(biāo)記待辦完成、刪除待辦。這里最常見的錯(cuò)誤是“按CRUD劃分方法”。很多AI生成代碼時(shí)天然喜歡把“創(chuàng)建”對(duì)應(yīng)insert“列表”對(duì)應(yīng)select“刪除”對(duì)應(yīng)delete一套數(shù)據(jù)操作四板斧。結(jié)果是標(biāo)記完成這種典型的“狀態(tài)變更用例”被硬生生拆成了“先把記錄查出來再改個(gè)狀態(tài)字段再存回去”的散裝代碼。按用例劃分的意思是讓ApplicationService的每個(gè)方法完整表達(dá)一個(gè)業(yè)務(wù)用戶故事。createTodo就是“創(chuàng)建一個(gè)待辦”從校驗(yàn)參數(shù)到落庫到返回VO一氣呵成。completeTodo就是“把一個(gè)待辦標(biāo)記完成”從查存在性到校驗(yàn)狀態(tài)到變更到落庫同樣一氣呵成。一個(gè)方法對(duì)應(yīng)一個(gè)完整用例調(diào)用鏈清晰AI也好模仿人也好review。2.2 調(diào)用鏈四層職責(zé)拆分待辦任務(wù)的方法調(diào)用結(jié)構(gòu)我用四層來定義這也是我在團(tuán)隊(duì)里推薦的標(biāo)準(zhǔn)形態(tài)層職責(zé)允許做的事禁止做的事ControllerHTTP入口適配參數(shù)解析、調(diào)用ApplicationService、返回VO寫業(yè)務(wù)判斷、直接操作實(shí)體、訪問RepositoryApplicationService用例編排調(diào)度DomainService和Repository開啟事務(wù)寫SQL、拼業(yè)務(wù)規(guī)則、直接操作實(shí)體內(nèi)部狀態(tài)DomainService領(lǐng)域規(guī)則校驗(yàn)狀態(tài)流轉(zhuǎn)校驗(yàn)、權(quán)限校驗(yàn)、業(yè)務(wù)不變量校驗(yàn)做持久化、編排多個(gè)用例、返回值里塞DTORepository持久化適配保存、查詢、刪除、分頁過濾寫業(yè)務(wù)規(guī)則、返回組裝好的VO這套劃分不是銀彈但勝在簡單可執(zhí)行AI照著樣本不容易跑偏。核心思想是每一層只做一件事層與層之間單向依賴不允許往回調(diào)用。拿DomainService舉例它很容易和ApplicationService混淆。我的判據(jù)很簡單ApplicationService管的是“這個(gè)用例要經(jīng)過哪些步驟”DomainService管的是“這個(gè)領(lǐng)域規(guī)則允不允許”。前者是流程編排者后者是規(guī)則裁判員。裁判員只做判斷不做操作所以DomainService的方法最好返回void校驗(yàn)不過就拋異常校驗(yàn)通過就靜靜返回。2.3 方法命名、返回值和異常的硬性約定骨架設(shè)計(jì)里最容易被忽略但恰恰是AI最需要明確指示的三件事方法怎么命名、返回值給什么、異常怎么拋。方法命名我要求“動(dòng)詞開頭、表達(dá)業(yè)務(wù)意圖”。創(chuàng)建待辦就叫createTodo不叫insertTodo標(biāo)記完成就叫completeTodo不叫updateStatus。命名是調(diào)用鏈的第一層語言命名爛了整個(gè)結(jié)構(gòu)就開始松動(dòng)。AI在這方面的能力比人更差因?yàn)樗鼉A向從數(shù)據(jù)視角命名你必須在樣本里替它立好規(guī)矩。返回值方面我的約定是“永不出實(shí)體一律出VO”。Controller返回給前端的必須是TodoVO不直接返回Todo實(shí)體。貧血模型還是充血模型之爭先放一邊至少對(duì)外輸出要保持穩(wěn)定。如果讓AI放飛自我它會(huì)在三個(gè)不同的方法里分別返回實(shí)體、DTO、Mapreview到懷疑人生。異常處理更是一個(gè)坑。我要求領(lǐng)域規(guī)則校驗(yàn)統(tǒng)一拋InvalidTodoException、狀態(tài)沖突拋TodoStateConflictException、未授權(quán)拋TodoPermissionException由全局異常處理器統(tǒng)一映射成HTTP狀態(tài)碼。一切為了不讓AI在Controller里寫try-catch。3. 一份可以直接復(fù)用的方法調(diào)用結(jié)構(gòu)樣本3.1 創(chuàng)建待辦任務(wù)的調(diào)用鏈樣本這部分我把實(shí)際在項(xiàng)目里用的樣本貼出來代碼用Java演示換成TypeScript或Golang只是語法差異調(diào)用結(jié)構(gòu)完全一樣。同時(shí)也是這段內(nèi)容的核心——先看完整調(diào)用鏈再怎么拆// #SAMPLE:CREATE_TODO // // 調(diào)用鏈TodoController.createTodo // → TodoApplicationService.createTodo // → TodoDomainService.validateNewTodo // → TodoRepository.save // 約束 // - Controller 只做 HTTP 參數(shù)解析不寫業(yè)務(wù)判斷 // - ApplicationService 內(nèi)部不出現(xiàn) if 和校驗(yàn)邏輯 // - 領(lǐng)域校驗(yàn)統(tǒng)一放 DomainService // RestController RequestMapping(/api/v1/todos) public class TodoController { private final TodoApplicationService todoApplicationService; public TodoController(TodoApplicationService todoApplicationService) { this.todoApplicationService todoApplicationService; } PostMapping public ResponseEntityTodoVO createTodo(RequestBody TodoCreateRequest request) { TodoCreateCommand command request.toCommand(CurrentUser.id()); TodoVO vo todoApplicationService.createTodo(command); return ResponseEntity.ok(vo); } }Service public class TodoApplicationService { private final TodoDomainService todoDomainService; private final TodoRepository todoRepository; public TodoApplicationService(TodoDomainService todoDomainService, TodoRepository todoRepository) { this.todoDomainService todoDomainService; this.todoRepository todoRepository; } Transactional public TodoVO createTodo(TodoCreateCommand cmd) { Todo todo cmd.toEntity(); todoDomainService.validateNewTodo(todo); todoRepository.save(todo); return TodoVO.from(todo); } }Component public class TodoDomainService { private static final int MAX_TITLE_LENGTH 50; public void validateNewTodo(Todo todo) { if (todo.getTitle() null || todo.getTitle().trim().isEmpty()) { throw new InvalidTodoException(待辦標(biāo)題不能為空); } if (todo.getTitle().length() MAX_TITLE_LENGTH) { throw new InvalidTodoException(標(biāo)題長度不能超過50個(gè)字符); } if (todo.getDeadline() ! null todo.getDeadline().isBefore(LocalDateTime.now())) { throw new InvalidTodoException(截止時(shí)間不能早于當(dāng)前時(shí)間); } } }public interface TodoRepository { void save(Todo todo); OptionalTodo findById(Long id); ListTodo findByUserId(Long userId, Pageable pageable); ListTodo findByUserIdAndStatus(Long userId, TodoStatus status, Pageable pageable); void delete(Todo todo); }這段樣本覆蓋了完整鏈路。留意幾個(gè)細(xì)節(jié)Controller連命令對(duì)象都不自己組裝而是讓Request的toCommand方法完成ApplicationService里沒有任何if校驗(yàn)完全委托給DomainServiceRepository接口在樣本里一并寫好為的是堵住AI“發(fā)明新方法”的嘴。3.2 標(biāo)記完成與刪除的調(diào)用鏈樣本創(chuàng)建是新增相對(duì)簡單。標(biāo)記完成是狀態(tài)變更調(diào)用鏈要復(fù)雜一截因?yàn)樗嗔艘粋€(gè)“先查后改”的過程// #SAMPLE:COMPLETE_TODO // 調(diào)用鏈TodoController.completeTodo // → TodoApplicationService.completeTodo // → TodoRepository.findById先查存在性 // → TodoDomainService.validateCompletion再校驗(yàn)規(guī)則 // → todo.markCompleted()執(zhí)行狀態(tài)變更 // → TodoRepository.save最后落庫 PatchMapping(/{id}/complete) public ResponseEntityTodoVO completeTodo(PathVariable Long id, RequestBody TodoCompleteRequest request) { TodoCompleteCommand command new TodoCompleteCommand( id, CurrentUser.id(), request.getCompletedAt()); TodoVO vo todoApplicationService.completeTodo(command); return ResponseEntity.ok(vo); }Transactional public TodoVO completeTodo(TodoCompleteCommand cmd) { Todo todo todoRepository.findById(cmd.getTodoId()) .orElseThrow(() - new TodoNotFoundException(cmd.getTodoId())); todoDomainService.validateCompletion(todo, cmd.getUserId()); todo.markCompleted(cmd.getCompletedAt()); todoRepository.save(todo); return TodoVO.from(todo); }public void validateCompletion(Todo todo, Long userId) { if (!todo.belongsTo(userId)) { throw new TodoPermissionException(無權(quán)操作他人的待辦任務(wù)); } if (todo.getStatus() TodoStatus.COMPLETED) { throw new TodoStateConflictException(該待辦已完成不能重復(fù)操作); } if (todo.getStatus() TodoStatus.CANCELLED) { throw new TodoStateConflictException(已取消的待辦不能標(biāo)記完成); } }刪除操作的調(diào)用鏈和完成操作很接近deleteTodo同樣先findById查存在性再做歸屬和狀態(tài)校驗(yàn)最后調(diào)TodoRepository.delete(todo)。沒必要整段貼出來但要注意刪除也要走“先查后刪”不能讓AI直接寫deleteById(id)了事否則把別人的待辦刪了都沒人知道。3.3 列表查詢鏈路與狀態(tài)流轉(zhuǎn)約束查詢鏈路和寫入鏈路不一樣寫入是“實(shí)例方法調(diào)用序列”查詢更接近“參數(shù)傳遞鏈”。但同樣有結(jié)構(gòu)約束// #SAMPLE:LIST_TODOS // 查詢鏈路TodoController.listTodos // → TodoApplicationService.listTodos // → TodoRepository.findByUserIdAndStatus // → 組裝 TodoVO // 約束排序、分頁、過濾全部在 Repository 完成 // 禁止把全量數(shù)據(jù)拉到內(nèi)存再過濾 GetMapping public ResponseEntityPageResultTodoVO listTodos( RequestParam(required false) TodoStatus status, RequestParam(defaultValue 0) int page, RequestParam(defaultValue 20) int size) { PageResultTodoVO result todoApplicationService.listTodos( CurrentUser.id(), status, page, size); return ResponseEntity.ok(result); }public PageResultTodoVO listTodos(Long userId, TodoStatus status, int page, int size) { Pageable pageable PageRequest.of(page, size, Sort.by(Sort.Direction.DESC, createdAt)); ListTodo todos; if (status null) { todos todoRepository.findByUserId(userId, pageable); } else { todos todoRepository.findByUserIdAndStatus(userId, status, pageable); } return PageResult.from(todos.stream().map(TodoVO::from).toList()); }查詢鏈路樣本里最重要的一條約束是“不要在內(nèi)存里過濾和排序”。AI特別容易在Repository沒有提供對(duì)應(yīng)方法時(shí)直接findByUserId拿到全量列表再在Service里用Stream做過濾排序。數(shù)據(jù)量小的時(shí)候沒問題一旦單用戶待辦破千這種寫法就是性能事故。所以樣本里必須寫死過濾排序分頁是Repository的職責(zé)。狀態(tài)流轉(zhuǎn)約束是待辦任務(wù)里最容易丟的一環(huán)。我把這張狀態(tài)機(jī)表也放進(jìn)樣本當(dāng)前狀態(tài)允許到達(dá)狀態(tài)觸發(fā)操作NEWIN_PROGRESS開始任務(wù)NEWCOMPLETED直接完成NEWCANCELLED取消任務(wù)IN_PROGRESSCOMPLETED標(biāo)記完成IN_PROGRESSCANCELLED取消任務(wù)COMPLETED無終態(tài)CANCELLED無終態(tài)4. 把樣本正確喂給AI的三種姿勢(shì)4.1 對(duì)話式AI樣本前置 明確指令很多人用對(duì)話式AI編程的習(xí)慣是直接說需求這其實(shí)是把AI當(dāng)成了“懂項(xiàng)目背景的老同事”。正確姿勢(shì)是把需求描述和項(xiàng)目約定分開先給項(xiàng)目約定再給需求。我實(shí)際用的提示詞結(jié)構(gòu)是這樣的你是一位熟悉分層架構(gòu)的Java工程師。項(xiàng)目使用 Controller → ApplicationService → DomainService → Repository 四層結(jié)構(gòu)方法調(diào)用約束如下 [此處粘貼上文的方法調(diào)用結(jié)構(gòu)樣本包括三個(gè)樣本代碼反例約定] 請(qǐng)按照以上調(diào)用鏈結(jié)構(gòu)實(shí)現(xiàn)“編輯待辦標(biāo)題”功能。 編輯規(guī)則標(biāo)題不能為空長度不超過50字符只能編輯自己的待辦。注意順序樣本在前需求在后。這份提示詞還有一個(gè)隱藏作用——當(dāng)需求描述和樣本矛盾時(shí)AI會(huì)優(yōu)先遵守約束更強(qiáng)的指令而不是放飛想象力。4.2 IDE輔助編程樣本目錄與符號(hào)標(biāo)記在Cursor、Copilot這類IDE工具里把全部樣本堆在提示詞里不現(xiàn)實(shí)更推薦的方式是把樣本做成項(xiàng)目里的“可檢索文檔”。我在項(xiàng)目根目錄維護(hù)了一個(gè)docs/ai-patterns/目錄里面放method-call-patterns.md核心代碼塊統(tǒng)一用#SAMPLE:CREATE_TODO、#SAMPLE:COMPLETE_TODO這類大寫標(biāo)簽開頭。這樣做有兩個(gè)好處。第一編輯器里的AI補(bǔ)全能通過注釋感知項(xiàng)目約定你在寫createTodo時(shí)它會(huì)從歷史代碼和樣本注釋里領(lǐng)悟調(diào)用風(fēng)格。第二用Cursor的對(duì)話功能時(shí)可以直接這個(gè)文件告訴AI“先讀這個(gè)文件再干活”。4.3 輸入輸出對(duì)和反例標(biāo)注只給“正向樣本”還不夠AI會(huì)把正向樣本當(dāng)成“參考風(fēng)格”但它并不知道哪些做法是紅線。所以我的樣本文件里專門有一節(jié)叫“反例約定”明文禁止四種寫法// 反例約定以下代碼模式禁止出現(xiàn)在本項(xiàng)目中 // 1. Controller 里出現(xiàn) if 判斷業(yè)務(wù)狀態(tài) // 2. ApplicationService 里出現(xiàn) SQL/JdbcTemplate // 3. Service 之間互相調(diào)用內(nèi)部方法繞過 ApplicationService // 4. Repository 返回 List 后在 Service 內(nèi)存中做過濾/排序/分頁經(jīng)驗(yàn)是AI對(duì)“禁止做什么”的遵守度遠(yuǎn)高于“應(yīng)該做什么”。人也一樣給一個(gè)明確禁止清單比對(duì)著一堆代碼猜隱含規(guī)則要高效得多。4.4 樣本也要納入版本管理樣本文件不是一次性產(chǎn)物它必須跟著項(xiàng)目架構(gòu)演進(jìn)。我見過最典型的場景是項(xiàng)目把Repository從MyBatis換成了Spring Data JPA但樣本文件沒更新AI繼續(xù)按老接口生成代碼編譯都過不了。所以凡是涉及調(diào)用鏈調(diào)整的PR都要同步改method-call-patterns.md。這和我把樣本當(dāng)“團(tuán)隊(duì)編碼憲法”的理念是一致的——它是活的約定不是存檔的筆記。我在提交記錄里甚至?xí)憽癲oc: 更新方法調(diào)用結(jié)構(gòu)樣本新增軟刪除鏈路”讓整個(gè)團(tuán)隊(duì)都能追溯架構(gòu)約定的變化。5. AI按樣本生成代碼時(shí)的典型偏差與修正5.1 偏差一方法拆分粒度不對(duì)即使給了樣本AI還是會(huì)在細(xì)節(jié)上跑偏。最常見的是方法拆分粒度問題要么把ApplicationService的多個(gè)用例塞進(jìn)一個(gè)方法要么把一個(gè)用例拆得支離破碎比如把校驗(yàn)寫成一個(gè)私有方法、把VO轉(zhuǎn)換寫成另一個(gè)私有方法、真正的業(yè)務(wù)邏輯只剩兩三行。識(shí)別方法很清楚看方法體里是不是超過30行、方法參數(shù)是不是超過4個(gè)、方法命名是不是變成了processTodoData之類。修正方法也很簡單讓AI“分步驟生成不要一次性輸出完整文件”。我通常讓它先輸出ApplicationService方法骨架再補(bǔ)DomainService校驗(yàn)規(guī)則最后寫Repository方法每步之間人工看一眼。5.2 偏差二AI自己“發(fā)明”Repository方法這是最隱蔽的一個(gè)坑。AI需要“按標(biāo)題模糊搜索待辦”時(shí)如果樣本里沒有findByTitleContaining它會(huì)很自然地在Repository接口里新增這個(gè)方法而不是復(fù)用已有的findByUserId。如果項(xiàng)目用的是JPAAI甚至?xí)l(fā)明一個(gè)映射關(guān)系完全不存在的查詢方法編譯期才發(fā)現(xiàn)錯(cuò)誤。更嚴(yán)重的是它會(huì)引入findAll()然后把過濾邏輯寫在Service里。剛才說了這是查詢鏈路的紅線。我的處理方式是樣本里加一句硬約束“Repository接口方法以樣本為準(zhǔn)AI不得新增必須新增時(shí)先詢問用戶?！边@句話看著簡單實(shí)戰(zhàn)里能省下大半review時(shí)間。5.3 偏差三事務(wù)邊界跑偏事務(wù)是AI最理解不了的機(jī)制之一。它經(jīng)常把Transactional加到DomainService上或者加到ApplicationService里一個(gè)被同類的其他方法調(diào)用的私有方法上事務(wù)直接失效。我吃過一次大虧讓AI生成“批量完成待辦”功能時(shí)AI在TodoApplicationService.batchComplete里調(diào)用了completeTodo方法但因?yàn)閮蓚€(gè)方法都在同一個(gè)類里completeTodo被同類內(nèi)部調(diào)用時(shí)繞過了代理對(duì)象事務(wù)注解根本沒生效。數(shù)據(jù)寫了一半。所以樣本里我固定了一條鐵律事務(wù)只標(biāo)注在ApplicationService的公開用例方法上DomainService和Repository一律不標(biāo)注。內(nèi)部方法調(diào)用一律通過注入的獨(dú)立Bean進(jìn)行。5.4 偏差四繞過領(lǐng)域方法直接改狀態(tài)這個(gè)偏差最隱蔽也最致命。AI生成了todo.setStatus(TodoStatus.COMPLETED)就直接落庫了完全跳過了todo.markCompleted()里的狀態(tài)機(jī)校驗(yàn)邏輯。結(jié)果就是一個(gè)CANCELLED狀態(tài)的任務(wù)可以被直接標(biāo)記成COMPLETED業(yè)務(wù)上毫無意義還污染數(shù)據(jù)。我會(huì)在樣本的實(shí)體示例代碼里明確寫出實(shí)體的內(nèi)部狀態(tài)變更方法public void markCompleted(LocalDateTime completedAt) { // 狀態(tài)流轉(zhuǎn)只在這里做 if (this.status ! TodoStatus.NEW this.status ! TodoStatus.IN_PROGRESS) { throw new TodoStateConflictException(當(dāng)前狀態(tài)不能標(biāo)記完成); } this.status TodoStatus.COMPLETED; this.completedAt completedAt; }配合“Repository保存的必須是狀態(tài)變更完成后的實(shí)體”這條約定AI基本不會(huì)再來硬改實(shí)體內(nèi)部字段。5.5 實(shí)測下來最有效的修正口訣經(jīng)過一段時(shí)間磨合我形成了一套最有效的修正檢查每次AI生成完代碼我都會(huì)跑一遍快速掃描搜索setStatus和setTitle這種直接setter確認(rèn)沒有繞過實(shí)體方法搜索new JdbcTemplate和jdbcTemplate確認(rèn)Service層沒寫SQL數(shù)一數(shù)Controller里有沒有if關(guān)鍵字有就多半是業(yè)務(wù)邏輯泄漏確認(rèn)所有Transactional都在ApplicationService的方法上?？谠E就四句先查后改校驗(yàn)在前倉儲(chǔ)接口不新增事務(wù)只寫在用例方法上。這十六個(gè)字基本上把AI在方法調(diào)用結(jié)構(gòu)上90%的偏差都堵住了。最后再分享一個(gè)我個(gè)人的使用習(xí)慣在項(xiàng)目的README里加一行鏈接指向docs/ai-patterns/method-call-patterns.md讓任何新加入項(xiàng)目的人以及任何AI編程工具都第一眼能看到這份樣本。每當(dāng)架構(gòu)有變動(dòng)先改樣本再讓AI生成代碼。這個(gè)順序一旦固定下來AI生成代碼的返工率會(huì)肉眼可見地下降。希望這篇關(guān)于方法調(diào)用結(jié)構(gòu)樣本的拆解能讓你在下次用AI寫待辦任務(wù)或者任何類似業(yè)務(wù)模塊時(shí)少踩幾個(gè)我已經(jīng)替你踩過的坑。