공개 API 응답의 키 집합은 시험으로 정확히 고정한다

로그인 없이 부르는 공개 API는 처음엔 화면에 필요한 몇 개만 돌려준다. 그런데 기능이 붙을 때마다 직렬화기에 필드가 하나씩 늘고, 어느새 내부 id, 설정값, 다른 사용자의 정보까지 나가고 있다. 무엇이 공개되는지 아무도 한눈에 모른다.

필드가 늘어나는 길은 많고(모델 전체 직렬화, 중첩 객체 통째로 넣기), 그 변경은 diff에서 「한 줄 추가」로만 보인다. 기존 시험은 보통 「필요한 키가 있는가」만 보니, 키가 늘어도 아무것도 깨지지 않는다.

해법

공개 응답의 키 집합을 정확히 비교하는 시험을 하나 둔다. 포함 여부가 아니라 같음을 본다. 중첩 객체도 따로 고정한다.

def test_public_widget_response_keys(client, widget):
    body = client.get(f"/api/public/widgets/{widget.slug}").json()

    assert set(body) == {"slug", "title", "theme", "greeting"}
    assert set(body["theme"]) == {"color", "position"}

여기에 문서 한 장을 곁들인다. 필드마다 「화면 어디서 쓰는가」를 적는다. 그러면 필드를 더하려는 사람은 시험을 고쳐야 하고, 시험을 고치는 diff에서 「이 값을 공개해도 되는가, 화면이 정말 쓰는가」가 리뷰어 눈에 드러난다. 공개 범위를 바꾸는 결정이 조용히 지나가지 않는다.