MAUI 嵌入式 Web 架构实战（三） 构建可扩展的 PicoServer REST API 框架

MAUI 嵌入式 Web 架构实战（三）

构建可扩展的 PicoServer REST API 框架

源码地址：
https://github.com/densen2014/MauiPicoAdmin

---

一、从简单 API 到可扩展架构

在上一篇文章 《MAUI 嵌入式 Web 架构实战（二）》 中，我们已经成功构建了多个 PicoServer API，例如：

/api/time
/api/product/list
/api/product/detail

这些接口已经可以：

• 处理 HTTP 请求
• 返回 JSON 数据
• 支持简单的参数读取

例如：

http://127.0.0.1:8090/api/product/list

返回：

{
  "code":0,
  "message":"ok",
  "data":[]
}

这意味着我们的 MAUI 应用已经具备了：

本地 REST API 服务能力

但随着接口数量增加，新的问题会逐渐出现：

• API 全部写在一个类中
• HTTP 逻辑和业务逻辑混在一起
• 返回格式不统一
• 错误处理难以维护

例如：

class PicoAdmin
{
    ProductList()
    ProductDetail()
    ProductAdd()
    ProductDelete()
}

当接口数量达到：

50+
100+
200+

代码就会变得难以维护。

因此，本篇文章将对 PicoServer 进行一次 架构升级。

目标是构建一个：

可扩展的本地 REST API 框架结构

核心目标包括：

• API 模块化
• Controller / Service 分层
• 统一返回结构
• 统一异常处理
• 清晰的项目结构

---

二、REST API 框架核心架构

升级后的 API 架构如下：

HTTP Request
      │
      ▼
   PicoServer
      │
     Router
      │
   Controller
      │
    Service
      │
Data / Device / Logic

各层职责：

层	作用
Router	路由分发
Controller	HTTP 请求处理
Service	业务逻辑
Data / Device	数据或设备操作

这种结构与常见 Web 框架（如 ASP.NET Core）非常类似。

---

三、推荐项目目录结构

为了让 API 更易维护，可以采用如下结构：

Server
 ├─ Controllers
 │   ├─ ProductController.cs
 │   └─ SystemController.cs
 │
 ├─ Services
 │   └─ ProductService.cs
 │
 ├─ Models
 │   └─ ApiResult.cs
 │
 └─ PicoServerHost.cs

目录职责说明：

目录	作用
Controllers	API 路由处理
Services	业务逻辑
Models	数据模型
PicoServerHost	服务器启动与路由注册

这种结构可以保持代码清晰、模块化。

---

四、统一 API 返回结构

在 API 系统中，统一返回格式非常重要。

我们先定义一个返回模型。

ApiResult.cs

public class ApiResult
{
    public int Code { get; set; }
    public string Message { get; set; }
    public object Data { get; set; }

    public static ApiResult Success(object data)
    {
        return new ApiResult
        {
            Code = 0,
            Message = "ok",
            Data = data
        };
    }

    public static ApiResult Error(string msg)
    {
        return new ApiResult
        {
            Code = 1,
            Message = msg
        };
    }
}

统一 JSON 返回格式：

{
  "code":0,
  "message":"ok",
  "data":{}
}

优点：

• 前端解析统一
• 错误处理简单
• API 结构规范

---

五、Service 层（业务逻辑）

业务逻辑应该与 HTTP 处理分离。

创建：

ProductService.cs

public class ProductService
{
    public List<object> GetProducts()
    {
        return new List<object>
        {
            new { id = 1, name = "Apple", price = 10 },
            new { id = 2, name = "Orange", price = 8 }
        };
    }

    public object GetProduct(string id)
    {
        return new { id = id, name = "Demo Product", price = 100 };
    }
}

职责：

Controller → 调用 Service
Service → 处理业务逻辑

好处：

• 业务逻辑可复用
• Controller 更简洁
• 易于维护和扩展

---

六、Controller 层（API 入口）

Controller 负责：

• 接收 HTTP 请求
• 读取参数
• 调用 Service
• 返回 JSON

创建：

ProductController.cs

public class ProductController
{
    private ProductService service = new ProductService();

    public async Task List(HttpListenerRequest request, HttpListenerResponse response)
    {
        var data = service.GetProducts();

        var result = ApiResult.Success(data);

        string json = JsonSerializer.Serialize(result);

        response.ContentType = "application/json";
        await response.WriteAsync(json);
    }

    public async Task Detail(HttpListenerRequest request, HttpListenerResponse response)
    {
        string id = request.QueryString["id"];

        var data = service.GetProduct(id);

        var result = ApiResult.Success(data);

        string json = JsonSerializer.Serialize(result);

        response.ContentType = "application/json";
        await response.WriteAsync(json);
    }
}

Controller 的职责非常清晰：

HTTP Request
      ↓
读取参数
      ↓
调用 Service
      ↓
返回 JSON

---

七、统一注册路由

接下来创建服务器启动类：

PicoServerHost.cs

public class PicoServerHost
{
    private readonly WebAPIServer api = new WebAPIServer();

    public PicoServerHost()
    {
        RegisterRoutes();
        api.StartServer();
    }

    private void RegisterRoutes()
    {
        var product = new ProductController();

        api.AddRoute("/api/product/list", product.List);
        api.AddRoute("/api/product/detail", product.Detail);
    }
}

完整调用流程变成：

HTTP Request
      ↓
PicoServer Router
      ↓
Controller
      ↓
Service
      ↓
Data / Device

这种结构已经非常接近一个 轻量级 Web 框架。

---

八、统一 JSON 输出工具

为了让 Controller 更简洁，可以封装一个工具方法。

public static class HttpHelper
{
    public static async Task WriteJson(HttpListenerResponse response, object obj)
    {
        string json = JsonSerializer.Serialize(obj);

        response.ContentType = "application/json";

        await response.WriteAsync(json);
    }
}

Controller 就可以写成：

await HttpHelper.WriteJson(response, ApiResult.Success(data));

代码会更简洁。

---

九、统一异常处理

在 API 系统中，建议统一捕获异常：

try
{
    var data = service.GetProducts();
    await HttpHelper.WriteJson(response, ApiResult.Success(data));
}
catch(Exception ex)
{
    await HttpHelper.WriteJson(response, ApiResult.Error(ex.Message));
}

这样可以保证：

• API 永远返回 JSON
• 不会出现 HTML 错误页
• 前端可以统一处理错误

最终把 MauiProgram.cs 的 class PicoAdmin 去掉, 初始化 new PicoAdmin()改为

var picoAdmin = new PicoServerHost(); //实例化PicoAdmin以启动PicoServer

var picoAdmin = new PicoServerHost();

---

十、升级后的完整架构

经过本篇改造后，整个系统结构如下：

浏览器 / WebView
        ↓
     HTTP
        ↓
    PicoServer
        ↓
     Router
        ↓
    Controller
        ↓
     Service
        ↓
   Data / Device

优势：

• API 清晰
• 模块化结构
• 易扩展
• 易维护

此时，我们已经拥有了一个：

轻量级嵌入式 REST API 框架

---

十一、下一步可以继续扩展

在当前架构基础上，可以继续扩展很多能力。

例如：

中间件系统

日志
鉴权
请求过滤
CORS

---

Token 登录系统

/api/login
/api/user/info

---

Web Admin 后台

结合前端框架：

Vue
React
Admin Dashboard

实现完整管理系统。

---

十二、本篇总结

在本篇文章中，我们完成了 PicoServer API 架构升级：

新增能力：

• API 分层结构
• Controller / Service 架构
• 统一 JSON 返回
• 路由统一注册
• 异常处理机制

至此，我们的 MAUI 应用已经具备：

一个可扩展的本地 REST API 服务框架

这也是后续构建 Web Admin 管理后台 的基础。

---

下一篇预告

下一篇将进入一个非常关键的部分：

《MAUI 嵌入式 Web 架构实战（四）》

静态文件托管与前端框架整合

我们将实现：

• 托管 HTML / CSS / JS
• 托管 Vue / React 构建产物
• 设置默认首页
• 构建真正的 本地 Web Admin 系统

最终架构将变成：

浏览器
   ↓
localhost:8090
   ↓
Web Admin UI
   ↓
PicoServer API
   ↓
MAUI 本地逻辑