Apache Maven 및 App Engine 플러그인 사용(App Engine SDK 기반)

이 페이지에서는 소프트웨어 프로젝트 관리 및 분석 도구인 Apache Maven을 사용하여 App Engine 프로젝트를 관리하는 방법을 설명합니다. 이 도구로 App Engine에 배포할 WAR 파일을 빌드할 수 있습니다. Google은 Maven 3.5에 포함되어 있는 Maven Archetype과 플러그인을 제공합니다.

Maven을 사용하는 경우 App Engine SDK에서 자바 라이브러리를 직접 다운로드할 필요가 없습니다. Maven이 필요에 따라 적절한 라이브러리를 자동으로 다운로드합니다. 또한 Maven을 사용하여 로컬에서 앱을 테스트하고 프로덕션 App Engine에 배포할 수 있습니다.

Maven 설정

자바 구성

  1. 자바가 설치되어 있지 않으면 다운로드하여 설치하고 구성합니다.
  2. pom.xml에서 컴파일러 플래그를 설정하여 자바 8 바이트코드를 지정합니다.
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

Maven 3.5 설치

다음 명령어를 호출하여 Maven 설치 여부 및 버전을 확인합니다.

 mvn -v

Maven의 올바른 버전이 설치되어 있지 않으면 다음을 수행합니다.

  1. Maven 웹사이트에서 Maven 3.5를 다운로드합니다.
  2. 로컬 머신에 Maven 3.5를 설치합니다.

Cloud 프로젝트 설정 및 유효성 검사

Cloud 프로젝트를 설정하고 App Engine SDK를 설치해야 합니다.

  1. Google Cloud Console을 사용하여 Cloud 프로젝트를 만들고 설정합니다.

    App Engine으로 이동

    1. 새 클라우드 프로젝트를 선택하거나 만듭니다.
    2. 프로젝트용 App Engine 애플리케이션을 만들어야 하는 경우, App Engine 애플리케이션을 배치할 리전을 선택하라는 메시지가 표시됩니다.
    3. 프로젝트에 App Engine 애플리케이션이 생성된 후 대시보드가 열립니다.
  2. 자바용 App Engine SDK를 설치하고 해당 디렉터리를 PATH에 추가합니다.

Maven 사용

기존 프로젝트에 App Engine 플러그인 추가(선택사항)

기존 Maven 프로젝트에 Google App Engine Maven 플러그인을 추가하려면 프로젝트 pom.xml 파일의 plugins 섹션에 다음을 추가합니다.

<plugin>
   <groupId>com.google.appengine</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.9.88</version>
</plugin>

아키타입 선택

사용자는 Maven Archetype을 통해 일반적인 시나리오를 지원하는 템플릿을 사용하여 Maven 프로젝트를 만들 수 있습니다. App Engine은 이 Maven 기능을 활용하여 Maven Central에서 몇 가지 유용한 App Engine archetype을 제공합니다. 사용 중인 앱에 적합한 App Engine archetype을 선택합니다.

애플리케이션 유형 아티팩트 설명
App Engine 앱 guestbook-archetype 바로 실행하고 테스트할 수 있는 완성된 방명록 데모 샘플을 생성합니다.
App Engine 앱 appengine-skeleton-archetype 클래스와 리소스를 직접 추가할 수 있는 빈 App Engine 프로젝트를 새로 생성합니다. 필수 파일 및 디렉토리를 포함합니다.

새 프로젝트 만들기

프로젝트를 만들 때 Maven에서는 프로젝트의 groupId, artifactId, versionpackage를 제공하라는 메시지가 표시됩니다.

항목 의미
groupId Maven 내에서 아티팩트를 추적하는 네임스페이스입니다. 다른 사람이 자체 Maven 프로젝트에서 내 프로젝트를 사용할 때 이 네임스페이스를 종속 항목 속성으로 지정합니다.
artifactId Maven 내에서 사용할 프로젝트 이름입니다. 다른 사람이 자체 Maven 프로젝트에서 내 프로젝트를 사용할 때 이 이름도 지정합니다.
version 프로젝트를 생성하려는 초기 Maven 버전입니다. version-SNAPSHOT을 서픽스로 붙이는 것이 좋습니다. 이렇게 하면 개발 중인 Maven 출시 버전의 플러그인을 지원할 수 있습니다. 자세한 내용은 출시 버전 플러그인 사용에 대한 Maven 가이드를 참조하세요.
package 생성 중에 만들어지는 자바 패키지입니다.

다음 절차에서는 App Engine Maven 아키타입을 사용하여 App Engine 애플리케이션을 만드는 방법을 설명합니다.

App Engine 앱을 만드는 방법은 다음과 같습니다.

  1. 프로젝트를 빌드할 디렉토리로 변경합니다.

  2. 다음 Maven 명령어를 호출합니다.

     mvn archetype:generate -Dappengine-version=1.9.88 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
    

    -Dappengine-version을 자바용 App Engine SDK의 최신 버전으로 설정하고 application-id를 클라우드 프로젝트의 ID로 설정합니다.

    자바 8 런타임에 프로젝트를 배포하도록 -Djava8=true를 설정합니다.

    자바용 App Engine SDK 도구를 사용하도록 -DCloudSDK_Tooling=false를 설정합니다.

  3. 아키타입을 선택하라는 메시지가 나타나면 App Engine 스켈레톤 아키타입의 값으로 2를 선택합니다. 그러면 필요한 디렉터리 구조와 파일을 포함하는 빈 프로젝트가 만들어집니다.

  4. 버전을 선택하라는 메시지가 나타나면 ENTER를 눌러 기본 최신 버전을 선택합니다.

  5. Define value for property 'groupId' 메시지가 나타나면 앱에 사용할 네임스페이스를 제공합니다(예: com.mycompany.myapp).

  6. Define value for property 'artifactId' 메시지가 나타나면 프로젝트 이름을 제공합니다(예: myapp).

  7. Define value for property 'version' 메시지가 나타나면 기본값을 수락합니다.

  8. Define value for property 'package' 메시지가 나타나면 선호하는 패키지 이름을 제공합니다(또는 기본값 사용). 생성된 자바 파일은 여기에 지정된 패키지 이름을 갖게 됩니다.

  9. 선택을 확인하라는 메시지가 나타나면 기본값(Y)을 수락합니다.

  10. 프로젝트에서 필요한 디렉터리 및 파일 생성이 완료될 때까지 기다립니다. 그런 다음 새 프로젝트 디렉터리(예시: myapp/)로 이동합니다.

    프로젝트가 성공적으로 완료되면 다음과 비슷한 메시지가 표시됩니다.

    [INFO] --------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] --------------------------------------------------
    [INFO] Total time: 1:16.656s
    [INFO] Finished at: 2017-06-04T16:18:24-07:00
    [INFO] Final Memory: 16M/228M
    [INFO] --------------------------------------------------
    
  11. 앱의 고유 클래스 코딩을 시작하기 전에 기본 프로젝트 레이아웃과 필요한 프로젝트 파일을 살펴봅니다. 프로젝트를 만든 디렉터리 내에는 pom.xml 파일이 포함된 myapp 하위 디렉터리와 src/main/javasrc/main/webapp/WEB-INF 하위 디렉터리가 있습니다.

    Maven 프로젝트 레이아웃

    • 직접 작성하는 애플리케이션 자바 클래스는 src/main/java/...에 추가합니다.
    • src/main/webapp/WEB-INF/appengine-web.xml 파일을 사용하여 애플리케이션을 구성합니다.
    • src/main/webapp/WEB-INF/web.xml 파일을 사용하여 애플리케이션 배포를 구성합니다.
  12. 애플리케이션 자바 클래스를 만들고 이를 src/main/java/.../에 추가합니다. 자세한 내용은 App Engine에 앱 빌드를 참조하세요.

  13. 앱 사용자에게 제공하려는 UI를 추가합니다. 자세한 내용은 양식 데이터 처리를 참조하세요.

  14. 프로젝트를 만드는 데 사용한 아티팩트에는 기본적인 src/main/webapp/WEB-INF/appengine-web.xml 구성이 자동으로 완료되어 있습니다. 그러나 고급 구성을 사용하려면 이 파일을 수정해야 할 수 있습니다. 자세한 내용은 appengine-web.xml 구성을 참조하세요.

  15. src/main/webapp/WEB-INF/web.xml 파일을 수정하여 앱 핸들러에 URL을 매핑하고 인증, 필터 등을 지정합니다. 자세한 내용은 배포 설명자를 참조하세요.

Maven 프로젝트 관리

프로젝트 컴파일 및 빌드

Maven App Engine 아키타입으로 생성한 앱을 빌드하는 방법은 다음과 같습니다.

  1. 디렉터리를 프로젝트의 기본 디렉터리로 변경합니다(예시: guestbook/).
  2. Maven을 호출합니다.

    mvn clean package
    
  3. 프로젝트가 빌드되기를 기다립니다. 프로젝트가 성공적으로 완료되면 다음과 비슷한 메시지가 표시됩니다.

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: Thur Jul 04 14:50:06 PST 2017
     Final Memory: 24M/213M
    
  4. 선택적으로 다음 절차에 따라 애플리케이션을 테스트합니다.

개발 서버에서 앱 테스트

개발 단계에서는 개발 서버에서 App Engine Maven 플러그인을 호출하여 언제든지 애플리케이션을 실행하고 테스트할 수 있습니다. 이 절차는 프로젝트를 만드는 데 사용된 아티팩트에 따라 약간 다릅니다.

앱을 테스트하는 방법은 다음과 같습니다.

  1. 앱을 아직 빌드하지 않았으면 빌드합니다(mvn clean package).

  2. 디렉터리를 프로젝트의 최상위 수준으로 변경하고(예: myapp) Maven을 호출하여 앱을 실행합니다.

    mvn appengine:devserver
    

    서버가 시작되기를 기다립니다. 서버가 완전히 시작되고 앱이 실행되면 다음과 비슷한 메시지가 표시됩니다.

    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
    INFO: The server is running at http://localhost:8080/
    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
    INFO: The admin console is running at http://localhost:8080/_ah/admin
    
  3. 브라우저에서 http://localhost:8080/으로 이동하여 앱에 액세스합니다.

  4. 실행을 시작한 Windows/Linux 터미널 창에서 Ctrl+C를 눌러 앱과 개발 서버를 종료합니다. Mac의 경우 CMD+C를 누르면 됩니다.

로컬 테스트를 위한 포트 지정

로컬 개발 서버에서 앱을 실행할 때 기본 포트는 8080입니다. 이 기본값을 변경하려면 appengine-maven-plugin의 플러그인 항목을 수정하거나 항목이 없는 경우 새로 추가합니다. 예를 들어 기본 앱 디렉터리의 pom.xml 파일(myapp/pom.xml)에 있는 <plugins>에서 다음 <plugin> 항목에 포트와 주소를 지정합니다.

 <plugin>
     <groupId>com.google.appengine</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>1.9.88</version>
     <configuration>
         <enableJarClasses>false</enableJarClasses>
         <port>8181</port>
         <address>0.0.0.0</address>
     </configuration>
 </plugin>

여기에서 <port>는 포트를 8181로 지정하고 있으며 주소는 0.0.0.0으로 지정되었습니다. 따라서 개발 서버는 로컬 네트워크에서 들어오는 요청을 수신 대기합니다.

앱 배포

앱 배포 가이드를 참조하세요.

참조: 사용 가능한 목표

프로젝트의 pom.xml 파일에 App Engine Maven 플러그인이 추가되면 몇 가지 App Engine용 Maven 목표를 사용할 수 있습니다. 사용 가능한 목표를 모두 확인하려면 다음 명령어를 호출합니다.

 mvn help:describe -Dplugin=appengine

App Engine Maven 플러그인 목표는 개발 서버 목표, 앱 및 프로젝트 관리 목표, 엔드포인트 목표로 분류할 수 있습니다.

개발 서버 목표

개발 서버 목표는 다음과 같습니다.

appengine:devserver

App Engine 개발 서버를 실행합니다. 서버를 실행하는 동안 appengine-web.xml이 변경되었는지 여부를 지속적으로 확인합니다. 이 파일이 변경되면 서버가 애플리케이션을 무중단으로 다시 로드합니다. 즉, appengine-web.xml의 변경을 이유로 애플리케이션을 중지했다가 다시 시작할 필요가 없습니다. 다음과 같은 매개변수를 사용할 수 있습니다.

  • <fullScanSeconds>
  • <address>
  • <disableUpdateCheck>
  • <jvmFlags>
  • <port>
  • <server>

예를 들어 시작 시 일시정지하지 않고 포트 8000에서 디버그 모드로 서버를 실행하려면 다음 플래그를 사용합니다.

<jvmFlags>
  <jvmFlag>-Xdebug</jvmFlag>
  <jvmFlag>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n</jvmFlag>
</jvmFlags>

기본적으로 <fullScanSeconds> 플래그는 5초로 설정되므로 서버가 5초마다 웹 애플리케이션 파일의 변경 여부를 확인하여 애플리케이션을 자동으로 다시 로드합니다. 이 기능은 NetBeans와 같이 저장 시 컴파일 기능을 지원하는 IDE에 유용합니다. 이 기능을 사용하려면 <build> 섹션을 구성해야 합니다.

<build>
   <outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
   <plugins>
      ....
   </plugins>
</build>
appengine:devserver_start

개발 서버를 비동기식으로 시작하고 명령줄로 돌아갑니다. 이 목표가 실행될 경우 동작은 Maven이 목표를 계속 처리하고 서버가 가동 및 실행된 후 종료된다는 점을 제외하고 devserver 목표와 동일합니다.

appengine:devserver_stop

개발 서버를 중지합니다. appengine:devserver_start로 개발 서버를 시작한 경우에만 사용할 수 있습니다.

애플리케이션 관리 목표

다음 표에서는 애플리케이션 및 프로젝트 관리를 위한 목표를 보여줍니다.

목표 설명 해당 gcloud 명령어
appengine:backends_stop pom.xml 파일에 구성된 포트에서 수신 대기하면서 실행 중인 개발 서버를 모두 중지합니다. 이 목표를 devserver_start 명령어와 함께 사용하여 Maven 플러그인과 통합 테스트를 수행 할 수 있습니다.
appengine:backends_configure 지정된 백엔드를 구성합니다.
appengine:backends_delete 지정된 백엔드를 삭제합니다.
appengine:backends_rollback 이전에 진행 중이던 업데이트를 롤백합니다.
appengine:backends_start 지정된 백엔드를 시작합니다.
appengine:backends_update 지정된 백엔드를 업데이트하거나, 백엔드를 지정하지 않은 경우 모든 백엔드를 업데이트합니다.
appengine:enhance App Engine Datanucleus JDO Enhancer를 실행합니다.
appengine:rollback 진행 중인 업데이트 롤백 gcloud app versions start gcloud app versions stop
appengine:set_default_version 기본 애플리케이션 버전 설정 gcloud app services set-traffic
appengine:update 앱 버전을 만들거나 업데이트합니다. gcloud app deploy
appengine:update_cron 애플리케이션 크론 작업을 업데이트합니다. gcloud app deploy
appengine:update_dispatch 애플리케이션 디스패치 구성을 업데이트합니다. gcloud app deploy
appengine:update_dos 애플리케이션 DoS 보호 구성을 업데이트합니다. gcloud app deploy
appengine:update_indexes 애플리케이션 색인을 업데이트합니다. gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues 애플리케이션 작업 대기열 정의를 업데이트합니다. gcloud app deploy
appengine:vacuum_indexes 애플리케이션에서 미사용 색인을 삭제합니다. gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version 지정된 모듈 버전을 시작합니다. gcloud app versions start
appengine:stop_module_version 지정된 모듈 버전을 중지합니다. gcloud app versions stop

업로드 오류 문제해결

업데이트 목표를 사용하는 경우 404 Not Found This application does not exist (app_id=u'your-app-ID')와 유사한 메시지가 표시되면서 업데이트 시도가 실패할 수 있습니다. 이 오류는 Google 계정이 여러 개이고 잘못된 계정을 사용하여 업데이트를 수행하면 발생합니다.

이 문제를 해결하려면 디렉터리를 ~로 변경하고 .appcfg_oauth2_tokens_java 파일을 찾아서 이름을 바꿉니다. 그런 다음 업데이트를 다시 시도합니다.