FORTIS FORTUNA ADIUVAT

1. SiteMesh란?

SiteMesh는 Java 기반 웹 애플리케이션에서 공통 레이아웃을 적용하기 위한 필터 기반 데코레이터

프레임워크.

2. 데코레이터 패턴이란?

기존 객체의 기능을 변경하지 않고, 동적으로 기능을 추가하거나 확장할 수 있게 하는 패턴

3. SiteMesh의 주요 개념

4. SiteMesh의 동작 방식

- 동작방식

   요청: /board/list.jsp

1. 사용자는 /board/list.jsp를 요청함
2. SiteMesh Filter가 요청을 가로채서 내부적으로 렌더링 시작
3. list.jsp의 내용(본문)을 먼저 생성함
   → 여기서 title, head, body 부분을 추출
4. layout.jsp(데코레이터)에 그 내용들을 끼워 넣음:
   • <sitemesh:write property="title"/> → list.jsp의 <title>로 채움
   • <sitemesh:write property="body"/> → list.jsp의 본문 내용으로 채움
5. 완성된 페이지를 사용자에게 전달

- Spring MVC의 ViewResolver와는 별개로 동작함

- 설정 파일 (decorators.xml) 또는 Java Config를 통해 URL 패턴 매핑 가능

5. SiteMesh의 장점

6. SiteMesh 3.x vs 2.x 설정 방식 비교

- 2.x는 전통적인 XML 설정 기반

- 3.x는 Java 기반 설정과 더 유연한 확장성 지원

SiteMesh 2.x 예제 (XML 설정 기반)

decorators.xml

<decorators defaultdir="/WEB-INF/decorators">
    <decorator name="default" page="layout.jsp">
        <pattern>/*</pattern>
    </decorator>
</decorators>

web.xml

<filter>
    <filter-name>sitemesh</filter-name>
    <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>sitemesh</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

SiteMesh 3.x 예제 (Java 설정 기반)

SiteMeshConfig.java

import org.sitemesh.builder.SiteMeshFilterBuilder;
import org.sitemesh.config.ConfigurableSiteMeshFilter;
import org.sitemesh.builder.SiteMeshFilterBuilder;
import org.sitemesh.webapp.WebAppContext;

import javax.servlet.annotation.WebFilter;
import javax.servlet.FilterConfig;

@WebFilter("/*")
public class SiteMeshConfig extends ConfigurableSiteMeshFilter {
    @Override
    protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
        builder
            .setMimeTypes("text/html")  // 필터링할 MIME 타입
            .addDecoratorPath("/*", "/WEB-INF/decorators/layout.jsp") // 데코레이터 지정
            .addExcludedPath("/static/*"); // 제외할 경로
    }
}

7. 정리

SiteMesh는 웹 페이지에 일관된 레이아웃을 자동으로 적용해 유지보수를 쉽게 만드는 필터 기반 템플릿 프레임워크다.

** SiteMesh 적용 프로젝트 | https://github.com/LuckyStrike1989/my-spring-framewrok-project

REST API Level3을 위한 HATEOAS 설정

Hateoas란?

HATEOAS(Hypermedia As The Engine of Application State)는 웹 API를 실제로 "RESTful"로 만드는 REST 애플리케이션 아키텍처의 제약 조건입니다. 기본적으로 요청에 대해 서버는 데이터만 클라이언트에 보냅니다. HATEOAS를 사용하면 응답에 데이터뿐만 아니라 해당 데이터와 관련된 가능한 작업도 링크 형식으로 포함됩니다.

Leonard Richardson이 제시한 REST 성숙도 모델

- 레벨 0

API 구현은 HTTP 프로토콜을 사용하지만 전체 기능을 활용하지는 않습니다. 또한 리소스에 대한 고유 주소가 제공되지 않습니다.

method : POST / URI : /movie

- 레벨 1

리소스에 대한 고유 식별자가 있지만 리소스에 대한 각 작업자에는 고유한 URL이 있습니다

method : POST / URI : /movie/1/delete

- 레벨 2

동작을 설명하는 동사 대신 HTTP 메소드를 사용합니다. 예를 들어 레벨 1처럼 URI에 delete를 표기하여 작업자를 나타내지않고, 대신 delete 메소드를 사용합니다.

method : DELETE / URI : /movie/1

- 레벨 3

HATEOAS라는 용어가 도입됨. 간단히 리소스에 하이퍼미디어를 도입합니다. 이를 통해 가능한 작업에 대해 알려주는 응답에 링크를 배치할 수 있으므로 API를 통해 탐색할 수 있는 가능성이 추가됩니다.

method : DELETE / URI : /movie/1

Level2에서는 단순히 데이터 영역만을 표기하여 응답해줍니다. Level3의 Hypermedia Controls 부터는 데이터 영역 뿐만 아니라 링크 영역을 통해 자원에 호출 가능한 API 정보를 반영하여 표현합니다. 링크영역에서 반영 되는 개념이 바로 HATEOAS 입니다. 

{
    ----- 데이터 영역 -----
    "id": 1,
    "name": "Kenneth",
    "joinDate": "2024-08-17T12:58:26.575+00:00",
    ----- 데이터 영역 -----
    
    ----- 링크 영역 -----
    "_links": {
        "self": {
            "href": "http://localhost:8088/users/1"
        },
        "all-users": {
            "href": "http://localhost:8088/users"
        }
    }
    ----- 링크 영역 -----
}

HATEOAS 프로젝트 설정 및 구현

▶ pom.xml (build.gradle)

## Maven
<dependency>  
    <groupId>org.springframework.boot</groupId>  
    <artifactId>spring-boot-starter-hateoas</artifactId>  
</dependency>

## Gradle
implementation 'org.springframework.boot:spring-boot-starter-hateoas'

먼저 프로젝트에 Hateoas를 추가해 줍니다.

▶ UserController.java

@GetMapping("/users/{id}")
    public ResponseEntity<EntityModel<User>> retrieveUser(
           @Parameter(description = "사용자 ID", required = true, example = "1") @PathVariable int id
    ) {
        User user = userDaoService.findOne(id);
		
        // 사용자가 없을 경우, 예외를 발생시킨다.
        if( user == null ) {
            throw new UserNotFoundException(String.format("ID[%s] not found", id));
        }

        // 단일로 link를 만들때
        // EntityModel entityModel = EntityModel.of(user);
        // WebMvcLinkBuilder linTo = linkTo(methodOn(this.getClass()).retrieveAllUsers());
        // entityModel.add(linTo.withRel("all-users"));    // http://localhost:8080/users -> all-users

		// 다수로 link를 만들때
        return ResponseEntity.ok().body(
                EntityModel.of(user)
                        .add(linkTo(methodOn(this.getClass()).retrieveUser(id)).withSelfRel()) // http://localhost:8080/users/1 -> self
                        .add(linkTo(methodOn(this.getClass()).retrieveAllUsers()).withRel("all-users")) // http://localhost:8080/users -> all-users
        );
    }

EntityModel<T> 클래스를 이용하고, Static Method로 객체를 만들기 때문에 EntityModel.of()를 통해서 객체르 생성합니다.

add()메소드를 통해서 link를 추가할 수 있습니다. linkTo(methodOn(Controller.class).method(argument)) 이런 형식으로 추가하면 API의 URI가 매핑됩니다.

link에 대한 이름은 withSelfRel()과 withRel()이 있습니다.

withSelfRel() 메소드는 self로 지정되는데 호출되는 자기 자신에 대한 정보를 표현합니다.

withRel()는 withRel("명칭") 형태로 사용하며 매개변수로 지정된 값이 이름으로 표현됩니다.

▶ 실행결과

{
    "id": 1,
    "name": "Kenneth",
    "joinDate": "2024-08-20T14:37:49.307+00:00",
    "_links": {
        "self": {
            "href": "http://localhost:8088/users/1"
        },
        "all-users": {
            "href": "http://localhost:8088/users"
        }
    }
}

Hateoas를 적용하여 실행한 결과 입니다. 다음과 같이 _links에 호출 가능한  API 정보를 반영 되었습니다. 

이번 포스팅은 간단하게 Hateoas 적용 방법을 정리해 봤습니다.

해당 Full Source는 아래 Git 주소를 통해서 확인 가능합니다. 여기까지 지루한 글 읽어주셔서 감사합니다!

https://github.com/LuckyStrike1989/restful-web-service

 Validation이란?

어떤 데이터의 값이 유효한지, 잘못된 내용이 있는지 확인하는 단계를 뜻합니다. 예를들어 휴대폰 번호의 포멧은 "010-1234-1234"이여야 하는데, 포멧과 맞지않는 값이 들어온다면 해당 값의 저장을 막을 수 있습니다.

(휴대 폰 번호 막고도 최소길이, 최대길이, 이전날짜, 이후날짜 등 다양하게 유효성 체크를 할 수 있습니다)

Validation  API 사용

의존성 추가

Validation API를 사용하기 위해서는 먼저 아래와 같이 라이브러리를 추가 해주어야 합니다.

## maven
<dependency>  
    <groupId>org.springframework.boot</groupId>  
    <artifactId>spring-boot-starter-validation</artifactId>  
    <version>3.0.2</version>  
</dependency>

## gradle
implementation 'org.springframework.boot:spring-boot-starter-validation'

VO(DTO)에서 어노테이션을 통해 체크하고 @Valid 어노테이션을 통해 간단히 유효성 체크를 할 수 있습니다.

유효성 체크 예제 소스

VO(DTO)에 어노테이션을 통해 유효성 체크 할 부분을 명시해 줍니다.

@Data  
@AllArgsConstructor  
public class User {
    private Integer id;  
  
    @NotBlank(message="이름을 입력해주세요.")
    @Size(min = 2, message = "Name은 2글자 이상 입력해 주세요.")  
    private String name;  
  
    @Min(0, "나이는 0보다 커야 합니다.")
    private int age;
    
    @Email("이메일 형식이 잘못되었습니다.")
    private int email;
  
    @Past(message = "등록일은 미래 날짜를 입력하실 수 없습니다.")  
    private Date joinDate;
}

Controller에서 유효성이 필요한 부분에서 주로 @RequestBody 앞에 @Valid 어노테이션 입력해 줍니다.

@PostMapping("/users")
public ResponseEntity<User> createUser(@Valid @RequestBody User user) {
	User savedUser = userDaoService.save(user);

	URI location = ServletUriComponentsBuilder.fromCurrentRequest()
               		.path("/{id}")
                	.buildAndExpand(savedUser.getId())
                	.toUri();

    // 반환 값을 201 Created 준다. 인자로 location을 넘겨주면, 헤더에 Location이 추가된다.
    return ResponseEntity.created(location).build();
}

VO(DTO)에서 명시해 놓은 값에서 문제가 발생 했을 경우 예외처리를 통해 결과 값을 받아 보실 수 있습니다.

@ControllerAdvice 어노테이션을 통해 Controller에서 발생한 예외처리를 진행합니다.

@ControllerAdvice를 간단히 설명하면 Controller에서 @RequestMapping가 달린 메서드 실행 중 발생한 예외를 가로채는 exceptions interceptor라고 생각 하시면 됩니다.

또한 ResponseEntity에서 발생된 예외상황을 처리하기위해 ResponseEntityExceptionHandler 상속 받고

예외 응답 객체를 만들어 ResponseEntity에 담아 처리해주면 조금 더 상세하게 유효성 체크를 할 수 있습니다.

@ControllerAdvice
public class CustomizedResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
        ExceptionResponse exceptionResponse = new ExceptionResponse(new Date(), "Validation failed", ex.getBindingResult().toString());
        return new ResponseEntity(exceptionResponse, HttpStatus.BAD_REQUEST);
    }
    
}

이번 포스팅에는 SpringBoot에서 유효성 체크 하는 방법을 정리 해보았는데요

해당 Full Source는 아래 Git주소를 통해서 확인 부탁드립니다!!

여기까지 지루한 글 읽어주셔서 감사합니다ㅎㅎ

https://github.com/LuckyStrike1989/restful-web-service