一、项目概述
本项目用 M5AtomS3R(ESP32-S3)以 STA 模式接入局域网,基于 Arduino WebServer 库在 80 端口启动 HTTP 服务,演示两类已经过实测的功能:一是根路径的静态文本响应,二是 URL 路径参数的提取与校验。后者分别使用 UriBraces(花括号通配)和 UriRegex(正则捕获组)两种方式注册路由,是本次测试的重点。
设备由路由器 DHCP 分配地址 192.168.10.230,串口波特率 9600。工程由 10PathArgServer.ino(设备端逻辑)和 ci.yml(编译约束)两个文件组成,没有额外依赖库。
二、测试环境
设备:M5AtomS3R(ESP32-S3),STA 模式连接 WiFi 热点“航天科宇”,实测 IP 为 192.168.10.230。
电脑:Windows 10 专业工作站版,与设备处于同一网段 192.168.10.0/24。
浏览器:直接访问 http://192.168.10.230/ ,用于人工确认页面内容。
验证工具:PowerShell 5.1 执行自编脚本 verify_routes.ps1,逐条比对 HTTP 状态码与响应正文。
判定方式:状态码与期望一致、且响应正文与期望文本一致,记为 PASS;任一不符记为 FAIL。脚本单次请求超时设为 5 秒。
三、功能一:根路由静态响应
setup() 中首先注册根路径处理函数,直接返回一段固定文本:
server.on(F("/"), []() { server.send(200, "text/plain", "hello from esp32!");});
浏览器打开 http://192.168.10.230/ ,页面显示 hello from esp32!。抓包可见响应状态码为 200,Content-Type 为 text/plain,Content-Length 为 17,Connection 为 close。
这一条同时验证了三件事:设备已成功联网并取得 IP;server.begin() 之后 HTTP 服务已正常监听;根路径的匿名回调被正确注册并触发。

四、功能二:URL 路径参数解析
所谓路径参数,就是把 URL 中某一段的内容提取成字符串交给处理函数,而不是为每一个具体地址单独注册一条路由。本例程注册了两条带参数的路由,分别对应两种匹配机制。4.1 UriBraces 花括号通配
server.on(UriBraces("/users/{}"), []() { String user = server.pathArg(0); server.send(200, "text/plain", "User: '" + user + "'");});/users/{} 中的 {} 表示“这里是一段可变内容”,匹配到的值通过 pathArg(0) 取出,索引从 0 开始。它的特点是:
{} 只匹配一个路径段,不跨越斜杠,因此 /users/tom 能匹配,/users/tom/devices/7 不能匹配。
取出的内容是原始路径片段,不做数值转换,123 与 tom 一视同仁。
该机制适合“取一个标识符”的场景,例如用户名、设备号。
4.2 UriRegex 正则捕获组
server.on(UriRegex("^\/users\/([0-9]+)\/devices\/([0-9]+)$"), []() { String user = server.pathArg(0); String device = server.pathArg(1); server.send(200, "text/plain", "User: '" + user + "' and Device: '" + device + "'");});
这条路由用正则描述完整路径:开头 ^、结尾 $,中间是固定的 users 与 devices 两段,两处 ([0-9]+) 分别捕获使用者编号与设备编号。pathArg(0) 对应第一个捕获组,pathArg(1) 对应第二个。
与花括号通配相比,正则方式的约束更强:路径必须是纯数字,层级必须完全一致,多一层、少一层、拼写不同或出现非数字字符都不会命中。
4.3 两条路由为何不会互相抢占
/users/{} 的花括号不跨斜杠,而 /users/42/devices/7 包含三段,因此前者根本无法匹配整条路径;后者由正则路由接手。实测该请求返回 User: '42' and Device: '7',而不是把 42/devices/7 当成一个用户名,说明两条路由边界清晰、互不干扰
五、测试用例与结果

测试脚本共 10 条用例,最终结果为“通过 10 / 共 10,失败 0”。逐条结果如下。
根路径:GET /,期望 200,实际 200,正文为 hello from esp32!,PASS。
花括号通配取字母参数:GET /users/tom,期望 200,实际 200,正文为 User: 'tom',PASS。
花括号通配取数字参数:GET /users/123,期望 200,实际 200,正文为 User: '123',PASS。
花括号不跨段:GET /users/tom/devices/7,期望 404,实际 404,未被 /users/{} 捕获,PASS。
正则路由正常取两个参数:GET /users/42/devices/7,期望 200,实际 200,正文为 User: '42' and Device: '7',PASS。
正则路由带前导零:GET /users/001/devices/999,期望 200,实际 200,正文为 User: '001' and Device: '999',说明参数按字符串原样提取,不做数值规范化,PASS。
正则路由使用者非数字:GET /users/tom/devices/7,期望 404,实际 404,PASS。
正则路由设备号非数字:GET /users/42/devices/abc,期望 404,实际 404,PASS。
正则路由路径拼写错误:GET /users/42/device/7,期望 404,实际 404,PASS。
正则路由多余层级:GET /users/42/devices/7/extra,期望 404,实际 404,正则首尾锚定生效,PASS。
六、复现步骤
用 Arduino IDE 或 arduino-cli 烧录 10PathArgServer.ino,打开 9600 波特率的串口监视器,等待打印出 Connected to 与 IP address。
记下串口打印的 IP,本例为 192.168.10.230。
浏览器访问 http://192.168.10.230/,确认页面显示 hello from esp32!。
在脚本所在目录执行验证脚本:
cd E:ESP32ESP32M5ATOMS3Rpersommake10PathArgServer
powershell -NoProfile -ExecutionPolicy Bypass -File .verify_routes.ps1 -BaseUrl http://192.168.10.230
观察脚本输出:每条用例打印 PASS 或 FAIL,并给出期望状态码与实际状态码;最后一行汇总通过数量,全部通过时退出码为 0。七、结论
根路由静态响应正常,设备联网、HTTP 服务启动、固定文本返回三个环节均已打通。
UriBraces 的路径参数提取正确,{} 只匹配单个路径段,且不会吞掉后续斜杠之外的内容。
UriRegex 的严格匹配有效:^...$ 锚定使多余层级无法命中,[0-9]+ 使非数字参数一律返回 404。
pathArg(0) 与 pathArg(1) 的取值顺序和正则捕获组顺序完全一致。
两条参数路由互不抢占,同一请求只会命中一条路由。
10 条用例全部通过,其中 6 条验证功能正常,4 条验证否定场景(404)。
整体来看,WebServer 的路径参数机制在本工程中已得到完整验证,可直接作为后续“按路径取参数”类接口的参考模板。
我要赚赏金
