Skip to content

architecture.cn.mdx

Latest commit

 

History

History
106 lines (84 loc) · 4.7 KB

architecture.cn.mdx

File metadata and controls

106 lines (84 loc) · 4.7 KB
title 架构
description 深入了解 ObjectDocs 的架构、目录结构和数据流。

import { Layers, FileJson, Code, FileText } from 'lucide-react';

架构

ObjectDocs 建立在严格的 关注点分离 (Separation of Concerns) 理念之上，将表现层、配置层和内容层完全分开。

核心原则

1. 配置即代码 (Configuration as Code)

与传统的文档站点将结构硬编码在 React 组件中不同，ObjectDocs 将文档组织视为 数据。

} title="元数据驱动"> 导航、侧边栏和页面顺序均由 JSON 文件定义，而非 React 代码。 } title="逻辑无关"> 内容创建者不需要关心路由逻辑或 UI 组件的实现细节。

2. 本地化内容管理

每个文档目录都是自包含的。如果你要新增一个章节，只需在该目录下创建文件并更新同级的 meta.json。这使得在大型团队中进行多人协作变得不容易冲突。

目录结构

初始化后的标准 ObjectDocs 项目结构：

.
├── content/               # [数据层] 所有文档文件
│   ├── package.json       # 脚本: dev, build, start (由 init 创建)
│   ├── .objectdocs/       # 站点引擎 (从 @objectdocs/site 复制, gitignored)
│   │   ├── node_modules/  # 依赖 (初始化时安装)
│   │   ├── .next/         # Next.js 构建缓存 (开发)
│   │   └── out/           # 静态构建输出 (生产)
│   ├── docs.site.json     # 全局配置 (导航, Logo, 品牌, i18n)
│   ├── public/            # 静态资源 (在构建/开发时复制到站点)
│   └── docs/
│       ├── meta.json      # 目录结构 & 页面顺序
│       └── index.mdx      # 文档内容
├── out/                   # 最终构建输出 (从 content/.objectdocs/out 复制)
├── .gitignore             # 自动更新以排除 content/.objectdocs
├── package.json           # (可选) 根目录 package.json
└── ...

核心组件:

  • content/.objectdocs/: 包含来自 @objectdocs/site 包的完整 Next.js 站点引擎
  • content/package.json: 由 init 命令创建，包含 dev/build/start 脚本
  • 构建流程: content/.objectdocs/out → out/ (根目录)
  • 环境: 命令在 content/.objectdocs 内运行，DOCS_DIR 环境变量指向文档目录

数据流向

初始化流程

  1. 初始化命令: npx @objectdocs/cli init
  2. 包复制: 整个 @objectdocs/site 包 → content/.objectdocs
  3. 脚本创建: 创建 content/package.json 并添加 dev/build/start 脚本
  4. 依赖安装: 在 content/.objectdocs 中运行 npm install
  5. Gitignore 更新: 添加排除生成文件的规则

开发流程

  1. 启动: 运行 cd content && npm run dev
  2. 配置同步: 复制 docs.site.json 和 public/ 到 content/.objectdocs
  3. 环境: 设置 DOCS_DIR 环境变量指向 content/docs
  4. 监听: 监控 docs.site.json 的变化并自动重启
  5. 服务器: Next.js 开发服务器在端口 7777 上运行（默认）

构建流程

  1. 构建时: 运行 cd content && npm run build
  2. 配置同步: 复制 docs.site.json 和 public/ 到 content/.objectdocs
  3. 环境: 设置 DOCS_DIR 环境变量
  4. MDX 解析: Fumadocs 从 DOCS_DIR 读取所有 .mdx 文件
  5. 元数据: 解析 meta.json 文件构建导航树
  6. 渲染: Next.js App Router 将内容渲染为 React Server Components
  7. 输出:
    • 静态模式: content/.objectdocs/out → out/ (根目录)
    • 动态模式: content/.objectdocs/.next → .next/ (根目录)

运行流程 (静态)

  1. 服务: 从 out/ 目录提供生产构建
  2. 资源: 静态 HTML、CSS、JS 和图片
  3. CDN: 可以部署到 Vercel、Netlify 或任何静态托管

运行流程 (动态)

  1. 启动: 运行 cd content && npm run start
  2. 服务器: 具有 ISR/SSR 功能的 Next.js 生产服务器
  3. 交互: 客户端组件（如 <Cards>, <Steps>）在浏览器中激活

为什么这样设计？

这种架构使得我们能够：

  • 清晰分离: 将文档内容与站点引擎完全分离
  • 项目无关: 可以在任何现有项目中添加文档而不污染根目录
  • 版本控制: 整个站点引擎都被 gitignore，只跟踪内容
  • 多产品支持: 通过切换不同的 content 目录，可以支持多个产品的文档
  • 低代码集成: 因为内容与 UI 分离，我们可以更容易地注入动态的低代码组件演示
  • 轻松更新: 通过重新运行 init 或更新 CLI 版本来更新站点引擎