来源：https://framework.docs.xihanfun.com/appendix/philosophy

# 设计哲学

这一页讲 XiHan Framework 5 背后的想法：我为什么把框架分成三层承诺，七条原则怎样推出具体的设计决策，从操作系统、语言、云原生项目和诸子百家里借了什么、又把它们落成了什么规则。读完它，你会理解后面每一章里「为什么这样设计」的答案。只想学怎么用的读者可以跳过，直接去[核心概念](/getting-started/concepts)。

## 一页结论

1. 十年不淘汰的不是代码，是边界。只冻结极小的一层，其余全部可替换。
2. 框架的本体是一份语言中立的规范，加一个 .NET 参考实现。没有规范和一致性测试，多语言只是口号。
3. 扩展有三条轴（能力包、插件、协议），共享一份清单模型和一条执行管道。
4. 所有借鉴都要落成机器能检查的规则：分析器、API 兼容性门禁、架构测试、一致性套件。不落成隐喻，不落成类名。
5. 默认实现必须能用。任何抽象都配一个零外部依赖、有容量上限的默认实现；五分钟起一个应用不需要任何数据库或中间件。
6. 一个领域一个词，全链路同词。包名、命名空间、能力 ID、配置节、错误码域、文档目录共用一张术语表。

## 三易模型

《易》有「不易、简易、变易」。这是整个方案里唯一允许进入架构骨架的哲学表达，因为它可以直接落成三层承诺：

| 层 | 名称 | 内容 | 承诺 | 变更策略 |
| --- | --- | --- | --- | --- |
| 不易 | 原语层 `Primitives`（Ring 0） | `Result<T>`、`Error`、`Maybe<T>`、`TypedId<T>`、调用上下文契约、错误码格式、清单模型、管道阶段、稳定性标记 | 永不破坏；跨语言语义一致 | 只增不改；若必须破坏，新包名并存，旧包永不删除 |
| 简易 | 内核 `Kernel`（Ring 1） | 特性契约、能力图谱、执行管道、宿主、诊断抽象、安全原语、操作契约、插件宿主抽象 | 大版本内不破坏；大版本间提供迁移工具 | 三阶段弃用；每个大版本对齐一个 .NET LTS |
| 变易 | 子系统、Provider、宿主、协议、插件、应用（Ring 2 到 6） | 持久化、缓存、消息、安全、多租户、调度等抽象与实现 | 各自演进；通过一致性测试即视为兼容 | 自由演进，实验包进孵化区 |

## 七条原则

| 原则 | 含义 | 落在代码里的规则 |
| --- | --- | --- |
| 内核克制 | 内核只定义稳定边界，不堆能力 | 依赖宿主、扫描、应用工厂的东西都不进内核；内核公开类型有预算；第三方依赖为零 |
| 装配显式 | 显式注册优先，自动发现只是增强 | 服务在特性的 `Configure` 里显式注册，源生成器产出的登记代码也要显式调用；不扫描程序集 |
| 模块化不是信仰 | 能力包是组织方式之一，不强迫 | 任何实现 `IFeature` 的类都可以是一个能力包，没有基类、没有生命周期钩子 |
| 边界刚、内部柔 | 依赖方向与分层刚性约束，实现内部自由 | 架构测试执行依赖方向、包 ID 文法、同环只经抽象包往来；包内可以随时重构 |
| 宿主落地 | 内核不感知宿主形态 | 管道不绑定 HTTP；Web、命令行、消息消费、作业、插件回调走同一条管道 |
| 规范先于实现 | 公共契约先进规范，再写代码 | 没有 RFC 的公开 API 变更不合并；规范没有的语义不进原语层与内核 |
| 默认实现必须可用 | 每个抽象配一个默认实现 | 零外部设施、容量有界、可降级、通过一致性测试，只在没有显式 Provider 时生效 |

## 借鉴矩阵

规则是：每一项借鉴都写成「借什么、落到哪、怎么检查」。写不出第三列的，只能进文档，不能进代码。下面是其中有代表性的几行。

### 操作系统

| 来源 | 借什么 | 落到哪 |
| --- | --- | --- |
| Linux | 「不破坏用户态」的系统调用 ABI | 原语层只增不改，CI 包验证做基线比对 |
| Linux | VFS：统一接口、可插拔文件系统 | 每个子系统是抽象加多个 Provider，调用方只见抽象 |
| Linux | `modprobe` 与符号版本 | 清单按能力 ID 与版本范围解析，启动期校验，缺失或冲突直接失败 |
| Linux | netfilter 钩子点 | 执行管道定义固定阶段，特性按阶段插入中间件，不需要知道其他中间件 |
| Windows NT | COM：接口一经发布不改，新能力用新接口 | 契约演进只加新版本并存；Provider 接口单独编号 |
| Windows NT | WDK 与 HLK 认证 | Provider 开发套件与一致性测试套件；通过套件才能标 Stable |
| macOS | XNU 混合内核：微内核原语加开箱即用的 BSD 层 | 微内核抽象加默认实现，不让使用者面对一堆空接口 |
| macOS | launchd 按依赖启动 | 特性生命周期状态机 |
| Android | Project Treble：供应商接口独立版本化 | Provider 接口单独版本化，写好的 Provider 在同一大版本内全程可用 |
| Android | 清单声明权限、运行时授予 | 插件权限模型 |
| 鸿蒙 | 系统能力注册与发现，本地远程透明 | 同一能力可由同进程、插件或远程协议提供 |

### 语言与框架

| 来源 | 借什么 | 落到哪 |
| --- | --- | --- |
| .NET | Generic Host、Options、源生成器、AOT、`TimeProvider`、`System.Threading.RateLimiting`、`Microsoft.Extensions.AI` | 只扩展不包装；内核依赖仅限 `Microsoft.Extensions.*` 抽象包 |
| Spring | 条件装配 | 默认实现只在没有显式 Provider 时生效，且在启动日志里可见 |
| Go | 小接口加组合；`context.Context` 传播取消、截止、值 | 调用上下文必带取消、截止、Trace、Baggage |
| Rust | `core` 与 `std` 分层；默认私有、显式公开；`Result` 与 `Option` | 原语层不依赖宿主；默认 `internal`，公开面受 PublicAPI 文件约束 |
| FastAPI | 类型即契约，自动校验与 OpenAPI | 操作契约由类型生成 Schema，源生成器产出 OpenAPI、proto 与 MCP tool |
| ASGI | 服务器与应用之间的协议 | XGI：协议适配器与管道之间的消息契约 |
| Vue | 渐进式，用多少装多少 | 从 Minimal 一路加到 Full |
| React | 单向数据流；Error Boundary | 管道单向；插件失败隔离在边界内，宿主不崩 |
| ABP | 模块化单体的完整度 | 作为子系统能力清单的对照表，不继承其强制基类与钩子 |

### 云原生与开源项目

| 来源 | 借什么 | 落到哪 |
| --- | --- | --- |
| Kubernetes | 探针、SIGTERM 与宽限期、ConfigMap 热更新、API 版本演进 | 探针直接映射特性状态机；Draining 状态；配置目录监听；能力契约版本规则 |
| Service Binding | 工作负载声明需要的资源，平台注入 | 清单 `bindings` |
| OpenTelemetry 与 MCP | 规范加多语言 SDK 加一致性测试 | XiHan Spec 的组织方式 |
| Dapr | Building Blocks；可插拔组件走 gRPC | 子系统端口集合；远程 Provider |
| Terraform | 子进程加 gRPC 的跨语言插件 | 进程外插件协议 |
| VS Code | 贡献点、激活事件、扩展宿主进程隔离 | 插件清单的 `contributes` 与 `activation`；进程外插件宿主 |
| Envoy | 过滤器链、Wasm 过滤器 | 管道阶段；Wasm 插件可贡献中间件 |
| Roslyn | PublicAPI 分析器、源生成器 | 公开面文件化；生成器替代反射 |

### 诸子百家

硬性规则：思想只能变成约束，不能变成类名或 API。代码里不出现 `Dao`、`Wuwei` 这类标识符。

| 思想 | 工程约束 | 机器检查 |
| --- | --- | --- |
| 《易》不易、简易、变易 | 三层承诺 | 包验证基线按层分级 |
| 道家 无为、大道至简 | 内核不自动注册、不扫描、不推断；默认实现零配置可用 | 内核公开类型预算、零反射分析器 |
| 道家 反者道之动 | 任何能力都可被移除，应用仍可编译 | 移除能力后的编译测试 |
| 道家 上善若水 | 内核不感知宿主形态 | 架构测试：内核不引用任何宿主包 |
| 儒家 正名 | 能力 ID、错误码、Baggage 键、操作 ID 是规范化命名，一经发布不改 | 命名注册表、分析器、包 ID 文法测试 |
| 儒家 礼 | 互操作标准就是「礼」：跨语言、跨实现共同遵守 | 一致性测试 |
| 儒家 中庸 | 显式优先，约定可用，二者都有退出机制 | 约定行为必须有显式覆盖 API |
| 法家 以法治 | 规则由工具执行，不靠人审 | 分析器、架构测试、API 兼容性作为 CI 必过项 |
| 墨家 节用 | 资源有界；不锁定供应商 | 容量测试；抽象包不暴露第三方类型 |
| 兵家 先胜后战 | 发布前过全部门禁；稳定主线加孵化区 | 孵化包只能标 Experimental |

### 明确不借

不做 Reconcile Loop 内核；不做 Sidecar；不做 OSGi 式运行时服务总线；不做低代码平台、不做 UI；不把哲学词汇写进标识符。

## 反模式清单

| 反模式 | 避免方式 |
| --- | --- |
| 上帝基类 | 无基类，只实现 `IFeature` |
| 隐式依赖 | 清单按能力 ID 声明，启动期求解并可打印 |
| 深层继承 | 接口组合，零层继承 |
| 反射魔法 | 源生成器加显式注册 |
| 包爆炸 | 抽象与实现分层、共享版本线、组合包 |
| 隐喻命名 | 思想只能变成约束，标识符里不出现哲学词汇 |
| 策略进包名 | `Default` 不进包名，实现按机制或技术命名 |
| 没有默认实现的抽象 | 每个抽象必须有 `InMemory` 之类的默认实现并通过一致性测试 |

## 十年稳定性治理

| 门禁 | 工具 | 规则 |
| --- | --- | --- |
| 公开面文件化 | PublicAPI 分析器 | 每包一份 `PublicAPI.Shipped.txt`；原语层已发布行不可改 |
| 包验证 | .NET SDK 包验证加基线版本 | 小版本禁止破坏；大版本列出破坏清单 |
| 稳定性标记 | 自研分析器 | 公开类型必须有 `[ApiLevel]`；`Internal` 被引用即报错 |
| 命名文法 | 架构测试 | 包 ID、命名空间、能力 ID、配置节、错误码域符合术语表与文法 |
| 架构边界 | 架构测试 | 依赖方向、抽象包不含第三方类型、内核零反射、批量优先、本地化文件齐全 |
| AOT | CI 发布冒烟 | 裁剪警告视为错误 |
| 一致性 | Conformance 套件 | Provider 标 Stable 的前提 |

弃用流程：标 `Deprecated` 并以 `[Obsolete]` 给出警告与迁移文档，至少跨两个小版本；下一个大版本前的最后一个小版本升级为编译错误；大版本移除并提供代码修复。

## 借鉴的边界

借鉴分三档：可落成机器检查的规则，进代码、分析器与架构测试；可落成文档约束的，进规范与审查清单；只是启发的，留在设计说明里，不进代码。写不出前两档的借鉴，一律按第三档处理。

## 下一步

- [规范与多语言](/appendix/spec)：规范怎样组织，一致性测试怎样保证多语言实现的一致
- [核心概念](/getting-started/concepts)：这些原则在代码里长什么样