Profanity Filter Library (Kotlin/Java)

비속어, 인격 모독 등에 대한 단어가 포함된 리포지토리입니다. 코드를 읽으실 때, 이 점 양해해주시면 감사하겠습니다.

Aho-Corasick 알고리즘 기반의 비속어 필터링 라이브러리입니다. 정규식(Regex) 기반 탐지의 성능 병목을 해결하고, 숫자나 공백을 섞은 변칙 우회 패턴을 $O(N)$ 시간 복잡도로 처리합니다. 우아한형제들 기술 블로그의 비속어 탐지 전략을 참고하여 설계되었습니다.

📊 성능 벤치마크 (Performance)

변칙 우회 패턴을 포함한 10만 자 길이의 텍스트(약 15,000 단어)를 대상으로 기존 탐지 방식들과 성능을 비교한 결과입니다.

• 테스트 환경: OpenJDK 21, Apple M1 Pro
• 테스트 조건: 금칙어 밀도 5%, 이 중 50%는 숫자/공백이 혼합된 변칙 우회 패턴 적용

탐지 방식	변칙 탐지 여부	평균 실행 시간	비고
Profanity Filter (본 라이브러리)	O	3.15 ms	Aho-Corasick + 정규화 + 허용 단어 검증 포함
복합 정규식 (Complex Regex)	O	85.89 ms	변칙 탐지는 가능하나 패턴이 길어질수록 성능 급감
단순 정규식 (Simple Regex)	X	77.64 ms	변칙 패턴 탐지 불가
Contains Loop (String.contains)	X	1.79 ms	가장 빠르나 변칙 탐지 불가 (기능적 한계)

성능 요약

본 라이브러리는 복합 정규식과 동일한 수준의 변칙 우회 탐지 기능을 제공하면서도 약 27배 빠른 처리 속도를 보입니다. 변칙 탐지가 불가능한 단순 contains 탐색과 근접한 응답 속도를 유지하므로, 트래픽이 집중되는 애플리케이션 계층에서 실시간 필터링 용도로 적합합니다.

벤치마크 테스트는 다음 명령어로 직접 실행해 볼 수 있습니다. ./gradlew test --tests "io.github.jwhyee.profanity.policy.PerformanceBenchmark" --info

💡 주요 기능

• 다중 패턴 매칭: Aho-Corasick 구조를 적용하여 금칙어 개수가 증가해도 탐색 성능을 $O(N)$으로 유지합니다.
• 변칙 우회 방어: 입력 문자열에서 정책에 따라 숫자(ㅅ123ㅂ)나 공백(시 발)을 정규화하여 탐지합니다.
• 지능형 예외 처리: "시발점"과 같이 정상 단어 내에 금칙어가 포함된 경우, 구간 중첩 알고리즘을 통해 오탐지(False Positive)를 방지합니다.
• Trie 빌드 캐싱: 정책 조합별로 허용 단어 트리를 메모리에 캐싱하여 런타임 오버헤드를 최소화합니다.

🚀 Quick Start

• Quick start document

🛠️ 동작 원리

탐지 알고리즘 파이프라인

1. 정규화: 입력 문장에서 설정된 정책(Policy)에 따라 숫자 및 공백을 제거 (예: 시 1발 → 시발)
2. 금칙어 탐지: Trie 기반의 Aho-Corasick 알고리즘으로 전체 금칙어 구간 탐색
3. 허용 단어 탐지: 동일한 정책이 적용된 허용 단어 트리를 통해 예외 구간 탐색
4. 구간 교집합 판단: 금칙어 탐지 구간이 허용 단어 구간 내에 포함될 경우 최종 결과에서 제외 처리

전처리 정책 (Policy)

정책	정규식	설명
NUMBERS	[\p{N}]	숫자 혼용 우회 탐지 방어 (예: 시1발)
WHITESPACES	[\s]	공백 우회 탐지 방어 (예: 시 발)

📁 프로젝트 구조

io.github.jwhyee.profanity
├── dto        # 데이터 모델 (결과 반환 객체 등)
├── helper     # Trie 빌더 및 내부 유틸리티
├── policy     # 금칙어/허용어 목록 및 정규화 정책
└── validator  # 검증 엔진 및 구간 중첩 판단 로직

🔗 참고 자료

• 우아한형제들 기술 블로그 - 고르곤졸라는 되지만 고르곤 졸라는 안 돼! 배달의민족에서 금칙어를 관리하는 방법
• Aho-Corasick Algorithm - Wikipedia

📜 License

이 프로젝트는 MIT License를 따릅니다. 자세한 내용은 LICENSE 파일을 확인해주세요.