框架概述
本页说明 XiHan Framework 的设计原则、环层与依赖规则、一次调用的执行路径、命名约定、稳定性分级与环境要求，供做技术评估与写扩展的读者参考。
三层承诺
框架按变化速度把代码分成三层，每层给出不同的兼容承诺：
| 层 | 范围 | 承诺 |
|---|---|---|
| 原语层 | XiHan.Framework.Primitives（Ring 0） | 只增不改，跨大版本不破坏；必须破坏时发布新包 ID Primitives.V2 并存 |
| 内核 | XiHan.Framework.Kernel（Ring 1） | 大版本内不破坏 |
| 子系统与其上 | 抽象、实现、宿主、协议、插件、组合包（Ring 2–6） | 各自演进，通过同一套一致性套件即视为兼容 |
设计原则
| 原则 | 落在代码里的规则 |
|---|---|
| 内核克制 | 内核只定义宿主、能力图谱、管道、诊断、安全原语、操作契约与插件抽象，不含任何子系统实现 |
| 装配显式 | 服务在特性的 Configure 里显式注册；源生成器产出的登记代码也要显式调用（AddGeneratedOperations、AddGeneratedRepositories），不扫描程序集 |
| 依赖按能力声明 | 清单按能力 ID 与接口版本声明依赖，内核求解后打印已解析图，缺失、循环、版本冲突、多候选都在启动期报错 |
| 边界刚、内部柔 | 依赖方向、同环只经抽象包往来、抽象包不暴露第三方类型，全部由架构测试执行；包内实现可以随时重构 |
| 宿主落地 | 管道不绑定 HTTP；ASP.NET Core、命令行、消息消费、作业与插件回调走同一条管道 |
| 规范先于实现 | 公开契约先进 XiHan Spec 的 RFC，再写 ADR、代码与一致性向量 |
| 默认实现必须可用 | 每个抽象配一个零外部依赖、容量有界、通过一致性套件的默认实现，只在没有显式 Provider 时被选中 |
环层与依赖规则
text
Ring 6 组合包 Profiles.Minimal / Standard / Full
Ring 5 协议与插件 Protocols.* / Plugins.InProcess / OutOfProcess / Wasm
Ring 4 宿主 Hosting.AspNetCore / Hosting.CommandLine
Ring 3 实现 <领域>.InMemory、<领域>.Database、Redis、EntityFrameworkCore 等
Ring 2 抽象 Domain、<领域>.Abstractions
Ring 1 内核 Kernel
Ring 0 原语层 Primitives
工具链 Kernel.Analyzers、Kernel.Generators、Persistence.Generators、
<领域>.Conformance、Testing、Cli- 只能依赖更低的环；同环之间只能引用对方的抽象包（
.Abstractions，以及纯契约的Domain）。 - 原语层不引用任何包；内核与全部抽象包只允许
Microsoft.Extensions.*抽象包，内核另加System.Threading.RateLimiting。 - 抽象包不暴露第三方类型，Provider 不被任何抽象包引用。
- 宿主与协议包不含业务规则；插件不被任何正式包引用。
- 原语层与内核零反射；反射只允许出现在
Plugins.InProcess，并标注RequiresDynamicCode。 - 工具链可以引用任何环。
规则由 framework/test/XiHan.Framework.Architecture.Tests 执行，违反即 CI 失败。
一次调用的路径
text
HTTP 请求 / gRPC 调用 / MCP tools/call / 命令行 / 消息投递 / 作业触发 / 插件回调
│ 协议适配器或派发器构造 InvocationContext，把线上消息翻译成操作请求
▼
Ingress → Observe → Resilience → Authenticate → Tenant → Authorize
→ Validate → Idempotency → Transaction → Handle → Egress
│ Handle 阶段执行操作，操作经子系统抽象访问 Provider
▼
Egress：Result 与 Error 翻译回协议（HTTP 为 RFC 9457 Problem Details，gRPC 为状态码与尾部元数据）调用上下文 InvocationContext 携带取消令牌、截止时间、W3C Trace、已登记的 Baggage 键（租户、主体、关联 ID、幂等键、区域）、作用域对象袋与作用域服务。安全上下文（主体、租户）由 Authenticate 与 Tenant 阶段写入，之后不可变。
命名约定
命名由 XiHan Spec 的术语表推出，架构测试校验：
| 对象 | 规则 | 示例 |
|---|---|---|
| 包 ID | XiHan.Framework.<领域>[.<角色>]，角色是 Abstractions、Conformance、Generators 或机制、技术名 | XiHan.Framework.Caching.Redis |
| 命名空间 | 等于包 ID，子命名空间最多一层 | XiHan.Framework.Caching.Abstractions.Locking |
| 能力 ID | <领域小写>.<能力>，引用时带接口版本 | caching.distributed@1 |
| 清单 ID | xihan.<领域>.<名称> | xihan.caching.redis |
| 配置节 | XiHan:<领域> | XiHan:Caching |
| 错误码 | <领域大写>_<KIND>_<三位序号> | PERSISTENCE_CONFLICT_001 |
| 操作 ID | <资源复数>.<动词> | orders.create |
| 消息键 | <领域>.<资源>.<键> | security.token.subject_missing |
类型名不带 XiHan 前缀；Default、Core、Common、Manager、Helper 等词不进包名与领域名；默认实现按机制命名（InMemory、FileSystem、Database），默认是清单里的 role，不是包名。
核心机制速览
| 机制 | 一句话 | 详见 |
|---|---|---|
| 特性与清单 | IFeature + Manifest，UseFeature<T>() 显式组合 | 能力包与清单 |
| 生命周期 | 九态状态机，探针直接映射应用状态 | 生命周期与健康 |
| 执行管道 | 十一个固定阶段，中间件按阶段插入 | 执行管道 |
| 操作契约 | [Operation] + IOperation<TRequest, TResponse>，一份契约多协议 | 操作契约 |
| 结果与错误 | Result / Error 代替异常表达可恢复失败，错误只带消息键 | 结果与错误 |
| 本地化 | 每种语言一个 JSON 文件，宿主按调用方区域翻译 | 国际化 |
| 默认实现与 Provider | 抽象包 + 默认实现 + Provider，按能力选择 | 包总览 |
| 一致性套件 | 默认实现与 Provider 通过同一套行为测试 | 测试与一致性套件 |
稳定性分级
公开类型都带 [ApiLevel(Stability, <引入版本>)]，公开面以各包的 PublicAPI.Shipped.txt 与 PublicAPI.Unshipped.txt 为准：
| 级别 | 含义 |
|---|---|
Stable | 大版本内不破坏 |
Preview | 可能变更 |
Experimental | 可能移除，用于收集反馈（如 Plugins.Wasm、Caching.Remote） |
Internal | 不对外承诺，分析器阻止外部引用 |
Deprecated | 将在下一个大版本移除 |
弃用按规范的流程进行：先标 Deprecated 并以 [Obsolete] 给出警告与迁移说明，至少保留两个小版本；下一个大版本前升级为编译错误，大版本时移除。
版本与兼容
- 全部包共享一条版本线。
- 目标框架
net10.0；版本号遵循 SemVer 2.0。 - 每个子系统的 Provider 接口单独版本化（
persistence.relational@1），接口变更只加新版本并存。
环境要求
| 项 | 要求 |
|---|---|
| SDK | .NET 10 SDK；构建框架源码时使用仓库 global.json 锁定的 10.0.4xx 功能带 |
| 测试运行器 | Microsoft.Testing.Platform（由 global.json 启用，dotnet test 用 --solution 或 --project） |
| 操作系统 | Windows、Linux、macOS；Wasm 插件宿主在 Windows 上要求宿主可执行项目设置 CETCompat=false |
| 外部设施 | 默认实现不需要；Provider 按各自包页的说明 |