XiHan Framework 处于预览阶段

查看获取方式
曦寒开发框架文档
取本页 Markdown

XiHan Framework ​

XiHan Framework 是一套语言中立的应用框架规范（XiHan Spec）及其 .NET 10 参考实现，以微内核、能力图谱与管道执行为核心。本页说明框架的整体形态、最小写法与文档组织，适合第一次接触框架的读者。

框架处于预览阶段

当前是预览版，取得方式见快速上手。

框架的形态 ​

应用由若干特性组成。特性是实现 IFeature 的类，带一份清单（Manifest），清单写明它提供哪些能力、依赖哪些能力，依赖以能力 ID（如 persistence.relational@1）声明，不按包名或类型。应用在启动时把特性交给内核，内核求解能力图谱、按拓扑顺序调用各特性的 Configure 注册服务与中间件，构建期就能发现缺失的依赖、版本冲突与循环。

每次调用都经过一条固定十一个阶段的管道：Ingress → Observe → Resilience → Authenticate → Tenant → Authorize → Validate → Idempotency → Transaction → Handle → Egress。认证、租户解析、授权、契约校验、幂等与工作单元都是某个阶段里的中间件，由对应子系统的特性贡献。

业务以操作契约声明：一个类实现 IOperation<TRequest, TResponse> 并标注 [Operation]，源生成器产出登记代码与请求、响应的 JSON Schema。协议适配器把 HTTP 请求、gRPC 调用、MCP 的 tools/call 与命令行参数翻译成同一种调用，交给同一条管道执行。

持久化、缓存、消息、安全、多租户等子系统各有一个抽象包（<领域>.Abstractions），配一个零外部依赖、容量有界的默认实现（InMemory、FileSystem），再由 Provider 包接入 EF Core、SqlSugar、Redis、RabbitMQ、Kafka、S3 等外部设施。换 Provider 只加包、加一行 UseFeature，业务代码不变。

最小写法 ​

下面三段代码组成一个可运行的 Web 应用：一个操作、一个特性、一个入口。完整步骤与项目文件见快速上手。

csharp
using XiHan.Framework.Kernel.Operations;
using XiHan.Framework.Primitives;

namespace HelloXiHan;

// 操作 ID greetings.create 经 HTTP 适配器推导为 POST /greetings
[Operation(Id, Stability = Stability.Experimental, Expose = Expose.Http)]
public sealed class Greet : IOperation<GreetRequest, GreetResponse>
{
    public const string Id = "greetings.create";

    public ValueTask<Result<GreetResponse>> HandleAsync(GreetRequest request, InvocationContext context)
        => ValueTask.FromResult(Result.Success(new GreetResponse($"Hello, {request.Name}!", context.TraceId)));
}

public sealed record GreetRequest(string Name);

public sealed record GreetResponse(string Message, string TraceId);
csharp
using XiHan.Framework.Kernel;
using XiHan.Framework.Kernel.Hosting;
using XiHan.Framework.Primitives;
using XiHan.Framework.Primitives.Manifests;

namespace HelloXiHan;

// 特性：清单声明依赖内核宿主能力，Configure 登记源生成器产出的操作
public sealed class GreetingsFeature : IFeature
{
    public Manifest Manifest { get; } = new()
    {
        Id = "xihan.hello.greetings",
        Package = "HelloXiHan",
        Version = "1.0.0",
        Primitives = 1,
        Stability = Stability.Experimental,
        Kind = ManifestKind.Capability,
        Requires = [new CapabilityRequirement(KernelCapabilities.Hosting, KernelCapabilities.Version)],
        Entry = typeof(GreetingsFeature).FullName,
    };

    public void Configure(FeatureContext context) => context.AddGeneratedOperations();
}
csharp
using HelloXiHan;
using XiHan.Framework.Hosting.AspNetCore;
using XiHan.Framework.Profiles.Minimal;
using XiHan.Framework.Protocols.Http;
using XiHan.Framework.Protocols.Http.Routing;

var builder = WebApplication.CreateBuilder(args);

builder.AddXiHan(xihan => xihan
    .UseMinimalProfile()
    .UseFeature<HttpProtocolFeature>()
    .UseFeature<GreetingsFeature>());

var app = builder.Build();

app.UseXiHan();            // HTTP 请求进入内核管道
app.MapXiHanHealth();      // /health/startup、/health/ready、/health/live
app.MapXiHanOperations();  // 按登记表映射操作路由

app.Run();

操作需要的 JsonSerializerContext（[JsonSerializable(typeof(GreetRequest))] 等）在快速上手里给出：内核不经反射序列化，源生成器据此检查请求与响应类型已登记。

文档怎么组织 ​

文档分两册：

册定位什么时候看
开发指南按能力域编号的任务式文档要做某件事：装配特性、写操作、接数据库、做授权、发消息
包总览按 NuGet 包组织的参考手册，每包一页要查某个包：提供什么能力、配置键、主要类型、限制

指南章节链接到对应的包页，两册不重复大段内容。给 AI 工具读取的纯文本版本见 LLMs.txt。

开发指南速览 ​

章内容
1–5能力包与清单 · 生命周期与健康 · 依赖注入 · 执行管道 · 配置与选项
6–10宿主与 Web 应用 · 操作契约 · HTTP 与 OpenAPI · gRPC、MCP 与 CloudEvents · 命令行宿主
11–12结果与错误 · 数据校验
13–16领域模型 · 持久化 · 工作单元与事务 · 多租户
17–19认证 · 授权 · 出站地址策略
20–24缓存与分布式锁 · 消息与事件 · 调度与后台作业 · 工作流 · 实时通信
25–28对象存储 · 国际化 · 审计 · 可观测性
29–32序列化与 Native AOT · 标识生成 · AI · 弹性与限流
33–35插件 · 部署与打包 · 测试与一致性套件
36–37扩展与二次开发 · 常见问题

环层一览 ​

包按环层组织，依赖只能指向更低的环，同环之间只经抽象包往来，规则由架构测试执行：

text
┌──────────────────────────────────────────────────────────────────────┐
│ Ring 6  组合包          Profiles.Minimal / Standard / Full             │
├──────────────────────────────────────────────────────────────────────┤
│ Ring 5  协议与插件      Protocols.Http / Grpc / Mcp / CloudEvents       │
│                        Plugins.InProcess / OutOfProcess / Wasm         │
├──────────────────────────────────────────────────────────────────────┤
│ Ring 4  宿主            Hosting.AspNetCore / Hosting.CommandLine        │
├──────────────────────────────────────────────────────────────────────┤
│ Ring 3  实现            <领域>.InMemory 等默认实现与 Redis、EF Core 等 Provider │
├──────────────────────────────────────────────────────────────────────┤
│ Ring 2  抽象            Domain 与 <领域>.Abstractions                    │
├──────────────────────────────────────────────────────────────────────┤
│ Ring 1  内核            Kernel：Hosting / Capabilities / Pipeline /      │
│                        Operations / Security / Plugins 等命名空间        │
├──────────────────────────────────────────────────────────────────────┤
│ Ring 0  原语层          Primitives：Result / Error / Maybe /             │
│                        InvocationContext / 清单模型 / 管道阶段           │
└──────────────────────────────────────────────────────────────────────┘
  工具链（Analyzers、Generators、Conformance、Testing、Cli）可引用任何环

每个包所在的环与提供的能力见包总览。

技术栈 ​

类别技术
运行时.NET 10
内核依赖Microsoft.Extensions.* 抽象包、System.Threading.RateLimiting
序列化System.Text.Json 源生成
ORM ProviderEF Core / SqlSugar
缓存 ProviderStackExchange.Redis
消息 ProviderRabbitMQ.Client / Confluent.Kafka
对象存储 ProviderAWSSDK.S3
认证 ProviderMicrosoft.IdentityModel.JsonWebTokens
AIMicrosoft.Extensions.AI / VectorData
gRPCGrpc.AspNetCore.Server
可观测性OpenTelemetry
Wasm 插件Wasmtime

具体版本以 framework/Directory.Packages.props 为准。原语层、内核与全部抽象包不引用第三方库；第三方库只出现在按技术命名的 Provider 包里。

社区资源 ​

Released under The MIT License

Copyright ©2021-Present XiHanFun and contributors.