跳至主要内容

如何切換 Mock 到真實 API

AppFuse 參考實作以同一份 src/conf/config.ts 支援 Mock 與真實 API。開發模式只由 .env 的 VITE_MSW 決定是否啟動 MSW；業務 service 一律呼叫相同的 /api/v1/* 契約，不應維護兩套 URL。

預設行為​

模組.env開發時行為
app-office-mockupVITE_MSW=trueMSW 攔截已註冊的 API
app-officeVITE_MSW=false/api/* 經 Vite proxy 轉到真實 Server
production build不受 VITE_MSW 啟用import.meta.env.DEV 為 false，MSW 關閉

src/conf/config.ts 的關鍵設定如下：

msw: {
  enabled: import.meta.env.DEV && import.meta.env.VITE_MSW === 'true',
},

App.tsx 取得環境配置後，只有 environOpts.app.msw.enabled 為 true 才動態載入 src/mocks/browser.ts。

從 Mock 切到真實 Server​

1. 關閉 MSW​

# .env
VITE_MSW=false

參考登入只傳全域唯一 username，tenant 由 Server 依 Account 推導。登入方式相關設定也必須與 Server 能力一致：

VITE_AUTH_LOCAL_LOGIN=true
# VITE_OIDC_REGISTRATION_ID=enterprise
# VITE_OIDC_LABEL=Company SSO

2. 設定開發代理​

// vite.config.ts
export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080/app-server',
        changeOrigin: true,
      },
    },
  },
});

代理讓瀏覽器仍以同源 /api/* 呼叫後端，通常不需要為本機開發額外放寬 CORS。若 Server 使用不同 context path，調整 target，不要在每個 service 改 URL。

3. 啟動並驗證​

npm run dev

依序確認：

  1. 瀏覽器沒有註冊中的 mockServiceWorker.js 攔截目標請求。
  2. 開發時 /config 回退使用 src/conf/config.ts，/api/v1/auth/* 經 Vite proxy 到真實 Server。
  3. 登入後的 API request 帶有預期 Authorization header。
  4. 前端、Server 顯示的 release version 與 build commit 符合部署目標。
  5. CRUD、檔案上傳、錯誤回應與分頁 header 的契約都與 Mock 相同。

暫時切回 Mock​

不需要修改程式碼：

VITE_MSW=true npm run dev

也可以把 app-office 的 .env 暫時改為 VITE_MSW=true。完成測試後應恢復 VITE_MSW=false，避免誤把 Mock 成功當成 Server 整合成功。

漸進式切換單一 API​

MSW 啟用時，未匹配的 request 會以 onUnhandledRequest: 'bypass' 通過。因此可以先從 handlers/index.ts 移除準備連接真實 Server 的 handler，再保留其他 Mock handlers。

export const handlers = [
  ...authHandlers,
  // 暫時不註冊 productHandlers，/api/v1/products 將通過 Vite proxy
  ...orderHandlers,
];

:::caution 認證與資料相依性 部分 Mock handler 共享 mock token、tenant 與 seed data。單獨旁路某個 domain 前，必須確認 真實 Server 接受目前的認證資料，而且其關聯資料 ID 不依賴 Mock database。 :::

常見問題​

症狀優先檢查
Request 仍回傳 Mock 資料.env 的 VITE_MSW、Service Worker 狀態、handler 是否仍註冊
/api/* 回 404vite.config.ts proxy target 與 Server context path
登入失敗username 是否全域唯一且存在、登入方式、token refresh 契約
瀏覽器出現 CORS是否繞過同源 proxy 直接呼叫另一個 origin

下一步​