002 - 둘러보기

원문 보기 위키 갱신 2026.10.07

기본 플러그인 기능

기본적으로 방금 만든 플러그인은 간단한 할 일(todo) 목록 애플리케이션을 호스팅해요. http://localhost:7007/api/todo/todos에 HTTP API를 노출해서 TODO를 만들고, 기존 TODO를 나열하고, 특정 TODO를 가져올 수 있어요. 이 TODO들은 메모리에 저장돼요. 즉 애플리케이션을 재시작하면 모든 TODO를 잃게 된다는 뜻이에요. 또한 TODO에 소프트웨어 카탈로그 엔티티로 태그를 달 수 있는데, 이는 프런트엔드 통합에 유용할 거예요.

이 플러그인을 프로덕션에 내보내려면 몇 가지를 손봐야 해요.

재시작해도 잃지 않도록 TODO를 데이터베이스에 쓴다.
우리가 기대하는 대로 모든 것이 동작하는지 확인하는 적절한 테스트를 작성한다.
사용자 피드백을 얻는다.

출처: 문서

본문

로컬에서 테스트하기

이 플러그인을 출시할 준비에 들어가기 전에 로컬에서 실행하는 방법을 하나씩 살펴볼게요. 백엔드 플러그인의 매니페스트(plugins/todo-backend/package.json)를 열고 scripts 섹션을 보면 몇 가지 중요한 명령이 눈에 띌 거예요. 지금 우리와 관련된 것은 다음과 같아요.

yarn start - dev/index.ts의 내용을 백엔드로 사용해 로컬 개발 서버를 시작한다.
yarn test - 백엔드 플러그인의 모든 테스트를 실행한다.

yarn start를 실행하면 플러그인 전용 커스텀 백엔드가 뜨는 걸 볼 수 있어요. 플러그인 하나를 대상으로 새 기능을 쉽게 테스트해 보면서 플러그인 개발과 반복을 단순화시켜 주죠. 필요할 때는 전역 packages/backend에 필요한 것을 추가하는 것만 잊지 마세요. 우리가 봐야 할 중요한 로그는 다음과 같아요.

2025-06-08T16:14:53.229Z rootHttpRouter info Listening on :7007

이 로그는 HTTP 서버가 떠서 테스트 HTTP 요청을 보내기 시작할 수 있다는 뜻이에요. 좋아하는 HTTP 클라이언트를 꺼내 테스트를 해볼게요.

시작하면서 깨끗한 상태에서 출발하는지부터 확인해 볼게요. 아래 명령으로 기존 TODO를 모두 나열해 보세요. 빈 목록이 나와야 해요.

curl http://localhost:7007/api/todo/todos

새 TODO를 만들려면 같은 엔드포인트에 POST 요청을 보내면 돼요. 다만 지금은 401 에러가 나올 거예요.

curl -X POST http://localhost:7007/api/todo/todos \
-H 'Content-Type: application/json; charset=utf-8' \
--data-binary @- << EOF
{
    "title": "My Todo"
}
EOF

401 에러가 나는 이유는 각 TODO를 만든 사용자의 ID를 추적하기 때문이에요. Authorization 헤더 없이 TODO 생성 요청을 보내면 이 실패를 보게 돼요. 프런트엔드도 함께 있는 플러그인이라면 이 자격 증명 관리는 자동으로 일어나야 해요. 이렇게 시도해 보세요.

curl -v -X POST http://localhost:7007/api/todo/todos \
-H 'Content-Type: application/json; charset=utf-8' \
-H "Authorization: Bearer *** -s http://localhost:7007/api/auth/guest/refresh | jq -r '.backstageIdentity.token')" \
--data-binary @- << EOF
{
    "title": "My Todo"
}
EOF

그다음 모든 TODO를 나열하면 새 TODO를 볼 수 있어요!

curl http://localhost:7007/api/todo/todos

createdBy가 user:development/guest로 나오는 걸 알 수 있어요. 그게 TODO를 만들 때 쓴 토큰이에요. 바로 요청의 -H "Authorization: Bearer *** -s http://localhost:7007/api/auth/guest/refresh | jq -r '.backstageIdentity.token')" 부분이 담당하는 거예요.