skycurtain
a9eaaa6023
- 新增品牌命名、商业化策略、SDK视觉噪音处理、可视化库设计和系统架构文档 - 更新开发规则，明确禁止主动修改项目源代码文件 - 所有文档均为中文编写，用于记录项目设计讨论和决策
110 lines
6.6 KiB
Markdown
110 lines
6.6 KiB
Markdown
# Structrail 系统架构设计与技术选型
|
||
|
||
本文档总结了 Structrail 平台的技术架构决策，包括 Monorepo 策略、服务拆分原则以及前后端架构方案的对比分析。
|
||
|
||
## 1. 总体架构策略：Monorepo (单体仓库)
|
||
|
||
考虑到 Structrail 项目涉及多语言 SDK、统一的协议定义、前端可视化组件以及后端执行服务，我们决定采用 **Monorepo** 架构。
|
||
|
||
### 核心收益
|
||
1. **单一事实来源 (Single Source of Truth)**：协议定义 (`@structrail/protocol`) 作为核心资产，被前端、后端、SDK 共同引用。协议变更时，所有依赖方均可即时感知（类型检查报错），避免版本割裂。
|
||
2. **原子化提交 (Atomic Commits)**：由于协议变更往往涉及多端修改（如 ArrayTracer 新增指令 -> 前端渲染逻辑更新 -> SDK 实现更新），Monorepo 允许在一个 Commit 中完成所有相关修改，保证系统一致性。
|
||
3. **统一版本管理**：便于统一管理多语言 SDK 的版本发布节奏。
|
||
4. **开发体验**：利用 `pnpm workspace` 和 `Turborepo` 等工具，实现高效的依赖管理和增量构建。
|
||
|
||
## 2. 服务架构设计
|
||
|
||
Structrail 的业务特性决定了其架构必须采用 **动静分离** 的策略，将轻量级的业务逻辑与重量级的代码执行隔离。
|
||
|
||
### 2.1 核心服务拆分
|
||
|
||
| 服务模块 | 职责描述 | 技术特征 |
|
||
| :--- | :--- | :--- |
|
||
| **Web (业务层)** | 用户界面、题目管理、社区互动、鉴权 | I/O 密集型，重交互，适合快速开发 |
|
||
| **API (接口层)** | 业务逻辑处理、数据转发、RPC 服务 | 高并发，低延迟，连接 Web 与 Runner |
|
||
| **Runner (执行层)** | 代码编译、沙箱运行、Trace 数据生成 | CPU 密集型，高风险，需独立部署与资源隔离 |
|
||
| **Protocol (共享层)** | 核心协议定义、类型声明、常量 | 纯代码库，无运行时依赖 |
|
||
|
||
### 2.2 架构方案对比
|
||
|
||
针对 Web 与 API 的实现，我们探讨了两种主流方案。两种方案均可行，且在 Monorepo 下都能实现 **100% 的端到端类型安全**。
|
||
|
||
#### 方案 A：Next.js 全栈架构 (SSR 优先)
|
||
* **架构描述**：Web 与 API 合二为一，直接在 Next.js 的 Server Actions / Route Handlers 中处理业务逻辑，并调用 Runner 服务。
|
||
* **优势**：
|
||
* **开发效率极致**：无 API 胶水层，前后端代码在同一文件中，调用后端函数像调用本地函数一样自然。
|
||
* **SSR 支持**：对 SEO 友好，首屏加载快（适合题目详情页、文档页）。
|
||
* **生态丰富**：Vercel/Next.js 生态拥有大量现成组件。
|
||
* **劣势**：
|
||
* **部署绑定**：较强依赖 Node.js Runtime 或 Vercel 平台。
|
||
* **边界模糊**：Server Actions 可能导致前后端代码耦合，心智负担较重。
|
||
|
||
#### 方案 B：React (SPA) + Hono (API) 前后端分离 (CSR + Edge 优先)
|
||
* **架构描述**：
|
||
* **Web**: 纯 React SPA，通过 CDN 分发。
|
||
* **API**: 独立 Hono 服务，提供 RPC 接口。
|
||
* **通信**: 通过 `hono/client` 实现类型安全的 RPC 调用。
|
||
* **优势**：
|
||
* **物理边界清晰**：前端关注 UI 交互，后端关注数据处理，职责分明。
|
||
* **部署极其灵活**：前端可部署至任何静态托管（OSS/Netlify），后端可部署至 Edge（Cloudflare Workers/Deno）或容器。
|
||
* **高性能**：Hono 基于 Web Standards，冷启动快，资源占用极低。
|
||
* **类型安全**：通过 Monorepo 导出 API 类型 (`AppType`)，前端直接引用，实现与 tRPC 类似的开发体验。
|
||
* **劣势**：
|
||
* **SEO 略弱**：纯 SPA 对 SEO 不如 SSR 友好（虽然可以通过预渲染解决）。
|
||
* **初期搭建成本**：需配置两个独立应用及通信链路。
|
||
|
||
### 2.3 结论与推荐
|
||
|
||
**推荐采用 Monorepo 架构，并根据团队偏好选择方案 A 或 B。**
|
||
|
||
* 如果更看重 **SEO** 和 **快速验证原型**，推荐 **方案 A (Next.js)**。
|
||
* 如果更看重 **架构清晰度**、**部署灵活性 (Edge)** 和 **前后端解耦**，推荐 **方案 B (React + Hono)**。
|
||
* *注：考虑到 Structrail 的编辑器交互极其复杂（重客户端逻辑），且 Runner 服务天然适合独立部署，**方案 B** 在长期维护和扩展性上可能更具优势。*
|
||
|
||
## 3. 建议的项目目录结构
|
||
|
||
无论选择哪种方案，Monorepo 的基础结构应保持一致：
|
||
|
||
```text
|
||
structrail/
|
||
├── apps/ # 应用程序（业务层）
|
||
│ ├── web/ # [React/Next.js] 平台前端
|
||
│ │ └── ... (Visualizer 组件调用)
|
||
│ ├── api/ # [Hono/Node] 业务后端 (如果是方案 B)
|
||
│ ├── runner/ # [Go/Rust] 代码执行沙箱服务
|
||
│ └── docs/ # [VitePress] 文档站点
|
||
│
|
||
├── packages/ # 共享库（核心资产）
|
||
│ ├── protocol/ # 核心协议定义 (JSON Schema, TS Interfaces)
|
||
│ │ ├── index.ts # 导出 Tracer 类型、指令定义
|
||
│ │ └── schema.json # 用于校验 Trace 数据的 Schema
|
||
│ ├── sdk-ts/ # TypeScript SDK 实现
|
||
│ ├── ui/ # 通用 UI 组件库 (可选)
|
||
│ └── eslint-config/ # 统一的代码规范配置
|
||
│
|
||
├── sdks/ # 多语言 SDK (非 JS/TS 生态)
|
||
│ ├── c/ # C 语言 SDK (Makefile)
|
||
│ ├── python/ # Python SDK (Poetry)
|
||
│ ├── java/ # Java SDK (Maven/Gradle)
|
||
│ └── ...
|
||
│
|
||
├── tools/ # 工程化脚本
|
||
│ └── scripts/ # 批量发布、协议生成脚本
|
||
│
|
||
├── package.json # Root package.json
|
||
├── pnpm-workspace.yaml # pnpm workspace 配置
|
||
└── turbo.json # Turborepo 构建编排配置
|
||
```
|
||
|
||
## 4. 关键技术栈建议
|
||
|
||
* **包管理器与运行时**: `Bun` (All-in-One 工具链，提供极致的安装速度和高性能运行时)
|
||
* 作为包管理器替代 `npm/pnpm`
|
||
* 作为脚本执行器替代 `ts-node`
|
||
* 作为测试运行器替代 `Jest/Vitest`
|
||
* **构建系统**: `Turborepo` (任务编排、远程缓存)
|
||
* **前端框架**: `React` (配合 Vite)
|
||
* **后端框架**: `Hono` (完美适配 Bun 运行时，性能卓越)
|
||
* **Runner 语言**: `Go` 或 `Rust` (高性能、并发强、安全性好)
|
||
* **API 通信**: `Hono RPC` (如果分离) 或 `Server Actions` (如果全栈)
|