SAEA.MVC 26.4.23.1

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

English Version | 中文版

基于 .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