PicoServer 跨平台 Web 实战系列(二) 路由机制与 API 设计

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

PicoServer 路由机制与 API 设计

在上一篇文章 《MAUI 嵌入式 Web 架构实战（一）》 中，我们已经完成了：

• 在 .NET MAUI 中嵌入本地 HTTP 服务
  
• 使用 PicoServer 启动服务器
  
• 浏览器访问 http://127.0.0.1:8090
  
• 返回示例内容：
  

1. Hello PicoServer

复制代码

这说明我们的 App 已经具备了 Web Server 能力。
但在真实项目中，仅仅返回一个字符串显然是不够的。
我们更希望这个服务器能够提供：

• API 接口
  
• JSON 数据
  
• 设备控制
  
• 本地后台管理系统
  

因此，本篇将重点介绍：

PicoServer 的路由机制与 API 设计方法

最终目标是把简单示例升级为 一个真正的本地 API 服务。
一、什么是路由（Route）

在 Web 服务器中，路由（Route） 用于定义：

URL 与处理函数之间的映射关系

例如：
URL处理逻辑/首页/api/time返回服务器时间/api/device/list返回设备列表当浏览器访问：

1. http://127.0.0.1:8090/api/time

复制代码

服务器就会找到对应的 路由处理函数，并返回结果。
二、PicoServer 路由基本用法

在上一篇示例中，我们已经使用了一个最简单的路由：

1. MyAPI.AddRoute("/", Hello);

复制代码

完整代码如下：

1. public class PicoAdmin
2. {
3.     private readonly WebAPIServer MyAPI = new WebAPIServer();
5.     public PicoAdmin()
6.     {
7.         MyAPI.AddRoute("/", Hello);
8.         MyAPI.StartServer();
9.     }
11.     private async Task Hello(HttpListenerRequest request, HttpListenerResponse response)
12.     {
13.         await response.WriteAsync("Hello PicoServer");
14.     }
15. }

复制代码

这里的逻辑非常简单：

1. /  → Hello()

复制代码

当访问 / 时，就会执行 Hello() 方法。
三、添加多个路由

在实际应用中，我们通常会有多个 API。
例如：

• 获取服务器时间
  
• 获取设备列表
  
• 查询系统状态
  

可以这样定义：

1. public PicoAdmin()
2. {
3.     MyAPI.AddRoute("/", Hello);
4.     MyAPI.AddRoute("/api/time", GetTime);
5.     MyAPI.AddRoute("/api/status", GetStatus);
7.     MyAPI.StartServer();
8. }

复制代码

然后实现对应方法：

1. private async Task GetTime(HttpListenerRequest request, HttpListenerResponse response)
2. {
3.     var time = DateTime.Now.ToString();
4.     await response.WriteAsync(time);
5. }
7. private async Task GetStatus(HttpListenerRequest request, HttpListenerResponse response)
8. {
9.     await response.WriteAsync("Server Running");
10. }

复制代码

访问测试：

1. http://127.0.0.1:8090/api/time

复制代码

返回：

1. 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 中完全可以这样设计：

1. MyAPI.AddRoute("/api/product/list", ProductList);
2. MyAPI.AddRoute("/api/product/detail", ProductDetail);

复制代码

五、返回 JSON 数据

实际 API 通常返回 JSON，而不是字符串。
例如：

1. {
2.   "code": 0,
3.   "message": "ok",
4.   "data": {
5.       "time": "2026-03-05 14:30:00"
6.   }
7. }

复制代码

在 C# 中可以这样实现：

1. private async Task GetTime(HttpListenerRequest request, HttpListenerResponse response)
2. {
3.     var result = new
4.     {
5.         code = 0,
6.         message = "ok",
7.         data = new
8.         {
9.             time = DateTime.Now
10.         }
11.     };
13.     string json = System.Text.Json.JsonSerializer.Serialize(result);
15.     response.ContentType = "application/json";
16.     await response.WriteAsync(json);
17. }

复制代码

访问：

1. http://127.0.0.1:8090/api/time

复制代码

返回：

1. {
2.   "code":0,
3.   "message":"ok",
4.   "data":{
5.     "time":"2026-03-05T14:30:00"
6.   }
7. }

复制代码

这样，一个 标准 API 接口就完成了。
六、读取 GET 参数

很多 API 需要读取参数，例如：

1. /api/product/detail?id=1001

复制代码

在 PicoServer 中可以这样获取：

1. private async Task ProductDetail(HttpListenerRequest request, HttpListenerResponse response)
2. {
3.     string id = request.QueryString["id"];
5.     var result = new
6.     {
7.         id = id,
8.         name = "Demo Product",
9.         price = 100
10.     };
12.     string json = JsonSerializer.Serialize(result);
14.     response.ContentType = "application/json";
15.     await response.WriteAsync(json);
16. }

复制代码

访问：

1. http://127.0.0.1:8090/api/product/detail?id=1001

复制代码

返回：

1. {
2.   "id":"1001",
3.   "name":"Demo Product",
4.   "price":100
5. }

复制代码

补上 ProductList

1.     private async Task ProductList(HttpListenerRequest request, HttpListenerResponse response)
2.     {
3.         var products = new[]
4.         {
5.             new { id = "1", name = "Demo Product 1", price = 100 },
6.             new { id = "2", name = "Demo Product 2", price = 200 },
7.             new { id = "3", name = "Demo Product 3", price = 300 }
8.         };
10.         var result = new
11.         {
12.             code = 0,
13.             message = "ok",
14.             data = products
15.         };
17.         string json = JsonSerializer.Serialize(result);
18.         response.ContentType = "application/json";
19.         await response.WriteAsync(json);
20.     }

复制代码

访问：

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

复制代码

返回：

1. {
2.     "code": 0,
3.     "message": "ok",
4.     "data": [
5.         {
6.             "id": "1",
7.             "name": "Demo Product 1",
8.             "price": 100
9.         },
10.         {
11.             "id": "2",
12.             "name": "Demo Product 2",
13.             "price": 200
14.         },
15.         {
16.             "id": "3",
17.             "name": "Demo Product 3",
18.             "price": 300
19.         }
20.     ]
21. }

复制代码

七、路由设计建议

在构建本地 API 时，建议遵循以下规则：
1 统一 API 前缀

推荐使用：

1. /api/*

复制代码

例如：

1. /api/product/list
2. /api/product/add
3. /api/device/list

复制代码

2 统一返回结构

推荐统一格式：

1. {
2.   "code":0,
3.   "message":"ok",
4.   "data":{}
5. }

复制代码

优点：

• 前端统一处理
  
• 错误处理简单
  

3 功能模块分组

例如：

1. /api/system/*
2. /api/device/*
3. /api/product/*

复制代码

这样结构会非常清晰。
八、本地 API 的典型用途

当你的 App 内部运行一个 HTTP Server 时，就可以实现很多有趣的架构：
本地 Web Admin

1. 浏览器
2.    ↓
3. localhost:8090
4.    ↓
5. PicoServer API
6.    ↓
7. MAUI 本地逻辑

复制代码

WebView + 本地 API

1. WebView 页面
2.     ↓
3. fetch("/api/product/list")
4.     ↓
5. PicoServer
6.     ↓
7. C# 业务逻辑

复制代码

局域网控制接口

1. 手机
2.    ↓
3. http://192.168.1.100:8090
4.    ↓
5. 本地设备控制

复制代码

这类架构在 IoT、设备管理、桌面软件后台 中非常常见。
九、本篇总结

本篇我们完成了三个关键步骤：
1️⃣ 理解 PicoServer 路由机制
2️⃣ 构建多个 API 接口
3️⃣ 返回标准 JSON 数据
至此，我们已经把最初的：

1. Hello PicoServer

复制代码

升级成了：

一个真正可用的本地 API 服务。

下一篇预告

下一篇我们将继续升级架构：

《PicoServer 跨平台 Web 实战系列（三）》
构建可扩展的本地 REST API 框架

内容包括：

• Controller 结构设计
  
• Service 分层
  
• 统一 API 返回模型
  
• 全局异常处理
  
• 日志系统
  

最终目标是构建一个 可扩展的本地 API 架构。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！