여러 파일 기능 구현: API·DB·화면을 한 번에 바꿀 때 지키는 순서

여러 파일의 기능 구현이 매주 수작업이 되는 이유#

여러 파일을 바꾸는 기능에서는 각 계층이 같은 데이터를 같은 의미로 다루는지 확인해야 합니다. 이 절의 표는 변경 계획을 세울 때 사용할 계약 점검표입니다.

작업 전 안전 확인: 비밀번호·토큰 등 비밀정보와 고객 데이터는 파일, 프롬프트, 로그에서 제외합니다.

기능 구현 가이드는 원하는 결과와 유지할 동작을 함께 설명하고 여러 부분의 변경을 나누어 확인하도록 안내합니다.

여러 파일 기능의 계획과 계층별 검토#

작업 전에는 계약과 영향 범위를 정하고, 작업 후에는 계층별 변경과 통합 결과를 비교합니다. 위 표는 검토 기준이며 실제 기능 구현이나 비용 절감 결과를 보여 주지는 않습니다.

기능 구현 가이드는 변경 파일과 실행한 검사, 확인하지 못한 검사를 정리하도록 권합니다. 표는 검증 계획이지 수행 결과가 아닙니다.

단계별로 하기: 입력 규칙 → 실행 → 검증#

1. 사용자에게 보일 결과, 유지할 동작, 입력·출력과 오류 처리를 적고 기존 데이터와 API 계약을 확인합니다.
2. Mirr Code의 Plan 모드에 관련 파일과 테스트, 호환성 위험을 조사해 달라고 요청한 뒤 계획을 검토합니다.
3. 예를 들어 DB → API → UI로 나누어 변경하며 각 단계의 차이와 검사를 확인합니다. 실제 배포 순서는 이전 버전 호환성과 서비스 제약에 맞춰 정합니다.
4. 정상·오류·권한·기존 데이터 사례를 계층별로 검사하고 통합 흐름을 확인합니다. 실행하지 못한 검사는 별도로 남깁니다.

검증: 테스트 출력과 체크리스트#

변경된 파일과 실제 diff, 테스트 명령과 결과를 함께 검토하세요. Plan 모드의 실제 파일 목록과 DB·API·UI 변경 및 통합 테스트 출력은 이 글의 사례 증거로 아직 필요합니다.

주의할 점과 한계#

DB 변경이나 외부 서비스 작업은 파일 복구만으로 되돌릴 수 없습니다. 운영 환경에 적용하기 전에는 백업, 별도 승인, 배포 및 복구 절차를 준비하세요. 세션과 복구에서 체크포인트의 한계를 확인할 수 있습니다.

기능을 파일 목록보다 사용자 계약으로 정의하기#

여러 파일을 바꾸는 기능에서 가장 먼저 정할 것은 파일 수가 아닙니다. 사용자가 어떤 입력을 주고 어떤 결과를 받아야 하는지 적으세요. 작업 목록에 보관 상태를 추가한다면 상태 필드, 기존 작업의 기본 상태, 목록에서 보일 항목, 권한 없는 변경의 처리와 오류 표시를 함께 정해야 합니다. “DB와 API, UI를 고쳐 줘”라는 요청만으로는 이런 결정을 알 수 없습니다. AI가 정한 기본값을 요구사항으로 받아들이기 전에 담당자가 검토해야 합니다.

계약에는 바꾸지 않을 동작도 넣습니다. 기존 API의 필드를 제거하지 않을지, 오래된 클라이언트가 새 응답을 읽을 수 있는지, 정렬과 페이지 처리의 의미를 유지할지 적으세요. 입력의 null, 빈 문자열과 필드 누락도 같은 뜻인지 나눠야 합니다. UI에서 선택하지 않은 상태를 API가 임의 기본값으로 바꾼다면 사용자의 의도와 저장된 값이 달라질 수 있습니다. 각 계층의 이름이 같아도 의미가 다르면 통합에서 실패합니다.

계약에서 결정하지 않은 항목은 코드로 추측해 채우지 말고 미결정으로 표시하세요. 모든 계층의 변경이 한 PR에 들어가더라도 요구사항과 위험을 설명할 수 있는 단위로 나눠 검토해야 합니다. 계획 단계에서 테스트할 결과까지 적으면 나중에 화면이 예뻐 보인다는 이유로 기능을 완료 처리하는 일을 줄일 수 있습니다.

DB 변경은 추가·전환·정리를 구분하기#

기존 코드가 계속 동작해야 하는 환경이라면 새 필드나 읽기 경로를 먼저 추가하고, 사용 경로를 전환한 뒤 오래된 구조를 정리하는 방식을 검토할 수 있습니다. 다만 모든 DB와 배포 환경에 같은 절차가 맞는 것은 아닙니다. 잠금, 데이터 크기와 기존 스키마에 따라 위험이 다르므로 DBA와 운영 담당자가 실제 계획을 정해야 합니다. 이 글은 운영 마이그레이션 실행이나 무중단 배포를 보장하지 않습니다.

기본값과 데이터 채우기는 구분합니다. 새로 들어오는 행의 기본값이 있다고 기존 데이터가 원하는 의미로 모두 해석되는지 자동으로 알 수는 없습니다. 이전 행, 새 행, 누락 값과 비정상 값의 읽기·쓰기 결과를 각각 검토하세요. 변환 작업을 한다면 재실행과 중단 뒤 재개, 실패 위치와 검증 방법도 필요합니다. 작은 스키마 diff라도 많은 데이터를 바꿀 수 있으므로 파일 변경량으로 위험을 판단하지 마세요.

되돌리기 계획은 역방향 SQL 한 줄로 끝나지 않을 수 있습니다. 새 필드에 실제 데이터가 쌓인 뒤 열을 지우면 정보가 사라집니다. 이전 애플리케이션이 새 데이터를 읽을 수 있는지, 백업에서 무엇을 복원해야 하는지와 복구 승인자를 정하세요. 로컬 체크포인트나 소스 되돌리기는 DB의 실제 변경을 취소하지 않습니다. 데이터 복구를 시험하지 않았다면 “롤백 가능”이라는 표현 대신 필요한 검증을 남겨야 합니다.

API를 구현할 때 권한과 오류를 먼저 확인하기#

요청과 응답 예시를 적을 때 정상 입력만 만들지 마세요. 필수 필드 누락, 잘못된 형식, 없는 대상과 접근 권한 없는 대상을 나눕니다. 클라이언트가 보낸 사용자 ID를 그대로 신뢰하지 않는지, 실제 인증 주체와 변경 대상의 관계를 서버에서 확인하는지 검토하세요. UI에서 버튼을 숨기는 것은 서버 권한 검사가 아닙니다. 공개하지 않아야 할 데이터가 오류 응답에 섞이지 않는지도 확인합니다.

응답의 필드명과 타입은 화면에서 사용하기 전에 계약으로 고정합니다. 숫자와 문자열, 시간의 형식, 페이지 토큰의 의미와 빈 목록의 표현이 달라지면 계층별 테스트가 통과해도 함께 동작하지 않을 수 있습니다. 기존 API 클라이언트와 직렬화 코드를 찾아 변경 범위를 확인하세요. 공통 타입이 있다면 새 타입을 중복으로 만들기보다 기존 계약을 확장할 수 있는지 검토합니다. API 문서와 테스트가 서로 다른 예시를 쓰지 않게 대조해야 합니다.

외부 요청과 재시도가 있다면 실패 이후의 상태도 정합니다. 서버가 저장했는데 응답이 늦었을 때 클라이언트가 다시 보내면 중복 동작이 생길 수 있습니다. 멱등성 지원은 선택한 서비스와 API의 실제 계약에서 확인해야 합니다. 지원하지 않는 기능을 프레임워크가 자동으로 해 준다고 가정하지 마세요. 테스트 환경에서는 승인된 합성 데이터로 재시도와 충돌을 확인하고 실제 외부 서비스 실행 여부를 구분해 보고합니다.

UI는 성공 화면 외의 상태도 구현하기#

화면에는 로딩, 빈 결과, 권한 부족과 실패 상태가 있습니다. API가 빈 목록을 반환했을 때 실제로 데이터가 없는지, 필터 때문에 보이지 않는지 사용자가 알 수 있어야 합니다. 오류를 모두 “잠시 후 다시 시도”로 바꾸면 사용자가 해결할 수 있는 입력 오류까지 숨길 수 있습니다. 반대로 내부 오류나 서버 경로를 그대로 노출하지 않도록 공개 문구를 정합니다. API의 오류 코드와 UI 문구가 어떻게 연결되는지 기록하세요.

변경 버튼은 요청 중 상태와 중복 클릭도 검토합니다. 화면에서 먼저 값을 바꾸는 낙관적 처리라면 실패했을 때 어떻게 원상태를 보여 줄지 정해야 합니다. 브라우저에서 보이는 값이 서버에 저장됐다는 증거는 아닙니다. 승인된 환경에서 다시 조회한 결과와 비교해야 합니다. 접근성, 키보드 조작과 작은 화면의 동작도 실제 UI 요구사항에 포함된다면 확인합니다. 코드를 읽은 것과 브라우저에서 확인한 것은 별도 결과입니다.

중간 검사로 계약 불일치를 빨리 찾기#

DB 단계에서는 허용하는 데이터와 기존 데이터의 해석을 확인합니다. API 단계에서는 같은 데이터를 어떤 응답으로 내보내는지 봅니다. UI 단계에서는 그 응답의 정상·빈 값·오류를 실제 화면 상태로 연결합니다. 각 단계의 검사가 끝난 뒤 한 번의 사용자 흐름으로 묶어 확인해야 합니다. 파일별 단위 테스트가 계층 사이의 직렬화와 권한 문제를 모두 다루지는 못합니다. 통합 검사의 빠진 경로를 명시하세요.

계약 테스트를 만들 때 구현의 현재 응답을 그대로 정답으로 복사하지 않습니다. 앞서 승인한 입력·출력 표에서 기대값을 가져오세요. 한 계층을 대체 구현으로 바꿨다면 무엇이 실제로 연결되지 않았는지 기록합니다. 예를 들어 가짜 DB로 API를 검사한 결과는 실제 DB 마이그레이션 성공이 아닙니다. 브라우저 없이 UI 함수를 검사했다면 실제 입력과 렌더링도 확인되지 않았습니다. 증거의 범위를 정확히 쓰는 것이 인계에 중요합니다.

중간 빌드와 테스트가 실패하면 마지막 변경부터 조사합니다. 환경 문제와 코드 문제를 나누고 변경 전 같은 명령의 결과가 있는지 확인하세요. 실패를 없애려고 타입을 넓히거나 테스트를 제외하면 계약을 약하게 만들 수 있습니다. 원인을 설명할 수 없을 때는 변경을 더 넓히기보다 현재 단위와 영향 범위를 줄여 검토하는 편이 좋습니다. 실행하지 못한 검사는 필요한 환경과 함께 남기고 통과로 바꾸지 않습니다.

코드 통합과 배포 승인을 나누기#

기능이 로컬에서 동작한다고 운영 배포 승인이 생기는 것은 아닙니다. 배포 순서, 설정 변경, 데이터 변환과 외부 서비스 권한을 담당자가 별도로 검토해야 합니다. 일부만 배포된 상태를 허용하는지와 이전 버전으로 돌아갈 때 데이터 의미가 유지되는지도 확인하세요. 플래그를 사용한다면 누가 켜고 끄는지와 기본 상태를 정합니다. 플래그 존재만으로 위험이 사라지거나 모든 변경을 되돌릴 수 있는 것은 아닙니다.

보관 기능을 이전 버전으로 되돌릴 때도 코드와 데이터의 의미를 나눠 봅니다. 새 클라이언트가 기록한 보관 값은 소스만 되돌렸다고 사라지지 않습니다. 이전 서버가 그 값을 무시한다면 사용자가 숨겼다고 생각한 항목이 다시 보일 수 있습니다. 그 조합을 허용할지 배포 계획에서 정해야 합니다. 이 글의 설계 예시는 실제 Plan 목록, 중간 실행 로그나 기능 전후 화면·API 응답이 아니며 외부 쓰기와 운영 복구는 별도 승인 범위입니다.

계층 사이에서 같은 의미를 유지하는 예시#

보관 상태를 저장하는 DB 필드가 boolean이고 API가 문자열을 받으며 화면이 체크박스를 사용한다면 변환 규칙이 필요합니다. 문자열 "false"를 단순히 값이 존재하는 것으로 판단하면 참으로 처리하는 실수가 생길 수 있습니다. 실제 언어와 프레임워크의 변환 규칙을 확인하고 허용할 입력 타입을 계약으로 정하세요. 편리한 자동 변환을 늘리기보다 잘못된 타입을 명확히 거부하는 편이 맞는 경우도 있습니다.

기존 데이터에 필드가 없다면 어떤 값을 보여 줄지 별도로 정해야 합니다. 응답 필드가 없는 경우와 실제 거짓 값이 같은지, 이전 클라이언트가 필드를 무시할 수 있는지 검토하세요. 계약을 정한 뒤 각 계층의 테스트가 같은 기대값을 쓰도록 대조합니다. 구현에서 나온 응답을 그대로 모든 테스트에 복사하지 않습니다.

변경 파일 목록에서 빠지기 쉬운 소비자#

기능을 추가하면 화면과 API 코드 외에도 검색, 내보내기, 캐시와 배치 작업이 같은 데이터를 읽을 수 있습니다. 보관 기능이라면 목록에서는 숨겼지만 CSV 내보내기에는 계속 나오는 것이 맞는지 담당자에게 확인해야 합니다. 관리자 화면과 일반 사용자 화면의 정책도 다를 수 있습니다. 이런 결정을 기존 코드의 우연한 동작으로 대신하지 마세요. 실제 소비자를 조사하고 각 계약을 문서로 확인한 다음 변경 범위를 정합니다.

권한 검사는 소비자마다 검토합니다. API의 한 경로에서만 제한하고 다른 검색·내보내기 경로에는 제한이 없을 수 있기 때문입니다. 한 화면의 버튼 상태를 바꿨다는 사실은 모든 데이터 접근 경계를 고친 증거가 아닙니다. 동적 호출과 문자열 키를 쓰는 위치도 조사하되 읽지 못한 영역을 확인했다고 표시하지 않습니다. 수정 권한이 다른 담당자에게 있다면 정확한 소비자 경로와 계약 차이, 필요한 검사를 인계하세요.

검증 행렬을 변경 계획과 함께 유지하기#

작업 목록의 보관 상태를 예로 더 구체화해 봅시다. 보관 상태 예에서 실행하지 않은 가상 정책은 다음과 같습니다. 이전 행의 누락 필드와 DB의 NULL은 읽을 때 미보관으로 해석하지만, 새 변경 API의 입력은 boolean만 허용하고 null과 문자열은 거부한다고 정합니다. 기본 목록과 검색은 보관 항목을 숨기고, 내보내기는 사용자가 명시한 포함 옵션이 있을 때만 보관 항목을 넣습니다. 이 선택은 실제 제품 정책이 아니라 계약 간 차이를 검토하기 위한 가정입니다.

입력의 null 거부와 기존 DB NULL 해석이 다른 것은 이 가정에서는 의도된 호환 정책입니다. 다만 문서에 설명하지 않으면 한 계층의 담당자가 두 규칙을 같은 것으로 단순화할 수 있습니다. 읽기 변환과 새 쓰기 검증을 각각 검사하고 그 경계를 연결하세요. 테스트가 가짜 저장소만 사용했다면 실제 기존 데이터 변환은 미확인이고, 가짜 네트워크 응답으로 화면만 봤다면 실제 서버의 오류 형식도 미확인입니다. 이 행렬은 그 차이를 드러내는 계획이지 통합 실행 결과가 아닙니다.

인수인계에서 막연한 완료 표현을 피하기#

검토에서 “DB와 API의 값은 true인데 검색에 계속 나온다”는 관찰이 나오면 위 행렬의 검색 경계를 조사할 수 있습니다. 목록 화면의 성공 결과만으로는 이전 응답이 남아 있는 상태를 구분할 수 없으므로 그 구분 방법을 계약에 넣을 수 있습니다. “상태는 바뀌었지만 새로고침 전까지 남는다”면 캐시와 화면 갱신 경계를, “내보내기에서만 다시 나타난다”면 포함 옵션의 해석과 출력 변환을 살펴야 합니다. 같은 필드의 오류라도 어느 소비자가 어긋났는지에 따라 읽을 코드가 달라집니다.

인계에는 이런 사용자 조건과 검사 경계를 연결해 적습니다. 실제 실행하지 않은 행에는 필요한 데이터·환경을 남기고 가상의 정책과 실제 서비스의 선택을 구분하세요. 기존 검사가 이 계약을 이미 다루면 중복 파일을 새로 만들기보다 빠진 행과 기대값을 보강할 수 있습니다. 파일 수가 많아도 사용자가 보는 한 흐름으로 검토해야 하는 이유입니다.

컬럼을 추가할 때 기존 행의 값 확인하기#

PostgreSQL 문서는 ADD COLUMN에 휘발성이 아닌 DEFAULT를 지정하면 기본값이 문장 실행 시점에 계산되어 테이블 메타데이터에 저장되고, 기존 행을 읽을 때도 그 값이 반환된다고 설명합니다(PostgreSQL ALTER TABLE 문서). 그래서 새 필드의 기본값이 기존 행의 의미와 같은지는 배포 전에 실제 행으로 확인해야 합니다. 기본값을 계산하는 식이 휘발성이면 이 설명의 적용 범위가 달라지므로 문서를 다시 확인하세요.

기본값이 문장 실행 시점에 계산되어 저장된다는 점은 기존 행의 값을 바꾸는 작업과 같은 단위로 볼 근거가 됩니다. 기본값 변경과 백필은 별도 승인으로 나누고, 백필 전후의 행 수와 실패 행 식별자를 기록하세요. 두 작업을 같은 배포에 넣을 때는 실패 조건과 되돌릴 수 있는 범위를 따로 적으세요.

배포 순서는 서버 변경, 저장소 변경, 화면 변경의 순서로 적고, 각 단계에서 이전 클라이언트가 새 응답을 읽을 수 있는지 확인합니다. 호환 기간이 끝나는 날짜와 그 뒤에 제거할 필드 목록을 함께 적어야, 이전 화면이 남은 상태를 인계받은 사람이 같은 판단을 반복할 수 있습니다. 데이터 변경은 기존 행이 새 규칙을 통과하는지 먼저 세고, 실패 행의 식별자를 남긴 뒤에 적용하세요. 이 글은 실제 배포 기록을 포함하지 않습니다.

다음에 읽을 것#

각 단계에서 테스트할 조건은 테스트 생성과 검증을 참고하세요.

관련#

• 기능 구현하기

편집 메모 (2026-11-02): 통합 실패의 확인 순서를 보충했습니다. UI 오류라면 요청·응답 계약과 권한·오류 상태를 대조하고, DB/API 불일치라면 실제 적용 버전과 기존 데이터 호환부터 확인하세요.