mirror of
https://github.com/ktds-dg0501/kt-event-marketing.git
synced 2025-12-06 15:26:23 +00:00
300 lines
8.5 KiB
Markdown
300 lines
8.5 KiB
Markdown
# Mermaid문법검사가이드
|
|
|
|
## 개요
|
|
|
|
Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다.
|
|
|
|
## Mermaid CLI 서버 설치 및 검사
|
|
|
|
### Docker로 Mermaid CLI 컨테이너 실행
|
|
|
|
```bash
|
|
# Mermaid CLI 컨테이너가 실행 중인지 확인
|
|
docker ps | grep mermaid-cli
|
|
|
|
# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지)
|
|
docker pull minlag/mermaid-cli:latest
|
|
|
|
# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용)
|
|
docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done"
|
|
|
|
# 컨테이너 상태 확인
|
|
docker logs mermaid-cli
|
|
```
|
|
|
|
#### 💡 Docker 이미지 다운로드 관련 주의사항
|
|
|
|
**첫 실행 시 발생할 수 있는 문제:**
|
|
- `minlag/mermaid-cli:latest` 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림
|
|
- `docker run` 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능
|
|
- **해결방법**: `docker pull` 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행
|
|
|
|
**권장 실행 순서:**
|
|
1. `docker pull minlag/mermaid-cli:latest` (이미지 다운로드)
|
|
2. `docker run` 명령으로 컨테이너 실행
|
|
3. 필수 설정 진행
|
|
|
|
#### ⚠️ 중요: 최초 컨테이너 생성 후 필수 설정
|
|
|
|
Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다.
|
|
컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다:
|
|
|
|
```bash
|
|
# Chromium 및 필요한 종속성 설치
|
|
docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont"
|
|
|
|
# Puppeteer가 사용할 설정 파일 생성
|
|
docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json"
|
|
```
|
|
|
|
이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다.
|
|
|
|
문법검사 후 Container를 중지하지 않고 계속 사용함
|
|
|
|
## 문법 검사 방법
|
|
현재 OS에 맞게 수행.
|
|
|
|
### Linux/macOS 버전
|
|
**스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행**
|
|
|
|
1. tools/check-mermaid.sh 파일 존재 여부 확인
|
|
2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦
|
|
3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
|
|
|
|
```bash
|
|
# 1. 스크립트 실행 권한 부여 (최초 1회)
|
|
chmod +x tools/check-mermaid.sh
|
|
|
|
# 2. 문법 검사 실행
|
|
./tools/check-mermaid.sh {검사할 파일}
|
|
|
|
# 예시
|
|
./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd
|
|
```
|
|
|
|
### Windows PowerShell 버전
|
|
**스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행**
|
|
|
|
1. tools/check-mermaid.ps1 파일 존재 여부 확인
|
|
2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦
|
|
3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
|
|
|
|
```powershell
|
|
# 문법 검사 실행
|
|
.\tools\check-mermaid.ps1 {검사할 파일}
|
|
|
|
# 예시
|
|
.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd
|
|
```
|
|
|
|
### 수동 검사 방법 (스크립트 없이)
|
|
|
|
```bash
|
|
# 1. 고유 파일명 생성 (충돌 방지)
|
|
TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd"
|
|
|
|
# 2. 파일 복사
|
|
docker cp {검사할 파일} mermaid-cli:${TEMP_FILE}
|
|
|
|
# 3. 문법 검사 (Puppeteer 설정 파일 사용)
|
|
docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q"
|
|
|
|
# 4. 임시 파일 삭제
|
|
docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg
|
|
```
|
|
|
|
**주의**: Puppeteer 설정 파일(`/tmp/puppeteer-config.json`)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요.
|
|
|
|
### 검사 결과 해석
|
|
|
|
| 출력 | 의미 | 대응 방법 |
|
|
|------|------|-----------|
|
|
| "Success: Mermaid syntax is valid!" | 문법 오류 없음 ✅ | 정상, 렌더링 가능 |
|
|
| "Parse error on line X" | X번째 줄 구문 오류 ❌ | 해당 라인 문법 확인 |
|
|
| "Expecting 'XXX'" | 예상 토큰 오류 ❌ | 누락된 문법 요소 추가 |
|
|
| "Syntax error" | 일반 문법 오류 ❌ | 전체 구조 재검토 |
|
|
|
|
## Mermaid 다이어그램 타입별 주의사항
|
|
|
|
### 1. Graph/Flowchart
|
|
```mermaid
|
|
graph TB
|
|
%% 올바른 사용법 ✅
|
|
A[Node A] --> B[Node B]
|
|
C[Node C] -.-> D[Node D]
|
|
E[Node E] ==> F[Node F]
|
|
|
|
%% 주의사항
|
|
%% - 노드 ID에 공백 불가 (대신 [Label] 사용)
|
|
%% - subgraph와 end 개수 일치 필요
|
|
%% - 따옴표 안에서 특수문자 주의
|
|
```
|
|
|
|
### 2. Sequence Diagram
|
|
```mermaid
|
|
sequenceDiagram
|
|
%% 올바른 사용법 ✅
|
|
participant A as Service A
|
|
participant B as Service B
|
|
|
|
A->>B: Request
|
|
B-->>A: Response
|
|
A->>+B: Call with activation
|
|
B-->>-A: Return with deactivation
|
|
|
|
%% 주의사항
|
|
%% - participant 선언 권장
|
|
%% - 활성화(+)/비활성화(-) 쌍 맞추기
|
|
%% - Note 블록 종료 확인
|
|
```
|
|
|
|
### 3. Class Diagram
|
|
```mermaid
|
|
classDiagram
|
|
%% 올바른 사용법 ✅
|
|
class Animal {
|
|
+String name
|
|
+int age
|
|
+makeSound() void
|
|
}
|
|
|
|
class Dog {
|
|
+String breed
|
|
+bark() void
|
|
}
|
|
|
|
Animal <|-- Dog : inherits
|
|
|
|
%% 주의사항
|
|
%% - 메서드 괄호 필수
|
|
%% - 관계 표현 정확히
|
|
%% - 접근 제한자 기호 확인
|
|
```
|
|
|
|
### 4. State Diagram
|
|
```mermaid
|
|
stateDiagram-v2
|
|
%% 올바른 사용법 ✅
|
|
[*] --> Idle
|
|
Idle --> Processing : start
|
|
Processing --> Completed : finish
|
|
Processing --> Error : error
|
|
Error --> Idle : reset
|
|
Completed --> [*]
|
|
|
|
%% 주의사항
|
|
%% - [*]는 시작/종료 상태
|
|
%% - 상태 이름에 공백 불가
|
|
%% - 전이 레이블 콜론(:) 사용
|
|
```
|
|
|
|
## 일반적인 오류와 해결 방법
|
|
|
|
### 1. 괄호 불균형
|
|
```mermaid
|
|
%% 잘못된 예 ❌
|
|
graph TB
|
|
A[Node (with parenthesis)] %% 괄호 안에 괄호
|
|
|
|
%% 올바른 예 ✅
|
|
graph TB
|
|
A[Node with parenthesis]
|
|
```
|
|
|
|
### 2. 특수 문자 이스케이프
|
|
```mermaid
|
|
%% 잘못된 예 ❌
|
|
graph TB
|
|
A[Security & Management] %% & 문자 직접 사용
|
|
|
|
%% 올바른 예 ✅
|
|
graph TB
|
|
A[Security & Management] %% HTML 엔티티 사용
|
|
```
|
|
|
|
### 3. subgraph/end 불일치
|
|
```mermaid
|
|
%% 잘못된 예 ❌
|
|
graph TB
|
|
subgraph One
|
|
A --> B
|
|
subgraph Two
|
|
C --> D
|
|
end %% Two만 닫힘, One은 안 닫힘
|
|
|
|
%% 올바른 예 ✅
|
|
graph TB
|
|
subgraph One
|
|
A --> B
|
|
subgraph Two
|
|
C --> D
|
|
end
|
|
end %% 모든 subgraph 닫기
|
|
```
|
|
|
|
### 4. 노드 참조 오류
|
|
```mermaid
|
|
%% 잘못된 예 ❌
|
|
graph TB
|
|
A --> UnknownNode %% 정의되지 않은 노드
|
|
|
|
%% 올바른 예 ✅
|
|
graph TB
|
|
A[Node A] --> B[Node B] %% 모든 노드 정의
|
|
```
|
|
|
|
## 컨테이너 관리
|
|
|
|
### 컨테이너 중지 및 삭제
|
|
```bash
|
|
# 컨테이너 중지
|
|
docker stop mermaid-cli
|
|
|
|
# 컨테이너 삭제
|
|
docker rm mermaid-cli
|
|
|
|
# 한 번에 중지 및 삭제
|
|
docker stop mermaid-cli && docker rm mermaid-cli
|
|
```
|
|
|
|
### 컨테이너 재시작
|
|
```bash
|
|
# 컨테이너 재시작
|
|
docker restart mermaid-cli
|
|
```
|
|
|
|
## 성능 최적화 팁
|
|
|
|
1. **컨테이너 유지**: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행
|
|
2. **배치 검사**: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행
|
|
3. **로컬 파일 사용**: 네트워크 경로보다 로컬 파일 경로 사용 권장
|
|
|
|
## 문제 해결
|
|
|
|
### Docker 관련 오류
|
|
```bash
|
|
# Docker 데몬 실행 확인
|
|
docker ps
|
|
|
|
# Docker Desktop 시작 (Windows/Mac)
|
|
# Docker 서비스 시작 (Linux)
|
|
sudo systemctl start docker
|
|
```
|
|
|
|
### 권한 오류
|
|
```bash
|
|
# Linux/Mac에서 스크립트 실행 권한
|
|
chmod +x tools/check-mermaid.sh
|
|
|
|
# Docker 권한 (Linux)
|
|
sudo usermod -aG docker $USER
|
|
```
|
|
|
|
### 컨테이너 이미지 오류
|
|
```bash
|
|
# 이미지 재다운로드
|
|
docker pull minlag/mermaid-cli:latest
|
|
|
|
# 기존 컨테이너 삭제 후 재생성
|
|
docker stop mermaid-cli && docker rm mermaid-cli
|
|
``` |