스피너를 그리기 전에 상태를 적으세요
이는 개발자 소유 하이킹 앱의 흐름 제안이며, 관측된 API 동작 기록이 아닙니다. 사용자가 offline maps를 입력하고 과거 토론을 요청한 뒤 기다립니다. 앱은 아직 조작하지 않은 폼, 결과를 기다리는 요청, 레코드가 있는 응답, 정상적인 빈 응답, 실패를 구분해야 합니다. 빈 패널 하나로는 그 차이를 전할 수 없습니다.
검색 대상을 설명하는 중립적인 대기 화면으로 시작하세요. 입력만으로 요청을 보낼 필요는 없습니다. 사용자가 명시적으로 제출하면 질문을 그 요청과 함께 저장하고 로딩 표시를 보여 줍니다. 입력을 읽을 수 있게 유지하고, 반복 터치로 같은 동작을 여러 번 보내지 않게 하세요. 스피너는 기다림을 알려 줄 뿐, 아카이브 처리의 진행률을 입증하지 않습니다.
늦은 응답도 원래 질문에 연결하세요
offline maps 요청을 기다리는 동안 사용자가 입력을 「다운로드한 지역」으로 바꾼다고 가정해 보세요. 이는 상호작용 예시이지 조회된 검색 결과가 아닙니다. 앱은 기다릴지, 다른 요청을 시작할지, 사용자가 현재 화면의 작업을 취소하게 할지 결정해야 합니다. 어느 쪽을 구현하든 이전 응답을 새 문구의 답처럼 조용히 바꾸어 놓아서는 안 됩니다.
앱의 상태에서 각 요청과 제출 입력을 연결하세요. 응답이 도착하면 여전히 현재 화면에 속하는지 확인합니다. 늦은 응답을 화면에서 버리는 것과 서버의 작업을 취소하는 것은 다릅니다. 이미 보낸 요청은 정상 완료되어 과금될 수 있습니다. 자체 구현에서 이 차이를 테스트하세요.
정상적인 빈 응답도 결과로 취급하세요
레코드가 반환되면 실제로 있는 필드를 보여 주고 과거 출처라는 표시를 유지하세요. data 배열이 비어 있으면 이번 요청에서 레코드가 반환되지 않았다는 별도 메시지를 사용합니다. 기존 문구와 필터를 보존하고 수정할 수 있게 해, 독자가 무엇을 바꿀지 판단하도록 하세요. 빈 결과를 지어낸 인기 게시물로 대체해서는 안 됩니다.
정상적인 빈 조회도 레코드가 있는 정상 응답처럼 1크레딧이 듭니다. 그래서 빈 응답을 오류로 숨길 것이 아니라 쿼리 변경을 의도적으로 만들 필요가 있습니다. 관련 토론이 어디에도 없다는 메시지는 피하세요. 아카이브는 불완전하며, 응답은 특정 쿼리와 제한된 조회 범위에 대한 것입니다.
기술 문제는 운영자에게 전달하세요
400 응답이면 요청 입력을 확인해야 합니다. 앱이 잘못된 날짜나 지원하지 않는 매개변수를 보냈다면 백엔드의 명세 위반을 이용자 탓으로 돌리지 마세요. 401은 서비스 키가 없거나 유효하지 않다는 뜻이며, 앱을 다시 로드하거나 사용자에게 로그인을 요청해도 해당 인증 정보가 고쳐지는 것은 아닙니다.
402는 서비스 계정의 크레딧 부족을 뜻합니다. 사용자에게 청구서를 보여 주지 말고 운영자가 결정하게 하세요. 429이면 Retry-After를 따르고 요청 반복을 줄여야 합니다. 앱이 여러 독자에게 같은 계정을 사용할 수 있으므로, 한 사람이 한도를 초과하게 했다고 자동으로 안내하지 마세요.
확실한 실패와 결과 불명을 분리하세요
상위 조회가 실패하면 게이트웨이는 502를 반환합니다. 예약된 크레딧은 해제되거나 대사 처리 보류로 보고됩니다. 쿼리와 앞서 표시된 페이지를 유지한 뒤 제한된 재시도 선택을 제공하세요. 자동으로 계속 재시도하면 독자가 상황을 이해하는 데 도움을 주지 못한 채 요청만 늘릴 수 있습니다.
앱이 응답을 전혀 받지 못했다면 서버가 실패했는지 완료했는지 알지 못할 수 있습니다. 나중에 대사할 수 있도록 불확실성을 기록하고, 확정된 반환이나 성공으로 표시하지 마세요. 공개 /v1/status 경로는 고정 범위 안내와 HTTP 응답 확인이므로, 이 문제를 판별하거나 아카이브 검색의 정상 상태를 인증할 수 없습니다.
스크린샷뿐 아니라 전환도 검토하세요
앱 책임자와 함께 제출, 대기 중 편집, 빈 응답 수신, 실패 후 재시도, 다음 페이지 로드, 화면 떠나기 순서를 살펴보세요. 전환마다 유지하는 입력, 보이는 콘텐츠, 다음 행동을 정합니다. 보기 좋은 시안만으로는 그런 전환이 작동한다고 입증할 수 없습니다.
운영자 진단, 원시 서비스 응답, 인증 정보를 공개 메시지에서 분리하세요. 토론 기능을 쓸 수 없어도 여행 준비를 계속할 만큼의 상황 설명을 제공합니다. 이 상태 흐름을 결정하는 요청 예산과 더 보기 선택은 /ko/#field-notes에서 확인하세요.
