Archify architecture Schema手册：components、boundaries、connections字段详解

Archify architecture Schema手册components、boundaries、connections字段详解【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 是一款把系统描述渲染成美观架构图architecture diagram的开源工具它的 architecture 模式用一份 JSON 文件声明式地描述架构图核心就是components组件、boundaries边界和connections连接三大字段。本手册带你逐字段读懂 archify/schemas/architecture.schema.json从零写出一张可验证、可导出的架构 Diagram并了解每种字段的取值规则和常见错误。一、architecture Schema 的顶层结构一份 architecture 类型的图表文件必须包含以下四个字段其余均为可选{ schema_version: 1, diagram_type: architecture, meta: { title: My System }, components: [ ... ] }字段必填说明schema_version✅固定为1锁定 IR 契约保证旧文件在新版本上仍可渲染diagram_type✅固定为architecturemeta✅图表元信息至少要有titlecomponents✅组件节点数组至少 1 个boundaries❌区域 / 安全组边界用来把组件框起来connections❌组件之间的连线与流向layout❌可选的 grid 网格布局参数cards❌渲染在图表下方的说明卡片整个 Schema 在每一层都设置了additionalProperties: false——写一个不存在的字段会直接报错而不是被悄悄忽略。这一点新手最容易踩坑拼写错了字段名校验器会立刻告诉你错在哪。完整的共享枚举定义在 archify/schemas/common.schema.json 中Schema 说明文档见 archify/schemas/README.md。二、components 字段详解架构图的节点components是一个数组每个元素描述一个框节点。必选字段只有三个id、type、label。{ id: api, type: backend, label: API Server, sublabel: FastAPI :8000, tag: JWT PKCE, pos: [670, 300], size: [130, 60] }2.1 每个字段在画什么id节点的唯一标识格式为字母开头后接字母、数字、下划线或连字符^[a-zA-Z][a-zA-Z0-9_-]*$。它是connections里from/to引用的目标也是meta.views中聚焦点的引用键所以务必取稳定、语义化的名字例如api、db而不是node1。type节点类型决定颜色、图标和图例归属共 7 种取值type含义典型例子frontend前端 / 浏览器侧Web App、React SPAbackend后端服务API Server、Workerdatabase存储PostgreSQL、Rediscloud云基础设施CDN、S3、Load Balancersecurity安全组件Auth Provider、API Gatewaymessagebus消息队列SQS、Kafkaexternal系统外部角色Users、第三方支付label节点主标题必填且不能为空。sublabel可选节点副标题适合写技术细节如primary :5432。tag可选节点角落的小标签用来标注端口、协议或归属团队。brand可选品牌标识可填内置品牌 ID 或{ url, sha256 }形式固定下来的图片地址渲染时会在节点左上角显示对应的品牌图标。sources可选1–3 条源码证据指向真实仓库里的path、line/end_line。配合--repo-root使用时Archify 会用 Git 验证提交和代码行是否真实存在让架构图有据可查。2.2 两种定位方式pos 与 row/col节点摆放有两种写法pos优先pos: [x, y]size: [宽, 高]自由坐标定位最直观。size的宽高必须都大于 0。row/col网格定位需要配合顶层layout字段使用layout: { mode: grid, cols: 4, origin: [40, 80], cellW: 130, cellH: 64 }网格参数由 archify/renderers/architecture/grid.mjs 处理默认值为cols: 4、gapX: 30、gapY: 40。注意两点col不能超出layout.cols - 1两个组件不能占用同一个格子rowcol相同会报诊断错误。 官方建议一张架构图保持6–12 个主要组件用一条从左到右的主干加短分支来组织external类型如用户在事实上位于系统外时就不要放进边界框里。三、boundaries 字段详解region 与 security-groupboundaries用来表达哪些组件属于同一个部署/信任边界每个边界必选kind、label、wraps三个字段{ kind: region, label: AWS Region: us-west-2, wraps: [cdn, lb, api, cache, db], pad: 20 }字段说明kind边界类型只有两种region部署区域橙色实线框和security-group安全组红色虚线框label边界名称显示在框的左上角wraps被这个框圈住的组件id数组至少 1 个pad可选边界框相对内部组件的内边距值越大框留白越多几个实用规则边界可以嵌套例如security-group框在region框内部就像安全组属于某个区域。边界只表达归属不代替连接。两个组件之间的调用关系仍然要靠connections画出来。只框真实的边界。归属、信任域、进程隔离、部署隔离才值得画框纯粹为了美观而框起来会误导读者。在启用meta.engineering_profile: deployment-ownership生产部署评审模式时边界还有更强的约束每个非 external 组件必须属于且仅属于一个region每个database必须位于某个security-group内文档必须同时包含两类边界。规则详见 archify/references/authoring-contract.md。四、connections 字段详解让箭头会说话connections描述组件之间的连线必选字段是from和to都引用组件id其余字段用于控制线的样式、走线和标签{ id: jwt-verification, from: auth, to: api, label: verify JWT, variant: security, fromSide: right, toSide: top, via: [[620, 142], [620, 246], [735, 246]], route: auto, width: 2 }4.1 variant线的语气variant控制连线的视觉语义共 4 种variant用途default普通调用关系emphasis主干路径视觉加重security安全相关链路红色虚线如认证、加密传输dashed次要 / 异步 / 静态资源链路4.2 走线控制fromSide、toSide、route、viafromSide/toSide指定箭头从哪个边出发 / 进入取值为left、right、top、bottom。不写时渲染器自动选边。left/right改变水平端点top/bottom改变垂直端点。route走线策略取auto默认自动选路并自动展开共享端口、straight直线、orthogonal-h水平优先折线、orthogonal-v垂直优先折线。via手动指定折点坐标数组[x, y]对。一旦写了via走线完全由你接管适合精修复杂路径。width线宽最小0.5。4.3 标签微调label、labelAt、labelDx/Dy、labelSegmentlabel是连线上的文字如HTTPS、SQL它是语义数据而不是装饰——协议、动作、方向、同步/异步、跨边界机制都值得写。当标签放不下时按以下顺序修复而不是直接删掉用labelAt指定标签的精确坐标用labelDx/labelDy做像素级微调用labelSegment把标签移到第 N 段折线上最后才缩短文字保留原意。另外可选的id字段同样用共享 ID 规则可以给连线一个稳定的#relationid查看器深链重排数组后链接依然有效。五、渲染效果一次看懂三大字段下面这张架构图由 archify/examples/web-app.architecture.json 渲染而来正好完整演示了三个字段如何协作components声明了 Users、CloudFront、API Server 等 10 个节点boundaries用region框出了 AWS 区域、用security-group框住了 LB 与 APIconnections则用emphasis画出主请求路径、用security虚线表示 JWT 校验、用dashed表示静态资源与异步任务。生成后的 HTML 是完全自包含的——内置明暗主题切换、引导视图meta.views、故事播放、路径追踪和 PNG/JPEG/SVG/WebP/WebM 导出打开即分享无需任何依赖六、新手避坑清单未知字段会报错Schema 全层additionalProperties: false写错字段名比如colour、label2校验立即失败按诊断信息里的路径和id/label提示修改即可。connections的from/to必须引用已存在的组件id跨集合的事实校验由 archify/renderers/shared/validator.mjs 完成拼错 id 会直接报诊断。节点重叠、标签压线是渲染器检查的几何问题与 Schema 校验是两道关卡。改完先跑validate再按诊断的code和supportedFixes修复不要一次猜多个几何参数。pos与row/col并存时pos优先row/col只是网格提示。语言选择meta.locale只支持en和zh-CN它只控制查看器的固定 UI 文案不会翻译你写的label。想写中文图表把所有label/sublabel写成中文并设locale: zh-CN即可。标题别复述图的内容meta.subtitle默认省略图本身就是解释。七、下一步完整字段与枚举archify/schemas/architecture.schema.json、共享定义 archify/schemas/common.schema.json可参考的两个完整实例archify/examples/web-app.architecture.json基础三层架构、archify/examples/production-deployment.architecture.json生产部署 所有权边界编写契约与几何规则archify/references/authoring-contract.md手动工作流validate / deliver / compare 命令docs/authoring-cookbook.md渲染器实现archify/renderers/architecture/render-architecture.mjs掌握components、boundaries、connections这三个数组你就掌握了 Archify architecture 模式 90% 的表达能力——剩下的layout、cards、views只是锦上添花。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考