快速上手

项目组成

本项目由 XiHan.Framework（开发框架）、XiHan.UI（视图组件）、XiHan.BasicApp（基础应用）组成。

• 开发框架子项目：是后端开发框架，基于 .NET 构建，核心是微内核、能力图谱和管道执行。
• 视图组件子项目：是框架无关的 Headless UI 组件库，提供 Vue、React 与 Web Components 适配器。
• 基础应用子项目：为开发框架和视图组件的结合，为通用、全面的管理系统。

环境准备

在开始使用 XiHan 系列项目前，请确保您的开发环境已安装以下工具：

后端开发环境

• .NET SDK (版本 10 或更高)
• 推荐 IDE：Visual Studio 2026、JetBrains Rider 或 VS Code

前端开发环境

• Node.js (版本 24 或更高)
• pnpm (版本 10 或更高；XiHan.BasicApp 前端要求 11 或更高)
• 推荐 IDE：Visual Studio Code 配合 Vue - Official 插件

运行 XiHan.BasicApp 额外需要

• PostgreSQL 14+（或 MySQL / MariaDB）
• Redis 6.0+

入门指南

使用 XiHan.Framework (后端框架)

框架是按能力装配的，用什么装什么。业务写成操作契约，一份契约可以同时经 HTTP、gRPC、MCP 和命令行暴露。搭一个 Web API 最少需要下面三个包：

1. 创建新项目并安装 NuGet 包：

dotnet new web -n HelloXiHan
cd HelloXiHan

# 内核、ASP.NET Core 宿主与内存本地化
dotnet add package XiHan.Framework.Profiles.Minimal --prerelease

# HTTP 协议适配器
dotnet add package XiHan.Framework.Protocols.Http --prerelease

# 操作源生成器，只在编译时运行，不进入运行时依赖
dotnet add package XiHan.Framework.Kernel.Generators --prerelease

2. 写第一个操作。新建 Greet.cs，操作 ID greetings.create 的资源是 greetings、动词是 create，HTTP 适配器据此推导出 POST /greetings，不需要写 Controller：

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

namespace HelloXiHan;

[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);

3. 登记序列化类型。内核不经反射序列化，新建 AppJsonContext.cs，把请求与响应类型登记到源生成的序列化上下文：

using System.Text.Json.Serialization;

namespace HelloXiHan;

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, PropertyNameCaseInsensitive = true)]
[JsonSerializable(typeof(GreetRequest))]
[JsonSerializable(typeof(GreetResponse))]
internal sealed partial class AppJsonContext : JsonSerializerContext;

4. 写特性。框架里一个"特性"就是一个实现 IFeature 的类，新建 GreetingsFeature.cs，清单声明它依赖哪些能力，Configure 调用源生成器产出的 AddGeneratedOperations 登记操作：

using XiHan.Framework.Kernel;
using XiHan.Framework.Kernel.Hosting;
using XiHan.Framework.Primitives;
using XiHan.Framework.Primitives.Manifests;

namespace HelloXiHan;

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();
}

5. 在 Program.cs 中把特性交给内核：

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);

// 把特性交给内核：求解能力图谱，按拓扑顺序调用各特性的 Configure
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();

6. 运行：

dotnet run --urls http://localhost:5000

启动日志会先打印已解析的能力图谱，再打印管道顺序。另开一个终端调用操作，返回 201 Created 和 {"message":"Hello, Ada!","traceId":"…"}：

curl -i -X POST http://localhost:5000/greetings -H "Content-Type: application/json" -d '{"name":"Ada"}'

换成 Standard 组合、观察管道里多出的认证、租户、授权、幂等和事务，以及完整示例，见框架快速上手。

使用 XiHan.UI (前端组件)

npm 上的 xihan-ui（单包，最后一版 0.9.8）是重构前的旧实现，已全部标记弃用，与下面这套不是同一个东西。

1. 安装适配器与默认皮肤（包按 @xihan-ui/* 分发，装哪几个取决于用哪个适配器）：

# Vue 项目
pnpm add @xihan-ui/vue @xihan-ui/styles

# React 项目
pnpm add @xihan-ui/react @xihan-ui/styles

# 原生 / 其它框架：自定义元素
pnpm add @xihan-ui/web-components @xihan-ui/styles

2. 在入口引入皮肤，并初始化视觉环境：

// main.ts
import { createVisualEnvironmentController } from "@xihan-ui/tokens/runtime";
import { createApp } from "vue";
import App from "./App.vue";

// 皮肤入口自带层序声明与令牌，只引这一行；单独引 tokens.css 是只要令牌不要皮肤的路径
import "@xihan-ui/styles";

// 把七轴视觉环境写到 <html> 上，并显式处理持久化失败
createVisualEnvironmentController({
  root: document.documentElement,
  storageKey: "app-visual-environment",
  onStorageError: detail => console.error("视觉偏好持久化失败", detail),
  initial: { mode: "system", motion: "system", transparency: "system" },
});

createApp(App).mount("#app");

3. 组件从主入口按需取，不需要注册插件（包声明了 sideEffects: false，打包器会摇掉没用到的）：

<template>
  <XhButton variant="solid" tone="brand">曦寒按钮</XhButton>
</template>

<script setup lang="ts">
import { XhButton } from "@xihan-ui/vue";
</script>

完整的安装选项、样式的三种接法、服务端渲染注意事项，见组件库安装与接入。

使用 XiHan.BasicApp (完整应用)

如果您想快速启动一个完整的应用，可以直接使用 XiHan.BasicApp：

# 克隆仓库
git clone https://github.com/XiHanFun/XiHan.BasicApp.git

# 启动后端
cd XiHan.BasicApp/backend
dotnet run --project src/main/XiHan.BasicApp.WebHost --launch-profile Development

# 在另一个终端中启动前端
cd XiHan.BasicApp/frontend
pnpm install
pnpm dev

后端启动后访问 http://127.0.0.1:9708/scalar 查看 API 文档，首次启动会自动建表并初始化种子数据。

数据库连接串在 backend/src/main/XiHan.BasicApp.WebHost/appsettings.Development.json 中配置。

下一步

三款主推产品各有独立文档站，从这里进去：

• 探索 开发框架文档 了解后端开发框架
• 探索 视图组件文档 了解前端视图组件
• 探索 基础应用文档 了解完整应用案例

三者的关系与选型建议见生态总览；用 Claude Code、Cursor 等 AI 编程工具开发时，先按AI 辅助开发接入框架与组件库的 MCP 服务端。