Kroki项目使用指南：从文本图表到图像的转换利器

Kroki项目使用指南：从文本图表到图像的转换利器

kroki Creates diagrams from textual descriptions! 项目地址: https://gitcode.com/gh_mirrors/kr/kroki

Kroki是一个强大的工具，它通过HTTP API将纯文本描述的图表转换为图像。本文将详细介绍Kroki的使用方法，帮助开发者快速上手这一实用工具。

核心功能概述

Kroki的核心功能是将各种文本格式的图表描述（如GraphViz、PlantUML等）转换为可视化的图像格式（如SVG、PNG等）。它支持两种主要的请求方式：GET和POST，为开发者提供了灵活的使用选择。

GET请求方式

GET请求适用于简单的图表转换场景，但需要注意图表文本需要进行编码处理：

1. 编码要求：图表文本需要使用deflate压缩算法和base64编码
2. 优点：请求简单，适合快速测试和小型图表
3. 缺点：URL长度限制可能导致大型图表无法使用此方法

编码示例

以一个GraphViz的"Hello World"示例为例：

digraph G {
  Hello->World
}

使用Python进行编码的一行命令：

cat hello.dot | python -c "import sys; import base64; import zlib; print(base64.urlsafe_b64encode(zlib.compress(sys.stdin.read().encode('utf-8'), 9)).decode('ascii'))"

编码结果将类似于：eNpLyUwvSizIUHBXqPZIzcnJ17ULzy_KSanlAgB1EAjQ

请求示例

GET /graphviz/svg/eNpLyUwvSizIUHBXqPZIzcnJ17ULzy_KSanlAgB1EAjQ

POST请求方式

POST请求更加灵活，支持多种数据格式，无需复杂的编码过程，是生产环境推荐的使用方式。

JSON格式请求

POST /
Content-Type: application/json

{
  "diagram_source": "digraph G {Hello->World}",
  "diagram_type": "graphviz",
  "output_format": "svg"
}

纯文本格式请求

POST /graphviz
Accept: image/svg+xml
Content-Type: text/plain

digraph G {
  Hello->World
}

简化版请求

也可以在URL中直接指定输出格式：

POST /graphviz/svg
Content-Type: text/plain

digraph G {
  Hello->World
}

高级选项配置

Kroki支持为图表库传递额外的配置选项，这些选项可以通过三种方式传递：

1. 查询参数（适用于GET请求）

GET /graphviz/svg/eNpLyUwvSizIU...?key=value

2. JSON请求体中的diagram_options字段

{
  "diagram_source": "...",
  "diagram_type": "...",
  "output_format": "...",
  "diagram_options": {
    "key": "value"
  }
}

3. HTTP头部（前缀为Kroki-Diagram-Options）

POST /graphviz
Kroki-Diagram-Options-Key: value
...

选项优先级

Kroki处理选项的优先级顺序为：

1. JSON请求体中的选项
2. HTTP头部中的选项
3. URL查询参数中的选项

最佳实践建议

1. 小型图表：可以使用GET请求快速测试
2. 生产环境：推荐使用POST请求，特别是JSON格式，它更易维护且没有URL长度限制
3. 复杂图表：考虑使用选项配置来优化图表输出效果
4. 性能考虑：对于频繁调用的场景，可以考虑本地安装Kroki服务减少网络延迟

通过本文的介绍，您应该已经掌握了Kroki的基本使用方法。这个工具的强大之处在于它能够将简单的文本描述转换为专业的图表，极大提高了开发文档和系统设计的效率。

kroki Creates diagrams from textual descriptions! 项目地址: https://gitcode.com/gh_mirrors/kr/kroki