2024년 6월 18일

Play Framework, 2.x에서 3.x로 환골탈태! 새로운 아키텍처 마스터하기

Play Framework 2.x에서 3.x로의 마이그레이션은 단순한 버전 업그레이드가 아닌, 완전히 새로운 Akka HTTP 기반 아키텍처로의 전환을 의미한다. 이는 기존 Play Framework 2.x에 익숙한 개발자들에게는 큰 변화이며, Stack Overflow에는 호환성 문제, Akka HTTP 학습 및 적용 관련 질문들이 쏟아지고 있다.

Play Framework 3.x 마이그레이션 가이드를 꼼꼼히 살펴보고, 변경된 API와 설정 방식을 익혀야 한다. Akka HTTP에 대한 충분한 학습과 예제 코드를 통해 새로운 아키텍처에 대한 이해도를 높이는 것이 중요하다. 특히 라우팅, 액션, HTTP context 처리 등 기존 Play Framework 2.x와는 다른 방식으로 동작하는 부분에 주의해야 한다. 이 글에서는 Play 2.x에서 3.x로 마이그레이션하는 과정을 단계별 코드 예제와 함께 설명하여, 새로운 아키텍처에 대한 이해도를 높이고 마이그레이션 과정에서 발생할 수 있는 문제들을 해결하는 데 도움을 주고자 한다.

1단계: 프로젝트 설정 변경

  • build.sbt 파일 수정: Play 3.x 버전 및 관련 의존성 추가
  • application.conf 파일 수정: Akka HTTP 설정 추가
// build.sbt
lazy val root = (project in file("."))
  .enablePlugins(PlayScala)
  .settings(
    scalaVersion := "2.13.8",
    libraryDependencies ++= Seq(
      guice,
      ehcache,
      ws,
      "org.scalatestplus.play" %% "scalatestplus-play" % "5.1.0" % Test
    )
  )

# application.conf
play.server.provider = "play.core.server.AkkaHttpServerProvider"

2단계: 라우팅 변경

  • routes 파일 수정: Play 2.x의 라우팅 방식에서 Play 3.x의 새로운 라우팅 방식으로 변경
# Play 2.x
GET     /                           controllers.HomeController.index()

# Play 3.x
GET     /                           controllers.HomeController.index

3단계: 액션 변경

  • 컨트롤러 수정: Play 2.x의 Action에서 Play 3.x의 play.api.mvc.Handler로 변경
// Play 2.x
def index() = Action { implicit request: Request[AnyContent] =>
  Ok("Hello World")
}

// Play 3.x
def index: Handler = Action { request =>
  Ok("Hello World")
}

4단계: HTTP context 처리 변경

  • request 객체 변경: Play 2.x의 RequestHeader 및 Request에서 Play 3.x의 Request로 변경
// Play 2.x
def index() = Action { implicit request: Request[AnyContent] =>
  val path = request.path
  // ...
}

// Play 3.x
def index: Handler = Action { request =>
  val path = request.uri.path
  // ...
}

5단계: 테스트 코드 변경

  • 테스트 클래스 수정: Play 2.x의 WithApplication에서 Play 3.x의 GuiceOneAppPerSuite로 변경
// Play 2.x
class HomeControllerSpec extends PlaySpec with OneAppPerSuite {
  // ...
}

// Play 3.x
class HomeControllerSpec extends PlaySpec with GuiceOneAppPerSuite {
  // ...
}

추가 고려 사항:

  • 의존성 업데이트: Play 3.x와 호환되는 버전으로 모든 의존성을 업데이트해야 한다.
  • deprecated된 API 제거: Play 3.x에서 deprecated된 API를 사용하는 코드는 제거하거나 대체해야 한다.
  • Java 8 이상 사용: Play 3.x는 Java 8 이상을 요구한다.

만약 당장 마이그레이션이 어렵다면, Play Framework 2.x를 유지하면서 최신 버전으로 업데이트하고, 새로운 기능을 점진적으로 적용해 나가는 방법도 고려해볼 수 있다.

참고 자료: