Kotlin Spring Boot 기반의 신규 프로젝트를 시작했습니다

기술 스펙은 아래와 같습니다

  • Spring Boot 2.6.6
    • 2.7 버전으로 올릴 수 있음
  • Kotlin 1.6.10
    • 2.0 버전으로 올릴 수 있음 or 1.6.21
  • Persistence
    • JPA
    • Mybatis
  • Test
    • JUnit - Kotlin 기반의 Kotest 가 좋다고 하지만 도입하지는 않았습니다
  • Security
    • Session - Cookie

Clean Architecture 를 표방하기 때문에 Mauve Point 와 비슷한 구조로 진행됩니다

다만 Legacy 부분과 격리 및 연동을 위해 가능하다면 Domain Model 을 도출해 재사용 가능한 Model 과 비즈니스 로직을 분리하려고 합니다

Legacy 영역에서는 Mybatis 가 쓰이고 그 밖의 새로운 기능은 JPA로 구현하기로 했습니다

앞으로는 테스트를 거쳐야만 빌드/배포가 가능한 SW 개발을 하기 위해 시작한 부분을 설명하고 발전시킬 부분에 대해 얘기하고자 합니다

먼저 선행 학습으로 본 내용으로는 최범균님이 소개해준 내용을 참고했습니다

  1. 세미나 공유 - 테스트
  2. 세미나 공유 - TDD 테스트 작성 순서, 기능 명세, 그리고 시연 한 번 더
  3. 세미나 공유 - TDD 테스트 코드 구조, 대역
  4. 세미나 공유 - 테스트 가능 구조

 

첫 번째 시도

위 내용을 기반으로 작성했고 Java 기반으로 되어 있기 때문에 이 부분을 Kotlin 으로 전부 변환 해봤습니다

왜? 수고스럽게 변환을 진행했냐면 기존에 사용했던 Swagger 형태에 비해 UI 가 많이 별로 입니다

Swagger-ui 코드를 커스텀하게 수정해서 사용한 적이 있는데 내부에 Backbone-JS 라는 것으로 동적 HTML 생성이 가능하게 되어 있습니다

정적인 화면이 아니라 클릭 이벤트나 테스트도 가능할 정도로 입력에 있어 사용자와 Interactive 하게 만들어지는 장점이 있습니다

Rest Doc 은 정적인 HTML 화면입니다 즉 스크롤 기능도 제한적이고 슬라이드 업/다운 같은 기능도 없습니다

화면 구성을 직접 구성해야 하고 공통 코드나 Request/Response 에 대해서도 표를 따로 구성해야 합니다

기본 화면 Base를 따라 가기 위해 직접 우아한 형제들 오픈 프로젝트를 Kotlin 언어로 변환해서 클론 코딩을 해봤습니다

적은 시간으로 아래와 같은 Utils 와 공통 부분을 생성했습니다

index.html 이 산출물 파일이며 저 파일을 서버에 올려서 웹 브라우저에서 볼 수도 있습니다
  • ApiDocumentUtil : Pretty Print 설정을 하는 파일입니다
  • CustomResponseFieldsSnippet : 테스트로는 API 에 대한 데이터만 만들어지기 때문에 공통 코드에 대해 Generic 하게 처리하는 부분입니다
  • DocumentFormatGenerator : DateTime Format 을 정하는 부분으로 필요한 Format 을 추가할 수 있습니다
  • DocumentLinkGenerator : 팝업 화면을 설정할 수 있는 부분입니다
  • MockitoHelper : Java 버전에는 없는 부분으로 Kotlin이 기본 Final Class 속성이어서 Mocking 이 안되는 부분이 있어 추가해 넣었습니다
  • CommonDocumentationTest, Docs, EnumViewController : 응답 코드/에러 코드 와 같은 공통 데이터를 정의한 부분입니다

Swagger 로 작성된 문서와 비교하면 더 어렵고 불편한 부분이 있습니다

Swagger 의 장점

  • UI 가 더 예쁘게 나온다
  • 문서가 편하게 자동 완성이 된다

Rest Docs 의 장점

  • 테스트 기반 코드로 문서를 만들 수 있다
    • 즉 테스트기반 코드를 만들 수 있다

 

테스트를 수행하면 아래와 같은 폴더에 snippet 파일이 생기고 index.adoc 파일을 직접 편집하면 파일 기반으로 index.html 이 생성됩니다

Swagger-UI 에 비교하면 아래 내용이 추가로 한땀 한땀 만들어야 하는 부분이 있어 불편하긴 합니다

 

두 번째 시도

  • 빌드 및 배포 상황에 테스트 먼저 수행하기 

tasks {
        val snippetsDir by extra { file("build/generated-snippets") }  // 변경   
       
       clean {
              delete("src/main/resources/static/docs")
       }  
        test {
               useJUnitPlatform() 
               outputs.dir(snippetsDir)
        }      
        asciidoctor {
                dependsOn(test)
                inputs.dir(snippetsDir)  
                doFirst {
                         delete("src/main/resources/static/docs")
                }      
        }
        register<Copy>("copyDocument") {
                  dependsOn(asciidoctor)  
                  from(asciidoctor.get().outputDir) {
                         into("src/main/resources/static/docs")
                  }
        }    
        build {
              dependsOn("copyDocument")   
        }  
        bootJar {
                dependsOn("copyDocument")
        }
}
일단 테스트 코드 작성에 대한 내용 자체는 여기서 한번 끊고 가려고 합니다 (일단 인프라 만 만들기)

현재 API 문서를 만들기 위한 테스트 부분은 API 요청과 응답에 대한 Controller 영역에 대한 슬라이스 테스트로 진행되는 부분으로 전체 적인 테스트를 하는 것은 아닙니다

통합 테스트 관점으로 모든 것을 해결하려하면 테스트 수행 시간이 점점 오래 걸리게 됩니다

점점 누적되고 쌓인 테스트로 개발-검증 생산성이 높아져야 하는 부분인데 이 부분은 분리해서 진행하려고 합니다

아래는 추가로 공부하려고 수집한 내용입니다

테스트를 도입하고 설계에 응용하는 방법과 의견들이 있으면 언제든 말을 걸어 주세요 (스터디도 있습니다)

저작자표시 (새창열림)

'My Work > Tech Blog' 카테고리의 다른 글

서버의 Error 에 따른 HTTP Status Code  (0) 2025.10.12
테스트 기반 개발 방법 실행하기(도입기 2)  (1) 2025.10.12
코드 리뷰 - 잘할 수 있을까?  (0) 2025.10.12
Ktor를 써 봤습니다  (0) 2025.10.12
Ktor 써도 될까요?  (0) 2025.10.12

+ Recent posts

티스토리툴바