아키텍처 및 코드 구조

이 페이지에서는 Fess 의 아키텍처, 코드 구조, 주요 컴포넌트에 대해 설명합니다. Fess 의 내부 구조를 이해함으로써 효율적으로 개발을 진행할 수 있습니다.

전체 아키텍처

Fess 는 다음 주요 컴포넌트로 구성됩니다:

┌─────────────────────────────────────────────────┐
│          사용자 인터페이스                         │
│  ┌──────────────┐      ┌──────────────┐        │
│  │  검색 화면     │      │   관리 화면    │        │
│  │  (JSP/HTML)   │      │   (JSP/HTML)  │        │
│  └──────────────┘      └──────────────┘        │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│              웹 애플리케이션 계층                   │
│  ┌──────────────────────────────────────────┐  │
│  │           LastaFlute                       │  │
│  │  ┌────────┐  ┌─────────┐  ┌──────────┐  │  │
│  │  │ Action │  │  Form   │  │  Service │  │  │
│  │  └────────┘  └─────────┘  └──────────┘  │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│              비즈니스 로직 계층                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ Crawler  │  │  Job     │  │  Helper  │    │
│  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│              데이터 액세스 계층                      │
│  ┌──────────────────────────────────────────┐  │
│  │          DBFlute / OpenSearch             │  │
│  │  ┌────────┐  ┌─────────┐  ┌──────────┐  │  │
│  │  │Behavior│  │ Entity  │  │  Query   │  │  │
│  │  └────────┘  └─────────┘  └──────────┘  │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│               데이터 스토어                         │
│              OpenSearch 3.5.0                   │
└─────────────────────────────────────────────────┘

계층 설명

사용자 인터페이스 계층

사용자가 직접 조작하는 화면입니다. JSP와 HTML, JavaScript로 구현되어 있습니다.

• 검색 화면: 최종 사용자용 검색 인터페이스

• 관리 화면: 시스템 관리자용 설정·관리 인터페이스

웹 애플리케이션 계층

LastaFlute 프레임워크를 사용한 웹 애플리케이션 계층입니다.

• Action: HTTP 요청을 처리하고 비즈니스 로직 호출

• Form: 요청 파라미터 수신 및 검증

• Service: 비즈니스 로직 구현

비즈니스 로직 계층

Fess 의 주요 기능을 구현하는 계층입니다.

• Crawler: 웹사이트나 파일 시스템에서 데이터 수집

• Job: 스케줄 실행되는 작업

• Helper: 애플리케이션 전체에서 사용되는 헬퍼 클래스

데이터 액세스 계층

DBFlute를 사용한 OpenSearch 액세스 계층입니다.

• Behavior: 데이터 조작 인터페이스

• Entity: 데이터 실체

• Query: 검색 쿼리 구축

데이터 스토어 계층

검색 엔진으로 OpenSearch 3.5.0을 사용합니다.

프로젝트 구조

디렉터리 구조

fess/
├── src/
│   ├── main/
│   │   ├── java/org/codelibs/fess/
│   │   │   ├── app/              # 웹 애플리케이션
│   │   │   │   ├── web/          # 검색 화면
│   │   │   │   │   ├── admin/    # 관리 화면
│   │   │   │   │   │   ├── ...Action.java
│   │   │   │   │   │   └── ...Form.java
│   │   │   │   │   └── ...Action.java
│   │   │   │   └── service/      # 서비스 계층
│   │   │   ├── crawler/          # Crawler
│   │   │   │   ├── helper/       # Crawler helper
│   │   │   │   ├── processor/    # Crawl processing
│   │   │   │   ├── service/      # Crawler service
│   │   │   │   └── transformer/  # Data transformation
│   │   │   ├── opensearch/       # OpenSearch related
│   │   │   │   ├── client/       # OpenSearch client
│   │   │   │   ├── config/       # Configuration management
│   │   │   │   ├── log/          # Log management
│   │   │   │   ├── query/        # Query builder
│   │   │   │   └── user/         # User management
│   │   │   ├── helper/           # 헬퍼 클래스
│   │   │   │   ├── ...Helper.java
│   │   │   ├── job/              # 작업
│   │   │   │   ├── ...Job.java
│   │   │   ├── util/             # 유틸리티
│   │   │   ├── entity/           # 엔티티(자동 생성)
│   │   │   ├── mylasta/          # LastaFlute 설정
│   │   │   │   ├── action/       # Action 기본 클래스
│   │   │   │   ├── direction/    # 애플리케이션 설정
│   │   │   │   └── mail/         # 메일 설정
│   │   │   ├── Constants.java    # 상수 정의
│   │   │   └── FessBoot.java     # 시작 클래스
│   │   ├── resources/
│   │   │   ├── fess_config.properties  # 설정 파일
│   │   │   ├── fess_config.xml         # LastaDi component configuration
│   │   │   ├── fess_message_ja.properties  # 메시지(일본어)
│   │   │   ├── fess_message_en.properties  # 메시지(영어)
│   │   │   └── ...
│   │   └── webapp/
│   │       ├── WEB-INF/
│   │       │   ├── view/          # JSP 파일
│   │       │   │   ├── admin/     # 관리 화면 JSP
│   │       │   │   └── ...
│   │       │   └── web.xml
│   │       ├── css/               # CSS 파일
│   │       ├── js/                # JavaScript 파일
│   │       └── images/            # 이미지 파일
│   └── test/
│       └── java/org/codelibs/fess/
│           ├── ...Test.java       # 테스트 클래스
│           └── it/                # 통합 테스트
├── pom.xml                        # Maven 설정
├── dbflute_fess/                  # DBFlute 설정
│   ├── dfprop/                    # DBFlute 속성
│   └── freegen/                   # FreeGen 설정
└── README.md

주요 패키지 상세

app 패키지

웹 애플리케이션 계층의 코드입니다.

app.web 패키지

검색 화면과 최종 사용자용 기능을 구현합니다.

주요 클래스:

• SearchAction.java: 검색 처리

• LoginAction.java: 로그인 처리

예:

@Execute
public HtmlResponse index(SearchForm form) {
    // 검색 처리 구현
    return asHtml(path_IndexJsp);
}

app.web.admin 패키지

관리 화면의 기능을 구현합니다.

주요 클래스:

• AdminWebconfigAction.java: 웹 크롤 설정

• AdminSchedulerAction.java: 스케줄러 관리

• AdminUserAction.java: 사용자 관리

명명 규칙:

• Admin 접두사: Admin용 Action

• Action 접미사: Action 클래스

• Form 접미사: Form 클래스

app.service 패키지

비즈니스 로직을 구현하는 서비스 계층입니다.

주요 클래스:

• SearchLogService.java: 검색 서비스

• UserService.java: 사용자 관리 서비스

• ScheduledJobService.java: 작업 관리 서비스

예:

public class ScheduledJobService {
    @Resource
    private ScheduledJobBhv scheduledJobBhv;

    // Job CRUD operations implementation
}

crawler 패키지

데이터 수집 기능을 구현합니다.

crawler 패키지 (fess-crawler 라이브러리)

주요 클래스:

• CrawlerClient.java: 크롤러 클라이언트 인터페이스

• HcHttpClient.java: HTTP 클라이언트

• FileSystemClient.java: 파일 시스템 클라이언트

• ExtractorFactory.java: 추출기 팩토리

• TikaExtractor.java: Apache Tika를 사용한 추출

• Transformer.java: 변환 인터페이스

crawler 패키지 (fess main)

주요 클래스:

• FessStandardTransformer.java: Fess 표준 트랜스포머

• FessXpathTransformer.java: Fess XPath 트랜스포머

opensearch 패키지

OpenSearch와의 연동을 구현합니다.

opensearch.client 패키지

OpenSearch 클라이언트 구현입니다.

주요 클래스:

• SearchEngineClient.java: OpenSearch 클라이언트

opensearch.query 패키지

검색 쿼리 구축을 구현합니다.

주요 클래스:

• QueryCommand.java: 쿼리 명령

• QueryProcessor.java: 쿼리 처리

helper 패키지

애플리케이션 전체에서 사용되는 헬퍼 클래스입니다.

주요 클래스:

• SystemHelper.java: 시스템 전체 헬퍼

• CrawlingConfigHelper.java: 크롤 설정 헬퍼

• SearchLogHelper.java: 검색 로그 헬퍼

• UserInfoHelper.java: 사용자 정보 헬퍼

• ViewHelper.java: 뷰 관련 헬퍼

• QueryHelper.java: 쿼리 구축 헬퍼

예:

public class SystemHelper {
    @PostConstruct
    public void init() {
        // 시스템 초기화 처리
    }
}

job 패키지

스케줄 실행되는 작업을 구현합니다.

주요 클래스:

• CrawlJob.java: 크롤 작업

• SuggestJob.java: 제안 작업

• ScriptExecutorJob.java: 스크립트 실행 작업

예:

public class CrawlJob extends ExecJob {
    @Override
    public void execute() {
        // 크롤 처리 구현
    }
}

entity 패키지

OpenSearch 문서에 대응하는 엔티티 클래스입니다. 이 패키지는 DBFlute로 자동 생성됩니다.

주요 클래스:

• SearchLog.java: 검색 로그

• ClickLog.java: 클릭 로그

• FavoriteLog.java: 즐겨찾기 로그

• User.java: 사용자 정보

• Role.java: 역할 정보

참고

entity 패키지의 코드는 자동 생성되므로 직접 편집하지 마세요. 스키마를 변경하여 재생성하는 것으로 업데이트합니다.

mylasta 패키지

LastaFlute의 설정과 커스터마이즈를 수행합니다.

mylasta.action 패키지

Action의 기본 클래스를 정의합니다.

• FessUserBean.java: 사용자 정보

• FessHtmlPath.java: HTML 경로 정의

mylasta.direction 패키지

애플리케이션 전체 설정을 수행합니다.

• FessConfig.java: 설정 읽기

• FessFwAssistantDirector.java: 프레임워크 설정

디자인 패턴 및 구현 패턴

Fess 에서는 다음과 같은 디자인 패턴이 사용됩니다.

MVC 패턴

LastaFlute에 의한 MVC 패턴으로 구현되어 있습니다.

• Model: Service, Entity

• View: JSP

• Controller: Action

예:

// Controller (Action)
public class SearchAction extends FessSearchAction {
    @Resource
    private SearchHelper searchHelper;  // Model (Service)

    @Execute
    public HtmlResponse index(SearchForm form) {
        return search(form);
    }
}

DI 패턴

LastaFlute의 DI 컨테이너를 사용합니다.

public class SearchService {
    @Resource
    private SearchEngineClient searchEngineClient;

    @Resource
    private UserInfoHelper userInfoHelper;
}

Factory 패턴

각종 컴포넌트 생성에 사용됩니다.

public class ExtractorFactory {
    public Extractor getExtractor(String key) {
        // MIME 타입에 따른 Extractor 생성
    }
}

Strategy 패턴

크롤러와 트랜스포머에서 사용됩니다.

public interface Transformer {
    ResultData transform(ResponseData responseData);
}

public class HtmlTransformer implements Transformer {
    // HTML용 변환 처리
}

설정 관리

Fess 의 설정은 여러 파일로 관리됩니다.

fess_config.properties

애플리케이션의 주요 설정을 정의합니다.

# OpenSearch 연결 설정
search_engine.http.url=http://localhost:9201

# 크롤 설정
crawler.document.max.site.length=100
crawler.document.cache.enabled=true

fess_config.xml

LastaDi component configuration file.

<component name="systemProperties" class="org.codelibs.core.misc.DynamicProperties">
    <arg>
        org.codelibs.fess.util.ResourceUtil.getConfPath("system.properties")
    </arg>
</component>

fess_message_*.properties

다국어 대응 메시지 파일입니다.

• fess_message_ja.properties: 일본어

• fess_message_en.properties: 영어

데이터 플로우

검색 플로우

1. 사용자가 검색 화면에서 검색
   ↓
2. SearchAction이 검색 요청 수신
   ↓
3. SearchService가 비즈니스 로직 실행
   ↓
4. SearchEngineClient가 OpenSearch에 검색 쿼리 전송
   ↓
5. OpenSearch가 검색 결과 반환
   ↓
6. SearchService가 결과 정형화
   ↓
7. SearchAction이 JSP에 결과 전달하여 표시

크롤링 플로우

1. CrawlJob이 스케줄 실행됨
   ↓
2. CrawlingConfigHelper가 크롤 설정 취득
   ↓
3. CrawlerClient가 대상 사이트에 접속
   ↓
4. Extractor가 콘텐츠에서 텍스트 추출
   ↓
5. Transformer가 데이터를 검색용 형식으로 변환
   ↓
6. SearchEngineClient가 OpenSearch에 문서 등록

확장 포인트

Fess 는 다음 포인트에서 확장할 수 있습니다.

커스텀 크롤러 추가

CrawlerClient 인터페이스를 구현하여 독자적인 데이터 소스에 대응할 수 있습니다.

커스텀 트랜스포머 추가

Transformer 를 구현하여 독자적인 데이터 변환 처리를 추가할 수 있습니다.

커스텀 추출기 추가

Extractor 를 구현하여 독자적인 콘텐츠 추출 처리를 추가할 수 있습니다.

커스텀 플러그인 추가

관리 UI의 플러그인 관리 기능을 통해 플러그인을 관리할 수 있습니다.

참고 자료

프레임워크

• LastaFlute 레퍼런스

• DBFlute 문서

기술 문서

• OpenSearch API 레퍼런스

• Apache Tika

다음 단계

아키텍처를 이해했다면 다음 문서를 참조하세요:

• 개발 워크플로우 - 실제 개발 플로우

• 빌드 및 테스트 - 빌드 및 테스트

• 기여 가이드 - 풀 리퀘스트 작성