# 第六堂：串接 API 之術
## 開課提醒
1. 錄影
2. **互動簡報連結**：<https://hexschool.github.io/2026-backend-slides/#/course/js-live>
3. 今天會用到一個外部 API（LiveJS 電商 API），請先到 <https://livejs-api.hexschool.io/> 註冊取得 API Path 與 Token
4. 請先 **fork** 本週作業專案：<https://github.com/hexschool/js-camp-week6>，再把你的 fork clone 下來、`npm install`
## 今日上課知識點
今天的內容分成三大區塊：
### 🌐 區塊一：HTTP 觀念
為什麼要 API、HTTP 是什麼、RESTful、狀態碼
### ⚡ 區塊二：fetch 怎麼用
非同步 + Promise、async/await、fetch GET、response 物件、錯誤處理
### 🛒 區塊三：真實場景實戰
環境變數、LiveJS、POST/PATCH/DELETE
---
## 今天的學習地圖
先別被上面的清單嚇到。今天看起來內容很多，但其實**核心只有兩件事**：
1. **理解非同步** — 為什麼 fetch 一定要 await
2. **學會 fetch 的兩個 pattern** — GET 一個、POST 一個（PATCH 跟 DELETE 都是 POST 的變化型）
其他的東西（HTTP、RESTful、狀態碼、.env）都是「順便認識的環境知識」。
這些觀念**現在聽過有印象就好**，作業卡住的時候再回來翻講義對照，不用一次背起來。
> 把今天當成**一張地圖**，不是一張考卷。
---
## 你每天都在用 API（但你不知道）
**你每天都在串 API**，只是不知道而已。Chrome 按 `F12` → Network → 逛任何網站，都會看到上百筆請求：
| 你做的事 | 背後的 API 請求 |
|---|---|
| 在蝦皮搜尋商品 | `GET https://shopee.tw/api/v4/search/items?q=咖啡` |
| 滑 IG 動態 | `GET https://i.instagram.com/api/v1/feed/timeline` |
| 看 YouTube 影片 | `GET https://www.youtube.com/youtubei/v1/player` |
| 查 Google Maps 路線 | `GET https://maps.googleapis.com/maps/api/directions/json` |
| 查天氣 | `GET https://opendata.cwa.gov.tw/api/v1/...` |
每次回應都帶一個三位數字（**狀態碼**），最常見是 `200`（成功）。
> 今天目標：**從程式碼發出這些請求、拿回資料來用**。
---
## 為什麼需要 API
前五堂資料都寫死在程式碼：
```jsx
const products = [
{ name: '拉麵', price: 180 },
{ name: '炒飯', price: 150 }
];
```
問題：
- 蝦皮幾百萬筆商品，能全部寫死嗎？
- 上架新商品要工程師重新上線？
- 昨天買的東西，今天怎麼還看得到？
資料其實放在**資料庫**，網站要用就跟資料庫要。但網站不能直接碰資料庫（危險、語言不通），中間需要「翻譯員」= **API**。
> API = Application Programming Interface，「程式跟程式之間的服務生」
### 餐廳比喻（全課通用）
| 角色 | 對應 |
|---|---|
| 客人（你） | 你寫的程式（client，前端） |
| 服務生 | API |
| 廚房 | Server（伺服器） |
| 食材倉庫 | 資料庫 |
你不會自己衝進廚房 — 跟服務生說「我要拉麵」，服務生去廚房拿回來。API 就是這個服務生。
---
## HTTP — 客人跟服務生的對話規則
兩台電腦講話也要有共同語言 = **HTTP**（HyperText Transfer Protocol）。拿德文在拉麵店點餐會沒人聽懂，HTTP 就是大家都聽得懂的那套規則。
每次對話 = 兩個步驟：
- **Request（請求）** — 客人說「我要 XX」
- **Response（回應）** — 服務生回「這是 XX」或「沒有 XX」
每一次串 API = 一次「請求 + 回應」。
---
## HTTP 方法 — 你要服務生做什麼
HTTP 五個常用動作：
| 方法 | 意思 | 餐廳比喻 |
|---|---|---|
| `GET` | 拿資料 | 「給我看菜單」 |
| `POST` | 送資料（新增） | 「我要下單：拉麵 + 煎餃」 |
| `PUT` | 整份取代 | 「整單重來，換成炒飯」 |
| `PATCH` | 改部分 | 「炒飯改成炒麵就好」 |
| `DELETE` | 刪除 | 「取消訂單」 |
### PUT vs PATCH 的差別
用「改個資」最好懂。假設個資有 10 個欄位，只想改電話：
| 方法 | 做法 |
|---|---|
| **PUT** | 10 個欄位全部重填一次寄回去，server 整份覆蓋 → 整份履歷重寄 |
| **PATCH** | 只寄「電話」一個欄位，其他不動 → 一張便利貼 |
> 大多數情況用 **PATCH**，省、又安全。
### RESTful API 是什麼
一種 API 設計風格，核心觀念：
> **網址只描述「資源」，動作交給 HTTP 方法表達。**
以購物車 `/carts` 為例：
```
GET /carts → 看購物車有什麼
POST /carts → 加東西到購物車
PATCH /carts → 改購物車裡的數量
DELETE /carts → 清空購物車
DELETE /carts/123 → 刪除 id 為 123 的那一筆
```
網址相同、方法不同 = RESTful 精神。
---
## 同步 vs 非同步
學 API 的關鍵觀念。
| | 同步 | 非同步 |
|---|---|---|
| 行為 | 排隊，做完一件才做下一件 | 給你號碼牌，等好了再來換 |
| 比喻 | 傻站在櫃台等拉麵 | 點完回座位滑手機，廣播叫號再去拿 |
```jsx
console.log('1');
console.log('2');
console.log('3');
// 一定按順序印出 1, 2, 3（同步）
```
為什麼網路要非同步？因為**等的時間很長**（幾秒起跳），JavaScript 不可能傻等什麼都不做。**所有網路請求都是非同步**。
### 直接 demo 給你看
```jsx
const result = fetch('https://jsonplaceholder.typicode.com/users');
console.log(result);
```
印出來：
```
Promise { <pending> }
```
這就是 JavaScript 給你的「號碼牌」:
> 「資料還在路上，先給你一個盒子，等資料到了會裝進去。」
盒子 = **Promise**，`<pending>` = 還沒裝好。
### Promise 是什麼
> **Promise = 一個「等一下會裝著資料的盒子」**
你只要記：
- 看到 Promise = 資料還沒到，等一下會到
- 要用 `await` 打開盒子拿值
---
## await 跟 async
### 為什麼會拿到 pending？
**JavaScript 不會停下來等你**。fetch 發出後立刻執行下一行，資料還沒回來，當然只拿到還沒裝好的盒子。
### await — 打開盒子拿值
> **`await` = 叫 JavaScript 停下來，等盒子裝好，把裡面的值拿出來**
```jsx
const result = await fetch('https://jsonplaceholder.typicode.com/users');
console.log(result);
// 這次印出來會是真的 Response 物件，不是 Promise pending 了
```
但直接這樣寫會報錯：
```
SyntaxError: await is only valid in async functions
```
### async — 給函式一個「我會等」的標籤
> **函式裡用了 await → 前面就要加 async**
```jsx
async function getUsers() {
// 1. 等 fetch 把資料拿回來
const response = await fetch('https://jsonplaceholder.typicode.com/users');
// 2. 印出結果
console.log(response);
}
getUsers(); // 別忘了呼叫
```
> `async` = 函式門口的招牌「本店有等待業務」。
記三件事：
1. 看到 Promise → 用 `await` 打開
2. 用了 `await` → 函式前加 `async`
3. 別忘了呼叫函式（宣告 ≠ 執行）
---
## fetch 取得資料（GET）
練習 API：**JSONPlaceholder**（免註冊、免 key、乾淨 JSON）
網址：`https://jsonplaceholder.typicode.com/users`
### 基本範例
```jsx
async function getUsers() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
const data = await response.json();
return data;
}
```
三行 code，兩個坑：
### ⚠️ 第一個坑：response.json() 也要 await
```jsx
// ❌ 沒加 await
async function getUsers() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
const data = response.json(); // ← 漏 await
return data;
}
```
`.json()` **也是非同步**，它回傳的是 Promise，所以也要 await 打開。
```jsx
// ✅ 兩個 await 都要有
async function getUsers() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
const data = await response.json();
return data;
}
```
> 記法：**fetch 跟 json 兩兄弟，一個都不能少 await**
### ⚠️ 第二個坑：函式要 return
| 寫法 | 結果 |
|---|---|
| ❌ 函式裡只 `console.log(data)`，沒 return | 呼叫端拿到 `undefined` |
| ✅ 函式裡 `return data` | 呼叫端拿到真實資料 |
```jsx
async function getUsers() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
const data = await response.json();
// console.log(data) 印得出來，但呼叫端拿到 undefined
return data; // ← 必須 return 才會把資料交給外面
}
```
> day3 的老觀念：**`console.log` ≠ `return`**。
### 用 await 接結果
`getUsers()` 是 async function → 回傳 Promise → 呼叫端**也要 await**：
```jsx
async function main() {
const users = await getUsers();
console.log(users);
console.log(users[0].name);
}
main();
```
> **規則**：呼叫 async function 的結果，要 await 才能拿到真實資料。
### 結合 day5 的陣列方法
拿到 users 後就是普通陣列，`map` / `filter` / `find` 全部照用：
```jsx
async function showAllUserNames() {
const users = await getUsers();
const lines = users.map(function(user) {
return `${user.name} - ${user.email}`;
});
console.log(lines);
}
showAllUserNames();
```
> fetch 把資料拉回來，剩下的就是 day5 已經會的東西。
### 完整可執行版本
組合起來，可以 `node 檔名.js` 直接跑：
```jsx
// 1. 宣告非同步函式去拉資料
async function getUsers() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
const data = await response.json();
return data;
}
// 2. 用另一個非同步函式接結果並處理
async function main() {
const users = await getUsers();
console.log(`一共有 ${users.length} 位使用者`);
// 用 map 把每筆資料轉成想要的格式
const lines = users.map(function(user) {
return `${user.name} - ${user.email}`;
});
console.log(lines);
}
// 3. 別忘了呼叫
main();
```
執行結果：
```
一共有 10 位使用者
Leanne Graham - Sincere@april.biz
Ervin Howell - Shanna@melissa.tv
Clementine Bauch - Nathan@yesenia.net
... （以下省略）
```
> 這個範本看熟，後面 LiveJS 的 `getProducts` 幾乎就是一樣的 pattern。
---
## response 物件裡到底有什麼？
除了 `.json()`，response 還有什麼？印出來看看：
```jsx
async function inspectResponse() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
console.log(response.status); // 200
console.log(response.ok); // true
console.log(response.statusText); // 'OK'
console.log(response.headers); // Headers 物件
}
inspectResponse();
```
`response` = fetch 給你的「整個信封」。內容要用 `.json()` 拿，其他重要欄位：
| 欄位 | 用途 |
|---|---|
| `response.status` | 狀態碼數字（例如 200、404、500） |
| `response.ok` | 布林值，**2xx 是 true、其他是 false** |
| `response.statusText` | 狀態的文字說明（例如 'OK'、'Not Found'） |
| `response.headers` | server 回應的 headers 資訊 |
| `response.json()` | 把 body 解析成 JSON（要 await） |
> `response.ok` 是判斷請求成功的最快方法，比自己 `response.status === 200` 更省力。
### HTTP 狀態碼五大類
`response.status` = **狀態碼**，三位數，告訴你這次處理結果。記**第一個數字**就好：
| 類別 | 意思 | 餐廳比喻 | 常見代碼 |
|---|---|---|---|
| `1xx` | 收到了，正在處理 | 「點餐單收到，廚房準備中」 | 100 |
| `2xx` | **成功** | 「您的餐點來了」 | 200 OK / 201 Created |
| `3xx` | 改去別的地方 | 「我們搬家了，請去隔壁那家」 | 301 / 304 |
| `4xx` | **你寫錯了** | 「你點的菜單上沒有」「你沒帶會員卡」 | 400 / 401 / 403 / 404 |
| `5xx` | **廚房爆炸** | 「廚房失火了，今天不能出餐」 | 500 / 502 / 503 |
必記清單：
| 代碼 | 意思 |
|---|---|
| **200** | 成功 |
| **201** | 新增成功（POST 常回這個） |
| **400** | 請求格式錯 |
| **401** | 沒登入 |
| **404** | 找不到（網址打錯） |
| **500** | Server 自己出包 |
> 簡單記法：**4 開頭是你的錯，5 開頭是別人的錯**
---
## 錯誤處理的第一道防線：`response.ok`
真實世界 URL 會打錯、server 會掛、權限會出包。**今天只學一件事 — 檢查 `response.ok`**。
### fetch 沒爆，但 server 回 4xx / 5xx
最常見情境：路徑打錯，server 回 404：
```jsx
async function inspectBadPath() {
const response = await fetch('https://jsonplaceholder.typicode.com/notfound');
console.log(response.status); // 404
console.log(response.ok); // false
// fetch 沒有丟錯誤，response 拿得到，只是 status 是 404
}
inspectBadPath();
```
重點：**fetch 沒有丟錯誤**，response 拿得到，只是 status 是 404。檢查 `response.ok` 就能判斷成功或失敗。
> 比喻：包裹寄達了（fetch 成功），收件人拒收（status 404）。
### 加上 response.ok 防護
```jsx
async function getUsersSafe() {
const response = await fetch('https://jsonplaceholder.typicode.com/users');
// 檢查 server 是不是回成功
if (!response.ok) {
console.error('Server 回錯誤：', response.status);
return;
}
const data = await response.json();
return data;
}
```
一行 `if (!response.ok)` 就把「server 回錯誤」擋掉了。
> `response.ok` 是布林值，**2xx 時 true，其他都 false**。
### 還有另一種錯誤：連線層級錯誤
網路整個斷、domain 不存在時，fetch 會**直接丟例外**，連 `response` 都拿不到。要擋這種錯誤要用 `try / catch`。
**今天不在主軸**，延伸研究章節有簡介，作業只要有檢查 `response.ok` 就過關。
---
## 中場休息
---
## LiveJS 電商 API
切換到真實 API：六角學院的練習用電商 API，產品 / 購物車 / 訂單一應俱全。
### 註冊取得 API Path
1. 開 <https://livejs-api.hexschool.io/> → 註冊 → 登入
2. 建立你的 **API Path**（隨便取，例如 `gonsakon`）
3. 複製你的 **API Key**（一串亂碼）
> **小提醒**：今天用的 customer 端點（products / carts）**不需要 token**，只要 API Path。API Key 之後管理員 API 會用到。
**Swagger 文件**：<https://hexschool.github.io/hexschoolliveswagger/> — 列出所有端點 / 參數 / 回傳格式，工程師日常翻的就是這種東西。
### Fork 本週作業專案
整堂課的 code 都寫在作業專案裡，現在 **fork 一份**到你的帳號：
1. 開 <https://github.com/hexschool/js-camp-week6> → 右上角 **Fork** → 確認建立
2. clone 你的 fork：
```bash
git clone https://github.com/你的帳號/js-camp-week6.git
cd js-camp-week6
npm install
```
> **為什麼 fork 不直接 clone？** 你要把作業 push 回自己的 repo（繳交時貼的是你 fork 的連結）。直接 clone 原始 repo 沒有 push 權限。
專案結構：
```
js-camp-week6/
├── homework.js ← 你要寫的地方（空框架 + TODO 註解）
├── test.js ← 自動測試（不要改）
├── .env ← 等下自己建立
├── package.json
└── README.md
```
### 設定 .env
在專案根目錄建立 `.env`：
```
API_PATH=你註冊的 path
API_KEY=你的 token
```
**為什麼要 .env？**
- API Key 是秘密，**寫死在 code 跟著 push GitHub 會被盜**
- 把秘密放 `.env`、程式碼用 `process.env.API_PATH` 讀取
- repo 公開也不外洩
> 作業已經幫你處理好：`homework.js` 有 `require("dotenv").config()`、`.gitignore` 也把 `.env` 列進去。你只要建檔填兩行。
### 第一個 LiveJS 範例：填 `getProducts()`
打開 `homework.js` 找到 `getProducts()` 空框架，跟 `getUsers` 範例幾乎一樣，差別只有兩個：
| 差別 | 說明 |
|---|---|
| 網址變長 | 用樣板字串把 `API_PATH` 塞進去 |
| 回傳結構 | JSONPlaceholder 直接給陣列，LiveJS 包在 `data.products` |
```jsx
async function getProducts() {
const response = await fetch(
`${BASE_URL}/api/livejs/v1/customer/${API_PATH}/products`
);
const data = await response.json();
return data.products;
}
```
> API 文件決定資料藏在哪一層。看到 `data.products` 就是「先拿 data、再從 data 拿 products」。
### 填完跑跑看
```bash
npm start
```
`runTests()` 會自動呼叫 `getProducts()`，預期輸出：
```
--- 任務一：基礎 fetch ---
getProducts: 成功取得 6 筆產品
```
看到筆數 = 串接成功 🎉。看到 `undefined` 最常見原因：
- `.env` 沒設好
- `data.products` 寫成 `data`
> 剩下六個函式都在同一個 `homework.js`，格式一樣 — 空框架等你填。下面會帶你寫。
#### 💡 除錯技巧：函式裡塞 `console.log`
`npm test` 跑 15 題太慢。除錯時直接在函式裡塞 log，搭 `npm start` 跑：
```jsx
async function getProducts() {
const response = await fetch(...);
const data = await response.json();
console.log(data); // ← 暫時加這行看看 data 長什麼樣
return data.products;
}
```
`runTests()` 會自動呼叫 `getProducts()`，log 就會被觸發。除錯完刪掉。
**用法**：卡住就一層層往下印，看哪一層變 `undefined`。
```js
console.log(response); // fetch 回了什麼
console.log(data); // parse 完是什麼
console.log(data.products); // 路徑對不對
```
### 填 `getCart()`
跟 `getProducts` 一模一樣的 pattern，差別只有：
| 差別 | 說明 |
|---|---|
| URL | 結尾從 `/products` 改成 `/carts` |
| 回傳 | 包成 `{ carts, total, finalTotal }`（`total` = 小計、`finalTotal` = 折扣後）|
```jsx
async function getCart() {
const response = await fetch(
`${BASE_URL}/api/livejs/v1/customer/${API_PATH}/carts`
);
const data = await response.json();
return {
carts: data.carts,
total: data.total,
finalTotal: data.finalTotal
};
}
```
`npm test` → `getProducts` + `getCart` 兩組綠燈。
---
## fetch 寫入資料（POST）
之前都是「拿資料」（GET），現在要「送資料過去」（POST）。GET 像明信片（只寫地址），POST 像包裹（地址 + 包裹內容）。
POST 要帶內容，所以 `fetch` 要多傳第二個參數，裡面有 `method` / `headers` / `body` 三個欄位。
### 回到 homework.js：把 `addToCart` 填完
找到 `addToCart(productId, quantity)` 的空框架，填進去：
```jsx
async function addToCart(productId, quantity) {
const response = await fetch(
`${BASE_URL}/api/livejs/v1/customer/${API_PATH}/carts`,
{
// method: 用哪個 HTTP 方法（預設是 GET，POST 要明寫）
method: 'POST',
// headers: 告訴 server「我寄的是 JSON 格式」。POST 沒加這行 9 成會壞
headers: { 'Content-Type': 'application/json' },
// body: 要送的資料。物件不能直接傳，要用 JSON.stringify 變字串
// ⚠️ LiveJS 的坑：body 要在外面再包一層 { data: ... }
body: JSON.stringify({ data: { productId, quantity } })
}
);
const data = await response.json();
return data;
}
```
三個要點直接寫在註解裡：
- **`method: 'POST'`** — 不寫的話 fetch 預設是 GET
- **`Content-Type: application/json`** — 沒加 server 不知道怎麼解析你的內容
- **`JSON.stringify(...)`** — 網路只能傳字串，物件要先「壓平」才能寄出去
- **`{ data: { ... } }`** — LiveJS 特殊規定，其他 API 不一定要這樣包，看 API 文件決定
存檔後跑 `npm test`，看到 `addToCart › 應回傳物件 ✓` 就過關。
### 回到 homework.js：把 `getProductsSafe()` 填完
`getProducts` + `response.ok` 檢查 + 統一回傳格式。
| 結果 | 回傳格式 |
|---|---|
| ✅ 成功 | `{ success: true, data: 產品陣列 }` |
| ❌ 失敗 | `{ success: false, error: '錯誤訊息' }` |
```jsx
async function getProductsSafe() {
const response = await fetch(
`${BASE_URL}/api/livejs/v1/customer/${API_PATH}/products`
);
// 先擋 4xx / 5xx
if (!response.ok) {
return { success: false, error: `HTTP ${response.status}` };
}
const data = await response.json();
return { success: true, data: data.products };
}
```
> `error` 字串自由，看得懂就好（`HTTP 404` / `server 500` 都行）。
`npm test` → 任務一三題全綠。
> 剩下的 `updateCartItem` / `removeCartItem` / `clearCart` 都是 `addToCart` 的變化型 — `method` 換成 `'PATCH'` 或 `'DELETE'`、`body` 內容換掉、DELETE 不用 body。**這三題留給你自己挑戰**，卡住的話回頭看 Swagger 文件或作業 README。
---
## 作業導讀
### Fork 作業專案
原始 repo：<https://github.com/hexschool/js-camp-week6>
1. 開上面的連結，右上角點 **Fork** 建一份到你的帳號下
2. clone 你自己的 fork：
```bash
git clone https://github.com/你的帳號/js-camp-week6.git
cd js-camp-week6
npm install
```
繳交作業時貼的是**你 fork 的 repo 連結**，不是原始 repo。
### 作業專案結構
```
js-camp-week6/
├── homework.js ← 你要寫的地方
├── test.js ← 自動測試（不要改）
├── .env ← 你的設定（自己建立）
├── package.json ← 套件清單
└── README.md ← 作業說明
```
### 三個指令
```bash
npm install # 第一次先裝套件（dotenv 跟 jest）
npm start # 跑你的程式看輸出
npm test # 跑完整 Jest 測試看通過幾個
```
---
## 自己研究的關鍵字
本堂主軸：`await` + `response.ok`。其他延伸觀念
| 關鍵字 | 用途 |
|---|---|
| `Promise` | 什麼是 Promise 寫法 |
| `try / catch / finally` | 接住 fetch 連線層級錯誤 |
| `throw new Error()` | 自己丟錯誤 |
| HTTP `Authorization` header | 帶 token 的 API（下堂課會用到） |
---
## 本週任務
必做：
1. [第六堂主線任務 — 電商 API 串接練習](https://rpg.hexschool.com/#/training/12063182914161572765/board/content/12063182914161572766_12063182914161572788?tid=12063182914167567607)
選做：
1. 每日任務
2. 課程筆記分享或延伸文章
## 正課結束，下方為加碼環節
## AI 實驗室
* 壓軸
## Claude Code 從零上傳教學
* 從零開始 Claude Code ~ 30~45min
* 錄影上傳
## 這週新增的服務（4/3 — 4/10）
## 這週新增的服務（4/3 — 4/10）
| Commit | 名稱 | 說明 |
|--------|------|------|
| `d0ea063` | **阿餘人設** | 260 行完整 skill 定義，設為專案預設人設 |
| `491b0e1` | **帽子島看板桌布** | 自動渲染看板狀態為桌布 HTML，開機就能看進度 |
| `9375a0d` | **早報 todo 自動推進** | 加上 `todo → in_progress` 規則，不用手動切狀態 |
| `caba3c3` | **query-calendar CLI** | 獨立日曆查詢腳本，杜絕 primary 日曆漏查 |
| `7aeff95` | **覆盤 skill** | session 結束後自動覆盤，找出協作摩擦點並產出改進建議 |
五項更新各補不同面向 — 人設定義、視覺化看板、工作流自動化、基礎工具修正、自我迭代機制。整個特助系統的縫隙在慢慢補起來。
## 模擬面試：順序
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet