Maui Blazor 中文社区 QQ群：645660665

MAUI 嵌入式 Web 架构实战（二） PicoServer 路由机制与 API 设计

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 架构
posted @ 2026-03-05 17:17  AlexChow  阅读(1082)  评论(0)    收藏  举报