C4BUILDER—用于构建C4模型图的Web项目

阳光穿透心脏的1/2处 2024-03-02 09:52 21阅读 0赞

### c4builder是什么？ ###

c4builder： 字面理解是产生C4架构图的构建器。

*  c4builder是一个轻量级的nodejscli工具，用于仅使用文本构建、维护和共享软件体系结构项目。
 *  c4builder是一种架构设计工具，可以帮助开发人员和架构师描述和可视化软件系统的架构，包括系统的组件、关系、依赖和交互。它基于C4模型（Context、Container、Component和Code）和DSL（Domain-specific language）的概念，使得设计者可以创建清晰、可维护、易于理解的架构图，并支持自动生成代码，提高系统的可靠性、可维护性和协作性。  
    c4builder的主要思想是：开发人员可以使用熟悉的工具来定义软件。

与git相结合，这些文档中定义的体系结构的任何更改都很容易跟踪。Pull请求、分支、cherry picks和所有git特性都可以作为一种更容易的方式来跟踪项目体系结构的变化。

到这估计还是有点晕， c4builder 到底是什么呢？  
c4builder 是基于NodeJS 一个扩展功能模块， 安装完成之后，提供了一些命令行， 使用命令行可以快速的创建一个可以用来编写C4模型图的Web项目框架， 该项目启动之后的效果如下图：  
![在这里插入图片描述][1d29955689dd478e932613520e756f76.png]

有了这个之后：开发人员， 项目管理，用户以及厂商等就可以很容易的在线查看这些系统相关的架构图了。

### c4builder 的依赖项目 ###

c4builder依赖于下面项目：

*  PlantUml ：通过纯文本创建图表。https://plantuml.com/zh/
 *  Markdown ：从普通文本创建富文本文档。https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
 *  C4Model : C4模型, https://c4model.com/
 *  C4 PlantUML： 生成PlantUML图的C4语法支持 https://github.com/plantuml-stdlib/C4-PlantUML
 *  Docsify ： 基于markdown文件创建一个单网页站点。 https://docsify.js.org/
 *  vscode-plantuml ： 用于visualstudio代码的vscode-plantuml插件，用于在设计时查看图表， https://github.com/qjebbs/vscode-plantuml

建议先熟悉上面内容

### 创建 c4项目 ###

1.  安装c4builder

npm i -g c4builder

*  这里是全局安装c4builder 的扩展。  
    安装的画面如下：  
    ![在这里插入图片描述][e9b0f9b118c74f07a9a5951a13ed20b0.png]

1.  创建项目： `c4builder new`

这一步会要求一些输入， 比如项目名等等， 可以一直点击回车就可以， 这里的项目名是 c4project

E:\workspace\nodejs\c4builder>c4builder new
           _  _   _           _ _     _
       ___| || | | |__  _   _(_) | __| | ___ _ __
      / __| || |_| '_ \| | | | | |/ _` |/ _ \ '__|
     | (__|__   _| |_) | |_| | | | (_| |  __/ |
      \___|  |_| |_.__/ \__,_|_|_|\__,_|\___|_|
    
    Blow up your software documentation writing skills
    
    This will create a new folder with the name of the project
    ? Project Name c4project
    ? PlantUML version: latest (compatible with plantuml online server)
    ? Include the VSCode autocomplete? Yes
    true

1.  命名行切换到项目目录： `cd c4project`
2.  项目配置： `c4builder`

这里同样需要一些交互输入，可以默认一直回车。

E:\workspace\nodejs\c4builder\c4project>c4builder
           _  _   _           _ _     _
       ___| || | | |__  _   _(_) | __| | ___ _ __
      / __| || |_| '_ \| | | | | |/ _` |/ _ \ '__|
     | (__|__   _| |_) | |_| | | | (_| |  __/ |
      \___|  |_| |_.__/ \__,_|_|_|\__,_|\___|_|
    
    Blow up your software documentation writing skills
    
    if you created the project using the 'c4model new' command you can just press enter and go with the default options to get a basic idea of how it works.
    
    you can always change the configuration by running > c4builder config
    
    ? HomePage Name MyHome
    ? Root documentation folder src
    ? Destination folder docs
    ? Compilation format: Generate multiple pdf files, Generate a single complete pdf file, Generate website
    ? Change the default docsify theme? //unpkg.com/docsify/lib/themes/vue.css
    ? Support search on navbar? true
    ? Include a repository url?
    ? Path to a specific Docsify template?
    ? Change the default serve port? 3000
    ? Add a custom css for the pdf (filename)? xx\node_modules\c4builder\pdf.css
    ? Compilation format: Include breadcrumbs, Place diagrams before text
    ? PlantUML Server URL https://www.plantuml.com/plantuml
    ? Diagram Image Format svg
    ? Change the default charset UTF-8
    
    building documentation in ./docs
    parsed 7 folders
    generating docsify site
    generating complete pdf file

这个命令会在项目目录下创建docs , src 等目录或文件。

1.  启动项目 ，可以使用`c4builder site` ，也可以使用docsify启动。  
    `c4builder site` 或者

docsify serve docs

在浏览器输入： http://localhost:3000/\#/ 查看效果。

### c4builder ###

的命令参数

可以通过 `c4builder --help` 查看命名参数。

*  `-V` 或者`--version` , 版本号
 *  `new` : 根据模板创建项目
 *  `config` ： 更改当前目录的配置
 *  `list`： 列出当前的配置
 *  `reset`： 清除所有配置
 *  `site`： 为生成的站点提供服务， 也就是启动服务
 *  `-w` 或者 `--watch`： 关注变更和重构
 *  `docs`： 配置选项的简要说明
 *  `-p 端口`, `--port 端口` ： 服务的端口
 *  `-h` 或者`--help` ： 帮助

默认情况下，运行c4builder将尝试构建项目  
如果没有设置配置，它会要求它，然后进行实际的构建。配置后仅运行c4builder将不再显示向导。  
要在第一次构建后更改配置，只需运行c4builder-config即可。默认值将是之前设置的配置，因此您可以编辑感兴趣的选项。

### 项目结构 ###

产生的项目包含两个主要的目录： 源代码目录(src)和目标目录(docs)。  
遵循C4模型，src目录表示Systems/Containers/Components或任何其他类型的有关软件的信息。

目录结构如下：

│   .gitignore
    │   README.MD
    ├───docs # 目标目录
    └───src # 源目录
        │   context.md
        │   context.puml
        └───Internet Banking System
            │   system.puml
            │   system.md
            ├───API Application
            │       container.puml
            │       container.md
            └───Single Page Application
                │   container.puml
                │   container.md
                └───Additional Information
                        additionalDetails.md
                        class.puml
                        sequence.puml
                        class.1.md

目标文件夹由生成过程自动生成，可以有各种格式。该文件夹可以以不同的方式提供系统/容器/组件的深入式视图。要么将其作为一个站点推送到gitpages，直接在存储库中用作可导航的标记，要么生成pdf并使用传统邮件。

### 在线示例 ###

*  [https://github.com/adrianvlupu/C4Builder-Demo][https_github.com_adrianvlupu_C4Builder-Demo]

### 安装问题: Failed to set up Chrome r116.0.5845.96! Set "PUPPETEER\_SKIP\_DO ###

完整的错误信息

npm ERR! command C:\windows\system32\cmd.exe /d /s /c node install.js
    npm ERR! ERROR: Failed to set up Chrome r116.0.5845.96! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.
    npm ERR! Error: write EPROTO 206C0000:error:0A000152:SSL routines:final_renegotiate:unsafe legacy renegotiation disabled:c:\ws\deps\openssl\openssl\ssl\statem\extensions.c:922:

解决方法：

set PUPPETEER_SKIP_DOWNLOAD=true

完整解析：

此错误信息表明尝试下载 Chrome (用于 Puppeteer，一个 Node.js 的无头浏览器库) 失败，可能是由于 SSL 认证问题所导致的。
    
    几种可能的解决方案如下：
    
    1. 通过环境变量设置来跳过 Puppeteer 的下载步骤。你可以在安装之前设置`PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`，使得 Puppeteer 安装过程中跳过 Chromium 的下载。但是这种方式需要你手动指定或者已经安装好可以使用的 Chromium 浏览器。
    
    ```bash
    # Windows
    set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
    npm install puppeteer
    
    # Linux/macOS
    PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install puppeteer

1.  如果是在公司或者学校网络下，可能会需要一个代理来进行外网访问。可以通过环境变量设置来配置代理：

# Windows
    set HTTP_PROXY=http://your-proxy.com:8080
    set HTTPS_PROXY=http://your-proxy.com:8080
    
    # Linux/macOS
    export HTTP_PROXY=http://your-proxy.com:8080
    export HTTPS_PROXY=http://your-proxy.com:8080

1.  升级Node.js 和 npm 到最新版本。这可能会解决 SSL 握手问题。可以通过 Node.js 官方网站下载最新版本的 Node.js 和 npm。

注意：以上解决方法可能需要根据具体实际情况进行一些调整。

## 参考与链接
    * 官方站点： [https://adrianvlupu.github.io/C4-Builder/#/](https://adrianvlupu.github.io/C4-Builder/#/)
    
    *****
    *****

[1d29955689dd478e932613520e756f76.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/02/f7e7cd81b34a4ded81a0523f7b2c2518.png
[e9b0f9b118c74f07a9a5951a13ed20b0.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/02/ef238b16300c43ac9dd64529eaa6e5f0.png
[https_github.com_adrianvlupu_C4Builder-Demo]: https://github.com/adrianvlupu/C4Builder-Demo