# JSON 구성으로 Python에서 다단계 대화 관리하기
설문조사, 온보딩 흐름, 복잡한 위자드를 구축하다 보면 유지보수와 확장이 어려운 조건문 논리가 쌓이게 됩니다. dialog-engine 라이브러리는 선언적 대안을 제공합니다: 대화 구조, 필드 표시 규칙, 탐색은 JSON이나 YAML로 정의됩니다. 엔진은 세션 컨텍스트에 기반해 사용 가능한 단계를 자동으로 계산하며, 모든 시나리오에 중첩 구조를 사용할 필요가 없습니다.
선언적 위자드 구축 방법
전통적인 다단계 폼 구현은 명시적인 상태 관리를 요구합니다. 개발자는 현재 단계를 수동으로 추적하고, 전환 조건을 확인하며, 인터페이스를 조립해야 합니다. 비즈니스 로직이 변경되거나 새로운 분기가 추가될 때 코드가 빠르게 엉망이 되어 if 문과 match 블록의 스파게티가 됩니다. dialog-engine은 이를 뒤집습니다: 대화가 명령어 순서가 아닌 데이터 구조가 됩니다.
구성 파일은 단계 배열을 포함합니다. 각 항목은 ID, 입력 유형, 텍스트, 선택적 유효성 검사 매개변수를 정의합니다. 엔진은 필드 유형을 해석하지 않습니다—text, choice, photo 또는 사용자 정의 값은 구성과 렌더링 계층 간의 규칙으로 처리됩니다. 이를 통해 Telegram 봇, 웹 인터페이스, 콘솔 유틸리티에 동일한 파일을 사용할 수 있습니다.
{
"steps": [
{ "id": "name", "type": "text", "text": "What is your name?" },
{ "id": "plan", "type": "choice", "text": "Choose a plan",
"choices": { "free": "Free", "pro": "Professional" } },
{ "id": "company_inn", "type": "text", "text": "Enter the company tax ID",
"show_when": { "field": "plan", "equals": "pro" } },
{ "id": "confirm", "type": "text", "text": "Is everything correct? Sending!" }
]
}기본 설치는 외부 종속성을 필요로 하지 않습니다. 추가 모듈은 필요에 따라 extras로 설치하며, 기본 패키지를 가볍게 유지합니다.
pip install dialog-engine
pip install dialog-engine[validation,yaml,aiogram]조건부 표시 및 탐색 메커니즘
엔진의 핵심 기능은 컨텍스트 의존적 라우팅입니다. 전환을 하드코딩하는 대신 사용자 응답 딕셔너리를 사용해 다음 및 이전 표시 단계의 인덱스를 계산합니다. 숨겨진 단계는 진행 바와 탐색 로직에서 자동으로 제외되어 "3단계 중 2단계"처럼 정확한 위치 카운트를 보장합니다.
표시 조건은 show_when과 skip_when 필드로 설정합니다. 기본 비교 연산자와 존재 확인을 지원하며, 복잡한 비즈니스 로직을 위한 any_of와 all_of 같은 복합 규칙도 가능합니다. 규칙은 깊이 제한 없이 중첩할 수 있습니다.
{
"skip_when": {
"any_of": [
{ "field": "plan", "equals": "free" },
{ "field": "age", "lt": 18 }
]
}
}Python API는 인덱스와 위치 작업을 위한 메서드를 제공하며, 수동 조건 탐색 없이 정확한 세션 상태 제어를 허용합니다.
ctx = {"plan": "free"}
next_idx = engine.next_index(1, ctx)
prev_idx = engine.previous_index(3, ctx)
pos = engine.effective_position(next_idx, ctx)
total = engine.effective_total(ctx)
if engine.is_last_visible(next_idx, ctx):
# Complete dialog
...세션 지속을 위해 DialogSessionState 클래스는 현재 인덱스와 컨텍스트를 JSON으로 직렬화합니다. 이는 사용자 요청 간 Redis나 관계형 데이터베이스에 상태를 저장하는 것을 단순화합니다.
aiogram 3와 콜백 처리 통합
라이브러리 코어는 프레임워크에 무관하지만, Telegram 생태계용으로 준비된 도우미를 제공합니다. 인라인 키보드를 생성하고, 선택된 값을 자동으로 표시하며, 올바른 callback_data를 형성합니다. 콜백 처리는 타이핑되어 선택, 건너뛰기, 뒤로가기 로직을 분리합니다.
from dialog_engine.integrations.aiogram import (
build_step_keyboard,
parse_choice_callback,
is_named_callback,
KeyboardCallbacks,
)
step = engine.get_step(current_index)
kb = build_step_keyboard(step, translate, show_back=True, current_value=ctx.get(step.id))
await message.answer(step.text, reply_markup=kb)수신 콜백 파싱은 단계 ID와 선택된 값을 반환하는 파서로 처리됩니다. 이는 수동 callback.data 문자열 파싱을 제거하고 접두사 충돌 위험을 줄입니다.
@router.callback_query()
async def on_callback(callback: CallbackQuery):
cb = KeyboardCallbacks()
pair = parse_choice_callback(callback.data, cb)
if pair:
step_id, choice_key = pair
ctx[step_id] = choice_key
next_idx = engine.next_index(current_index, ctx)
...CLI 도구와 구성 유효성 검사
선언적 구성 지원을 위해 정적 분석 도구가 필요합니다. 포함된 CLI는 앱 시작 전에 파일 구조를 검사해 중복 ID, 깨진 참조, 구문 오류를 확인합니다. 엄격 모드는 Pydantic으로 완전한 타입 검사를 수행합니다.
dialog-engine validate wizard.json— 기본 구조 검사.dialog-engine validate --strict wizard.json— Pydantic 유효성 검사.dialog-engine mermaid wizard.json— 문서용 전환 다이어그램 생성.dialog-engine schema > dialog.schema.json— IDE 자동완성을 위한 JSON Schema 출력.dialog-engine init -o my-dialog.json— 새 대화 템플릿 생성.
CI/CD 파이프라인에 유효성 검사를 통합하면 잘못된 구성이 프로덕션에 도달하지 않습니다. JSON Schema는 코드 에디터에서 구문 강조와 자동완성을 제공해 폼을 편집하는 제품 관리자와 분석가의 진입 장벽을 낮춥니다.
주요 포인트
- 대화는 JSON/YAML로 선언적으로 설명되어 비즈니스 로직을 앱 코드와 분리하고, 재배포 없이 시나리오를 편집할 수 있습니다.
- 탐색과 단계 표시는 세션 컨텍스트에서 동적으로 계산되어 중첩 조건문 구조를 피합니다.
- aiogram 3 통합은 키보드 생성기와 타이핑된 콜백 파서를 제공해 보일러플레이트 코드를 줄입니다.
- CLI 유틸리티와 JSON Schema는 정적 구성 검사와 원활한 IDE 개발을 가능하게 합니다.
- 라이브러리는 소스 사용 가능 라이선스로 배포됩니다: 프로젝트 사용은 허용되지만 소스 코드 수정 및 재배포는 제한됩니다.
— Editorial Team
아직 댓글이 없습니다.