/serverpod:endpoint — 백엔드 API 만들어주는 일꾼#

한마디로#

앱 화면이 서버와 데이터를 주고받을 때 쓰는 "창구(API)"를 자동으로 만들어주는 도우미입니다. 식당에 비유하면, 손님 주문을 받아 주방에 전달하는 "주문 창구"와 그 뒤에서 실제로 요리하는 "주방"을 한 번에 차려주는 셈이에요.

누가·언제 쓰나요#

• 새 기능에 필요한 서버 API(데이터를 만들고·읽고·고치고·지우는 기능)를 만들어야 할 때
• 직접 /serverpod:endpoint 명령을 실행하거나, 전체 기능을 한 번에 만드는 /feature:create 작업의 한 단계로 자동 호출될 때

무엇을 해주나요#

기능 이름과 데이터 이름만 알려주면, 아래 파일들을 일정한 규칙에 맞춰 만들어 줍니다.

• 앱용 창구({feature_name}_endpoint.dart) — 일반 사용자 앱이 쓰는 API
• 관리자용 창구({feature_name}_console_endpoint.dart) — 관리자 전용 API (권한 확인 포함)
• 실제 처리 로직({feature_name}_service.dart) — 데이터를 다루는 핵심 업무 처리
• 입력값 검증({feature_name}_validator.dart) — 잘못된 입력을 걸러내는 장치

만들기만 하고 끝나는 게 아니라, 서버가 이 새 창구를 인식하도록 마무리 작업(코드 생성)까지 자동으로 실행합니다. 이 마무리를 빠뜨리면 새 API를 앱에서 부를 수 없으니 꼭 필요한 단계예요.

어떻게 쓰나요#

# 기본 (앱용 API, 전체 CRUD 자동 생성)
/serverpod:endpoint

# 같은 일을 하는 다른 이름(별칭)으로도 호출 가능
/backend:endpoint
/api:create

전달할 수 있는 값:

• feature_name (필수) — 기능 모듈 이름 (snake_case, 예: banner)
• entity_name (필수) — 데이터 이름 (PascalCase, 예: Banner)
• endpoint_type (선택) — app(앱용) / console(관리자용) / both(둘 다), 기본값은 app
• methods (선택) — 만들 기능 목록, 기본값은 전체 CRUD(생성·조회·수정·삭제)

안에서 무슨 일이 벌어지나요#

1. 창구와 주방을 차립니다 — 앱용·관리자용 API 창구와, 그 뒤에서 실제로 데이터를 처리하는 로직 파일을 규칙에 맞게 생성합니다.
2. 권한을 챙깁니다 — 관리자용 창구에는 "로그인 필수 + 관리자 권한" 같은 보호 장치를 걸고, 앱용 창구에는 로그인 사용자 확인을 넣습니다.
3. 안전하게 삭제합니다 — 데이터를 진짜로 지우지 않고 "지워진 표시"만 남기는 방식(soft delete)을 적용합니다.
4. 마무리 작업을 실행합니다 — 서버가 새 API를 인식하도록 코드 생성(backend:pod:generate)을 자동으로 돌리고, 변경 사항을 커밋합니다.

backend/kobic_server/lib/src/feature/{feature_name}/
├── endpoint/
│   ├── {feature_name}_endpoint.dart       # App endpoint
│   └── {feature_name}_console_endpoint.dart  # Console endpoint
├── service/
│   └── {feature_name}_service.dart        # Business logic
└── validation/
    └── {feature_name}_validator.dart      # Input validation

// 1. Serverpod framework
import 'package:serverpod/server.dart';

// 2. Generated protocol (models)
import 'package:kobic_server/src/generated/protocol.dart';

// 3. Feature internal services
import 'package:kobic_server/src/feature/{feature}/service/{service}.dart';

// 4. Common utilities
import 'package:kobic_server/src/common/authenticated_mixin.dart';

backend/kobic_server/lib/src/feature/banner/endpoint/banners_endpoint.dart
backend/kobic_server/lib/src/feature/banner/endpoint/banners_console_endpoint.dart
backend/kobic_server/lib/src/feature/banner/service/banner_service.dart
backend/kobic_server/lib/src/common/authenticated_mixin.dart
backend/kobic_server/lib/src/utils/auth.dart  # getCurrentUserInfo / requireCurrentUserInfo

# 1. [Required] Code generation - Update Protocol and endpoint registration
melos run backend:pod:generate

# 2. Commit
git add .
git commit -m  " chore(backend): code generation "