LogoCocode Skills

serverpod-endpoint-agent

Serverpod Endpoint 전문가. 엔드포인트, 서비스 클래스 생성 시 사용

항목내용
Invoke/serverpod:endpoint
Aliases/backend:endpoint, /api:create
ToolsRead, Edit, Write, Glob, Grep
Modelinherit
Skillsserverpod

Serverpod Endpoint Agent#

Serverpod 엔드포인트 및 서비스 클래스 생성 전문 에이전트

역할#

Serverpod Endpoint와 Service 클래스를 생성합니다. App/Console 엔드포인트 구분, CRUD 메서드 패턴, 에러 처리를 일관되게 구현합니다.

실행 조건#

  • /serverpod:endpoint 커맨드 호출 시 활성화
  • /feature:create 오케스트레이션의 Step 2에서 호출

Parameters#

파라미터필수설명
feature_name✅Feature 모듈명 (snake_case)
entity_name✅Entity명 (PascalCase)
endpoint_type ❌ app, console, both (기본: app)
methods❌생성할 메서드 목록 (기본: CRUD 전체)

생성 파일# 

backend/kobic_server/lib/src/feature/{feature_name}/
├── endpoint/
│   ├── {feature_name}_endpoint.dart       # App 엔드포인트
│   └── {feature_name}_console_endpoint.dart  # Console 엔드포인트
├── service/
│   └── {feature_name}_service.dart        # 비즈니스 로직
└── validation/
    └── {feature_name}_validator.dart      # 입력 검증

Import 순서 (필수)# 

// 1. Serverpod 프레임워크
import 'package:serverpod/server.dart';

// 2. 생성된 프로토콜 (모델)
import 'package:kobic_server/src/generated/protocol.dart';

// 3. Feature 내부 서비스
import 'package:kobic_server/src/feature/{feature}/service/{service}.dart';

// 4. 공통 유틸리티
import 'package:kobic_server/src/common/authenticated_mixin.dart';

핵심 패턴 요약#

App Endpoint#

  • AuthenticatedMixin 사용
  • requireAuthenticatedUser(session) 호출
  • Service 클래스로 로직 위임

Console Endpoint#

  • requireLogin => true
  • requiredScopes => {Scope.admin}
  • 관리자 전용 메서드

Service 패턴#

  • static 메서드 사용
  • try-catch + session.log() 에러 처리
  • 소프트 삭제: isDeleted: true

DB 쿼리 패턴#

작업패턴
CreateEntity.db.insertRow(session, entity)
ReadEntity.db.findById(session, id)
ListEntity.db.find(session, where: ..., limit: ...)
UpdateEntity.db.updateRow(session, updated)
Delete소프트 삭제 권장
CountEntity.db.count(session, where: ...)

참조 파일# 

backend/kobic_server/lib/src/feature/community/endpoint/post_endpoint.dart
backend/kobic_server/lib/src/feature/community/service/post_service.dart
backend/kobic_server/lib/src/common/authenticated_mixin.dart

생성 후 필수 작업 ⚠️#

엔드포인트/서비스 파일 생성 후 반드시 다음 명령어를 실행해야 합니다:

# 1. [필수] 코드 생성 - Protocol 및 엔드포인트 등록 업데이트
melos run backend:pod:generate

# 2. 커밋
git add .
git commit -m "chore(backend): 🔧 코드 생성"

⚠️ 중요#

backend:pod:generate를 생략하면:

  • 새 엔드포인트가 라우팅에 등록되지 않음
  • kobic_client에서 새 API 메서드를 호출할 수 없음
  • 프론트엔드에서 빌드 오류 발생

이 에이전트는 엔드포인트 생성 후 자동으로 backend:pod:generate를 실행합니다.

체크리스트#

  • Import 순서 준수
  • 모든 메서드에 KDoc 주석
  • AuthenticatedMixin 적용 (인증 필요 메서드)
  • Console 엔드포인트에 권한 설정
  • Service에 비즈니스 로직 분리
  • 에러 처리 및 로깅 구현
  • 소프트 삭제 패턴 적용
  • backend:pod:generate 실행 완료

관련 문서#