介绍
让 .NET 应用的边界清楚十年。
序言
写框架的人很多，能把一个框架维护十年的人很少。我希望 XiHan Framework 成为后者，所以它的每一条设计都在回答同一个问题：十年后这段代码还能不能用、还能不能换。
名字的由来
曦，是清晨的第一缕光；寒，是冬日的清冷。我把这两个字放在一起给框架命名，是想让它像冬天的早晨：清冷、克制、不喧哗，但光一出来，一整天的工作就能看得清楚。框架、视图组件、基础应用和四款设计器共用「曦寒」这个前缀，组织叫曦寒懿（XiHanFun），寓意这一整套东西是一个有完整生态的家族，而不是零散的仓库。
文档地址
| 文档 | 地址 |
|---|---|
| 开发框架（本站） | framework.docs.xihanfun.com |
| 视图组件 | ui.docs.xihanfun.com |
| 基础应用 | basicapp.docs.xihanfun.com |
| 组织门户 | docs.xihanfun.com |
给 AI 编码助手读的纯文本版本见 LLMs.txt。
开源地址
| 平台 | 地址 |
|---|---|
| GitHub（主库） | XiHanFun/XiHan.Framework |
| Gitee（同步备库） | XiHanFun/XiHan.Framework |
| GitCode（同步备库） | XiHanFun/XiHan.Framework |
| NuGet | XiHanFun |
| 规范 | XiHanFun/framework-spec |
| Go SDK | XiHanFun/framework-sdk-go |
框架包
框架由一组可以独立引用的 NuGet 包组成，全部共享一条版本线。包名由术语表与文法推出：XiHan.Framework.<领域>[.<角色>]。多数应用只需要记住三个组合包，再按需加协议适配器与 Provider：
| 包 | 说明 |
|---|---|
XiHan.Framework.Profiles.Minimal | 原语层、内核、ASP.NET Core 宿主、内存本地化 |
XiHan.Framework.Profiles.Standard | Minimal 加领域模型，以及持久化、缓存、多租户、安全、消息五个子系统的抽象与内存默认实现 |
XiHan.Framework.Profiles.Full | Standard 加对象存储、调度、审计、工作流的默认实现，AI 工具目录，OpenTelemetry 导出与运行信息，HTTP、gRPC、MCP、CloudEvents 四种协议适配器 |
常用的单包：
| 类别 | 包 |
|---|---|
| 原语与内核 | Primitives、Kernel、Kernel.Generators（源生成器）、Kernel.Analyzers（分析器） |
| 协议 | Protocols.Http、Protocols.Grpc、Protocols.Mcp、Protocols.CloudEvents |
| 宿主 | Hosting.AspNetCore、Hosting.CommandLine |
| 持久化 | Persistence.Abstractions、Persistence.InMemory、Persistence.EntityFrameworkCore、Persistence.SqlSugar、Persistence.Generators |
| 缓存 | Caching.Abstractions、Caching.InMemory、Caching.Redis、Caching.Hybrid、Caching.Remote |
| 消息 | Messaging.Abstractions、Messaging.InMemory、Messaging.RabbitMQ、Messaging.Kafka |
| 安全 | Security.Abstractions、Security.InMemory、Security.Database、Security.Jwt、Security.OpenIdConnect、Security.Ip2Region |
| 多租户 | MultiTenancy.Abstractions、MultiTenancy.InMemory、MultiTenancy.Database |
| 其他子系统 | ObjectStorage.*、Scheduling.*、Workflow.*、Auditing.*、Localization.*、Configuration.*、Observability.*、AI.* |
| 插件 | Plugins.Protocol、Plugins.InProcess、Plugins.OutOfProcess、Plugins.Wasm |
| 工具链 | Cli（xihan 工具）、Testing、各 <领域>.Conformance |
完整清单与每个包的能力、配置节、主要类型见包参考。
框架特点
- 微内核：内核只定义宿主、能力图谱、管道、诊断、安全原语、操作契约与插件抽象，公开类型有预算，第三方依赖为零。
- 按能力装配：特性在清单里按能力 ID 声明提供与依赖，内核在启动前求解整张图并打印；缺失、循环、冲突在启动期报错，不在第一次请求时报错。
- 固定阶段的管道：每次调用依次经过 Ingress 到 Egress 十一个阶段，认证、租户、授权、校验、幂等、事务都是阶段里的中间件，顺序确定、可打印、可单独测试。
- 一份契约多协议：操作用
[Operation]声明一次，源生成器产出 JSON Schema；HTTP、gRPC、MCP 与命令行共用同一份 Schema、授权要求与错误码。 - 默认实现零外部依赖：每个子系统的抽象都配一个内存或文件系统实现，容量有界，通过一致性套件；换 Redis、EF Core、SqlSugar、RabbitMQ 只加包与配置，业务代码不变。
- 零反射与 Native AOT：原语层与内核不使用运行时反射，注册与 Schema 在编译期生成；示例应用以 Native AOT 发布作为 CI 冒烟项。
- 规范先于实现：原语、清单、上下文、管道阶段、协议映射与插件协议写在 XiHan Spec，Go SDK 与 .NET 参考实现通过同一套一致性向量。
- 边界由机器执行：依赖方向、包 ID 文法、命名空间、零反射、第三方类型泄漏、本地化文件齐全都由架构测试与分析器守护。
功能模块
| 模块 | 内容 | 章节 |
|---|---|---|
| 应用启动 | 装配、特性与清单、能力图谱、生命周期与健康、依赖注入、管道、调用上下文 | 应用启动 |
| 配置 | 配置节、选项、配置目录热更新、资源绑定、远程配置与密钥 | 配置与选项 |
| Web | ASP.NET Core 宿主、操作契约、HTTP 路由、端点、实时通信、OpenAPI | Web 应用开发 |
| 结果与校验 | Result 与 Error、错误码、Problem Details、契约校验 | 结果与错误处理与数据校验 |
| 数据 | 领域模型、仓储、工作单元、EF Core、SqlSugar、建表约定、连接、标识生成 | 数据库操作指南 |
| 多租户 | 租户解析与隔离、分片与分库、数据库租户目录 | SaaS 多租户 |
| 安全 | 认证、授权、RBAC 授予、条件引擎、IP 归属地、出站地址策略 | 安全鉴权 |
| 缓存 | 缓存读写、分布式锁、幂等、两级缓存、键管理 | 分布式缓存 |
| 消息 | 发布订阅、领域事件、发件箱、队列与流 | 消息与事件 |
| 协议 | gRPC、MCP、CloudEvents、命令行宿主 | 多协议暴露 |
| 本地化 | 消息键、十种内置区域、回退链、数据库翻译 | 全球化和本地化 |
| 调度 | 作业、cron、集群分发、领导选举 | 定时任务 |
| 工作流 | 定义、实例、用户任务、活动、补偿 | 工作流 |
| 对象存储 | 读写列举、分片上传、预签名、命名实例 | 对象存储 |
| 审计与可观测性 | 审计事件与查询、追踪、指标、日志、运行信息 | 审计与日志与可观测性 |
| AI | 模型与对话、护栏、操作即工具、知识库 | AI |
| 弹性 | 截止时间、熔断、限流、并发上限 | 弹性与限流 |
| 插件 | 进程内、进程外、Wasm 三级隔离，Go SDK | 插件 |
| 部署 | 应用清单、xihan pack、Kubernetes | 托管、部署、发布 |
| 测试 | 测试宿主、一致性套件、架构门禁 | 测试指南 |
框架依赖
原语层、内核与全部抽象包不引用任何第三方库，只允许 Microsoft.Extensions.* 抽象包，内核另加 System.Threading.RateLimiting。第三方库只出现在按技术命名的 Provider 包里：
| 类别 | 技术 |
|---|---|
| 序列化 | System.Text.Json 源生成 |
| ORM Provider | EF Core、SqlSugar |
| 缓存 Provider | StackExchange.Redis |
| 消息 Provider | RabbitMQ.Client、Confluent.Kafka |
| 对象存储 Provider | AWSSDK.S3 |
| 认证 Provider | Microsoft.IdentityModel.JsonWebTokens |
| AI | Microsoft.Extensions.AI、Microsoft.Extensions.VectorData |
| gRPC | Grpc.AspNetCore.Server |
| 可观测性 | OpenTelemetry |
| Wasm 插件 | Wasmtime |
具体版本以仓库的 framework/Directory.Packages.props 为准。
环境要求
| 项 | 要求 |
|---|---|
| SDK | .NET 10 SDK；构建框架源码时用仓库 global.json 锁定的功能带 |
| 编辑器 | Visual Studio、JetBrains Rider 或 VS Code（C# Dev Kit） |
| 测试运行器 | Microsoft.Testing.Platform，由 global.json 启用 |
| 外部设施 | 默认实现不需要；Provider 按各自包页的说明 |
支持平台
| 类别 | 支持 |
|---|---|
| 运行环境 | Windows、Linux、macOS；容器与 Kubernetes；Native AOT 发布 |
| 数据库 | 由持久化 Provider 决定：EF Core 支持的数据库，SqlSugar 支持的数据库；一致性套件在 SQLite 上运行，PostgreSQL、MySQL 与 Oracle 在 CI 里实测 |
| 缓存 | 内存、Redis、两级缓存、远程插件 |
| 消息 | 内存、RabbitMQ、Kafka、CloudEvents Webhook |
| 对象存储 | 文件系统、Amazon S3 与兼容服务（MinIO、OSS、COS、R2） |
| 远程配置 | Nacos |
| 协议 | HTTP、gRPC、MCP、CloudEvents、命令行 |
| 插件语言 | .NET、Go，以及任何能编译到 Wasm 或实现 gRPC 的语言 |
Wasm 插件宿主在 Windows 上要求宿主可执行项目设置 CETCompat=false。
关于性能
内核的预算是：冷启动在 ASP.NET Core 基线之上少于 50 毫秒，单个中间件的管道执行少于 0.1 毫秒，空应用常驻内存少于 30 MB，原语层加内核的包少于 500 KB，基准回归超过 5% 阻断。基准项目在仓库的 framework/benchmarks 下，可以本地运行；我不贴测试图，因为它们只在特定机器上成立。
贡献代码
框架遵循 MIT 协议，欢迎提交 Pull Request 与 Issue。流程、代码规范与门禁见贡献指南。感谢每一位为框架贡献代码、文档与一致性向量的朋友。
下一步
- 环境与安装：开始使用