快速上手
项目组成
本项目由 XiHan.Framework（开发框架）、XiHan.UI（视图组件）、XiHan.BasicApp（基础应用）组成。
- 开发框架子项目：是后端模块化应用开发框架集成，基于 DotNet 构建。
- 视图组件子项目：是前端组件库集成，基于 Vue 构建。
- 基础应用子项目：为开发框架和视图组件的结合，为通用、全面的管理系统。
环境准备
在开始使用 XiHan 系列项目前，请确保您的开发环境已安装以下工具：
后端开发环境
- .NET SDK (版本 10 或更高)
- 推荐 IDE：Visual Studio 2022、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 (后端框架)
框架是按模块安装的，用什么装什么。搭一个 Web API 最少需要下面两个包：
- 创建新项目并安装 NuGet 包：
bash
dotnet new web -n MyApp
cd MyApp
# 动态 API + 中间件管道（依赖会自动带上 Core、Web.Core、Application 等）
dotnet add package XiHan.Framework.Web.Api
# API 文档（Scalar / Swagger UI），开发期推荐
dotnet add package XiHan.Framework.Web.Docs- 定义启动模块。框架里一个"模块"就是一个继承
XiHanModule的类，用[DependsOn]声明它要用哪些能力：
csharp
// MyAppModule.cs
using XiHan.Framework.Core.Modularity;
using XiHan.Framework.Web.Api;
using XiHan.Framework.Web.Docs;
namespace MyApp;
[DependsOn(
typeof(XiHanWebApiModule), // 动态 API + 中间件管道
typeof(XiHanWebDocsModule) // Scalar / Swagger 文档
)]
public class MyAppModule : XiHanModule
{
// 可重写 ConfigureServices / OnApplicationInitialization 等生命周期钩子
}- 在 Program.cs 中加载模块树：
csharp
using MyApp;
using XiHan.Framework.Web.Core.Extensions.DependencyInjection;
var builder = WebApplication.CreateBuilder(args);
// 加载以 MyAppModule 为根的整棵模块依赖树（自动拓扑排序）
await builder.AddApplicationAsync<MyAppModule>();
var app = builder.Build();
// 触发所有模块的初始化钩子，装配中间件管道
await app.InitializeApplicationAsync();
await app.RunAsync();- 写第一个接口。框架用动态 API 暴露接口，只需写一个应用服务类，不需要写 Controller：
csharp
// HelloAppService.cs
using XiHan.Framework.Application.Attributes;
using XiHan.Framework.Application.Services;
namespace MyApp;
[DynamicApi]
public class HelloAppService : ApplicationServiceBase
{
public string GetGreeting(string name)
{
return $"你好，{name}！欢迎使用 XiHan.Framework。";
}
}dotnet run 后打开 https://localhost:<端口>/scalar 即可在线调用。
更详细的分步讲解、数据访问接入与可选模块清单，见框架快速上手。
使用 XiHan.UI (前端组件)
npm 上的
xihan-ui（单包，最后一版0.9.8）是重构前的旧实现，已全部标记弃用，与下面这套不是同一个东西。
- 安装适配器与默认皮肤（包按
@xihan-ui/*分发，装哪几个取决于用哪个适配器）：
bash
# Vue 3 项目
pnpm add @xihan-ui/vue @xihan-ui/styles
# React 19 项目
pnpm add @xihan-ui/react @xihan-ui/styles
# 原生 / 其它框架：自定义元素
pnpm add @xihan-ui/web-components @xihan-ui/styles- 在入口引入皮肤，并初始化视觉环境：
ts
// 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");- 组件从主入口按需取，不需要注册插件（包声明了
sideEffects: false，打包器会摇掉没用到的）：
vue
<template>
<XhButton variant="solid" tone="brand">曦寒按钮</XhButton>
</template>
<script setup lang="ts">
import { XhButton } from "@xihan-ui/vue";
</script>完整的安装选项、样式的三种接法、服务端渲染注意事项，见组件库安装与接入。
使用 XiHan.BasicApp (完整应用)
如果您想快速启动一个完整的应用，可以直接使用 XiHan.BasicApp：
bash
# 克隆仓库
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 文档。仓库当前 Development 与 Production 都监听 9708，部署时可通过 Hosting:Urls 或容器端口映射覆盖。
数据库连接串在 backend/src/main/XiHan.BasicApp.WebHost/appsettings.Development.json 中配置。
下一步
三个仓库各有独立文档站，从这里进去：
三者的关系与选型建议见生态总览。