231018.md

그래들 빌드 최적화

문제 상황

api 문서 빌드 태스크 스크립트를 작성하는 과정에서 openapi3.yaml 파일이 빌드 시 누락되는 문제가 발생했다.

로컬에서는 openapi3.yaml 파일이 있으니 api-guide.html을 열더라도 별다른 문제가 발생하지 않았다. 하지만 개발서버에서만 희안하게 openapi3.yaml 요청 시 404가 발생했다. 처음에는 권한 문제인 줄 알았지만 그것도 아니었고, 리소스 핸들러를 등록해줘서 해결할 수 있을 줄 알았지만 그것도 아니었다.

도커에서 마는 과정에서 문제가 생기나 싶어서 github actions에서 시크릿을 넣어줄 때 openapi3.yaml 파일을 직접 넣어줬는데, 이 때는 잘 작동했다.

실제로 로컬에서 이미지를 받아서

결론부터 말하자면 문서화 태스크가 bootjar 이후에 실행되기 때문에 bootjar에서는 openapi3.yaml

...

문제 원인

• build 작업의 bootJar 작업이 api 문서화 작업 이전에 실행되기 때문에, jar 파일에서 openapi3.yaml 파일이 누락되는 것
• openapi3.yaml 이 누락된 jar 파일을 docker로 말아 올리면서 개발서버의 문제가 발생함
• 로컬 환경에서는 build 작업을 재실행할 경우 먼저 생성된 openapi3.yaml을 참조하기 때문에 2번째 실행부터는 문제가 발생하지 않음 (즉, clean build 상황에서만 문제 발생)
• github actions의 가상 인스턴스에서는 build가 최초로 실행되므로 항상 openapi3.yaml이 누락되게 됨

해결 방법

• gradle의 bootjar 작업을 api 문서화 작업 이후에 실행되도록 변경

그 외 작업내용

• 여러 작업으로 구성된 api 문서화 작업의 의존관계를 개선함
• api 문서 생성 작업은 openapi3 (생성) -> copyOasToResources (복사) 두 단계로 구성됨
• 이 두 단계에 대한 의존성을 관리하는 lifecycle task(일종의 의존성 앵커 역할)인 generateApiDocs 작업으로 묶음 -> 추후 api 문서에 대해 추가적인 작업을 해주는 경우 generateApiDocs에다가 디펜던시로 묶어주면 된다.
• 이 작업은 test 작업 이전에 수행되어야 함 -> check 가 종결될 때 generateApiDocs를 호출하는 디펜던시 추가
• 이 작업 완료 후에는 bootJar 작업을 수행해야 함 -> generateApiDocs가 종결될 때 bootJar를 추가하는 디펜던시 추가