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 本地逻辑
