## 概述
XiHan.Framework 是面向企业级应用的模块化后端框架，专为前后端分离的 ASP.NET Core 应用设计。框架优先使用 .NET 原生功能，减少第三方依赖，强调模块清晰、依赖可控、扩展可维护。通过 `[DependsOn]` 属性声明模块依赖，自动拓扑排序加载，以应用服务与动态 API 约定统一接口暴露方式。
## 文档
| 去处 | 内容 |
| --- | --- |
| [文档站](https://framework.docs.xihanfun.com) | 完整指南与 66 个包的逐包 API 文档 |
| [框架工程说明](./framework/README_cn.md) | 分层架构、模块清单、目录结构、依赖关系 |
| [更新日志](https://framework.docs.xihanfun.com/changelog) | 各版本变更与升级须知 |
| [贡献指南](./CONTRIBUTING.md) | 分支约定、提交规范、本地构建与测试 |
## 设计原则
- **分层架构** - 遵循清晰的分层原则，避免循环依赖
- **依赖倒置** - 高层模块不依赖低层模块，都依赖抽象接口
- **单一职责** - 每个包只负责一个特定的功能领域
- **开闭原则** - 对扩展开放，对修改关闭，通过接口和抽象类支持自定义
- **优先 .NET 10** - 使用内置功能（DI、日志、序列化），仅在必要时引入第三方库
- **性能优化** - 利用 .NET 10 高性能特性；AOT 不在支持范围（核心依赖 SqlSugar / Castle DynamicProxy / Newtonsoft.Json 暂不兼容裁剪）
## 技术栈
| 类别 | 技术 |
| --- | --- |
| 运行时 | .NET |
| 语言 | C# |
| ORM | SqlSugarCore |
| 日志 | Serilog.AspNetCore |
| 缓存 | Microsoft.Extensions.Caching.Hybrid + StackExchangeRedis |
| AOP | Castle.Core (DynamicProxy) |
| 加密 | BouncyCastle.Cryptography |
| 序列化 | System.Text.Json（内置）+ Newtonsoft.Json |
| 模板引擎 | Scriban |
| AI | Microsoft.Extensions.AI + Microsoft.Agents.AI + MCP |
| HTTP 韧性 | Microsoft.Extensions.Http.Polly |
| gRPC | Grpc.AspNetCore |
| 实时通信 | ASP.NET Core SignalR |
| API 文档 | Scalar.AspNetCore + Swashbuckle.AspNetCore |
| IP 定位 | IP2Region.Net |
| 消息通知 | MailKit + Telegram.Bot |
| 搜索 | Elastic.Clients.Elasticsearch |
| 测试 | xunit.v3 + Microsoft.Testing.Platform（含 CodeCoverage 扩展） |
各依赖的具体版本以 `framework/src` 下各工程的 `PackageReference` 为准。
## 快速开始
### 安装
通过 NuGet 安装所需模块：
```bash
# 安装核心模块
dotnet add package XiHan.Framework.Core
# 安装 Web API 模块（包含完整中间件管道）
dotnet add package XiHan.Framework.Web.Api
# 安装 API 文档模块
dotnet add package XiHan.Framework.Web.Docs
# 安装数据访问模块
dotnet add package XiHan.Framework.Data
```
### 定义模块
每个模块继承 `XiHanModule`，通过 `[DependsOn]` 声明依赖：
```csharp
using XiHan.Framework.Core.Modularity;
using XiHan.Framework.Web.Api;
using XiHan.Framework.Data;
[DependsOn(
typeof(XiHanWebApiModule),
typeof(XiHanDataModule)
)]
public class MyAppModule : XiHanModule
{
public override Task ConfigureServicesAsync(ServiceConfigurationContext context)
{
// 注册服务
return Task.CompletedTask;
}
public override Task OnApplicationInitializationAsync(ApplicationInitializationContext context)
{
// 应用初始化
return Task.CompletedTask;
}
}
```
### 启动应用
```csharp
using XiHan.Framework.Core.Extensions.DependencyInjection;
using XiHan.Framework.Web.Core.Extensions.DependencyInjection;
var builder = WebApplication.CreateBuilder(args);
await builder.AddApplicationAsync
