mermaid-go

Mermaid-Go

一个基于 mermaid.js 架构的 Go 语言 Mermaid 图表解析器和生成器。

项目作者

由 gytmtc 创建，基于 mermaid.js 的架构设计。

架构设计

该实现严格遵循 mermaid.js 的设计模式：

• AST 包: 类型定义镜像 mermaid.js 的 FlowVertex, FlowEdge 等结构
• Lexer 包: 基于 JISON 词法规则的标记化词法分析
• Parser 包: 遵循 flow.jison 结构的语法分析
• Renderer 包: AST 到字符串的渲染
• FlowDB: 图表构建的中央状态管理

功能特性

• 流程图解析和渲染
• 多种节点形状支持 (矩形、圆形、菱形等)
• 多种箭头类型支持 (实线、虚线、粗线等)
• 边标签支持
• 完整的往返转换 (解析 → AST → 渲染)
• 序列图支持 (待实现)
• 类图支持 (待实现)
• 状态图支持 (待实现)

快速开始

# 克隆项目
git clone <repository-url>
cd mermaid-go

# 运行演示
go run demo.go

# 运行测试
go test ./tests/

# 构建 CLI 工具
go build -o mmdc cmd/mermaid-cli/main.go

使用示例

基础 API 使用

package main

import (
    "fmt"
    "log"

    "mermaid-go/pkg/ast"
    "mermaid-go/pkg/lexer"
    "mermaid-go/pkg/parser"
    "mermaid-go/pkg/renderer"
)

func main() {
    input := `graph TD
    A[圣诞节] -->|获得金钱| B(去购物)
    B --> C{让我想想}
    C -.->|一| D[笔记本电脑]
    C -.->|二| E[iPhone]
    C -.->|三| F[汽车]`

    // 解析 Mermaid 语法
    parser := parser.NewParser()
    diagram, err := parser.Parse(input)
    if err != nil {
        log.Fatal(err)
    }

    // 验证图表
    if err := diagram.Validate(); err != nil {
        log.Fatal(err)
    }

    // 渲染回 Mermaid 语法
    renderer := renderer.NewFlowchartRenderer()
    output := renderer.Render(diagram)
    fmt.Println(output)
}

词法分析示例

// 创建词法分析器
lexer := lexer.NewLexer("graph TD\nA --> B")
tokens, err := lexer.Tokenize()
if err != nil {
    log.Fatal(err)
}

// 过滤空白和注释
filtered := lexer.FilterTokens(tokens)
for _, token := range filtered {
    fmt.Printf("%s: %s\n", token.Type, token.Value)
}

AST 操作示例

// 创建新的流程图
flowchart := ast.NewFlowchart()
flowchart.Direction = "TD"

// 添加顶点
vertexA := &ast.FlowVertex{
    ID: "A",
    Text: StringPtr("开始"),
    Type: &ast.VertexTypeRect,
}
flowchart.Vertices["A"] = vertexA

vertexB := &ast.FlowVertex{
    ID: "B",
    Text: StringPtr("结束"),
    Type: &ast.VertexTypeCircle,
}
flowchart.Vertices["B"] = vertexB

// 添加边
edge := &ast.FlowEdge{
    Start: "A",
    End: "B",
    Text: "流程",
    Type: StringPtr("arrow_point"),
    Stroke: &ast.StrokeNormal,
}
flowchart.Edges = append(flowchart.Edges, edge)

// 渲染
renderer := renderer.NewFlowchartRenderer()
output := renderer.Render(flowchart)
fmt.Println(output)

CLI 工具使用

# 从文件解析并输出
./mmdc -i input.mmd -o output.mmd

# 从标准输入读取
echo "graph TD\nA --> B" | ./mmdc -i - -o -

# 指定输出格式
./mmdc -i input.mmd -o output.mmd -f mermaid

支持的语法

节点形状

graph TD
    A[矩形] --> B(圆角矩形)
    B --> C{菱形}
    C --> D((圆形))
    D --> E([体育场形])
    E --> F[[子程序]]
    F --> G[("圆柱形")]
    G --> H{{六边形}}

箭头类型

graph TD
    A --> B        %% 实线箭头
    B -.-> C       %% 虚线箭头
    C ==> D        %% 粗线箭头
    D --x E        %% 交叉箭头
    E --o F        %% 圆圈箭头
    F --- G        %% 开放箭头

边标签

graph TD
    A -->|标签文本| B
    B -->|"带引号的标签"| C

测试

项目包含完整的测试套件：

# 运行所有测试
go test ./tests/

# 运行词法分析器测试
go test ./tests/ -run TestLexer

# 运行解析器测试
go test ./tests/ -run TestParser

# 运行集成测试
go test ./tests/ -run TestMermaid

开发指南

架构说明

该项目的设计严格遵循 mermaid.js 的内部架构：

1. 词法分析 (Lexer): 基于 flow.jison 的词法规则，将输入文本转换为标记流
2. 语法分析 (Parser): 基于 flow.jison 的语法规则，构建 AST
3. AST: 镜像 mermaid.js 的 TypeScript 类型定义
4. FlowDB: 模拟 mermaid.js 的 FlowDB 类，管理解析状态
5. 渲染器: 将 AST 转换回 Mermaid 语法字符串

添加新功能

1. 在 pkg/ast/ 中定义新的 AST 节点类型
2. 在 pkg/lexer/ 中添加新的标记类型
3. 在 pkg/parser/ 中实现解析逻辑
4. 在 pkg/renderer/ 中实现渲染逻辑
5. 添加相应的测试用例

代码风格

• 遵循 Go 语言规范
• 使用 go fmt 格式化代码
• 添加适当的注释和文档
• 所有公共 API 都需要有测试覆盖

与 mermaid.js 的对应关系

mermaid.js	mermaid-go
flow.jison	pkg/lexer/lexer.go + pkg/parser/flowchart.go
flowDb.ts	pkg/parser/flowchart.go (FlowDB)
types.ts	pkg/ast/flowchart.go
flowRenderer.ts	pkg/renderer/flowchart.go

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

致谢

• 感谢 mermaid.js 项目提供的优秀架构设计
• 感谢 Knut Sveidqvist 和所有 mermaid.js 贡献者