2024 iThome 鐵人賽

DAY 23

Modern Web

從零開始：全端新手的困境與成長系列第 23 篇

Day23 API 撰寫初體驗 – 避免常見錯誤，心態與設計皆重要

16th鐵人賽 api 開發 restful 設計 api 測試初學者指南

Chiayu

2024-10-01 22:19:15

163 瀏覽

分享至

Day23 API 撰寫初體驗 – 避免常見錯誤，心態與設計皆重要

撰寫 API 對新手來說，可能像是進入一片未知領域，總覺得哪裡有點難。但其實，只要掌握一些基本原則和正確心態，就能減少犯錯的機會，也讓你的 API 設計變得清晰好用。今天我們就來聊聊撰寫 API 時可能犯的錯誤，並分享如何保持良好的設計心態與命名規範，確保 API 既簡單又高效。

文章大綱：

開始撰寫 API 可能犯的錯誤
心態的調整
API 命名與路徑的設計
RESTful API 的實現與範例
一步步優化，邁向穩定高效

1. 開始撰寫 API 可能犯的錯誤

寫 API 不就是直接寫，然後可以回傳資料就好嗎，就像我當初一樣，滿懷信心地開始寫，結果 API 的路徑設計、命名和擴展性一團亂，最後自己都搞不清楚該怎麼調整。

1-1. 命名不一致

很多新手會在命名上出錯，比如對於同一個功能，API 路徑名稱變來變去，/getUsers、/get-products 這種不一致的命名，會讓 API 的使用者搞不清楚該如何正確使用。API 命名不但要清楚，也要有一致性，這樣才能讓團隊協作和維護變得更容易。

1-2. 路徑設計不清晰

在設計 API 路徑時，常常會忽略「路徑結構清晰」的重要性。結果路徑設計得很混亂，像 /product/createNew 或 /newproduct1，看起來真的不夠直觀。好的 API 路徑應該一看就知道是用來做什麼的，例如 /products（取得所有產品）和 /products/:id（取得單一產品），這樣的設計簡單直白，讓使用者一眼就明白。

2. 心態的調整

當你開始設計 API 的時候，可能會感覺壓力山大。因為 API 是整個系統與外界溝通的橋樑，設計不好，後續問題一大堆。

2-1. 循序漸進

千萬不要急著一次搞定所有事情，API 的設計是一個「循序漸進」的過程。你可以先從小範圍開始設計，比如針對單一資源（如 users），再慢慢擴展到其他功能。每次只專注解決一個問題，這樣才能逐步完成整體設計。

2-2. 調整與測試

API 設計不可能一次完美，這是很正常的。重要的是不斷調整和測試。可以要使用工具（如 Postman）來進行 API 測試，並隨時記錄下改善的點。

3. API 命名與路徑的設計

一個好的 API 設計，首先需要注意命名和路徑設計。這兩個部分直接影響使用者體驗，設計不當的 API 路徑會讓人摸不著頭緒。

3-1. 命名規範

API 命名必須保持一致且簡潔，這樣才能讓使用者快速理解。例如，針對「產品」這個資源，你可以使用 GET /products 來取得所有產品，POST /products 來新增產品，GET /products/:id 來查詢單一產品。這樣的命名不僅清晰，也符合 RESTful 的慣例。

3-2. 路徑設計

路徑設計應該反映資源的結構和層次。比如 /users/:id/orders 可以用來取得指定用戶的訂單，這樣的路徑設計能夠清楚展示資源的關聯性。使用清晰的層次結構，能夠幫助開發者和使用者快速理解 API 的邏輯。

使用 HTTP 動詞

設計 API 時，應該充分利用 HTTP 動詞來表達操作的語意：

GET：用來取得資源。
POST：用來新增資源。
PUT：用來更新資源。
DELETE：用來刪除資源。

這樣的語意清晰又符合標準，是設計良好 API 的關鍵。

RESTful API 的最佳實踐

URL 結構：保持簡潔和一致，避免過於複雜的路徑。
版本管理：API 版本應該通過 URL 或 HTTP header 來明確標識，如 /api/v1/products。
錯誤處理：使用正確的 HTTP 狀態碼來反映錯誤情況，如 404 Not Found 表示資源不存在，400 Bad Request 表示請求參數錯誤。

4. RESTful API 的實現與範例

在這個部分，我們將帶著零基礎的你，逐步實現一個簡單的 GET API，並使用 Postman 來進行測試，確認 API 是否能夠正確運作。

步驟 1：建立一個簡單的 `GET` API

首先，我們需要在你的 Express 專案中建立一個 API 來取得所有的使用者資料。

假設已經有一個 Users 表格，並且已經插入了一些測試資料。
在 routes 資料夾中找到 users.js 檔案：

routes/users.js 是處理使用者相關 API 的地方，我們將在這裡新增一個 GET 路由。

在 models 資料夾中新增 users.js 檔案，才能正確取得資料

// models/user.js
module.exports = (sequelize, DataTypes) => {
  const User = sequelize.define(
    "User",
    {
      id: {
        type: DataTypes.INTEGER,
        autoIncrement: true,
        primaryKey: true,
      },
      username: {
        type: DataTypes.STRING,
        allowNull: false,
      },
      email: {
        type: DataTypes.STRING,
        allowNull: false,
        unique: true,
      },
      createdAt: {
        type: DataTypes.DATE,
        allowNull: false,
      },
      updatedAt: {
        type: DataTypes.DATE,
        allowNull: false,
      },
    },
    {
      tableName: "Users", // 指定資料表名稱，避免 Sequelize 將表名自動變為複數形式
      timestamps: true, // 自動維護 createdAt 和 updatedAt
    }
  );

  return User;
};

新增 GET 路由來取得使用者資料：

打開 users.js，並加入以下程式碼：

var express = require('express');
var router = express.Router();
var { User } = require('../models');  // 假設 User 是我們使用 Sequelize 定義的模型

// GET /users - 取得所有使用者
router.get('/', async function(req, res, next) {
  try {
    const users = await User.findAll();  // 使用 Sequelize 的 findAll 方法查詢所有使用者
    res.json(users);  // 回傳查詢到的使用者資料
  } catch (error) {
    res.status(500).json({ error: '無法取得使用者資料' });  // 若發生錯誤，回傳錯誤訊息
  }
});

module.exports = router;

保存檔案：這樣我們就完成了建立一個簡單的 GET /users API，用來取得所有使用者的資料。

步驟 2：啟動伺服器

在完成 GET API 的路由設定後，確保伺服器已經啟動。打開終端機並執行以下指令：

npm start

現在伺服器已經在監聽，接下來我們會使用 Postman 來測試 API。

步驟 3：使用 Postman 測試 API

Postman 是一個很棒的工具，能幫助你測試和調試 API。讓我們看看如何使用 Postman 測試剛剛建立的 API。

開啟 Postman：如果還沒有安裝 Postman，可以前往 Postman 官網下載並安裝。
建立一個 GET 請求：
- 點擊「New Request」，選擇 GET。
- 在輸入欄位輸入 http://localhost:3000/users，這是我們的 API 路徑。
- 確保請求類型選擇的是 GET。
發送請求：
- 點擊「Send」按鈕，發送 GET 請求。
- 在下方的回應區域應該會看到一個 JSON 陣列，列出所有使用者的資料。這表示我們的 API 運行正常。