Backend Brick

Serverpod 백엔드 atomic brick 상세

Backend Brick (7종)#

Serverpod 백엔드를 구성하는 atomic brick 7종(b- 접두사)의 상세 레퍼런스입니다. 단일 소스는 coco-de/bricks 저장소의 bricks/registry.yaml입니다.

{project}는 모노레포의 프로젝트 이름, {feature}는 feature 이름입니다. 모든 brick은 backend/{project}_server/lib/src/feature/{feature}/ 하위에 배치됩니다.

spy.yaml 계약 체인#

b-entity·b-dto가 생성하는 spy.yaml 모델은 그 자체로 끝이 아니라 serverpod generate 후 protocol 클래스가 됩니다. 이 클래스가 앱과 백엔드가 공유하는 계약입니다.

spy.yaml → serverpod generate → {project}_client Dart class → 앱 serverpod_mixin

전역 네임스페이스 주의: serverpod 모델명(class/enum/exception)은 서버 전역 네임스페이스에서 유일해야 합니다. feature 디렉토리가 달라도 같은 이름의 모델을 두 번 선언할 수 없습니다. cob compose는 생성 전에 이 충돌을 pre-flight 계약으로 검사해 hard fail시킵니다.

barrel 동작은 backend 전체에서 "해당 없음"입니다 — 모델·엔드포인트 등록은 serverpod generate가 수행합니다.

b-entity#

Serverpod spy.yaml 엔티티(DB 테이블)를 생성합니다. 앱-백엔드 계약서 역할을 합니다.

변수	설명
`name`	엔티티 이름 (snake_case)
`project_name`	프로젝트 이름
`fields`	필드 목록 (필드명 → 타입)
`has_table`	DB 테이블 매핑(`table:`) 여부
`relations`	관계 선언

항목	값
산출 파일	`model/entities/{name}.spy.yaml`
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/model/entities/`
의존 brick	없음
barrel 동작	해당 없음 (serverpod generate가 등록)

feature.yaml의 models.entities 선언이 이 brick으로 생성됩니다. backend.endpoint/service/dto가 켜진 매니페스트는 feature 동명 엔티티 {Feature}를 요구합니다 (동명 엔티티 계약).

b-dto#

Serverpod spy.yaml Request/Response DTO를 생성합니다. 엔드포인트의 입출력 계약입니다. dto_type 4종: request, response, result, info.

변수	설명
`name`	DTO 기준 이름 (snake_case)
`project_name`	프로젝트 이름
`fields`	필드 목록
`dto_type`	`request` \| `response` \| `result` \| `info`
`has_pagination`	페이지네이션 result 모델 추가 생성 여부

항목	값
산출 파일	`model/dto/{computed_name}.spy.yaml` , `model/dto/paginated_{name}_result.spy.yaml` (has_pagination)
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/model/dto/`
의존 brick	`b-entity` — result의 items가 entity를 참조
barrel 동작	해당 없음 (serverpod generate가 등록)

b-endpoint#

Serverpod 엔드포인트를 생성합니다. endpoint_type 3유형: app, console, public. CRUD 또는 커스텀 메서드를 선언할 수 있습니다.

변수	설명
`name`	엔드포인트 이름 (snake_case)
`project_name`	프로젝트 이름
`endpoint_type`	`app` \| `console` \| `public`
`has_auth`	인증 요구 여부
`methods`	생성할 메서드 목록
`entity_name`	참조할 엔티티 이름

인증 규칙 (endpoint_type별):

endpoint_type	requireLogin	requiredScopes
`app`	`true`	-
`console`	`true`	`{Scope.admin}`
`public`	`false`	-

항목	값
산출 파일	`endpoint/{name}_endpoint.dart`, `test/integration/{name}_endpoint_test.dart`
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/endpoint/`
의존 brick	`b-entity`, `b-dto`, `b-service`
barrel 동작	해당 없음 (serverpod generate가 `endpoints.dart`에 등록)

b-service#

엔드포인트가 위임하는 비즈니스 로직 서비스를 생성합니다. 엔드포인트는 얇게 유지하고 로직은 서비스에 둡니다.

변수	설명
`name`	서비스 이름 (snake_case)
`project_name`	프로젝트 이름
`methods`	생성할 메서드 목록
`has_exception_handler`	예외 핸들러 래핑 여부
`entity_name`	참조할 엔티티 이름

항목	값
산출 파일	`service/{name}_service.dart`, `test/unit/{name}_service_test.dart`
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/service/`
의존 brick	`b-entity`
barrel 동작	해당 없음

b-exception#

백엔드 sealed class 예외 계층을 생성합니다. SerializableException 기반이라 클라이언트로 직렬화되어 전파됩니다. 예외 모델명 역시 전역 네임스페이스를 공유합니다.

변수	설명
`name`	예외 그룹 이름 (snake_case)
`project_name`	프로젝트 이름
`exception_types`	생성할 예외 타입 목록

항목	값
산출 파일	`exception/{name}_exceptions.dart`
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/exception/`
의존 brick	없음
barrel 동작	해당 없음

b-validator와 함께 쓸 때는 exception_types에 invalid_parameter를 포함해 생성해야 합니다 (아래 b-validator 참고).

b-validator#

백엔드 입력값 검증 클래스를 생성합니다. validation_rules는 id / paging / required_fields 규칙의 조합입니다.

변수	설명
`name`	validator 이름 (snake_case)
`project_name`	프로젝트 이름
`validation_rules`	`id` \| `paging` \| `required_fields` 조합

항목	값
산출 파일	`validation/{name}_validator.dart`, `test/unit/{name}_validator_test.dart`
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/validation/`
의존 brick	`b-constant`, `b-exception` — 상수/에러 메시지 + invalid_parameter 예외 필요
barrel 동작	해당 없음

의존 주의: b-exception은 exception_types에 invalid_parameter를 포함해 생성해야 하고, b-constant는 has_error_messages=true로 생성해야 합니다 (invalidParameter/idRequired 메시지 참조).

b-constant#

백엔드 상수/캐시 설정/에러 메시지를 생성합니다. 페이징·ID·DB작업·필드명 기본 상수가 포함됩니다.

변수	설명
`name`	상수 그룹 이름 (snake_case)
`has_cache`	캐시 상수 파일 생성 여부
`has_error_messages`	에러 메시지 파일 생성 여부

항목	값
산출 파일	`constant/{name}_constants.dart` , `constant/{name}_cache_constants.dart` (has_cache), `constant/{name}_error_messages.dart` (has_error_messages)
배치 경로	`backend/{project}_server/lib/src/feature/{feature}/constant/`
의존 brick	없음
barrel 동작	해당 없음

b-validator 사용 시 has_error_messages=true가 필요합니다 (invalidParameter/idRequired 참조).

생성 후 단계#

backend brick 생성 후에는 모델·엔드포인트를 protocol에 반영하기 위해 codegen을 실행해야 합니다.

cd backend/{project}_server
serverpod generate