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

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项目框架， 该项目启动之后的效果如下图：

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

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
1

• 这里是全局安装c4builder 的扩展。
  安装的画面如下：
  

2. 创建项目： 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
2
3
4
5
6
7
8
9
10
11
12
13
14

3. 命名行切换到项目目录： cd c4project

4. 项目配置： 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

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

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

docsify serve docs
1

在浏览器输入： 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

在线示例

• 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:



1
2
3
4
5
6

解决方法：

set PUPPETEER_SKIP_DOWNLOAD=true


1
2
3

完整解析：

此错误信息表明尝试下载 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

# 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
2
3
4
5
6
7

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

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

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

*****
*****

1
2
3
4
5
6
7