PlantUML 조건부 동적 다이어그램

PlantUML 동적 시퀀스 다이어그램: 변수와 조건 활용

PlantUML은 변수와 조건을 활용한 전처리를 지원해 동적 시퀀스 다이어그램을 만들 수 있습니다. 사용자가 토글로 세부 수준을 조절하며 중첩 로직을 표시하거나 숨길 수 있어 별도의 다이어그램을 만들 필요가 없습니다.

주문 생성 API 엔드포인트를 문서화한다고 가정해 보세요. 수십 개의 내부 검증이 발생하는데, 전체 다이어그램은 너무 복잡해지고 여러 정적 버전 사이를 오가는 건 비효율적입니다.

다이어그램 텍스트 준비

기본 다이어그램 텍스트에 변수와 조건을 추가합니다. 예시:

participant Bob as b
participant Alice as a

!$aliceThoughts = "No"
!$bobThoughts = "No"

b -> a: Hi!

!if ($aliceThoughts == "Yes")
activate a
a->a: Oh my god, he messaged me!
a->a: What to do, what to say..
create participant Lisa as l
a -> l: Bob messaged me, what should I do?
activate l
l -> a: Just reply to him, gosh
deactivate l
!endif

a->b: Hi!
deactivate a

!if ($bobThoughts == "Yes")
activate b
b->b: She replied o_O
!endif

b->a: Uh... How are you?
deactivate b

$aliceThoughts와 $bobThoughts 변수가 블록 표시 여부를 제어합니다. PlantUML 전처리기는 렌더링 시 조건을 평가합니다.

제어용 HTML 인터페이스

HTML 폼과 JavaScript로 토글을 구현합니다. 사용자가 세부 수준을 선택하면 다이어그램 텍스트가 동적으로 업데이트되고 이미지가 생성됩니다.

<form>
  <label for="aliceThoughts">앨리스 생각 표시:</label>
  <select id="aliceThoughts" name="aliceThoughts">
    <option value="no">숨기기</option>
    <option value="yes">표시</option>
  </select>
</form>

<form>
  <label for="bobThoughts">밥 생각 표시:</label>
  <select id="bobThoughts" name="bobThoughts">
    <option value="no">숨기기</option>
    <option value="yes">표시</option>
  </select>
</form>

JavaScript는 select 요소 변경을 감지해 PlantUML 템플릿에 값을 주입하고 인코더를 호출해 URL을 생성합니다.

PlantUML API용 텍스트 인코딩

PlantUML은 HTTP API로 렌더링을 제공합니다: https://www.plantuml.com/plantuml/png/<encoded_text>. PNG와 SVG 형식을 지원합니다.

간단한 방법 (Hex)

UTF-8 텍스트를 ~h 접두사와 함께 16진수로 변환:

function toHex(uml) {
  const umlFormatted = `@startuml\r\n${uml}\r\n@enduml`;
  const utf8 = unescape(encodeURIComponent(umlFormatted));
  var result = '';
  for (var i=0; i<utf8.length; i++) {
    result += utf8.charCodeAt(i).toString(16).padStart(2, '0');
  }
  return `https://www.plantuml.com/plantuml/png/~h${result}`;
}

짧은 다이어그램에 적합. 제한: URL 길이 (약 8KB).

고급 방법 (Deflate + 커스텀 Base64)

• Deflate 압축.
• PlantUML base64 인코딩: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.

압축으로 대형 다이어그램 처리 가능.

function encodePlantUml(data) {
    const base64Map = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_';
    let result = '';
    for (let i = 0; i < data.length; i += 3) {
        const b1 = data[i];
        const b2 = i + 1 < data.length ? data[i + 1] : 0;
        const b3 = i + 2 < data.length ? data[i + 2] : 0;
        result += base64Map[b1 >> 2];
        result += base64Map[((b1 & 3) << 4) | (b2 >> 4)];
        result += base64Map[((b2 & 15) << 2) | (b3 >> 6)];
        result += base64Map[b3 & 63];
    }
    return result;
}

Confluence에 임베드

Confluence 매크로로 HTML+JS 삽입. 백엔드 없이 브라우저에서 PlantUML 공용 서버로 렌더링. 엔터프라이즈는 로컬 PlantUML 서버 사용.

주요 장점:

• 아티팩트 전환 없이 상호작용.
• 전처리로 복잡 로직 구현.
• 최소 자원: HTML, JS, PlantUML API.
• Confluence 호환.

구현 제한사항

• Hex 인코딩 URL 길이.
• 외부 PlantUML 서버 의존 (로컬 배포로 해결).
• PlantUML 전처리기 제한: 복잡 연산 불가, 기본 연산만.

| 방법 | 최대 텍스트 크기 | 복잡도 |

|----------|----------------------|--------|

| Hex | ~2000 문자 | 낮음 |

| Deflate | ~50k+ 문자 | 높음 |

주요 요약

• PlantUML 전처리로 !if 조건과 변수를 활용한 동적 다이어그램 가능.
• HTML+JS 토글로 실시간 업데이트.
• PlantUML API로 인코딩 URL에서 PNG 생성, 백엔드 불필요.
• 간단 케이스는 Hex, 대형은 Deflate.
• Confluence에서 VPN 문제 없이 실행.

— Editorial Team