회사 안에서 사용하는 코드와 규격을 맞추면 새로 합류한 사람이 구조를 익히기 쉽고, 다른 프로젝트의 소스를 살펴볼 때도 기준을 찾기 편해집니다. 비슷한 문제를 매번 다시 해결하지 않아도 된다는 장점도 있습니다.
하지만 이전의 공통 라이브러리들이 오래 유지되지 못하는 경우도 자주 봤습니다. 프로젝트의 성격과 프레임워크 버전이 달라졌고, 당시의 구현 방식이나 기술 흐름도 바뀌었습니다. 여러 상황을 모두 지원하려다 기능이 많아지거나, 최신화되지 않은 표준이 새로운 개발의 발목을 잡기도 했습니다.
표준화에 먼저 반대했던 이유
이번 API 규격 라이브러리 작업을 처음 검토했을 때도 비슷한 우려가 있었습니다. 기존 프로젝트를 살펴봤지만 하나의 라이브러리로 옮길 만큼 분명하게 반복되는 구현 패턴을 찾기 어려웠습니다.
프로젝트마다 필요한 기능과 운영 방식이 달랐고, 앞으로 사용할 기술도 계속 바뀔 수 있었습니다. 이 상태에서 먼저 표준을 만들면 아직 존재하지 않는 공통점을 가정한 채 여러 프로젝트의 선택지를 좁힐 수 있다는 생각이 들었습니다.
그래서 어떤 기능을 공통으로 제공할지보다, 프로젝트가 달라져도 계속 남는 문제가 실제로 있는지를 먼저 살펴봤습니다.
구현보다 제약이 반복되고 있었습니다
클라이언트와 API가 통신할 때 사용하는 암호화는 대부분의 프로젝트에서 피하기 어려운 조건이었습니다. 암호화 어노테이션이 붙은 요청은 실제 통신에서는 POST로 처리됐지만, 데이터를 조회하거나 수정하는 것처럼 기능이 가진 의미는 서로 달랐습니다.
일반적인 Swagger 화면에서는 이 요청들이 모두 POST로 표시됐습니다. 실제 전송 방식은 확인할 수 있었지만 각 API가 무엇을 하는지 한눈에 읽기 어려웠고, 암호화된 요청을 문서 화면에서 바로 시험하기도 쉽지 않았습니다.
규격을 자세히 적을수록 문서가 길어져 읽기 어려워지는 문제도 있었습니다. 각 프로젝트가 같은 암호화 흐름과 문서의 한계를 다시 해결하는 일은 기술 선택의 차이라기보다 반복되는 제약에 가까웠습니다.
반복되는 부분만 좁게 묶기
라이브러리는 모든 API 구현 방식을 정하는 대신 계약, 실행 시 필요한 처리와 문서 생성을 나누어 구성했습니다. 문서가 필요하지 않은 서비스는 관련 기능을 선택하지 않을 수 있고, 프로젝트마다 달라질 정책까지 공통 규칙으로 강제하지 않으려 했습니다.
문서에서는 실제 통신 방식과 API가 가진 기능의 의미를 함께 읽을 수 있도록 정리했습니다. 암호화 키는 문서에 포함하지 않고, 테스트할 때 화면에서 직접 입력해 요청을 암호화하도록 만들었습니다. 키가 달라질 때마다 문서를 다시 배포하지 않아도 되는 구조였습니다.
여기서 공통으로 묶은 것은 특정 프로젝트의 화면이나 업무 규칙이 아니었습니다. 여러 프로젝트에서 반복되는 암호화 통신과, 그 때문에 생기는 API 문서와 테스트의 불편이었습니다.
표준화의 기준은 비슷해 보이는 코드가 아니라, 프로젝트가 달라져도 반복되는 제약에 가까웠습니다.
표준은 사용하는 경로에서 확인하기
라이브러리 안에서 예제가 동작하는 것만으로는 표준이 실제로 사용될 수 있는지 알기 어려웠습니다. 별도의 프로젝트가 배포된 라이브러리를 받아 설정하고, 문서만 보고 요청을 시험하는 과정까지 확인해야 했습니다.
같은 저장소 안에서 코드를 직접 참조하면 보이지 않던 버전, 배포와 설정 문제는 사용하는 쪽에서 처음 드러날 수 있었습니다. 그래서 표준 라이브러리의 완료 조건도 기능을 한곳에 모으는 데서 끝나지 않고, 다른 프로젝트가 정해진 경로를 따라 실제로 적용할 수 있는지까지 확인하는 일에 가까웠습니다.
이번 작업을 거치며 표준화 자체에 찬성하거나 반대하는 것보다, 무엇이 오래 유지될 수 있는지 구분하는 편이 중요하다는 생각이 들었습니다. 달라질 가능성이 큰 구현은 각 프로젝트에 남겨두고, 반복해서 해결하고 있던 제약만 좁게 공유하는 편이 이후의 변경에도 대응하기 쉬웠습니다.