화면과 서버에 같은 요청을 보내 비교했더니 20곳이 달랐어요

HANUI·
API계약테스트Vue공공기관OpenAPI

Vue로 공공 CMS 만들기 시리즈

(2편)
  1. 1.JS가 실행되기 전 화면이 틀려 있었어요 — SSR과 선택 상자의 함정
  2. 2.화면과 서버에 같은 요청을 보내 비교했더니 20곳이 달랐어요

공공 CMS를 만들면서 화면은 mock 서버로 먼저 붙였어요. 백엔드(전자정부 프레임워크)가 나오기 전에 화면을 다 만들 수 있으니까요. 흔한 방식입니다.

문제는 운영에서는 mock이 없다는 거예요. 화면은 실제 백엔드와 말을 섞습니다. 둘이 조금이라도 다르게 답하면, 그 차이는 납품 후에 드러나요.

그래서 같은 요청을 두 서버에 보내 비교하는 시험을 만들었어요. 비정상 입력까지 112개를 보냈고, 20곳이 달랐습니다.

왜 "계약"이 필요했나

먼저 구조부터요. 화면과 백엔드 사이에 OpenAPI 계약(openapi.yaml)을 두고, 양쪽이 그걸 기준으로 만듭니다.

계약을 문서로만 두면 금방 썩어요. 그래서 버전 규칙을 정하고 변경 기록을 같은 커밋에서 고치게 했습니다.

바뀐 것올릴 자리예
기존 화면·백엔드가 깨지는 변경 — 동작·칸 삭제, 이름·형식 변경, 필수 칸 추가, 상태 코드 의미 변경주1.4.0 → 2.0.0
깨지지 않는 추가 — 새 동작, 선택 칸 추가, 새 오류 코드부1.4.0 → 1.5.0
설명·예시·오타만수1.4.0 → 1.4.1

그리고 이 규칙을 하나 더 붙였어요.

계약을 바꾸면 같은 커밋에서 TS 타입·mock 서버·계약 테스트를 함께 고친다.

여기까지 하면 계약과 양쪽 구현이 같이 움직입니다. 그런데 그래도 20곳이 어긋났어요.

어긋난 건 "정상 동작"이 아니었어요

20곳을 보고 알게 된 게 있어요. 정상 입력에서는 둘이 똑같이 답합니다. 당연해요 — 화면을 만들면서 정상 흐름은 수백 번 돌려봤으니까요.

다른 건 전부 비정상 입력이었습니다. 계약에 안 적혀 있던 구석이고, 그래서 양쪽이 각자 알아서 처리한 곳이에요.

실제로 어긋난 예 두 가지입니다.

1) 버전이 빠졌을 때

낙관적 잠금을 위해 저장 요청에 version을 받아요. "내가 보던 버전이 이거다"라는 뜻이고, 서버 값과 다르면 409(그사이 누가 저장했음)를 돌려줍니다.

그런데 version이 아예 빠진 요청은? mock은 409를 줬어요. 백엔드는 400을 줬습니다.

둘 다 일리가 있어요. mock은 "맞지 않으니 충돌"로 봤고, 백엔드는 "필수 칸이 없으니 요청 오류"로 봤습니다. 백엔드 쪽이 맞아요 — **409는 "올바른 정수를 보냈는데 서버 값과 다를 때"**여야 합니다. 값이 없거나 정수가 아니면 그건 입력 오류죠.

차이가 왜 중요하냐면, 화면이 409를 받으면 "다시 불러오기" 안내를 띄우고 400을 받으면 칸에 오류를 표시해요. 같은 상황에서 화면이 다르게 반응합니다.

2) 요청 형식 자체가 깨졌을 때

깨진 JSON, 객체가 아닌 본문, 칸 종류가 다른 값, 숫자가 아닌 경로 id — 이런 요청에 백엔드는 400 "요청 형식이 올바르지 않습니다."(fieldErrors 없음)로 일관되게 답합니다.

mock은 무시하고 저장하거나, 401이나 404를 줬어요. 가장 나쁜 쪽은 "무시하고 저장"이에요. 화면 개발 중에는 아무 문제가 없다가, 운영에서 400이 오면 화면이 처리하지 못합니다.

비교 대상을 셋으로 좁혔어요

시험을 만들 때 고민한 건 무엇을 같다고 볼 것인가였어요. 응답 본문을 통째로 비교하면 id·시각 같은 게 달라서 전부 실패합니다.

그래서 세 가지만 봤어요.

  • 상태 코드 — 화면의 분기가 여기서 갈립니다
  • 오류 code — 화면이 어떤 안내를 띄울지 정하는 값
  • 오류 칸 이름 (정렬해서) — 어느 입력칸에 오류를 표시할지

메시지 글자는 비교하지 않았어요. 문구는 바뀔 수 있고, 화면이 문구로 분기하지는 않으니까요. 화면 동작을 바꾸는 것만 비교 대상으로 뒀습니다.

시험 설명에 이유를 적어뒀어요.

마지막 괄호가 핵심이에요. 이건 품질 취향이 아니라 GS인증 시험에서 결함으로 잡히는 종류입니다.

입력 규칙은 한 곳에 두고 양쪽이 읽어요

대조 시험이 "다른 걸 찾는" 쪽이라면, 애초에 안 달라지게 하는 쪽도 필요해요.

입력 규칙(칸 길이, 중복, 개수 상한 같은 것)은 정답 예제 파일로 뽑아뒀습니다.

파일 머리에 이렇게 적혀 있어요.

직접 고치지 않는다가 중요해요. 이 파일은 TS 규칙에서 생성됩니다. 규칙을 바꾸고 UPDATE_FIXTURES=1로 다시 만들면 파일이 갱신되고, 그 diff가 "무엇이 달라졌는지"를 보여줘요.

그리고 백엔드 테스트가 같은 파일을 읽습니다. 화면이 쓰는 규칙과 서버가 검사하는 규칙이 같은 정답표를 보는 구조예요. 한쪽만 고치면 다른 쪽 테스트가 깨집니다.

실제로 이 과정에서 규칙이 늘어난 것도 있어요 — 게시판 분류 50개 상한, 페이지 템플릿 칸 500자 상한 같은 건 정답표를 만들다가 "이건 안 막혀 있네"를 발견해서 추가했습니다.

돌리는 비용

정직하게 적으면 이 시험은 싸지 않아요.

백엔드를 띄워야 돌아갑니다(pnpm contract:parity). 로그인도 역할마다 한 번씩만 해요 — 백엔드에 IP 단위 로그인 제한(10분에 60번)이 걸려 있어서, 케이스마다 로그인하면 자기 시험이 자기 제한에 걸립니다. mock은 시험이 별도 포트에 새로 띄우고 파일 저장을 끕니다.

그래서 매 커밋마다 돌리는 시험은 아니고, 계약이 바뀌거나 백엔드 동작을 손봤을 때 돌리는 쪽으로 뒀어요.

계약은 "설명만" 바뀌었어요

20곳을 맞춘 뒤 계약 버전을 1.1.1로 올렸습니다. 수 자리예요 — 설명만 바뀌었다는 뜻입니다.

처음엔 이상하게 느껴졌어요. 20곳을 고쳤는데 설명만?

그런데 맞아요. 계약에 적혀 있지 않던 동작을 백엔드 기준으로 적은 것이라서, 계약이 약속한 내용은 바뀌지 않았습니다. 변경 기록에 이렇게 남겼어요.

계약에 적혀 있지 않던 동작을 백엔드 기준으로 적었다 — 화면은 늘 올바른 값을 보내므로 화면 동작은 바뀌지 않는다.

마지막 문장이 이 작업의 성격이에요. 정상 흐름에서는 아무것도 안 바뀝니다. 바뀐 건 "뭔가 잘못됐을 때 양쪽이 같은 말을 한다"는 것뿐이고, 그게 운영에서 드러나는 차이예요.

오늘 정리

  1. mock과 실제 서버의 차이는 정상 흐름에 없어요. 비정상 입력, 즉 계약에 안 적힌 구석에 있습니다.
  2. 비교 대상을 화면 동작이 갈리는 것으로 좁히세요. 상태 코드·오류 코드·오류 칸이면 충분하고, 메시지 글자까지 비교하면 유지가 안 돼요.
  3. 입력 규칙은 생성된 정답표로 두고 양쪽이 읽게. 손으로 고치는 파일이면 또 갈라집니다.

mock으로 화면을 만드는 프로젝트라면, 한 번만 해보세요. 깨진 JSON을 두 서버에 보내보세요. 답이 다르면 거기부터예요.

관련 링크

시리즈: Vue로 공공 CMS 만들기

HANUI

KRDS 기반 React 컴포넌트 라이브러리. 공공 웹 개발을 더 쉽게.