[Spring Boot] 4. Getting Started | 공식 문서 번역

영어 공부 && 취미로 공식 문서 번역합니다.
의역, 오역 주의!!!!!!!!
영어 못함

원문 : https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#getting-started

Spring Boot Reference Documentation

---

 

Spring Boot 또는 Spring 을 시작하려면 해당 페이지를 읽으세요. 기초적인 "무엇을?", "어떻게?", "왜?"에 대한 질문에 해결해줍니다. 해당 페이지는 설치 방법에 따라서 Spring Boot 소개가 포함되어 있습니다. 우리는 핵심 원리를 알려주면서 당신의 첫 Spring Boot application 빌드를 위해 도와줍니다.

 

4.1. Spring Boot 소개

Spring Boot는 당신이 홀로 서는, 제품 급의 Spring 기반의 application을 만들 수 있도록 도와줍니다. Spring Boot는 Spring 플랫폼에서 제안된 내용과 서드파티 라이브러리를 차용했습니다. 그래서 짧은 시간으로 시작할 수 있습니다. 대부분 Spring Boot application은 아주 적은 Spring configuration 설정만 하면 됩니다.

jar 파일을 이용하거나 더 고전적인 war 파일 배포를 할 수 있는 Java application을 만들기 위해 Spring Boot를 사용할 수 있습니다. 

Spring Boot의 주요 목표:

• 미친 듯이 빠르고 널리 접근가능한 Spring 개발 경험을 제공한다.
• 즉시 의견을 제시하되 요구사항이 기본값에서 벗어나기 시작하면 신속하게 해결한다.
• 대규모의 프로젝트에서나 가능했던 비-기능적인 기능을 제공한다. (내장 서버라든지, 보안, metrics, 모니터링, 외부 설정 등)
• (네이티브 이미지를 타겟으로 하지 않았을 때) 코드 발생이 필요 없습니다. (추가적이 설정이 없다는 뜻?) 그리고 XML 설정을 요구하지 않습니다.

 

4.2. 시스템 요구사항

Spring Boot 3.0.4 은 Java 17 이상과 호환합니다. Spring Framework 6.0.6 이상 버전이 필요합니다.

빌드 툴은 다음과 호환됩니다.:

 

Build ToolVersion

Maven	3.5+
Gradle	7.x (7.5 or later) and 8.x

 

4.2.1. Servlet Containers

Spring Boot는 내장 

Spring Boot는 내장 servlet container를 제공합니다:

 

NameServlet Version

Tomcat 10.0	5.0
Jetty 11.0	5.1
Undertow 2.2 (Jakarta EE 9 variant)	5.0

또한 호환되는 5.0 이상의 어떤 서블릿을 사용해도 Spring Boot를 배포할 수 있습니다.

 

4.2.2. GraalVM Native Images

Spring Boot application은  GraalVM 22.3 이상 버전을 사용하면 converted into a Native Image (네이티브 이미지로 변환될 수 있습니다.)

이미지는 native build tools Gradle/Maven plugins or native-image tool provided by GraalVM 를 사용해 만들 수 있습니다. 또 native-image Paketo buildpack를 사용해 네이티브 이미지를 제작할 수 있습니다.

지원되는 버전은 다음과 같습니다:

NameVersion

GraalVM Community	22.3
Native Build Tools	0.9.20

 

4.3. Spring Boot 설치하기

Spring Boot는 "고전적인" Java 개발 툴 또는 설치되어 있는 커맨드 라인 툴을 이용해 사용할 수 있습니다. 어떤 것이든 Java 17 (Spring Boot 3.0+ 기준) 버전 이상의 SDK가 필요합니다. 시작하기 전, 다음 명령어를 이용해 현재 Java 설치 유무를 확인하세요:

$ java -version

 

Java 개발이나 Spring Boot 경험이 없다면,  Spring Boot CLI (Command Line Interface) 를 먼저 시행해 보고 싶겠지만 "고전적인" 설치 안내문을 읽으세요.

 

4.3.1. Java 개발자를 위한 설치 안내문 

당신이라면 다른 기본적인 Java 라이브러리를 사용했던 것처럼 Spring Boot를 사용할 수 있습니다. 해야 할 일은 다음과 같습니다. 적절한 spring-boot-*.jar 파일을 클래스 파일에 추가하세요. 어떤 IDE 또는 편집기를 이용하든 Spring Boot는 다른 특별한 툴-통합이 필요 없습니다. 또한, Spring Boot application도 특별할 것 없습니다. 어떠한 Java 프로그램에서도 Spring Boot 실행 및 디버깅이 가능합니다.

비록 Spring Boot jars를 복사하는 수고스러움이 있지만, 일반적으로 Maven과 Gradle같은 운영을 지원해주는 빌드 툴을 사용하는 것을 추천합니다. (build tool that supports dependency management)

 

- Maven 설치하기

Spring Boot는 Apache Maven 3.5 이상 버전과 호환됩니다. 이미 Maven 설치 되어 있지 않다면, 다음 maven.apache.org 지시를 따라오세요.

On many operating systems, Maven can be installed with a package manager. If you use OSX Homebrew, try brew install maven. Ubuntu users can run sudo apt-get install maven. Windows users with Chocolatey can run choco install maven from an elevated (administrator) prompt.

Spring Boot 의존성은 org.springframework.boot 그룹 아이디를 사용합니다. 일반적으로, Maven POM 파일은 spring-boot-starter-parent를 상속합니다. 그리고 그 의존성들을 “Starters”라고 선언합니다. Spring Boot 또한 실행가능한 jar 파일을 생성하기 위해 선택적인 Maven plugin 를 제공합니다.

Maven과 Spring Boot를 시작하기 위한 추가적인 도움은 Getting Started section 의 Maven 플러그인 가이드에서 확인할 수 있습니다.  

 

 

- Gradle 설치하기

Spring Boot는 Gradle 7.x (7.5 or later) and 8.x 버전과 호환됩니다. Gradle 이미 설치되어 있지 않다면, 다음 gradle.org 에서 설치하세요.

Spring Boot 의존성은 org.springframework.boot 그룹을 사용합니다. 일반적으로,  의존성들은 “Starters” 로 선언됩니다. Spring Boot 실행 가능한 jar 파일을 생성하기 위해, 단순화된 의존성을 사용할 수 있는, 효과적인 Gradle plugin을 제공합니다.

 

- Gradle Wrapper

프로젝트를 빌드하고자 할 때, Gradle Wrapper은 멋진 “통용되는” Gradle 방식을 제공합니다. Gradle Wrapper는 빌드 프로세스를 부트스트랩하기 위해 코드와 같이 커밋하는 작은 스크립트 및 라이브러리입니다.  docs.gradle.org/current/userguide/gradle_wrapper.html 를 참고하면 자세한 내용을 알 수 있습니다.

Gradle과 Spring Boot를 시작하기 위한 추가적인 도움은 Getting Started section의 Gradle 플러그인 가이드에서 확인할 수 있습니다.

 

4.3.2. Spring Boot CLI 설치하기

Spring Boot CLI (Command Line Interface) 는 빠르게 Spring 프로토타입을 사용해 볼 수 있는 명령어 툴입니다. 

Spring Boot를 작동하기 위해 CLI가 필수적이지 않지만, IDE 없이 가장 빠르게 Spring applicaion을 얻을 수 있는 방법입니다. 

 

- 설치 매뉴얼

다음 제공되는 파일 중 하나를 선택해 Spring CLI를 다운로드 받을 수 있습니다:

• spring-boot-cli-3.0.4-bin.zip
• spring-boot-cli-3.0.4-bin.tar.gz

다운받을 때, INSTALL.txt의 upacked archive 지시를 따르세요. 요약하면, .zip 파일의 bin/directory에 Spring 스크립트(spring.bat for Windows)가 포함되어 있습니다. 대안으로, .jar 파일을 java -jar 명령어를 사용할 수 있습니다. (스크립트가 클래스패스가 정확히 설정되어 있음을 보장합니다.)

 

- SDKMAN! 이용하여 설치하기

SDKMAN! (The Software Development Kit Manager)는 Groovy와 Spring Boot CLI를 포함해 다양한 SDK를 멀티 운용 가능하게 해줍니다. sdkman.io에서 SDKMAN! 를 다운받으세요. 그리고 다음 명령어를 사용해 Spring Boot 설치하세요:

$ sdk install springboot
$ spring --version
Spring CLI v3.0.4

 

CLI를 이용해 개발하고 싶다면 그리고 빌드한 버전에 접근하고 싶다면, 다음 명령어를 사용하세요:

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-3.0.4-bin/spring-3.0.4/
$ sdk default springboot dev
$ spring --version
Spring CLI v3.0.4

 

앞의 지시는 개발용 인스턴스라 불리는 로컬 Spring 인스턴스를 설치하게 됩니다. 빌드할 타겟 위치를 표시하기 때문에 항상 Spring Boot를 재빌드할 때마다 Spring이 최신 상태를 유지합니다.

다음 명령어를 입력하면 확인할 수 있습니다:

$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 3.0.4

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

 

 

- OSX Homebrew 설치하기

당신이  Homebrew를 사용하는 Mac 사용자라면, 다음 명령어를 이용해 Spring Boot CLI를 설치할 수 있습니다.:

$ brew tap spring-io/tap
$ brew install spring-boot

 

Homebrew는 Spring을 /usr/local/bin경로에 설치합니다..

 

- MacPorts 설치하기

당신이 MacPorts를 사용하는 Mac 사용자라면, 다음 명령어를 이용해 Spring Boot CLI를 설치할 수 있습니다.:

$ sudo port install spring-boot-cli

 

 

 

- Command-line 완성

Spring Boot CLI 은  BASH와 zsh shells 명령어 완성을 위한 스크립트를 포함합니다. spring이란 이름을 가진 스크립트를 아무 shell에서 확인하거나, 개인적이건 system-wide bash 완성 초기화에 사용할 수 있습니다.(?? 원문 : You can source the script (also named spring) in any shell or put it in your personal or system-wide bash completion initialization.)

Debian 시스템에서는, system-wide 스크립트는<installation location>/shell-completion/bash 하위에 존재합니다. 그리고 모든 스크립트는 새로운 shell이 시작될 때 디렉토리에서 실행됩니다. 예를 들어,  SDKMAN!를 이용해 설치하여 매뉴얼적으로 스크립트를 실행하고자 한다면, 다음 명령어를 사용하세요:

$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
  grab  help  jar  run  test  version

 

Homebrew MacPorts를 이용해 Spring Boot CLI 설치했다면 명령어 완성 스크립트는 자동적으로 shell에 등록됩니다.

 

- Windows Scoop 이용해 설치하기

Scoop 을 이용한 Windows 사용자라면, 다음 명령어를 사용해 Spring Boot CLI를 설치할 수 있습니다.:

> scoop bucket add extras
> scoop install springboot

Scoop은  ~/scoop/apps/springboot/current/bin 하위에 Spring을 설치합니다..

만약 app manifest를 보고 싶지않다면, scoop을 사용한 설치는 구식일 것입니다.이런 경우엔 scoop을 업데이트 후 재실행 해보세요.

 

4.4. 첫 번째  Spring Boot Application 개발하기

이번 섹션에서는 Spring Boot의 핵심 기능을 사용해서 "Hello World!"를 찍는 웹 애플리케이션 개발 방법을 알아봅니다. IDE가 대부분 지원하기 때문에 Maven을 이용해 프로젝트를 빌드할 것입니다.

 

시작하기 전, 터미널을 열어 Java와 Maven 버전이 유효한지 확인하기 위해 다음 명령어를 입력하세요:

$ java -version
openjdk version "17.0.4.1" 2022-08-12 LTS
OpenJDK Runtime Environment (build 17.0.4.1+1-LTS)
OpenJDK 64-Bit Server VM (build 17.0.4.1+1-LTS, mixed mode, sharing)

 

$ mvn -v
Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
Maven home: usr/Users/developer/tools/maven/3.8.5
Java version: 17.0.4.1, vendor: BellSoft, runtime: /Users/developer/sdkman/candidates/java/17.0.4.1-librca

 

 

 

4.4.1. POM 파일 생성하기

우리는 Maven pom.xml 생성해야만 합니다. pom.xml는 프로젝트를 빌드하는 데 사용하는 레시피와 같습니다. 가장 좋아하는 편집기를 열어 다음과 같이 추가하세요:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>myproject</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.4</version>
    </parent>

    <!-- Additional lines to be added here... -->

</project>

 

위의 목록은 작업이 빌드를 제공할 것입니다. mvn 패키지를 실행시켜 테스트할 수 있습니다. (지금은  “jar will be empty - no content was marked for inclusion!” 경고를 무시해도 됩니다.)

여기서, IDE에 프로젝트를 import 해도 괜찮습니다. (대부분의 Java IDE들은 Maven을 지원합니다.) 예제에서 간단히 순수-텍스트 편집기를 사용합니다.

 

4.4.2. Classpath 의존성 추가하기

Spring Boot는 많은 "Starter" 의존성을 제공합니다. (앞서 jar 파일로 프로젝트 하위에 추가했습니다.) 

provides a number of “Starters” that let you add jars to your classpath. Our applications 연기 테스트?(smoke tests)를 위해 예제 application은 POM의 parent 섹션 안에 spring-boot-starter-parent를 사용합니다. spring-boot-starter-parent는 유용한 Maven를 제공하는 특별한 의존성입니다. 또한 dependency-management 섹션을 제공하여 "축복받은" 의존성의 버전 태그를 생략할 수 있습니다.  (버전 자동 설정 기능)

다른 "Starters"는 개발할 때 좋아할만한 의존성을 제공합니다. 예제에서는 웹 application을 개발하기 때문에, spring-boot-starter-web을 추가합니다.

추가하기 전에 다음 명령어를 실행해 현재 어떤 의존성들이 있는지 확인할 수 있습니다:

$ mvn dependency:tree

[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT

 

위 명령어는 프로젝트의 의존성을 tree 형태로 출력합니다. spring-boot-starter-parent는 어떠한 의존성을 제공하지 않습니다. 필요한 의존성을 추가하기 위해 pom.xml에 spring-boot-starter-web 의존성을 아래처럼 추가합시다.

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

 

다시 [mvn dependency:tree] 명령어를 다시 실행해보면, 이제 Tomcat 웹 서버와 Spring Boot를 포함해 추가한 의존성을 확인할 수 있습니다.

 

4.4.3. 코드 작성하기

application을 만들기 위해 Java 파일을 생성해야 합니다. 기본적으로 Maven은 src/main/java 하위에 소스를 컴파일합니다. 따라서 src/main/java 디렉토리를 생성하고 하위에 MyApplication.java 파일을 추가하세요. 코드는 다음과 같습니다:

@RestController
@SpringBootApplication
public class MyApplication {

    @RequestMapping("/")
    String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}

 

많은 코드가 있진 않지만 많아질 것입니다. 다음의 섹션이 중요합니다.

 

- @RestController and @RequestMapping Annotations

@RestController는 잘 알려진 애너테이션입니다. Spring 코드를 읽을 때 힌트를 제공하고 애너테이션이 붙은 class는 특정한 역할을 수행합니다. 예제의 class는 웹 컨트롤러이므로 Spring은 웹 요청을 처리할 때 이 class를 고려합니다.

@RequestMapping 애너테이션은 "라우팅" 정보를 제공하는 애너테이션입니다. "/" 경로로 HTTP 요청은 해당 메서드로 매핑되어야 한다고 Spring에 알리는 용도입니다. @RestController 애너테이션은 결과를 즉시 string 으로 렌더링해 반환합니다. 

@RestController와 @RequestMapping은 Spring MVC 애너테이션입니다. (Spring Boot만의 기능이 아닙니다.) Spring 공식문서의 MVC section 에서 더 자세한 내용을 알 수 있습니다.

 

- @SpringBootApplication Annotation

두 번째 class-level 애너테이션은 @SpringBootApplication은 메타 애너테이션으로 @SpringBootConfiguration와 @EnableAutoConfiguration, @ComponentScan을 결합한 애너테이션입니다.

세 애너테이션 중 @EnableAutoConfiguration에 집중해 봅시다. @EnableAutoConfiguration은 Spring Boot에게 추가된 의존성을 기반으로 Spring을 어떻게 설정하고 싶은지 "추측"하게 해줍니다. spring-boot-starter-web이 Tomcat과 Spring MVC를 추가했기 때문에 auto-configuration은 웹 application을 개발하는구나 가정하고 그에 맞게 Spring을 설정합니다.

 

- Starters와 Auto-configuration

Auto-configuration은 "Starters"가 잘 작동하도록 설정됐습니다. 하지만 두 개가 직접적으로 묶인 개념은 아닙니다. 당신은 의존성을 starters에서 제외할 수 있고 Spring Boot는 자동 설정하기 위해 최선을 다합니다. 

 

- “main” 메서드

마지막으로 main 메서드는 Java 컨벤션에 따른 application의 entry point가 되는 기본 메서드입니다. Our main method delegates to Spring Boot’s SpringApplication class by calling run. SpringApplication은 application을 작동시키고, Tomcat 웹 서버로 자동 설정을 해 Spring을 시작합니다. Spring의 기본 구성 요소인 SpringApplication이 메서드를 실행하기 위해 MyApplication class에 인자를 넘겨줘야 합니다. 물론 외부 명령어 인자로도 인자 배열을 넘겨줄 수 있습니다.

 

4.4.4. 예제 실행하기

여기서, 예제 application이 작동해야 합니다. spring-boot-starter-parent POM을 사용했기 때문에 application을 효과적으로 실행할 수 있습니다. 프로젝트 디렉토리 루트에서 명령어 [mvn spring-boot:run]를 입력해 application을 실행하면 다음과 비슷하게 출력될 것입니다:

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.0.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

 

 

웹 브라우저에서 localhost:8080을 접속하면 다음과 같이 출력될 것입니다:

Hello World!

우아하게 종료하려면 ctrl+c를 누르세요!

 

4.4.5. Jar 실행 파일 생성하기

production으로 실행할 수 있는 self-contained jar Executable jar file("fat jars"라고 불리기도 함, 이하 jar 파일)을 생성함으로써 예제를 마칠 수 있게 됐습니다. jar 파일은 추가한 의존성과 컴파일한 class를 포함한 아카이브(? 저장소?)입니다.

 

- Executable jars와 Java

Java는 중첩된 jar 파일을 실행할 방법을 제공하지 않습니다. 당신이 self-contained applicaion을 배포하고자 한다면 어려움을 겪을 것입니다.

문제를 해결하고자, 수많은 개발자들이 "uber" jars 를 이용합니다. 우버 jar란, application의 모든 의존성과 class들을 하나의 아카이브에 포장하는 것입니다. 하지만 application의 라이브러리를 보기 힘들게 하고, 중복되는 이름의 파일이 만들어질 수 있는  문제점이 있습니다.

Spring Boot는 different approach을 차용했고 당신이 직접 jar를 만들 수 있게 해줍니다.

 

jar 실행 파일을 생성하기 위해 spring-boot-maven-plugin를 pom.xml에 추가해야 합니다. <dependencies> 태그 아래에 다음과 같이 추가하세요:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

 

pom.xml을 저장하고 다음 명령어로 mvn 패키지를 실행하세요:

$ mvn package

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:3.0.4:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

 

target 디렉토리 아래에 보이면 myproject-0.0.1-SNAPSHOT.jar가 생성된 것을 확인할 수 있습니다. 이 파일은 약 10MB 사이즈로 안의 내용을 확인하고 싶으면 [jar tvf ~] 명령어를 입력하세요.:

$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar

 

또한 더 작은 사이즈의 myproject-0.0.1-SNAPSHOT.jar.original이 target 디렉토리에 생성된 것을 확인할 수 있습니다. 이것은 Maven이 jar 파일을 생성하기 전 Spring Boot가 생성한 원본 jar 파일입니다.

application을 실행하기 위해 [java -jar ~] 명령어를 입력하세요:

$ java -jar target/myproject-0.0.1-SNAPSHOT.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.0.4)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.536 seconds (process running for 2.864)

 

ctrl + c 를 누르면 application이 종료됩니다.

 

4.5. 다음 내용

희망적이게도, 해당 섹션은 Spring Boot 기초를 제공했고 당신이 개인만의 application을 개발할 수 있게 만들었습니다. 당신이 task-oriented 타입의 개발자라면, spring.io로 넘어가서, "Spring 가지고 내가 어떻게 해야 하는데?" 질문의 해답을 얻을 수 있는 getting started 가이드를 따르고 싶어할 수도 있습니다. 우리는 또한 Spring Boot  “How-to” 공식 문서를 제공합니다.

하지만 다음 논리적인 절차는 Developing with Spring Boot입니다. 당신이 정말 참을성이 없다면 Spring Boot features로 건너뛰어도 괜찮습니다.