MAUI嵌入式Web架构中，PicoServer路由机制与API设计如何优化？
摘要：MAUI 嵌入式 Web 架构实战（二） PicoServer 路由机制与 API 设计 构建 MAUI 本地 HTTP REST API 服务 源码地址： https:github.comdensen2014MauiPicoAdm
MAUI 嵌入式 Web 架构实战（二）
PicoServer 路由机制与 API 设计
构建 MAUI 本地 HTTP REST API 服务
源码地址：
https://github.com/densen2014/MauiPicoAdmin
一、整体架构
在 .NET MAUI 应用 中嵌入 PicoServer 后，可以形成如下的嵌入式 Web 架构：
Browser / WebView
│
HTTP
│
┌────────────┐
│ PicoServer │
└────────────┘
│
┌──────────────┼──────────────┐
│ │
REST API Web Admin
│ │
└──────────────┬──────────────┘
│
Service Layer
│
MAUI App
在这个架构中：
PicoServer 负责处理 HTTP 请求
REST API 提供数据接口
Web Admin 提供管理界面
Service Layer 负责业务逻辑
MAUI App 负责设备能力与本地功能
这种模式可以让一个 移动或桌面应用同时具备 Web Server 能力。
二、从 Hello PicoServer 到 API Server
在上一篇文章 《MAUI 嵌入式 Web 架构实战（一）》 中，我们已经完成了基础环境搭建：
在 MAUI 中嵌入 PicoServer
启动本地 HTTP 服务
浏览器访问
http://127.0.0.1:8090
返回：
Hello PicoServer
这说明我们的应用已经具备了：
本地 Web Server 能力
但在真实项目中，仅仅返回字符串显然远远不够。
一个真正可用的本地 Web 服务通常需要：
REST API
JSON 数据接口
设备控制接口
本地 Web 管理后台
因此，本篇文章将重点介绍：
PicoServer 的路由机制与 API 设计方法
并将示例服务器升级为 一个真正可用的本地 API 服务。
三、什么是路由（Route）
在 Web 服务器中，路由（Route） 用于定义：
URL 与处理函数之间的映射关系
例如：
URL
处理逻辑
/
首页
/api/time
返回服务器时间
/api/device/list
返回设备列表
当浏览器访问：
http://127.0.0.1:8090/api/time
服务器处理流程如下：
Browser
│
HTTP Request
│
/api/time
│
PicoServer Router
│
Handler Method
│
JSON Response
因此，路由系统是 Web 服务的核心组件之一。
四、PicoServer 路由基本用法
在第一篇示例中，我们已经使用了最简单的一条路由：
MyAPI.AddRoute("/", Hello);
完整代码如下：
public class PicoAdmin
{
private readonly WebAPIServer MyAPI = new WebAPIServer();
public PicoAdmin()
{
MyAPI.AddRoute("/", Hello);
MyAPI.StartServer();
}
private async Task Hello(HttpListenerRequest request, HttpListenerResponse response)
{
await response.WriteAsync("Hello PicoServer");
}
}
路由映射关系：
/ → Hello()
当访问 / 时，就会执行 Hello() 方法。
五、添加多个 API 路由
在实际项目中，我们通常需要多个 API，例如：
获取服务器时间
查询系统状态
获取设备列表
可以这样定义多个路由：
public PicoAdmin()
{
MyAPI.AddRoute("/", Hello);
MyAPI.AddRoute("/api/time", GetTime);
MyAPI.AddRoute("/api/status", GetStatus);
MyAPI.StartServer();
}
实现对应接口：
private async Task GetTime(HttpListenerRequest request, HttpListenerResponse response)
{
var time = DateTime.Now.ToString();
await response.WriteAsync(time);
}
private async Task GetStatus(HttpListenerRequest request, HttpListenerResponse response)
{
await response.WriteAsync("Server Running");
}
访问：
http://127.0.0.1:8090/api/time
返回示例：
2026/3/5 14:30:12
六、设计 REST 风格 API
现代 Web 系统通常采用 REST 风格 API。
例如：
API
功能
GET /api/product/list
商品列表
GET /api/product/detail?id=1
商品详情
POST /api/product/add
新增商品
这种设计具有以下优点：
接口语义清晰
结构可扩展
方便前端调用
在 PicoServer 中可以这样设计：
MyAPI.AddRoute("/api/product/list", ProductList);
MyAPI.AddRoute("/api/product/detail", ProductDetail);
七、返回 JSON 数据
实际 API 通常返回 JSON 数据，而不是简单字符串。
例如：
{
"code": 0,
"message": "ok",
"data": {
"time": "2026-03-05 14:30:00"
}
}
在 C# 中可以这样实现：
private async Task GetTime(HttpListenerRequest request, HttpListenerResponse response)
{
var result = new
{
code = 0,
message = "ok",
data = new
{
time = DateTime.Now
}
};
string json = System.Text.Json.JsonSerializer.Serialize(result);
response.ContentType = "application/json";
await response.WriteAsync(json);
}
访问：
http://127.0.0.1:8090/api/time
返回：
{
"code":0,
"message":"ok",
"data":{
"time":"2026-03-05T14:30:00"
}
}
这样，一个 标准 REST API 就完成了。
八、读取 GET 参数
很多 API 需要读取请求参数，例如：
/api/product/detail?id=1001
可以这样获取参数：
private async Task ProductDetail(HttpListenerRequest request, HttpListenerResponse response)
{
string id = request.QueryString["id"];
var result = new
{
id = id,
name = "Demo Product",
price = 100
};
string json = JsonSerializer.Serialize(result);
response.ContentType = "application/json";
await response.WriteAsync(json);
}
访问：
http://127.0.0.1:8090/api/product/detail?id=1001
返回：
{
"id":"1001",
"name":"Demo Product",
"price":100
}
九、商品列表 API 示例
private async Task ProductList(HttpListenerRequest request, HttpListenerResponse response)
{
var products = new[]
{
new { id = "1", name = "Demo Product 1", price = 100 },
new { id = "2", name = "Demo Product 2", price = 200 },
new { id = "3", name = "Demo Product 3", price = 300 }
};
var result = new
{
code = 0,
message = "ok",
data = products
};
string json = JsonSerializer.Serialize(result);
response.ContentType = "application/json";
await response.WriteAsync(json);
}
访问：
http://127.0.0.1:8090/api/product/list
返回：
{
"code": 0,
"message": "ok",
"data": [
{ "id": "1", "name": "Demo Product 1", "price": 100 },
{ "id": "2", "name": "Demo Product 2", "price": 200 },
{ "id": "3", "name": "Demo Product 3", "price": 300 }
]
}
十、API 路由设计建议
在设计本地 API 时，建议遵循以下规则。
1 统一 API 前缀
推荐统一使用：
/api/*
例如：
GET /api/product/list
GET /api/product/detail?id=1
POST /api/product/add
DELETE /api/product/delete?id=1
HTTP 方法说明：
GET 查询
POST 创建
PUT 更新
DELETE 删除
2 统一返回结构
建议统一 JSON 返回格式：
{
"code":0,
"message":"ok",
"data":{}
}
优点：
前端统一处理
错误处理简单
接口规范清晰
3 API 模块分组
推荐按业务模块分组：
/api/system/*
/api/device/*
/api/product/*
这样可以保持接口结构清晰、易维护。
十一、本地 API 的典型应用场景
当 App 内部运行一个 HTTP Server 时，可以实现很多有趣的架构模式。
本地 Web Admin
Browser
↓
localhost:8090
↓
PicoServer API
↓
MAUI 本地逻辑
WebView + 本地 API
WebView 页面
↓
fetch("/api/product/list")
↓
PicoServer
↓
C# 业务逻辑
局域网设备控制
手机 / PC
↓
http://192.168.1.100:8090
↓
设备控制 API
这种模式在以下场景非常常见：
IoT 设备管理
桌面软件后台
本地控制台
调试接口
十二、本篇总结
在本篇文章中，我们完成了三个关键步骤：
1️⃣ 理解 PicoServer 路由机制
2️⃣ 构建多个 API 接口
3️⃣ 返回标准 JSON 数据
至此，我们已经将最初的：
Hello PicoServer
升级成：
一个真正可用的本地 REST API 服务。
下一篇预告
下一篇我们将继续升级架构：
《MAUI 嵌入式 Web 架构实战（三）》
构建可扩展的 PicoServer REST API 框架
内容包括：
Controller 结构设计
Service 分层架构
统一 API 返回模型
全局异常处理
日志系统
最终目标是构建一个 可扩展的嵌入式 API 框架。
系列文章
1 MAUI 中嵌入 PicoServer
2 PicoServer 路由机制与 API 设计
3 构建可扩展 REST API 框架
4 静态文件托管与前端整合
5 构建 Web Admin 管理后台
6 登录认证与权限系统
7 局域网访问与设备管理
8 本地缓存架构
9 PicoServer + PWA 离线系统
10 完整 App Web Shell 架构