如何构建可扩展的MAUI PicoServer REST API框架实现实战？
摘要：MAUI 嵌入式 Web 架构实战（三） 构建可扩展的 PicoServer REST API 框架 源码地址： https:github.comdensen2014MauiPicoAdmin 一、从简单 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);
await response.WriteAsync(json, contentType: "application/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 本地逻辑