Astro + Vue 3 串接 Laravel API 的 Vibecode 防錯誤完整指南

 Astro + Vue 3 串接 Laravel API 的 Vibecode 防錯誤完整指南

在用 AI 進行 Vibecode（用 AI 高速寫程式碼）時，最容易翻車的場景就是前端串接後端 API。 AI 常常還沒搞清楚 Laravel API 的請求格式、回應結構、錯誤格式、認證方式，就直接開始亂寫，導致以下常見災難：

• 亂猜 API 路徑與 HTTP Method
• 完全不定義 TypeScript 型別，資料結構全靠猜
• 請求 Payload 格式錯誤（FormData vs JSON）
• 沒處理巢狀資料、分頁、驗證錯誤（422）
• Token 處理錯誤、CORS 問題、loading 與 error state 混亂

這篇文章提供一套系統化、防幻覺、生產可用的 Vibecode 指南，專注解決「連 API 資料格式都沒搞懂就亂寫」的核心問題。

---

一、Vibecode 核心防幻覺原則（API 專用版）

1. 環境與規則鐵律鎖定（每次提示必貼）

text

你是一位資深的 Full-stack 工程師。
專案環境：
- 前端：Astro 5 + Vue 3.4 + TypeScript + TailwindCSS 3.4
- 後端：Laravel 10/11 + Sanctum API
- 嚴格使用 Composition API (<script setup lang="ts">)
- 禁止使用 Options API、this、export default
- 所有 API 相關程式碼必須先定義完整的 TypeScript interfaces
- 使用 fetch，必須包含 loading、error、資料驗證機制

2. 「先定義資料結構」鐵律

這是最關鍵的一步。 絕對不要讓 AI 直接寫 API 呼叫，必須先強迫它理解資料格式。

正確提示順序：

1. 提供 Laravel API 的實際回應範例（JSON）
2. 要求 AI 轉成 TypeScript interfaces
3. 再要求根據 interfaces 撰寫 composable

---

二、完整開發流程（防錯誤版）

Step 1：取得並定義 API 資料結構

提示詞範例：

以下是 Laravel API 「取得文章列表」的真實回應 JSON：

JSON

{
  "success": true,
  "data": [
    { "id": 1, "title": "...", "content": "...", "author": { "name": "..." }, "created_at": "..." }
  ],
  "meta": { "current_page": 1, "last_page": 5, "total": 42 }
}

請先幫我轉換成完整的 TypeScript interfaces（放在 src/types/api.ts），包含 success、data、meta、以及可能的 error 格式（422 validation error）。

讓 AI 先輸出型別，再繼續下一步。

Step 2：建立統一的 API Client

提示詞：

根據上面定義的 types，建立 src/composables/useApi.ts。 要求：

• 基底 URL 可透過 import.meta.env.VITE_API_URL 設定
• 自動從 localStorage 或 cookie 取得 Sanctum token 並加入 Authorization: Bearer xxx
• 支援 GET/POST/PUT/DELETE
• 統一處理 HTTP 錯誤（401 登出、422 回傳 validationErrors）
• 回傳格式統一為 { data, error, loading }
• 完整 TypeScript 支援

Step 3：針對特定功能建立 Composable

提示詞（以文章列表為例）：

現在請依照以下步驟：

1. 先條列這個功能的實作思路（包含資料 fetching 時機、ref 變數、錯誤處理）
2. 根據前面定義的 interfaces，撰寫 src/composables/usePosts.ts
3. 實作 getPosts(page?: number)、createPost() 等方法
4. 最後自我檢查型別安全與錯誤處理是否完整

Step 4：建立 Vue 島嶼元件

根據 usePosts.ts，建立 src/components/PostList.vue 作為 Astro Island。

• 使用 client:visible
• 顯示 loading 狀態
• 錯誤訊息提示
• 分頁功能
• 嚴格使用 defineProps / defineEmits（如果需要）

Step 5：在 Astro 頁面中整合

在 src/pages/posts.astro 中正確引入 PostList.vue 島嶼，並傳遞必要 props。

---

三、推薦專案結構

text

src/
├── types/
│   └── api.ts                 # 所有 Laravel 回應型別
├── composables/
│   ├── useApi.ts              # 核心 API client
│   ├── useAuth.ts
│   └── usePosts.ts
├── components/                # .vue Islands
├── layouts/
├── pages/                     # .astro
└── lib/
    └── auth.ts                # token 管理

---

四、常見幻覺錯誤與精準修正指令

當 AI 出錯時，直接複製以下指令回應：

• 型別錯誤：「你沒有使用前面定義的 Post interface，請修正並確保所有資料都符合型別。」
• 請求格式錯誤：「POST 請求請使用 JSON body（Content-Type: application/json），並確認 payload 符合 Laravel 預期。」
• 錯誤處理不足：「請加入 422 validation error 的處理，把 errors 物件顯示在表單上。」
• Astro 島嶼問題：「Vue 元件在 Astro 中必須加上 client:xxx 指令，請修正。」
• Token 處理：「請在 useApi 中正確處理 token 過期（401）並呼叫 logout。」

---

五、高效提示模板（直接複製使用）

text

你現在是 Astro + Vue 3 + Laravel API 專家。
[環境鎖定段落貼這裡]

需求：實作會員中心 - 我的文章列表

請嚴格依照以下步驟：
1. 先確認或補充相關 TypeScript interfaces（Post, ApiResponse, ValidationError）
2. 用條列式說明實作思路
3. 輸出完整程式碼：
   - src/composables/usePosts.ts
   - src/components/MyPosts.vue
4. 最後進行自我審核，列出可能問題並修正

請務必確保型別安全與錯誤處理完整。

---

六、進階防護技巧

• 提供多個 API 範例：一次給列表、單筆、建立、錯誤回應，讓 AI 更了解後端風格。
• 要求生成測試資料：讓 AI 同時產生 mock data，方便前端在後端未完成時開發。
• 強制使用 Zod 或 runtime 驗證（可選）：在重要 composable 中加入資料驗證層。
• 版本控制提示：把目前使用的 Laravel API 版本與主要 endpoint 清單固定在提示中。

---

結語

Vibecode 的真正威力不在於「AI 寫得快」，而在於你能否讓 AI 理解真實世界的資料結構與限制。

只要堅持「先定義型別 → 再寫 composable → 再做 UI → 最後整合」的流程，並且每次都鎖定環境與規則，你會發現：

• 生成的程式碼錯誤率大幅下降
• 前後端串接順暢許多
• 重構與維護成本降低
• 真正實現「一天完成原本三天的功能」

如何在 Antigravity 中建立高效防幻覺機制—— Astro + Vue 3 + Laravel 12 全端專案實戰指南在 AI Agent 輔助開發（Vibe Coding）越來越普及的今天，Agent 寫程式碼的速度飛快，但「幻覺」（Hallucination）問題也隨之而來：亂用不存在的 API、破壞專案架構、混用不同版本語法、忘記既有的 composable……這些問題在長任務中特別明顯。本文將手把手教你，如何透過規則文件化 + 結構化流程 + 分層審核，在 Antigravity 中打造一套實戰級的防幻覺系統，特別適用於 Astro + Vue 3 + Laravel 12 + Filament v3 技術棧。

---

一、為什麼需要系統化的防幻覺機制？單靠單一 Prompt 很容易失效，尤其當專案越來越大、上下文越來越長時，Agent 容易「記憶漂移」。有效解法是把「架構思維」轉化為可執行、可驗證的規則，讓 Agent 從「自由發揮」變成「按規範施工」。

---

二、專案規則文件化（最重要基礎）在專案根目錄建立資料夾：

bash

.antigravity/
└── rules/
    ├── PROJECT_CONTEXT.md
    ├── TECH_STACK_SCHEMA.md
    ├── API_RULES.md
    ├── FORBIDDEN_PATTERNS.md
    └── RECOMMENDED_PATTERNS.md

1. PROJECT_CONTEXT.md（專案總覽）

markdown

## 技術棧鎖定
- Backend: Laravel 12 (PHP 8.3+)
- Admin: Filament v3
- Frontend: Astro 5.0 + Vue 3.5 (Composition API + <script setup>)
- 狀態管理: Nano Stores（跨 Island）+ Pinia（複雜頁面）

## 架構鐵律
- 所有商業邏輯必須放在 `app/Services/` 或 Domain 層
- Controller 只負責驗證、授權與 Response 格式化
- 前端所有 API 呼叫必須經過 `src/composables/useApi.ts`
- 禁止在 Vue Component 中直接寫 API URL 或複雜業務邏輯

2. TECH_STACK_SCHEMA.md（技術細節規範）

• Filament v3 Form 必須使用 Schema 方式撰寫
• Vue 3 強制使用 TypeScript + <script setup>
• Astro Island 通訊優先使用 Props → Nano Stores → emit
• Laravel 12 新特性正確使用方式（例如 Str::ulid()、cast 屬性等）

3. API_RULES.md（API 防幻覺重點）

• 修改路由前必須確認 routes/api.php 已存在對應路由
• 所有 API Response 必須對應 src/types/api.ts 中的 TypeScript 介面
• 後端 422 驗證錯誤必須映射到前端表單錯誤欄位
• 所有 API 呼叫必須帶上 Sanctum Token（由 useApi 統一處理）

---

三、核心防幻覺流程設計Step 1: Reference Discovery（現狀探查）在每一次任務 Prompt 中強制加入：

「在開始撰寫程式碼前，請先掃描 src/composables/ 和 app/Services/ 目錄，找出 2~3 個最相似的現有檔案，並嚴格參考它們的命名風格、錯誤處理模式與型別定義。」

Step 2: Agentic TDD（測試驅動）要求 Coder Agent 完成程式碼後，立即產生測試：

• Backend：使用 Pest PHP
• Frontend：使用 Vitest + Vue Test Utils

並加入指令：

「請生成測試並在 Terminal 中執行。若測試失敗，請根據錯誤訊息進行自我修正，最多重試 3 次。若仍失敗則停止並說明原因。」

Step 3: 分層審核機制（Reviewer Agent）設定 Slash Command /verify：

markdown

**System Command (/verify)**

請以 Reviewer Agent 身分，掃描目前 Workspace 的變更，對照 `.antigravity/rules/` 下的所有規則文件。
請條列回報：
1. 潛在幻覺（不存在的函式、API、變數）
2. 違反的架構規則
3. 型別安全問題
4. 安全性風險
並給出具體修正建議。

---

四、實戰範例：新增一個「使用者設定」功能任務描述：新增後台會員設定頁面，包含個人資料更新與密碼修改。正確流程：

1. Reviewer 先確認 routes/api.php 是否已有對應路由
2. Coder Agent 參考現有 UserService.php 與 useApi.ts
3. 後端使用 Form Request 做驗證
4. 前端使用 useApi composable + TypeScript 介面
5. 完成後執行 /verify 審核
6. 產生並通過 Vitest 測試

---

五、進階建議

1. 把規則文件加入 Git，讓團隊與 Agent 保持同步。
2. 定期更新規則：每完成一個較大功能後，檢視是否需要補充新規則。
3. 可視化審核：讓 Reviewer Agent 輸出 Markdown 報告，方便 PR 檢視。
4. CI/CD 整合（進階）：低於一定標準時自動 block Merge。

---

六、常見幻覺與對應解法

• 幻覺：在 Controller 塞一堆業務邏輯
  解法：強制使用 Service 層 + 規則檔明文禁止
• 幻覺：前端直接寫 fetch('/api/xxx')
  解法：useApi 統一管理 + Reference Discovery
• 幻覺：混用 Filament v2 寫法
  解法：TECH_STACK_SCHEMA.md 明確列出 v3 正確 Schema

---

結語防幻覺不是靠「叫 Agent 不要亂來」，而是建立清晰的規則、強制的流程、以及獨立的審核機制。當你把架構思維轉化成文件，並讓 Agent 嚴格遵循時，AI 就會從「熱情但容易出錯的助手」，變成「真正能提升生產力的開發夥伴」。這套方法已在多個 Astro + Vue 3 + Laravel 專案中驗證有效，強烈建議你今天就建立 .antigravity/rules/ 資料夾開始實作。