Files

skycurtain a9eaaa6023 docs: 新增项目文档并更新开发规则

- 新增品牌命名、商业化策略、SDK视觉噪音处理、可视化库设计和系统架构文档
- 更新开发规则，明确禁止主动修改项目源代码文件
- 所有文档均为中文编写，用于记录项目设计讨论和决策

2026-02-18 00:18:35 +08:00

6.6 KiB

Raw Blame History

Structrail 系统架构设计与技术选型

本文档总结了 Structrail 平台的技术架构决策，包括 Monorepo 策略、服务拆分原则以及前后端架构方案的对比分析。

1. 总体架构策略：Monorepo (单体仓库)

考虑到 Structrail 项目涉及多语言 SDK、统一的协议定义、前端可视化组件以及后端执行服务，我们决定采用 Monorepo 架构。

核心收益

单一事实来源 (Single Source of Truth)：协议定义 (@structrail/protocol) 作为核心资产，被前端、后端、SDK 共同引用。协议变更时，所有依赖方均可即时感知（类型检查报错），避免版本割裂。
原子化提交 (Atomic Commits)：由于协议变更往往涉及多端修改（如 ArrayTracer 新增指令 -> 前端渲染逻辑更新 -> SDK 实现更新），Monorepo 允许在一个 Commit 中完成所有相关修改，保证系统一致性。
统一版本管理：便于统一管理多语言 SDK 的版本发布节奏。
开发体验：利用 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 的基础结构应保持一致：

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 (如果全栈)

6.6 KiB Raw Blame History Unescape Escape