👁 Image
SAEA.MVC 26.4.23.1

SAEA.MVC - 轻量级高性能 MVC Web 框架 🌐

👁 NuGet version
👁 License

| 中文版

基于 .NET Standard 2.0 的轻量级 MVC Web 框架，采用 IOCP 技术，自宿主运行，无需 IIS/Kestrel。

快速导航 🧭

30秒快速开始 ⚡

最快上手方式，只需3步即可启动 Web 服务器：

Step 1: 安装 NuGet 包

dotnet add package SAEA.MVC

Step 2: 创建 MVC 应用（仅需5行代码）

using SAEA.MVC;

var config = SAEAMvcApplicationConfigBuilder.Read();
var app = new SAEAMvcApplication(config);
app.SetDefault("home", "index");
app.Start();

Step 3: 创建第一个 Controller

public class HomeController : Controller
{
 [HttpGet]
 public ActionResult Index()
 {
 return Content("Hello, SAEA.MVC!");
 }
}

就这么简单！ 🎉 访问 http://localhost:28080/home/index 即可看到结果。

核心特性 🎯

架构设计 📐

组件架构图

┌─────────────────────────────────────────────────────────────┐
│ SAEA.MVC 架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ SAEAMvcApplication │ │
│ │ (应用程序入口) │ │
│ └────────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ┌────▼────┐ ┌───▼────┐ ┌───▼────┐ │
│ │ Route │ │ Filter │ │ Static │ │
│ │ Table │ │ (AOP) │ │ File │ │
│ │ (路由) │ │(过滤器)│ │(静态) │ │
│ └────┬────┘ └───┬────┘ └───┬────┘ │
│ │ │ │ │
│ └───────────┼────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ Controller │ │
│ │ (控制器) │ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────────┼───────────┐ │
│ │ │ │ │
│ ┌────▼───┐ ┌───▼────┐ ┌──▼───┐ │
│ │Action │ │ Http │ │Result│ │
│ │Result │ │Context │ │Types │ │
│ │(结果) │ │(上下文)│ │(类型)│ │
│ └────────┘ └────────┘ └──────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ SAEA.Sockets (底层) │ │
│ │ IOCP 通信引擎 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘

请求处理流程图

HTTP 请求处理流程:

客户端请求 ──► SAEA.Sockets 接收
 │
 ▼
 ┌─────────────────┐
 │ HttpParser │ 解析 HTTP 请求
 │ 解析请求头/体 │
 └─────────────────┘
 │
 ▼
 ┌─────────────────┐
 │ RouteTable │ 路由匹配
 │ 查找 Controller│
 └─────────────────┘
 │
 ▼
 ┌─────────────────┐
 │ ActionFilter │ 执行前置过滤器
 │ OnActionExecuting│
 └─────────────────┘
 │
 ▼
 ┌─────────────────┐
 │ Controller │ 执行 Action 方法
 │ Action 执行 │
 └─────────────────┘
 │
 ▼
 ┌─────────────────┐
 │ ActionResult │ 生成响应结果
 │ ExecuteResult │
 └─────────────────┘
 │
 ▼
 ┌─────────────────┐
 │ ActionFilter │ 执行后置过滤器
 │ OnActionExecuted│
 └─────────────────┘
 │
 ▼
 ┌─────────────────┐
 │ OutputCache │ 缓存处理
 │ (如果启用) │
 └─────────────────┘
 │
 ▼
 HTTP 响应返回客户端


ActionResult 类型分支:

ActionResult ──┬── JsonActionResult ──► JSON 序列化输出
 │
 ├── ContentResult ────► 文本/HTML 输出
 │
 ├── FileResult ───────► 文件下载(小文件)
 │
 ├── BigDataResult ────► 大文件流式传输
 │
 ├── DataResult ───────► 二进制数据输出
 │
 ├── EmptyResult ──────► 空响应
 │
 └── SSEActionResult ───► Server-Sent Events 推送

应用场景 💡

✅ 适合使用 SAEA.MVC 的场景

❌ 不适合的场景

与 ASP.NET Core 对比

性能对比 📊

与其他 Web 框架对比

输出缓存性能

IOCP vs 传统模型

💡 提示: IOCP 是 Windows 平台最高效的异步 IO 模型，专为高并发场景设计。

常见问题 ❓

Q1: SAEA.MVC 与 ASP.NET Core MVC 有什么区别？

A: 主要区别：

SAEA.MVC 更适合轻量级、高性能 API 服务场景。

Q2: 如何启用输出缓存？

A: 使用 OutputCacheAttribute 特性：

[OutputCache(Duration = 60)] // 缓存 60 秒
public ActionResult GetList()
{
 return Json(GetDataFromDatabase());
}

Q3: 如何处理文件上传？

A: 通过 HttpContext.Request.PostFiles 获取：

[HttpPost]
public ActionResult Upload()
{
 var files = HttpContext.Request.PostFiles;
 foreach (var file in files)
 {
 var path = Path.Combine(uploadPath, file.FileName);
 file.Save(path);
 }
 return Json(new { Count = files.Count });
}

Q4: 如何实现全局异常处理？

A: 创建全局异常过滤器：

public class GlobalExceptionFilter : ActionFilterAttribute
{
 public override void OnActionExecuted(HttpContext httpContext)
 {
 if (httpContext.Exception != null)
 {
 httpContext.Response.StatusCode = 500;
 httpContext.Response.Write(JsonConvert.SerializeObject(new
 {
 Error = httpContext.Exception.Message
 }));
 httpContext.Exception = null;
 }
 base.OnActionExecuted(httpContext);
 }
}

// 应用全局过滤器
[GlobalExceptionFilter]
public class BaseController : Controller { }

Q5: 如何配置跨域 (CORS)？

A: 在配置中设置 CORS 头：

public class CorsFilter : ActionFilterAttribute
{
 public override void OnActionExecuting(HttpContext httpContext)
 {
 httpContext.Response.Headers["Access-Control-Allow-Origin"] = "*";
 httpContext.Response.Headers["Access-Control-Allow-Methods"] = "GET,POST,PUT,DELETE";
 httpContext.Response.Headers["Access-Control-Allow-Headers"] = "Content-Type";
 base.OnActionExecuting(httpContext);
 }
}

Q6: 如何实现 SSE 服务器推送？

A: 返回 SSEActionResult：

public ActionResult StreamEvents()
{
 var stream = new SSEActionResult();
 
 // 定时发送事件
 Task.Run(async () =>
 {
 for (int i = 0; i < 10; i++)
 {
 stream.Send("message", $"Event {i} at {DateTime.Now}");
 await Task.Delay(1000);
 }
 stream.Close();
 });
 
 return stream;
}

// 客户端
// var source = new EventSource("/home/streamevents");
// source.onmessage = e => console.log(e.data);

Q7: 如何部署到生产环境？

A: 部署步骤：

1. 发布应用程序

dotnet publish -c Release -r win-x64 --self-contained true

1. 配置文件 (可选)

var config = new SAEAMvcApplicationConfig
{
 Root = "wwwroot",
 Port = 80,
 IsStaticsCached = true,
 MaxConnects = 5000,
 Timeout = 180
};
SAEAMvcApplicationConfigBuilder.Write(config);

1. 注册为 Windows 服务 (可选)

sc create SAEAMvc binPath="path/to/your/app.exe" start=auto

核心类 🔧

使用示例 📝

启动 MVC 应用

using SAEA.MVC;

// 读取配置
var config = SAEAMvcApplicationConfigBuilder.Read();

// 创建 MVC 应用
var app = new SAEAMvcApplication(config);

// 设置默认路由
app.SetDefault("home", "index");
app.SetDefault("index.html");

// 设置禁止访问路径
app.SetForbiddenAccessList("/content/");
app.SetForbiddenAccessList(".config");

// 启动服务
app.Start();

Console.WriteLine($"MVC 服务已启动，端口: {config.Port}");

定义 Controller

using SAEA.MVC;

[LogAttribute] // 类级别过滤器
public class HomeController : Controller
{
 [HttpGet]
 public ActionResult Index()
 {
 return Content("Hello, SAEA.MVC!");
 }

 [HttpGet]
 public ActionResult GetInfo(string name, int age)
 {
 var result = new { Name = name, Age = age };
 return Json(result);
 }

 [HttpPost]
 public ActionResult Login(string username, string password)
 {
 if (username == "admin" && password == "123456")
 return Json(new { Success = true, Message = "登录成功" });
 return Json(new { Success = false, Message = "登录失败" });
 }

 [HttpPost]
 public ActionResult Upload(string name)
 {
 var files = HttpContext.Request.PostFiles;
 return Json(new { Name = name, FileCount = files.Count });
 }

 public ActionResult Download()
 {
 return File(HttpContext.Server.MapPath("/files/document.pdf"));
 }

 [OutputCache(Duration = 60)]
 public ActionResult Cached()
 {
 return Content($"时间: {DateTime.Now}");
 }
}

ActionResult 类型

// JSON 结果
return Json(new { Id = 1, Name = "Test" });

// 文本/HTML 内容
return Content("<h1>Hello World</h1>");

// 文件下载
return File(@"C:\files\document.pdf");

// 大文件流式传输
return BigData(@"C:\files\large_video.mp4");

// 二进制数据
return Data(new byte[] { 0x01, 0x02, 0x03 });

// 空结果（直接操作 Response）
var response = HttpContext.Response;
response.ContentType = "text/html";
response.Write("<h3>自定义响应</h3>");
response.End();
return Empty();

SSE 服务器推送

using SAEA.MVC;

public ActionResult StreamEvents()
{
 var stream = GetEventStream();
 
 stream.Send("message", "Hello Client!");
 stream.Send("update", DateTime.Now.ToString());
 
 return stream;
}

// 客户端通过 EventSource 接收
// var source = new EventSource("/home/streamevents");
// source.onmessage = (e) => console.log(e.data);

AOP 过滤器

using SAEA.MVC.Model;

// 自定义过滤器
public class LogAttribute : ActionFilterAttribute
{
 public override void OnActionExecuting(HttpContext httpContext)
 {
 Console.WriteLine($"请求: {httpContext.Request.Url}");
 }

 public override void OnActionExecuted(HttpContext httpContext)
 {
 Console.WriteLine($"响应完成");
 }
}

// 应用过滤器
[LogAttribute]
public class UserController : Controller
{
 [HttpGet]
 [Log2Attribute] // 方法级别过滤器
 public ActionResult List()
 {
 return Json(GetUsers());
 }
}

配置项

using SAEA.MVC;

var config = new SAEAMvcApplicationConfig
{
 Root = "wwwroot", // 网站根目录
 Port = 28080, // 监听端口
 IsStaticsCached = true, // 静态文件缓存
 IsZiped = false, // GZIP 压缩
 BufferSize = 1024 * 64, // 缓冲区大小
 MaxConnects = 1000, // 最大连接数
 DefaultPage = "index.html", // 默认首页
 IsDebug = false, // 调试模式
 Timeout = 180, // 接口超时(秒)
 ConnectTimeout = 6 // 连接超时(秒)
};

SAEAMvcApplicationConfigBuilder.Write(config);

异步 Action

public class AsyncController : Controller
{
 [HttpGet]
 public async Task<ActionResult> GetData()
 {
 var data = await GetDataFromDatabaseAsync();
 return Json(data);
 }

 private async Task<List<User>> GetDataFromDatabaseAsync()
 {
 await Task.Delay(100);
 return new List<User> { new User { Id = 1, Name = "Test" } };
 }
}

依赖项

相关项目

• SAEA.Rested - 基于 SAEA.MVC 的 REST API 示例项目

更多资源

• GitHub 仓库
• NuGet 包
• 作者博客

许可证

Apache License 2.0