View Scaffolding - 🌲 Sonamu

Sonamu의 스캐폴딩 시스템으로 관리자 페이지의 목록과 폼 뷰를 자동으로 생성하는 방법을 알아봅니다.

View Scaffolding 개요

자동 생성

목록/폼 뷰웹 UI로 생성

타입 안전

Entity 기반컴파일 타임 검증

커스터마이징

생성 후 수정완전한 제어

일관성

통일된 UI/UX베스트 프랙티스

View Scaffolding이란?

문제: 반복적인 CRUD 뷰 작성

전통적인 개발에서는 각 엔티티마다 비슷한 CRUD 화면을 수동으로 반복 작성해야 합니다. 수동 작성 시 문제점:

시간 낭비: 목록, 생성, 수정 페이지를 모두 손으로 작성
일관성 부족: 개발자마다 다른 스타일, 다른 구조
유지보수 어려움: 엔티티 변경 시 모든 뷰 수정 필요
실수 가능성: 필드 누락, 잘못된 타입, 유효성 검사 누락
보일러플레이트: 테이블, 폼, 버튼 등 반복 코드

예시: User 엔티티 하나에 필요한 페이지

/admin/users        → 목록 페이지 (테이블, 페이지네이션, 검색)
/admin/users/form   → 생성/수정 페이지 (폼, 유효성 검사)

각 페이지마다 100~200줄 이상의 코드가 필요하고, 이를 모든 엔티티에 반복해야 합니다.

해결: 자동 스캐폴딩

Sonamu는 Entity 정의를 기반으로 관리자 페이지 뷰를 자동 생성합니다. 장점:

✨ 즉시 생성: 웹 UI로 클릭만으로 뷰 생성
✨ 타입 안전: Entity 타입이 컴포넌트에 그대로 반영
✨ 일관된 UI: 통일된 디자인 시스템
✨ 베스트 프랙티스: 검증된 패턴 적용
✨ 커스터마이징 가능: 생성 후 필요한 부분만 수정

Sonamu의 스캐폴딩 철학:

“80%는 자동으로, 20%는 커스터마이징”

대부분의 CRUD 기능은 자동 생성하고, 특별한 비즈니스 로직만 추가로 구현합니다.

스캐폴딩 실행

Sonamu 웹 UI 사용

Sonamu는 웹 기반 관리 UI를 제공합니다.

# Sonamu 개발 서버 실행
pnpm dev

# 브라우저에서 Sonamu UI 접속
# http://localhost:3000/sonamu

웹 UI에서 뷰 생성:

Sonamu UI 접속
“Scaffold” 메뉴 선택
Entity 선택 (예: User)
“Generate View List” 버튼 클릭 → index.tsx 생성
“Generate View Form” 버튼 클릭 → form.tsx 생성

CLI 명령어는 현재 비활성화되어 있습니다. 뷰 생성은 Sonamu 웹 UI를 통해서만 가능합니다.

생성되는 파일 구조

web/src/routes/admin/
└── users/
    ├── index.tsx    # 목록 페이지 (테이블 포함)
    └── form.tsx     # 생성/수정 통합 폼

실제 생성되는 파일:

index.tsx: 목록 테이블이 직접 포함된 페이지
form.tsx: 생성과 수정을 하나의 폼으로 통합

주의:

별도의 컴포넌트 파일(UserTable.tsx, UserForm.tsx)은 생성되지 않음
상세 페이지([id].tsx)는 자동 생성되지 않음
모든 로직이 두 개의 페이지 파일에 통합됨

생성된 뷰 구조

목록 페이지 (index.tsx)

목록을 테이블로 표시하고 페이지네이션, 검색 기능을 제공합니다.

// web/src/routes/admin/users/index.tsx (자동 생성)
import { useState } from "react";
import { useNavigate } from "react-router-dom";
import { UserService } from "@/services/services.generated";

export default function UsersPage() {
  const navigate = useNavigate();
  const [page, setPage] = useState(1);
  const [search, setSearch] = useState("");
  
  // TanStack Query Hook 사용
  const { data: users, isLoading } = UserService.useUsers("A", {
    page,
    pageSize: 20,
    search,
  });
  
  return (
    <div className="admin-page">
      <div className="header">
        <h1>Users</h1>
        <button onClick={() => navigate("/admin/users/form")}>
          Create New User
        </button>
      </div>
      
      <div className="search">
        <input
          type="text"
          placeholder="Search users..."
          value={search}
          onChange={(e) => setSearch(e.target.value)}
        />
      </div>
      
      {/* 테이블이 직접 포함됨 */}
      <table className="data-table">
        <thead>
          <tr>
            <th>ID</th>
            <th>Email</th>
            <th>Username</th>
            <th>Actions</th>
          </tr>
        </thead>
        <tbody>
          {users?.map((user) => (
            <tr key={user.id}>
              <td>{user.id}</td>
              <td>{user.email}</td>
              <td>{user.username}</td>
              <td>
                <button onClick={() => navigate(`/admin/users/form?id=${user.id}`)}>
                  Edit
                </button>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
      
      {/* 페이지네이션 */}
      <div className="pagination">
        <button disabled={page === 1} onClick={() => setPage(page - 1)}>
          Previous
        </button>
        <span>Page {page}</span>
        <button onClick={() => setPage(page + 1)}>
          Next
        </button>
      </div>
    </div>
  );
}

기능:

페이지네이션
검색 필터
“Create New” 버튼
“Edit” 버튼 (각 행)
테이블이 페이지에 직접 포함 (별도 컴포넌트 없음)

폼 페이지 (form.tsx)

생성과 수정을 하나의 폼으로 통합합니다.

// web/src/routes/admin/users/form.tsx (자동 생성)
import { useState, useEffect } from "react";
import { useNavigate, useSearchParams } from "react-router-dom";
import { UserService } from "@/services/services.generated";

export default function UserFormPage() {
  const navigate = useNavigate();
  const [searchParams] = useSearchParams();
  const userId = searchParams.get("id");
  
  const [formData, setFormData] = useState({
    email: "",
    username: "",
    bio: "",
  });
  
  const [saving, setSaving] = useState(false);
  
  // 수정 모드: 기존 데이터 로드
  useEffect(() => {
    if (userId) {
      UserService.getUser("C", parseInt(userId)).then((user) => {
        setFormData({
          email: user.email,
          username: user.username,
          bio: user.bio || "",
        });
      });
    }
  }, [userId]);
  
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setSaving(true);
    
    try {
      if (userId) {
        // 수정
        await UserService.update(parseInt(userId), formData);
      } else {
        // 생성
        await UserService.create(formData);
      }
      
      navigate("/admin/users");
    } catch (error) {
      alert("Failed to save");
    } finally {
      setSaving(false);
    }
  }
  
  return (
    <div className="admin-page">
      <div className="header">
        <h1>{userId ? "Edit User" : "Create New User"}</h1>
        <button onClick={() => navigate("/admin/users")}>
          Back to List
        </button>
      </div>
      
      <form onSubmit={handleSubmit} className="entity-form">
        <div className="form-field">
          <label>Email *</label>
          <input
            type="email"
            value={formData.email}
            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
            required
          />
        </div>
        
        <div className="form-field">
          <label>Username *</label>
          <input
            type="text"
            value={formData.username}
            onChange={(e) => setFormData({ ...formData, username: e.target.value })}
            required
          />
        </div>
        
        <div className="form-field">
          <label>Bio</label>
          <textarea
            value={formData.bio}
            onChange={(e) => setFormData({ ...formData, bio: e.target.value })}
            rows={4}
          />
        </div>
        
        <div className="form-actions">
          <button type="submit" disabled={saving}>
            {saving ? "Saving..." : "Save"}
          </button>
        </div>
      </form>
    </div>
  );
}

기능:

생성/수정 통합: URL 파라미터(?id=)로 모드 구분
수정 시 기존 데이터 자동 로드
유효성 검사
저장 중 버튼 비활성화
“Back to List” 버튼

생성 파일의 특징

통합 구조

Sonamu의 스캐폴딩은 최소한의 파일로 구성됩니다: 전통적인 구조 (복잡함):

pages/users/
  ├── index.tsx
  ├── [id].tsx
  ├── new.tsx
  └── [id]/edit.tsx
components/users/
  ├── UserTable.tsx
  ├── UserDetail.tsx
  └── UserForm.tsx

Sonamu 구조 (간결함):

admin/users/
  ├── index.tsx    # 테이블 포함
  └── form.tsx     # 생성/수정 통합

통합 구조의 장점:

파일 수 최소화
파일 간 이동 감소
유지보수 간편
코드 응집도 높음

라우팅 패턴

GET  /admin/users           → index.tsx (목록)
GET  /admin/users/form      → form.tsx  (생성)
GET  /admin/users/form?id=1 → form.tsx  (수정)

URL 파라미터로 생성/수정 모드를 구분합니다.

커스터마이징

생성 후 수정

생성된 파일은 완전히 수정 가능합니다.

// web/src/routes/admin/users/index.tsx (커스터마이징)
export default function UsersPage() {
  // 추가: 역할별 필터
  const [role, setRole] = useState<string | null>(null);
  
  const { data: users } = UserService.useUsers("A", {
    page,
    pageSize: 20,
    search,
    role, // 커스텀 파라미터
  });
  
  return (
    <div>
      {/* 추가: 역할 필터 UI */}
      <select value={role || ""} onChange={(e) => setRole(e.target.value || null)}>
        <option value="">All Roles</option>
        <option value="admin">Admin</option>
        <option value="user">User</option>
      </select>
      
      {/* 기존 테이블... */}
    </div>
  );
}

useTypeForm으로 폼 업그레이드 (권장)

자동 생성된 폼은 기본적으로 useState와 직접 이벤트 핸들러를 사용합니다. 이를 useTypeForm으로 업그레이드하면 훨씬 간결하고 타입 안전한 코드가 됩니다. 생성된 코드 (기본):

// admin/users/form.tsx (자동 생성)
const [formData, setFormData] = useState({
  email: "",
  username: "",
  bio: "",
});

async function handleSubmit(e: React.FormEvent) {
  e.preventDefault();
  setSaving(true);

  try {
    if (userId) {
      await UserService.update(parseInt(userId), formData);
    } else {
      await UserService.create(formData);
    }
    navigate("/admin/users");
  } catch (error) {
    alert("Failed to save");
  } finally {
    setSaving(false);
  }
}

return (
  <form onSubmit={handleSubmit}>
    <input
      value={formData.email}
      onChange={(e) => setFormData({ ...formData, email: e.target.value })}
    />
    {/* ... */}
  </form>
);

useTypeForm으로 업그레이드:

// admin/users/form.tsx (개선)
import { useTypeForm } from "@sonamu-kit/react-components/lib";
import { Input, Button } from "@sonamu-kit/react-components/components";
import { UserSaveParams } from "@/services/user/user.types";

const { register, submit, errors } = useTypeForm(UserSaveParams, {
  email: "",
  username: "",
  bio: "",
});

const saveMutation = UserService.useSaveMutation();

const handleSubmit = submit(async (form) => {
  saveMutation.mutate(
    { spa: [form] },
    {
      onSuccess: () => navigate("/admin/users"),
      onError: () => alert("Failed to save"),
    }
  );
});

return (
  <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
    <div>
      <Input {...register("email")} placeholder="Email" />
      {errors.email && <span className="error">{errors.email.message}</span>}
    </div>
    {/* ... */}
    <Button type="submit" disabled={saveMutation.isPending}>
      {saveMutation.isPending ? "Saving..." : "Save"}
    </Button>
  </form>
);

개선 효과:

✅ 코드량 50% 감소: useState, 이벤트 핸들러 제거
✅ 자동 유효성 검사: SaveParams 스키마 기반
✅ 타입 안전: 컴파일 타임 에러 감지
✅ 에러 처리 통합: 필드별 에러 메시지 자동 표시

자동 생성된 파일을 Git에 커밋한 후 useTypeForm으로 업그레이드하면, 변경 사항을 쉽게 추적할 수 있습니다.

별도 컴포넌트로 분리

필요하면 수동으로 컴포넌트를 분리할 수 있습니다:

// components/users/UserTable.tsx (수동 생성)
export function UserTable({ users }: { users: User[] }) {
  return (
    <table className="data-table">
      {/* 테이블 내용 */}
    </table>
  );
}

// admin/users/index.tsx (수정)
import { UserTable } from "@/components/users/UserTable";

export default function UsersPage() {
  const { data: users } = UserService.useUsers("A", { page, pageSize: 20 });
  
  return (
    <div>
      <UserTable users={users || []} />
    </div>
  );
}

상세 페이지 추가

자동 생성되지 않는 상세 페이지는 수동으로 추가:

// admin/users/[id].tsx (수동 생성)
import { useParams } from "react-router-dom";
import { UserService } from "@/services/services.generated";

export default function UserDetailPage() {
  const { id } = useParams();
  const { data: user } = UserService.useUser("C", parseInt(id!));
  
  return (
    <div>
      <h1>{user?.username}</h1>
      <p>{user?.email}</p>
      <p>{user?.bio}</p>
    </div>
  );
}

베스트 프랙티스

1. 생성 후 즉시 Git 커밋

# Sonamu UI에서 뷰 생성
git add web/src/routes/admin/users/
git commit -m "feat: scaffold User views"

이렇게 하면 커스터마이징 내역을 추적할 수 있습니다.

2. 공통 로직은 Hook으로 추출

// hooks/useEntityList.ts
export function useEntityList<T>(
  entityName: string,
  useHook: any
) {
  const [page, setPage] = useState(1);
  const [search, setSearch] = useState("");
  
  const { data, isLoading } = useHook("A", {
    page,
    pageSize: 20,
    search,
  });
  
  return { data, isLoading, page, setPage, search, setSearch };
}

3. 스타일은 전역으로 관리

/* styles/admin.css */
.admin-page { }
.data-table { }
.entity-form { }

모든 관리자 페이지에서 일관된 스타일 사용.

주의사항

View Scaffolding 사용 시 주의사항:

웹 UI에서만 생성 가능 (CLI 명령어 비활성화됨)
index.tsx, form.tsx만 생성 (별도 컴포넌트 없음)
상세 페이지는 수동 추가 필요
재생성하면 커스터마이징 손실 (Git 커밋 필수)
생성 후 필요에 따라 컴포넌트 분리 권장

다음 단계

커스텀 컴포넌트

컴포넌트 커스터마이징

ID Async Select

관계 데이터 선택

Search Input

검색 컴포넌트

Service 사용하기

Service 통합

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​View Scaffolding 개요

자동 생성

타입 안전

커스터마이징

일관성

​View Scaffolding이란?

​문제: 반복적인 CRUD 뷰 작성

​해결: 자동 스캐폴딩

​스캐폴딩 실행

​Sonamu 웹 UI 사용

​생성되는 파일 구조

​생성된 뷰 구조

​목록 페이지 (index.tsx)

​폼 페이지 (form.tsx)

​생성 파일의 특징

​통합 구조

​라우팅 패턴

​커스터마이징

​생성 후 수정

​useTypeForm으로 폼 업그레이드 (권장)

​별도 컴포넌트로 분리

​상세 페이지 추가

​베스트 프랙티스

​1. 생성 후 즉시 Git 커밋

​2. 공통 로직은 Hook으로 추출

​3. 스타일은 전역으로 관리

​주의사항

​다음 단계

커스텀 컴포넌트

ID Async Select

Search Input

Service 사용하기

View Scaffolding 개요

View Scaffolding이란?

문제: 반복적인 CRUD 뷰 작성

해결: 자동 스캐폴딩

스캐폴딩 실행

Sonamu 웹 UI 사용

생성되는 파일 구조

생성된 뷰 구조

목록 페이지 (index.tsx)

폼 페이지 (form.tsx)

생성 파일의 특징

통합 구조

라우팅 패턴

커스터마이징

생성 후 수정

useTypeForm으로 폼 업그레이드 (권장)

별도 컴포넌트로 분리

상세 페이지 추가

베스트 프랙티스

1. 생성 후 즉시 Git 커밋

2. 공통 로직은 Hook으로 추출

3. 스타일은 전역으로 관리

주의사항

다음 단계