📂 Spring static resources custom – uri로 파일 시스템에 접근하기

이 글에서는 Spring에서 원하는 폴더에 http://ip:port/resources/{file_name} 등의 uri로 접근할 수 있도록 설정하는 방법에 대해 다룹니다.
구현 방법은 🧭 환경 설정 부터 나와있습니다.

왜 정적 리소스 접근이 필요한가

저도 그럴 생각은 없었는데요......

현재 진행 중인 프로젝트에서는 FE, BE, AI가 하나의 워크스테이션에서 돌아가도록 해야한다는 요구사항이 있었다. 이러한 특성을 반영해 파일을 주고받을 때 resource path를 기준으로 하위 relative path를 주고 받도록 API를 설계했다. 그래서 파일을 직접적으로 전송하지 않고, 필요한 파일의 path만 전달해 사용한다.

왜 그렇게 설계한건데?

해당 프로젝트에서는 DICOM 파일을 주고받아야 한다. 처음에는 파일을 직접적으로 전송하는 방향으로 설계를 했었지만, DICOM 파일의 크기를 보고 설계를 수정하게 되었다. DICOM 파일은 개당 20~30MB의 큰 용량을 가지고 있다. 각 study의 세부 조회 등에서 약 20개 이상의 DICOM 파일을 전송해야했기에 직접 전송하는 방식이 오버헤드가 클 것이라 판단했다. 특히 DICOM 파일을 BE → FE로 해당 DICOM 파일이 있는 resource path만 전달해주면 프론트에서 필요할 때 파일을 로딩할 수 있어 효율적이었다. 결론적으로는 그게 효율적이라서 그렇게 설계하게 되었다는 얘기다.

Spring에서 정적 리소스 접근을 지원하는가

네? 기본적으로 지원해준다고요?

일반적으로 우리가 프로젝트를 생성하면 있는 {project root path}/src/main/resources/static 내부에 있는 파일에 기본적으로 접근 가능하다. 별도로 설정해주지 않아도 위의 경로에 있는 모든 정적 리소스들에 대해 http://ip:port/{static_resource_file}로 접근하면 된다.

프로젝트 내의 정적 리소스에 대한 url 설정

접근 경로(url)는 기본적으로 /**(root)부터 매핑된다. 이를 수정하고싶다면, application.yml에서 spring.mvc.static-path-pattern을 아래와 같이 설정해주면 된다.

spring:
	mvc:
    	static-path-pattern: {원하는 url 설정} (e.g. /static/**)

프로젝트 내의 정적 리소스 위치 설정

{project root path}/src/main/resources/ 내부의 원하는 디렉토리에 접근하도록 설정할 수도 있다. 이를 설정하기 위해서는 application.yml에서 spring.resources.static-locations를 설정해주면 된다. 기본 값은 /static/로 설정되어있다.

spring:
	resources:
    	static-locations: {원하는 경로 설정} (e.g. /images/)

저는 프로젝트 외부의 디렉토리에 접근하고싶은데........

기본적으로 지원하는 정적 리소스 접근은 원하는 리소스를 모두 위의 경로에 넣어줘야 하기 때문에 해당 프로젝트에서는 사용할 수 없는 방법이었다. 따라서 BE 서버 내부 저장 공간에 있는 resource 디렉토리를 원하는 url에 매핑해주기 위해 별도로 설정해주었다.

그거 누가 해주는건데

정적 리소스 접근을 커스텀하기 위해서는WebMvcConfigurer를 구현하는 클래스에서 addResourceHandlers를 override해주면 된다. ResourceHandler를 정의하면서 uri와 파일 시스템 내부의 경로를 설정해주면 url을 통해 접근이 가능하다.

🧭 환경 설정

environment

• Spring v3.3.1
• Gradle build

application.yml

resourcePath 디렉토리 하위의 모든 resource에 접근하기 위해서는 /로 끝나도록 아래와 같이 directory path를 설정해야 한다. 환경 변수명은 원하는대로 설정해줘도 된다. 여기서는 DICOM 파일들에 대한 resourcePath를 아래와 같이 설정해주었다.

dicom:
	resourcePath: /home/ubuntu/dicom/

🚀 How to use

MvcConfig.java

MvcConfig.java 클래스는 WebMvcConfigurer의 구현체이다.resource handler 설정 시 위에서 미리 정의해둔 환경 변수를 사용한다. 내 경우에는 http://ip:port/api/v1/resources/**로 접근하기 위해 아래와 같이 설정해주었다.

package example.global.config;

import java.io.File;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class MvcConfig implements WebMvcConfigurer {

    @Value("${dicom.resourcePath}")
    private String localStoragePath;

    /**
     * add resource handlers to serve static resources with http://ip:port/api/v1/resources/**
     *
     * @param registry resource handler registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler(File.separator + "api/v1/resources" + File.separator + "**")
            .addResourceLocations("file:" + localStoragePath);
    }
}

GET 요청을 통한 정적 리소스 접근

테스트 시 웹 브라우저에 http://ip:port/api/v1/resources/{resource file path}를 입력해 정상적으로 접근 가능한 것을 확인한다. 당연한 말이지만 위에서 설정한 url로 접근해야한다. 프론트에서 요청 시 동일한 url에 GET 요청을 전송해 접근 가능하다.

짜잔~ 사실 단점이 있답니다~

생각보다 큰 단점인데?

저렇게만 설정하면 모든 게 좋을 것 같지만...... 사실 큰 단점이 있다. 인증 및 인가 없이 uri로 정적 자원에 접근할 수 있게 만드는 것은 보안 측면에서 문제의 소지가 있다. 별로 큰 문제가 아닐 수 있다고 생각할 수 있지만, 경로만 안다면 개인정보 등이 담긴 파일에 접근하는 것도 가능하기 때문에 이를 방지하기 위해 아래의 조치를 미리 취해두는 것을 추천한다. 물론 식약처 등의 공공기관에서 요구하는 사이버보안 요구사항에는 포함되어 있지는 않다.

어떻게 보완하는가

필요한 자원이 포함된 최소 단위의 디렉토리 연결하기

원하는 자원이 포함된 디렉토리를 resourcePath로 설정해두면 하위 디렉토리 및 파일에 모든 접근이 가능하다. 따라서 불필요하게 상위 디렉토리가 resourcePath로 설정되어있다면 이를 필요한 자원만 모아둔 하위 디렉토리로 변경하는 것을 권장한다. 물론 그래도 접근 자체를 막지는 못한다.

정적 자원 접근 uri에 authenticated() 설정하기

Spring security를 활용해 인증을 구현하고 있다면, 설정해둔 정적 자원에 접근한 uri에 권한 설정을 부여할 수 있다. 내 경우에는 /api/v1/resources/**에 적어도 로그인해야 접근할 수 있도록 SecurityConfig.java에서 아래와 같이 설정해주었다.

package example.global.config;

// package 생략

/**
 * Security Configuration
 */
@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            ... // 나머지 설정은 생략
            .authorizeHttpRequests(
                (authorizeRequests) ->
                    authorizeRequests
						// 정적 자원에 접근하는 uri에 대해 권한 설정
                        .requestMatchers("/api/v1/resources/**").authenticated()
                        .anyRequest().permitAll()
            )
        return http.build();
    }
}

이전에 /resources/**에 대해서 authenticated()를 설정해 테스트 해본 적이 있었는데, 동작하지 않았다. 커스텀한 경우에만 설정되는 이유에 대해서는 더 공부가 필요할 것으로 생각된다.

---

Reference : Serve Static Resources with Spring | Baeldung