Skip to content

Commit 9d02e71

Browse files
hotlonghotlong
authored
创建 roadmap_core.md
1 parent ef29eb6 commit 9d02e71

1 file changed

Lines changed: 153 additions & 0 deletions

File tree

‎docs/roadmap_core.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
你的直觉是对的。让我基于代码现实来做一个精确对比：
2+
3+
---
4+
5+
## Core vs Runtime：职责解剖
6+
7+
### 用 OS 类比来理解
8+
9+
```
10+
┌───────────────────────────────────────────────┐
11+
│ @objectstack/spec = 宪法 (Constitution) │ ← 纯 Schema, 零运行时
12+
├───────────────────────────────────────────────┤
13+
│ @objectstack/core = 内核 (Kernel) │ ← 进程调度、内存管理、系统调用
14+
├───────────────────────────────────────────────┤
15+
│ @objectstack/runtime = 标准库 (libc/glibc) │ ← 包装内核 + HTTP + 应用加载
16+
├───────────────────────────────────────────────┤
17+
│ @objectstack/objectql = 文件系统 (ext4) │ ← 数据引擎
18+
│ @objectstack/rest = 网络栈 (TCP/IP) │ ← HTTP CRUD 路由
19+
│ @objectstack/metadata = 注册表 (Registry) │ ← 元数据管理
20+
└───────────────────────────────────────────────┘
21+
```
22+
23+
### 逐文件对比
24+
25+
#### `@objectstack/core` — 实际内容
26+
27+
```typescript name=core/src/index.ts url=https://github.com/objectstack-ai/spec/blob/ef29eb6b1823e8fdc47916a5c14a46e2aedd7a90/packages/core/src/index.ts#L1-L41
28+
// 导出清单：
29+
export * from './kernel-base.js'; // ① ObjectKernelBase 抽象基类
30+
export * from './kernel.js'; // ② ObjectKernel 完整版（高级生命周期）
31+
export * from './lite-kernel.js'; // ③ LiteKernel 精简版
32+
export * from './types.js'; // ④ Plugin, PluginContext 接口
33+
export * from './logger.js'; // ⑤ ObjectLogger (Pino 封装)
34+
export * from './plugin-loader.js'; // ⑥ 插件加载器 + DI 容器 + 工厂模式
35+
export * from './api-registry.js'; // ⑦ API 注册表
36+
export * from './api-registry-plugin.js'; // ⑧ API 注册表插件
37+
export * as QA from './qa/index.js'; // ⑨ QA 测试框架
38+
export * from './security/index.js'; // ⑩ 安全（签名验证、配置校验、权限执行）
39+
export * from './utils/env.js'; // ⑪ 环境检测
40+
export * from './health-monitor.js'; // ⑫ 插件健康监控
41+
export * from './hot-reload.js'; // ⑬ 热更新状态管理
42+
export * from './dependency-resolver.js'; // ⑭ 依赖解析器
43+
```
44+
45+
| # | 模块 | 行数 | 职责 | 是否属于"微内核"？ |
46+
|---|------|------|------|-------------------|
47+
| ①②③ | Kernel × 3 | ~700行 | 插件生命周期 init→start→destroy | ✅ 核心 |
48+
| ④ | types | 120行 | Plugin/PluginContext 接口 | ✅ 核心 |
49+
| ⑤ | logger | ~400行 | Pino 封装 + 浏览器降级 | ⚠️ 可独立 |
50+
| ⑥ | plugin-loader | ~500行 | 插件验证、版本兼容、工厂DI、作用域 | ⚠️ 过重 |
51+
| ⑦⑧ | api-registry | ~300行 | API 端点注册/发现/冲突解决 | ❌ 不是内核 |
52+
| ⑨ | QA | ? | 测试框架 | ❌ 不是内核 |
53+
| ⑩ | security | ~300行 | 签名验证、配置校验、权限 | ⚠️ 边界 |
54+
| ⑫ | health-monitor | ~300行 | 插件健康检查 | ⚠️ 可独立 |
55+
| ⑬ | hot-reload | ~300行 | 状态快照/恢复 | ❌ 高级特性 |
56+
| ⑭ | dependency-resolver | ? | 拓扑排序 + 循环检测 | ✅ 核心 |
57+
58+
#### `@objectstack/runtime` — 实际内容
59+
60+
```typescript name=runtime/src/index.ts url=https://github.com/objectstack-ai/spec/blob/ef29eb6b1823e8fdc47916a5c14a46e2aedd7a90/packages/runtime/src/index.ts#L1-L38
61+
export { ObjectKernel } from '@objectstack/core'; // 直接转发
62+
export { Runtime } from './runtime.js'; // ① 69行薄包装
63+
export { DriverPlugin } from './driver-plugin.js'; // ② 数据库驱动适配器
64+
export { AppPlugin } from './app-plugin.js'; // ③ 应用包加载器
65+
export { createDispatcherPlugin } from './dispatcher-plugin.js'; // ④ HTTP 路由分发
66+
export { HttpServer } from './http-server.js'; // ⑤ HTTP 抽象层
67+
export { HttpDispatcher } from './http-dispatcher.js'; // ⑥ 请求分发器（40KB!）
68+
export { MiddlewareManager } from './middleware.js'; // ⑦ 中间件管理
69+
70+
// 转发 @objectstack/rest 和 @objectstack/core
71+
export * from '@objectstack/rest';
72+
export * from '@objectstack/core'; // ← 全量 re-export core
73+
```
74+
75+
| # | 模块 | 行数 | 职责 |
76+
|---|------|------|------|
77+
| ① | Runtime | 69行 | `new ObjectKernel()` + `kernel.bootstrap()` 的薄包装 |
78+
| ② | DriverPlugin | 76行 | 驱动注册 + 自动配置 default datasource |
79+
| ③ | AppPlugin | ~150行 | 解析 Stack Definition → 注册元数据 + seed data |
80+
| ④ | DispatcherPlugin | ~250行 | 注册 auth/graphql/analytics 等非 CRUD 路由 |
81+
| ⑤ | HttpServer | ~130行 | IHttpServer 适配器 |
82+
| ⑥ | HttpDispatcher | **~1000行** | 所有 HTTP 请求的分发逻辑（最大的文件） |
83+
| ⑦ | MiddlewareManager | ~140行 | 中间件链排序和过滤 |
84+
85+
---
86+
87+
### 问题核心：你说的"core 更复杂"是事实
88+
89+
| 对比维度 | `@objectstack/core` | `@objectstack/runtime` |
90+
|----------|:---:|:---:|
91+
| **源文件数** | 14+ | 7 |
92+
| **依赖数** | spec + pino + zod | core + rest + spec + types |
93+
| **职责纯度** | ❌ 混合了很多不属于微内核的东西 | ⚠️ 定位模糊 |
94+
| **"微内核"名副其实？** | **否** — API 注册表、QA、热更新、安全验证都塞进来了 | — |
95+
| **Runtime 实际是什么？** | — | 69行薄壳 + 几个便利 Plugin + 巨大的 HttpDispatcher |
96+
97+
### 依赖关系现实
98+
99+
```
100+
runtime 的 index.ts 最后一行：
101+
export * from '@objectstack/core'; ← runtime 是 core 的超集！
102+
```
103+
104+
这意味着：**任何 `import from '@objectstack/runtime'` 都能拿到 core 的全部导出**。runtime 不是 core 的"使用者"，它就是 core 的"facade + 追加"。
105+
106+
---
107+
108+
## 诊断结论：职责边界模糊
109+
110+
### 当前的问题
111+
112+
```
113+
应该的架构：
114+
core = 纯微内核 (Kernel + Plugin + DI + Hooks + 依赖解析)
115+
runtime = 标准库 (HTTP + 插件集 + 应用加载)
116+
117+
实际的架构：
118+
core = 微内核 + 日志 + 安全 + 健康监控 + 热更新 + API注册表 + QA框架
119+
runtime = core 的 re-export + 69行 Runtime 壳 + HTTP + 3个Plugin
120+
```
121+
122+
**core 承担了太多**，runtime 又**太薄**（核心只有 69 行的 `Runtime` 类）。
123+
124+
### 理想拆分方案
125+
126+
如果从零设计，边界应该是：
127+
128+
| 包 | 职责 | 包含什么 |
129+
|---|------|----------|
130+
| **core** (真·微内核) | 插件生命周期 + DI + Hooks | `ObjectKernel`, `LiteKernel`, `KernelBase`, `types`, `dependency-resolver`, `env` |
131+
| **core** 不该有的 → | 应迁出 | `logger` → 独立包或留但精简<br>`api-registry` → runtime<br>`QA` → 独立包 `@objectstack/qa`<br>`security/` → `@objectstack/plugin-security` 或 runtime<br>`health-monitor` → runtime 或独立<br>`hot-reload` → runtime 或独立 |
132+
| **runtime** (标准库) | HTTP + 标准 Plugin + 应用加载 | 现有内容 + 从 core 迁入的 api-registry, health-monitor |
133+
134+
### 但现在能做什么？
135+
136+
**不建议现在大拆**。原因：
137+
138+
1. **23 个包 + fixed 版本组** — 重构 core/runtime 边界会触发全量级联发版
139+
2. **runtime 的 `export * from '@objectstack/core'`** — 所有下游消费者都通过 runtime 拿 core，改了会断
140+
3. **核心套件 10/10 已完成** — 当前架构虽不完美但能工作
141+
142+
### 务实建议：渐进式瘦身
143+
144+
| 阶段 | 动作 | 影响 |
145+
|------|------|------|
146+
| **Now** | 把 fallback factories 放 core (上次讨论的) | ��向：内核自动 fallback，不增加 core 复杂度（只加一个目录） |
147+
| **v3.x** | 从 core 导出中标记 `@internal`：QA, api-registry, hot-reload | 零破坏，但表明意图 |
148+
| **v4.0** | 将 QA → `@objectstack/qa`，api-registry → runtime | Breaking change，major 版本做 |
149+
| **v4.0** | Runtime 增加 core auto-fallback 逻辑，承担更多"标准库"职责 | Runtime 变厚，core 变薄 |
150+
151+
**一句话总结**：**core 确实太重了**，runtime 确实太薄了。核心原因是历史上所有"不知道放哪"的东西都堆进了 core。但现在不是拆的时候——v4.0 major 版本再清理边界，当前先用 `@internal` 标记 + 渐进式迁出。
152+
153+
> **注**: 搜索结果可能不完整，更多代码可在 [GitHub 代码搜索](https://github.com/search?q=repo%3Aobjectstack-ai%2Fspec+path%3Apackages%2Fcore%2Fsrc+OR+path%3Apackages%2Fruntime%2Fsrc&type=code) 中查看。

0 commit comments

Comments
 (0)