Unvus Docs

Appearance

Firo - 파일 업로드/관리 라이브러리 ​

Firo는 엔터프라이즈급 파일 관리 라이브러리로, 다양한 저장소 백엔드(Local, FTP, SFTP, S3, Azure Blob)를 지원합니다. JPA와 MyBatis 중 선택적으로 사용할 수 있는 모듈형 아키텍처를 제공하며, 체계적인 필터링 시스템과 보안 기능을 포함합니다.

프로젝트 구조 ​

firo/
├── firo-core/          # 핵심 로직, REST API, 인터페이스, 도메인 모델
├── firo-jpa/           # JPA 구현체 (Spring Data JPA + QueryDSL)
└── firo-mybatis/       # MyBatis 구현체

시작하기 ​

1. 의존성 추가 ​

JPA 사용 시 ​

gradle
dependencies {
    implementation 'com.unvus.firo:firo-core:1.3.1-SNAPSHOT'
    implementation 'com.unvus.firo:firo-jpa:1.3.1-SNAPSHOT'
}

MyBatis 사용 시 ​

gradle
dependencies {
    implementation 'com.unvus.firo:firo-core:1.3.1-SNAPSHOT'
    implementation 'com.unvus.firo:firo-mybatis:1.3.1-SNAPSHOT'
}

2. 설정 ​

application.properties ​

properties
# Firo 활성화 (기본값: true)
firo.enabled=true

# 데이터베이스 구현체 선택 (기본값: jpa)
firo.db.type=jpa  # jpa 또는 mybatis

# 기본 설정
firo.cdn-url=https://cdn.example.com/
firo.directory.base-dir=/var/uploads/
firo.directory.tmp-dir=/var/uploads/temp/
firo.directory.separator=/
firo.direct-upload-path=direct

application.yml ​

yaml
# Firo 기본 설정
firo:
  enabled: true
  db:
    type: jpa  # jpa 또는 mybatis
  cdn-url: https://cdn.example.com/
  directory:
    base-dir: ./uploads/
    tmp-dir: ./uploads/temp/
    separator: /
  direct-upload-path: direct
  api-prefix: /api/firo

# Spring Boot 파일 업로드 설정
spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB

버전 호환성 ​

Gradle ​

  • 권장 버전: 8.13+
  • 최소 버전: 8.0

Java ​

  • 필수 버전: Java 17+

Spring Boot ​

  • 지원 버전: 3.4.4
  • Spring Boot 3.x 자동 설정 방식 적용

지원 기능 ​

저장소 어댑터 ​

  • Local: 로컬 파일 시스템
  • FTP: FTP 서버
  • SFTP: SFTP 서버
  • S3: Amazon S3
  • Azure: Azure Blob Storage

이미지 필터 ​

  • 자동 회전 보정: EXIF 정보 기반 이미지 자동 회전
  • 크기 조정: 이미지 리사이징
  • 크기 제한: 최대 파일 크기 검증

데이터베이스 지원 ​

  • JPA: Spring Data JPA + QueryDSL + Hibernate (기본값)
  • MyBatis: MyBatis + 동적 쿼리 + Type Alias 충돌 방지
  • 조건부 로딩: firo.db.type 설정에 따라 선택적 활성화

API 사용 예시 ​

파일 업로드 ​

java
@Autowired
private FiroService firoService;

// 임시 파일 업로드
String uuid = firoService.uploadTemp(file, category, null, true);

// 직접 업로드
String path = firoService.uploadDirect(file, "domain", "category", null, LocalDateTime.now(), true);

파일 조회 ​

java
// ID로 조회
FiroFile file = firoService.getAttach(fileId);

// 참조 정보로 조회
List<? extends FiroFile> files = firoService.listAttachByRef("domain", 123L, "category");

// AttachBag으로 조회 (카테고리별 그룹핑)
AttachBag bag = firoService.getAttachBagByRef("domain", 123L, null);

REST API ​

bash
# 임시 파일 업로드
POST /api/firo/attach/tmp
Content-Type: multipart/form-data

# 직접 파일 업로드  
POST /api/firo/attach/direct
Content-Type: multipart/form-data

# AttachBag 저장
POST /api/firo/attach/{refDomain}/{refKey}

# AttachBag 조회
GET /api/firo/attach/{refDomain}/{refKey}

# 시스템 설정 조회
GET /api/firo/config

설정 가이드 ​

S3 어댑터 설정 ​

properties
firo.s3.access-key=YOUR_ACCESS_KEY
firo.s3.secret-key=YOUR_SECRET_KEY
firo.s3.bucket=your-bucket
firo.s3.region=us-west-2

Azure 어댑터 설정 ​

properties
firo.azure.connection-string=DefaultEndpointsProtocol=https;AccountName=...
firo.azure.container=files

FTP 어댑터 설정 ​

properties
firo.adapters.ftp.host=ftp.example.com
firo.adapters.ftp.port=21
firo.adapters.ftp.username=username
firo.adapters.ftp.password=password

호환성 및 안정성 ​

MyBatis 호환성 ​

Firo는 외부 프로젝트(예: iflex)와의 MyBatis Type Alias 충돌을 방지합니다:

  • Firo 전용 Type Alias: 모든 도메인 클래스에 Firo 접두사 사용
  • 격리된 설정: 독립적인 MyBatis 설정으로 외부 프로젝트와 분리
  • 호환성 보장: 기존 코드 변경 없이 안전한 통합 가능

조건부 Bean 로딩 ​

  • 데이터베이스: firo.db.type 설정에 따라 JPA 또는 MyBatis만 로드
  • 저장소 어댑터: 설정이 있는 어댑터만 활성화 (Azure, S3, FTP 등)
  • 메타데이터 안전성: 클래스 존재 여부 사전 확인으로 초기화 실패 방지

iflex 1.8.0 호환성 ​

  • 자동 호환성 설정: FiroCompatibilityConfiguration으로 seamless 통합
  • Bean 충돌 방지: 조건부 로딩으로 Repository 구현체 충돌 해결
  • 안정적 초기화: 설정 누락 시에도 기본값으로 정상 동작

자세한 내용은 관련 가이드 문서를 참고하세요.

문서 ​

시작 가이드 ​

상세 가이드 ​

통합 가이드 ​

문제 해결 ​