[LIBRARY] Java, Kotlin 기반 Spring 환경에서 사용 가능한 비속어 필터 라이브러리

🛠️ 개발 환경

• Kotlin: 2.2.20

📚 라이브러리 정보

Repository: github.com/Jwhyee/profanity-filter

이 라이브러리는 Java, Kotlin, Spring Boot 기반에서 모두 정상적으로 동작합니다. 이 포스팅에서는 Kotlin 기반으로 설명하지만, README.md에는 Java 코드도 추가되어 있습니다. Gradle(Kotlin, Groovy), Maven 각각의 설정 방법 또한 README.md에서 확인할 수 있습니다.

 

아직 부족한 점이 많지만, 커뮤니티의 피드백을 받으며 점진적으로 개선해나갈 예정입니다. 관심 있으신 분들의 기여(PR)와 의견(Issue) 모두 환영합니다!

🎯 개발 배경

최근 토이 프로젝트에서 인기 검색어 기능을 개발하던 중, '누군가가 의도적으로 비속어를 검색하여 인기 검색어에 올리는 상황이 생기지 않을까?'라는 생각이 들었다. 그래서 비속어를 필터링하는 기능을 만들려고 이것저것 찾아보니, 대부분 문자열 매칭 및 정규 표현식 기반의 코드가 많았다.

 

그런 코드도 나쁘지는 않지만, 한국어 특성상 "시1발", "시 발" 같은 변칙 우회 표현이 많아 단순 매칭으로는 한계가 있었다. 또한 "시발점"이라는 단어는 욕이 아니지만 비속어가 포함되어 있어, 대부분의 라이브러리에서는 욕으로 인식하기에 직접 만드는 게 맞겠다고 판단했다.

 

어떻게 개발할지 찾아보던 중, 예전에 Trie 알고리즘을 공부하며 보았던 우아한형제들 기술 블로그의 글을 다시 보게 되었는데, 딱 내가 원하던 구조였고 이 글을 기반으로 만들면 원하는 기능을 구현할 수 있을 것 같다는 생각이 들었다.

📚 핵심 알고리즘

Trie (트라이)

Trie는 문자열 집합을 트리 형태로 저장하는 자료구조다. 예를 들어 ["시발", "씨발", "시바"]라는 단어를 Trie에 넣는다고 가정해보자.

(root)
 ├─ 시
 │   ├─ 발 [END]
 │   └─ 바 [END]
 └─ 씨
     └─ 발 [END]

각 노드는 하나의 문자를 나타내며, 루트에서 특정 노드까지의 경로가 하나의 문자열을 형성한다. [END] 표시는 해당 위치에서 하나의 단어가 완성됨을 의미한다.

시간 복잡도

L: 모든 금칙어 길이의 합, N: 입력 문자열의 길이, K: 금칙어 개수

• 삽입: O(L)
• 검색: O(N × K)

Trie의 한계

Trie는 한 번에 하나의 패턴만 검색할 수 있다. 수천 개의 비속어를 동시에 찾으려면 각 패턴을 개별적으로 검사해야 하므로 비효율적이다.

예를 들어 다음 상황을 보자:

private val FILTER_WORDS = arrayOf(
    "안녕하세요",
    "안녕하세여",
    "안녕하세유"
)

private const val INPUT = "안녕하세용"

fun check(trie: Trie) {
    FILTER_WORDS.forEach { trie.insert(it) }
    val isFiltered = trie.contains(INPUT)
}

이 경우 Trie 구조는 다음과 같다.

(root)
 └─ 안
     └─ 녕
         └─ 하
             └─ 세
                 ├─ 요 [END]
                 ├─ 여 [END]
                 └─ 유 [END]

효율적으로 동작하려면 "안녕하세"까지 진행한 후 '세'의 자식 노드들만 확인하면 되지만, 일반적인 Trie 검색은 각 패턴을 처음부터 끝까지 개별적으로 매칭한다.

 

즉, "안녕하세용"이라는 입력에 대해서 다음과 같이 검사하는 것이다.

1. "안녕하세요" 검사 → 매칭 실패
2. 처음부터 다시 "안녕하세여" 검사 → 매칭 실패
3. 처음부터 다시 "안녕하세유" 검사 → 매칭 실패

이처럼 공통 접두사를 반복해서 탐색하는 비효율이 발생한다. 이것이 Trie만으로는 다중 패턴 매칭이 느린 이유다.

Aho-Corasick (아호-코라식)

Aho-Corasick은 Trie에 실패 함수(Failure Function)를 추가하여 여러 패턴을 동시에 O(N) 시간에 검색할 수 있게 만든 알고리즘이다. 기본적인 동작 방식은 다음과 같다.

1. Goto 함수: 기본 Trie 구조로, 다음 문자로 이동
2. Failure 함수: 현재 상태에서 매칭 실패 시 되돌아갈 상태
3. Output 함수: 현재 위치에서 발견된 모든 패턴

동작 예시

Trie와 같은 예시를 Aho-Corasick으로 처리해보자.

패턴: ["안녕하세요", "안녕하세여", "안녕하세유"]
입력: "안녕하세용"

1단계: Trie 구조 (Goto 함수)

(root)
 └─ 안
     └─ 녕
         └─ 하
             └─ 세
                 ├─ 요 [END]
                 ├─ 여 [END]
                 └─ 유 [END]

2단계: Failure 링크 구축

(root)
 └─ 안
     └─ 녕 --fail--> (root)
         └─ 하 --fail--> (root)
             └─ 세 --fail--> (root)
                 ├─ 요 [END] --fail--> (root)
                 ├─ 여 [END] --fail--> (root)
                 └─ 유 [END] --fail--> (root)

3단계: 검색 과정

입력: "안녕하세용"

1. '안' → goto(root, '안') = state_안
2. '녕' → goto(state_안, '녕') = state_녕
3. '하' → goto(state_녕, '하') = state_하
4. '세' → goto(state_하, '세') = state_세
5. '용' → goto(state_세, '용') = FAIL
   → failure(state_세) = root
   → goto(root, '용') = FAIL
   → 매칭 실패

Trie vs Aho-Corasick 비교

Trie

• "안녕하세요" 전체 검사 (5글자)
• "안녕하세여" 전체 검사 (5글자)
• "안녕하세유" 전체 검사 (5글자)
• 총 15글자 비교

Aho-Corasick

• "안녕하세용" 한 번만 순회 (5글자)
• 총 5글자 비교

이처럼 Aho-Corasick은 입력 문자열을 단 한 번만 순회하면서 모든 패턴을 동시에 찾을 수 있다. 이것이 비속어 필터링처럼 수천 개의 패턴을 찾아야 하는 경우 압도적으로 빠른 이유다.

⚙️ 적용 방법

Gradle 설정

2026년 1월 14일 : Maven Central에는 올리지 않았기 때문에 Jitpack을 설정해주어야 합니다.

 

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

build.gradle.kts

dependencies {
    implementation("com.github.Jwhyee:profanity-filter:1.0.0")
}

Spring 통합 예시

Configuration

@Configuration
class FilterConfig {
    @Bean
    fun profanityValidator(): ProfanityValidator {
        val banTrie = ProfanityTrie.create(
            customWords = listOf("커스텀비속어"),
            excludeWords = listOf("제외할비속어")
        )
        return ProfanityValidator(banTrie, setOf("시발점", "개발"))
    }
}

Service (생성자 주입)

@Service
class CommentService(
    private val validator: ProfanityValidator
) {
    fun createComment(content: String) {
        try {
            validator.validate(content)
            // 정상 처리
        } catch (e: ProfanityDetectedException) {
            throw IllegalArgumentException(
                "부적절한 단어 감지: ${e.detectedWords}"
            )
        }
    }
}

POJO 예시

class ContentFilter {
    private val validator = ProfanityValidator(
        ProfanityTrie.create(),
        setOf("시발점")
    )

    fun filter(text: String): Boolean {
        return try {
            validator.validate(text)
            true
        } catch (e: ProfanityDetectedException) {
            false
        }
    }
}

🤔 회고

예전에 Trie를 공부하면서 "이게 실제로 어디에 쓰일까?"라는 의문이 있었는데, 비속어 필터링이라는 실제 문제를 만나 공부한 것을 직접 만들어볼 수 있어 재미있었다. 작은 라이브러리지만 Trie 알고리즘을 다시 공부할 수 있었고, 설계와 최적화 등의 과정을 경험할 수 있어 더 재미있었던 것 같다. 하지만 아직 부족한 점이 많은 것 같다. 생각나는 것들을 Issue에 하나씩 추가하고 처리하면서 업데이트를 해나가야겠다.