de_DEen_USes_ESfa_IRfr_FRhi_INjapl_PLpt_PTru_RUzh_CN

本指南旨在引导您完成在 VPasCode 中使用 Mermaid 语法创建专业图表,并无缝发布到 OpenDocs 知识库的完整工作流程。我们将涵盖从设置到发布的整个流程,并提供真实可用的示例。

From Diagram-as-Code To Open Publishing: VPasCode + OpenDocs Workflow

为什么这一工作流程至关重要

软件开发中的文档常常滞后于代码。工程师花费数小时构建复杂的系统架构,而技术写作者却难以在静态文档中保持图表的更新。结果?过时的图表、失效的链接,以及无法反映现实的知识库。

VPasCode 和 OpenDocs 解决了这一问题。VPasCode 允许您使用简单的文本语法(如 Mermaid)创建专业图表,而 OpenDocs 则是一个由 AI 驱动的知识管理平台。当两者连接时,神奇的事情发生了:通过 VPasCode 到 OpenDocs 的流水线集成,您只需点击一下,即可将图表从代码编辑器直接发送到文档中。再也不需要导出、下载或重新上传。

设置与工具

开始使用

在开始创建图表之前,请确保您已获得所需工具的访问权限:

  • VPasCode:一个交互式的、基于浏览器的“代码即图表”(DaC)实验环境和编辑器。它在统一界面中支持 Mermaid.js、PlantUML 和 Graphviz。

  • OpenDocs:一个专为“图表感知”而设计的基于网页的知识管理平台。

  • Visual Paradigm 账户:虽然免费版提供实时预览和导出功能,但付费版本可解锁高级 AI 功能,如错误修复和翻译。

了解 VPasCode 的界面

VPasCode 采用响应式的双栏布局,兼顾代码编写与即时视觉反馈:

  • 左侧面板:代码编辑器 – 包含语法高亮、引擎选择器和实时错误计数。

  • 右侧面板:视觉预览 – 输入时即时渲染您的图表。

  • 状态栏:显示实时语法验证和错误计数。

连接流水线

该集成已内置,因此无需复杂的 API 密钥。只需使用相同的 Visual Paradigm 账户登录两个平台即可。当您准备分享图表时,“发送到 OpenDocs 流水线”按钮会安全地将您的图表路由到您的 OpenDocs 工作区。

流水线充当所有视觉资产的安全、基于云的中央存储库。它可追踪资产版本,维护修订历史,并记录用户评论——所有操作均无需手动保存文件。

实用的 Mermaid 示例

让我们探讨如何在 VPasCode 中使用 Mermaid 语法创建实际应用的图表。

示例 1:用户认证流程图

此示例展示了一个使用流程图的基本登录过程。流程图非常适合用于记录业务逻辑、用户旅程和流程图。

graph TD
    A[开始:用户打开应用] --> B[输入用户名和密码]
    B --> C{尝试登录}
    C -->|成功| D[重定向到仪表板]
    C -->|失败| E[显示错误消息]
    E --> F{重试?}
    F -->|是| B
    F -->|否| G[结束:登录已取消]
    D --> G

    style A fill:#e1f5fe
    style D fill:#e8f5e8
    style E fill:#ffebee
    style C fill:#f3e5f5

如何使用此功能: 将此代码复制到 VPasCode 的编辑器中,选择“Mermaid”作为引擎,即可立即看到流程图渲染。点击“发送到 OpenDocs 流水线”可将此图表直接推送到您的技术规范文档中。

示例 2:REST API 认证序列图

为了记录系统组件之间的交互,序列图极为有用。此示例展示了带有 JWT 令牌生成的完整 REST API 认证流程。

 

sequenceDiagram
    autonumber
    
    actor 用户
    participant 客户端 as 网页客户端
    participant API as REST API
    participant 认证服务 as 认证服务
    participant 数据库 as 数据库

    用户->>客户端: 输入凭据
    客户端->>+API: POST /login
    API->>+认证服务: 验证凭据
    认证服务->>+数据库: 查找用户

    alt 用户存在
        数据库-->>认证服务: 用户记录
        认证服务->>认证服务: 验证密码
        
        alt 密码匹配
            认证服务->>认证服务: 生成 JWT
            认证服务-->>-API: 令牌
            API-->>-客户端: 200 OK + 令牌
            客户端->>客户端: 存储令牌
            客户端-->>用户: 登录成功
        else 密码错误
            认证服务-->>API: 凭据无效
            API-->>客户端: 401 未授权
            客户端-->>用户: 密码错误
        end
    else 用户未找到
        数据库-->>-认证服务: 未找到
        认证服务-->>API: 用户无效
        API-->>客户端: 401 未授权
        客户端-->>用户: 用户未找到
    end

演示的关键功能:

  • 自动编号自动为每一步编号

  • 参与者参与者定义不同类型的实体

  • 条件分支条件块显示条件路径

  • +-符号表示服务的激活和停用

示例 3:微服务架构的 C4 容器图

对于高层架构文档,C4 模型提供了极佳的清晰度。此示例展示了一个在线银行系统的容器图。

graph TD
    subgraph "网上银行系统"
        WebApp[Web 应用程序<br/>Java, Spring MVC<br/>向用户交付内容]
        API[API 后端<br/>Java, Spring Boot<br/>处理业务逻辑]
        DB[(数据库<br/>SQL<br/>存储用户账户与交易信息)]
    end
    
    User[客户] -->|使用| WebApp
    WebApp -->|通过 HTTPS 调用| API
    API -->|读取/写入| DB

    style User fill:#08427b,color:#fff
    style WebApp fill:#1168bd,color:#fff
    style API fill:#1168bd,color:#fff
    style DB fill:#1a5276,color:#fff

为何此方案有效: 此可视化帮助利益相关者理解系统边界,而不会陷入代码细节中。子图将相关组件分组,样式使图表更具专业性。

示例 4:复杂的 OAuth 2.0 流程

对于更高级的认证场景,此示例展示了带有令牌刷新的 OAuth 2.0 授权码流程。

 

sequenceDiagram
    autonumber
    
    actor 用户
    participant 浏览器
    participant App 作为客户端应用
    participant Auth 作为认证服务器
    participant Resource 作为资源 API

    用户->>浏览器: 点击 "使用 OAuth 登录"
    浏览器->>App: 启动登录流程
    App->>浏览器: 重定向至认证服务器
    浏览器->>Auth: 认证请求

    Auth->>用户: 显示登录表单
    用户->>Auth: 输入凭据
    Auth->>用户: 显示授权页面
    用户->>Auth: 授予权限

    Auth->>浏览器: 重定向并附带授权码
    浏览器->>App: 授权码回调

    rect rgb(255, 240, 200)
        Note over App,Auth: 服务器间通信(安全)
        App->>Auth: 用授权码换取令牌
        Auth-->>App: 访问令牌 + 刷新令牌
    end

    App->>浏览器: 设置会话
    浏览器-->>用户: 已登录

    loop API 调用
        浏览器->>App: 请求数据
        App->>Resource: API 调用 + 访问令牌
        
        alt 令牌有效
            Resource-->>App: 数据
            App-->>浏览器: 响应
        else 令牌过期
            Resource-->>App: 401
            App->>Auth: 刷新令牌
            Auth-->>App: 新的访问令牌
            App->>Resource: 使用新令牌重试
            Resource-->>App: 数据
            App-->>浏览器: 响应
        end
    end

展示的高级功能:

  • rect创建一个带有自定义背景色的高亮区域

  • Note over添加解释性文字

  • loop显示重复的交互

  • alt用于处理错误情况的分支

示例 5:带子图的决策流程

对于包含多个阶段的复杂工作流,使用子图可使图表逻辑更清晰。

graph TD
    subgraph "构建阶段"
        A[代码检查] --> B[运行测试] --> C[构建构件]
    end
    
    subgraph "部署阶段"
        D[部署到预发布环境] --> E[运行集成测试]
        E --> F{测试通过?}
        F -->|是| G[部署到生产环境]
        F -->|否| H[回滚]
    end
    
    C --> D
    
    style A fill:#e1f5fe
    style B fill:#e1f5fe
    style C fill:#e1f5fe
    style D fill:#e8f5e8
    style E fill:#e8f5e8
    style F fill:#f3e5f5
    style G fill:#a5d6a7
    style H fill:#ffebee

最佳实践: 对于包含 5 个以上任务的工作流,使用子图将相关步骤分组。

通过流水线发布到 OpenDocs

一旦您的图表准备就绪,发布只需一键完成:

  1. 发送到流程:在 VPasCode 中,点击“发送到 OpenDocs 流程”。

  2. 可选备注:添加上下文信息,例如“v2.1 – 更新的认证流程”,以帮助识别版本。

  3. OpenDocs 插入:在 OpenDocs 中,编辑您的文档,点击插入 > 流程,然后从资产列表中选择您的图表。

该流程消除了手动下载和上传的繁琐操作。它保留了您模型的可编辑性,并确保每位利益相关者都能查看设计的最新版本。

AI 驱动功能

Visual Paradigm 的 AI 能力将绘图提升到了全新水平:

提示转图表:在 OpenDocs 中,使用 AI 聊天机器人通过自然语言生成图表。例如,输入“为支付处理流程创建一个时序图”,AI 将生成代码,您随后可在 VPasCode 中进行优化。

AI 代码错误修复:出现语法错误了吗?AI 可以检测并提出修复建议。

AI 翻译:需要本地化文档吗?使用 AI 将图表标签翻译成多种语言。

最佳实践与技巧

为最大化效率,请遵循以下最佳实践:

  • 使用描述性标题:为您的图表添加标题,以提高文档的清晰度。

  • 充分利用流程窗格:在 OpenDocs 中,使用流程窗格来整理已发送的图表。

  • 使用铅笔按钮进行迭代:如果图表需要更新,请在 OpenDocs 中点击铅笔图标将其重新打开至 VPasCode。进行修改后重新发送,即可无缝替换旧版本。

  • 保持图表版本控制:由于图表基于代码,您可以在 Git 中追踪变更,轻松回滚或比较版本。

结论

VPasCode 与 OpenDocs 的集成标志着技术文档领域的一次重大飞跃。通过将图表视为代码,您将获得更高的精确度、版本控制以及便捷的更新能力。无缝的流程消除了手动操作步骤,使工程师和写作者能够专注于内容本身,而非格式排版。

从在 VPasCode 中尝试使用简单的 Mermaid 图表并将其发送到 OpenDocs 开始。随着您逐渐熟悉,可进一步探索 AI 功能,并与更广泛的 Visual Paradigm 生态系统集成。通过这一工作流程,您的文档将不再只是事后补充——它将成为您开发过程中的一个动态、活跃的组成部分。