使用 Next.js + FastAPI 建構表單資料轉換器（Mapper）模組

在實務專案中，前端表單往往由多層巢狀的資料組成，例如使用者輸入的一系列目標設定、報告項目、子任務等。但後端通常需要儲存成平坦化的資料表（例如：一張批次表、一張細項表、一張子細項表）。

為了解決前端與後端資料格式不一致的問題，我們可以設計一個 Mapper 模組，作為兩端資料結構之間的轉譯橋梁。

🧰 系統架構概覽

  • 前端：使用 Next.js + React Hook Form 建構表單
  • 後端：使用 FastAPI 作為 RESTful API 框架
  • 資料庫：PostgreSQL，使用多張關聯表設計

📌 範例情境：多層表單資料送出

假設你要送出一份多層結構的「使用者目標設定表單」：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "category_id": 3,
  "year": 2024,
  "owner": "Alice",
  "items": [
    {
      "name": "任務 A",
      "value": 100,
      "sub_items": [
        { "label": "子任務 A1", "score": 30 },
        { "label": "子任務 A2", "score": 70 }
      ]
    }
  ]
}

後端需要將資料拆解後分別寫入：

  • goal_batches 表（紀錄批次）
  • goal_items 表（每個任務）
  • goal_sub_items 表（任務下的子任務）

🔧 Mapper 設計

撰寫一個通用的 map_goal_payload() 函式，協助拆解 JSON 結構：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
def map_goal_payload(payload: dict) -> dict:
    batch_data = {
        "category_id": payload["category_id"],
        "year": payload["year"],
        "owner": payload["owner"]
    }

    items_data = []
    for item in payload["items"]:
        item_data = {
            "name": item["name"],
            "value": item["value"],
            "sub_items": item.get("sub_items", [])
        }
        items_data.append(item_data)

    return {
        "batch": batch_data,
        "items": items_data
    }

💡 實際應用 in FastAPI

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@router.post("/goals/submit")
def submit_goals(payload: dict, db: Session = Depends(get_db)):
    mapped = map_goal_payload(payload)

    batch = GoalBatch(**mapped["batch"])
    db.add(batch)
    db.flush()

    for item in mapped["items"]:
        goal_item = GoalItem(batch_id=batch.id, name=item["name"], value=item["value"])
        db.add(goal_item)
        db.flush()

        for sub in item["sub_items"]:
            sub_item = GoalSubItem(item_id=goal_item.id, **sub)
            db.add(sub_item)

    db.commit()
    return {"message": "成功建立目標紀錄"}

🧪 搭配 Pydantic 型別驗證

定義清楚的 Schema 可提升開發效率與資料安全性：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class SubItemSchema(BaseModel):
    label: str
    score: int

class GoalItemSchema(BaseModel):
    name: str
    value: int
    sub_items: List[SubItemSchema]

class GoalBatchSchema(BaseModel):
    category_id: int
    year: int
    owner: str
    items: List[GoalItemSchema]

🔍 結語：將前端巢狀資料結構轉換為後端關聯資料的利器

透過 Mapper 設計：

  • ✅ 將複雜表單結構轉成簡潔平坦格式
  • ✅ 降低後端邏輯耦合，方便重用與測試
  • ✅ 對應前端 JSON 結構變化，只需更新 mapping 規則即可

這種設計特別適合複雜業務系統、ERP、CRM、內部管理後台等場景。