PicoServer 跨平台 Web 实战系列（二）
路由机制与 API 设计
在上一篇文章 《PicoServer 跨平台 Web 实战系列（一）》 中，我们已经完成了：
- 在 .NET MAUI 中嵌入本地 HTTP 服务
- 使用 PicoServer 启动服务器
- 浏览器访问
http://127.0.0.1:8090 - 返回示例内容：
Hello PicoServer
这说明我们的 App 已经具备了 Web Server 能力。
但在真实项目中，仅仅返回一个字符串显然是不够的。
我们更希望这个服务器能够提供：
- API 接口
- JSON 数据
- 设备控制
- 本地后台管理系统
因此，本篇将重点介绍：
PicoServer 的路由机制与 API 设计方法
最终目标是把简单示例升级为 一个真正的本地 API 服务。
一、什么是路由（Route）
在 Web 服务器中，路由（Route） 用于定义：
URL 与处理函数之间的映射关系
例如：
| URL | 处理逻辑 |
|---|---|
/ |
首页 |
/api/time |
返回服务器时间 |
/api/device/list |
返回设备列表 |
当浏览器访问：
http://127.0.0.1:8090/api/time
服务器就会找到对应的 路由处理函数，并返回结果。
二、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。
例如：
- 获取服务器时间
- 获取设备列表
- 查询系统状态
可以这样定义：
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"}
}
这样，一个 标准 API 接口就完成了。
六、读取 GET 参数
很多 API 需要读取参数，例如：
/api/product/detail?id=1001
在 PicoServer 中可以这样获取：
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 时，建议遵循以下规则：
1 统一 API 前缀
推荐使用：
/api/*
例如：
/api/product/list
/api/product/add
/api/device/list
2 统一返回结构
推荐统一格式：
{"code":0,"message":"ok","data":{}
}
优点：
- 前端统一处理
- 错误处理简单
3 功能模块分组
例如：
/api/system/*
/api/device/*
/api/product/*
这样结构会非常清晰。
八、本地 API 的典型用途
当你的 App 内部运行一个 HTTP Server 时，就可以实现很多有趣的架构：
本地 Web Admin
浏览器↓
localhost:8090↓
PicoServer API↓
MAUI 本地逻辑
WebView + 本地 API
WebView 页面↓
fetch("/api/product/list")↓
PicoServer↓
C# 业务逻辑
局域网控制接口
手机↓
http://192.168.1.100:8090↓
本地设备控制
这类架构在 IoT、设备管理、桌面软件后台 中非常常见。
九、本篇总结
本篇我们完成了三个关键步骤：
1️⃣ 理解 PicoServer 路由机制
2️⃣ 构建多个 API 接口
3️⃣ 返回标准 JSON 数据
至此，我们已经把最初的：
Hello PicoServer
升级成了：
一个真正可用的本地 API 服务。
下一篇预告
下一篇我们将继续升级架构：
《PicoServer 跨平台 Web 实战系列（三）》
构建可扩展的本地 REST API 框架
内容包括：
- Controller 结构设计
- Service 分层
- 统一 API 返回模型
- 全局异常处理
- 日志系统
最终目标是构建一个 可扩展的本地 API 架构。
