L0–L9 十层架构、节点类型与 CLI 技术参考
面向架构师与研发工具团队的 ArchRay Graph v2 技术词典:完整收录十层分层语义、三维空间分区、中英文别名及命令行全参数。
ArchRay Graph v2 定义了 10 个规范架构层(`client` 至 `observability`)、19 种节点类型(`kind`)与 14 种已知连接协议,支持 `tech`/`blueprint`/`glass`/`paper` 四套皮肤,内置 212 条技术栈识别提示与 167 枚离线矢量品牌徽标。
1. L0–L9 十个规范架构层与 3D 空间象限
每个模块归属的 canonical layer 不仅决定三维空间纵深与体块形态,还直接绑定斜杠命令和 CLI `--layers` 的中英文别名筛选:
| 层级 | 标准层 ID | 可用中英文别名 | 3D 空间分区与体块造型 | 典型技术栈示例 |
|---|---|---|---|---|
| L0 | client | frontend, client, 前端, 客户端 | 顶层入口 · 倾斜屏幕薄板 | Next.js, Vue 3, React Native, Electron |
| L1 | edge | network, edge, 网络, 边缘 | 上层接入缓冲 · 宽幅接入层板 | Cloudflare, Nginx, Envoy, Traefik |
| L2 | gateway | security, gateway, 网关, 鉴权 | 鉴权枢纽 · 网关分流棱台 | Kong, Better Auth, Clerk, Keycloak |
| L3 | service | service, backend, 后端, 服务 | 中央主塔 · 圆角核心方台 | NestJS, FastAPI, Spring Boot, Go |
| L4 | async | async, worker, 异步, 队列 | 左侧任务翼 (-X) · 胶囊任务体 | Kafka, BullMQ, Socket.IO, Celery |
| L5 | data | data, db, 数据, 存储 | 核心存储底座 · 三段存储圆柱 | PostgreSQL, Redis, Elasticsearch, S3 |
| L6 | ai | ai, model, AI, 智能 | 智能侧翼 (-X) · 推理核心体 | Gemini, Claude, Qdrant, pgvector |
| L7 | external | external, saas, 外部, 三方 | 右侧独立轨 (+X) · 虚线外部边界 | Stripe, Resend, Twilio, OAuth SaaS |
| L8 | platform | platform, infra, 平台, 运维 | 底层地基 · 基础设施宽台 | Docker, Kubernetes, Terraform, Actions |
| L9 | observability | observability, obs, 可观测, 监控 | 底层遥测面 · 遥测追踪平面 | OpenTelemetry, Prometheus, Grafana, Sentry |
2. 19 种节点类型(kind)与 14 种连线协议
212 条分类提示会优先匹配 167 枚内嵌矢量徽标;如未识别到特定产品徽标,会自动匹配对应角色的三维体块图标:
- 19 种已知节点 kind:client、cli、gateway、service、worker、function、library、module、database、cache、queue、storage、search、external-api、ai-model、config、group、saas、archive(也允许自定义字符串)。
- 14 种已知连接协议:http、grpc、graphql、ws、sse、amqp、kafka、sql、redis、ipc、import、fs、llm、event。
- 4 套视觉主题(--style):tech(科技深空,默认)、blueprint(架构蓝图)、glass(极光磨砂)、paper(高对比打印白底)。
- 3 档动效控制(--motion):full、calm、off(遵循系统减弱动效偏好)。
3. Graph v2 极简双语 JSON 示例
`.archray/graph.json` 严格禁止大模型写入像素坐标,仅表达节点、父子层级与连线关系:
{
"schemaVersion": "2.0",
"meta": { "name": { "zh-CN": "Acme 系统", "en": "Acme App" }, "locales": ["zh-CN", "en"], "generatedAt": "2026-11-20T00:00:00Z" },
"layers": [
{ "id": "client", "name": { "zh-CN": "客户端", "en": "Client" }, "order": 0 },
{ "id": "service", "name": { "zh-CN": "核心服务", "en": "Services" }, "order": 3 },
{ "id": "data", "name": { "zh-CN": "数据存储", "en": "Data" }, "order": 5 }
],
"nodes": [
{ "id": "web", "layer": "client", "kind": "client", "name": { "zh-CN": "Web 控制台", "en": "Web App" }, "sourcePaths": ["apps/web/src/app/page.tsx"] },
{ "id": "api", "layer": "service", "kind": "service", "name": { "zh-CN": "订单服务", "en": "Order API" }, "sourcePaths": ["apps/api/src/order.ts"] },
{ "id": "pg", "layer": "data", "kind": "database", "name": { "zh-CN": "PostgreSQL 主库", "en": "PostgreSQL" }, "tech": ["PostgreSQL"], "sourcePaths": ["prisma/schema.prisma"] }
],
"edges": [
{ "id": "e1", "from": "web", "to": "api", "protocol": "http" },
{ "id": "e2", "from": "api", "to": "pg", "protocol": "sql" }
]
}
4. 全部 CLI 子命令速查
在项目根目录直接调用 `./.archray/archray`(Windows 下使用 `.archray\archray.cmd`):
| CLI 命令 | 功能与常用选项 |
|---|---|
| ./.archray/archray doctor | 检查 Node.js 20+、内嵌 Schema、查看器与图标资源完整性 |
| ./.archray/archray validate .archray/graph.json | TypeBox 校验、唯一 ID 冲突检测、双语完整度与 UTF-8 无乱码检测 |
| ./.archray/archray build <json> [选项] | 离线构建单文件 HTML(支持 --layers、--style、--lang、--motion、--output、--force、--no-open) |
| ./.archray/archray update [--check] | 只读检查新版本或 SHA-256 校验更新工具链(保留现有图谱成果) |
| ./.archray/archray uninstall [--dry-run] [--purge] | 预览或卸载适配器与命令文件,加 --purge 清除全部产物 |
常见问题
每个仓库必须把 10 层全部填满吗?
不需要。建议按仓库真实复杂度只声明 3–6 个实际存在的层(例如官网在线沙盒 FreshMart 只使用了 5 层),同时每层归属会自动匹配十层布局规则。
子模块怎么归属到父节点实现自动折叠?
在平铺 `nodes` 数组中为子节点填写 `parent: "<父节点ID>"`,确保全库节点 ID 唯一(例如 `order/repo`),缩放到全景比例时引擎会自动折叠显示 `+N` 数量标记。
自定义调好的 3D 角度、隐藏层与筛选状态如何发给别人?
点击画布顶部工具栏导出 `view.json` 并发送,对方在你导出的同一份 `index.html` 中导入该 `view.json` 即可还原完全相同的视角与高亮状态。
内嵌的 167 枚技术栈品牌图标会走外部 CDN 请求吗?
绝对不会。所有 SVG 图标全部来自构建期封装的离线图标包,生成的单文件 HTML 断网环境下照常高清展示。