ESP WebServer动态路径参数不生效，请求触发onNotFound求助

你使用的WebServer.h是Arduino官方为ESP8266/ESP32提供的基础WebServer库，它本身不支持:userId这类动态路径参数的语法——你写的带:param的路由会被当作字面量路径匹配，只有请求路径完全等于/api/:userId/lights时才会命中，这就是为什么更换{}、<>符号也无效的核心原因。

以下是两种可行的解决方式：

方式一：在现有库中手动解析路径（无需换库） #

通过onNotFound回调统一处理所有请求，手动匹配路径格式并解析参数：

1. 替换原有的路由注册逻辑，只保留固定路径的路由：

#include <WebServer.h>

// ... 其他初始化代码 ...

webServer.on("/", HTTP_GET, [this]() { handle_root(); });
webServer.on("/debug/clip.html", HTTP_GET, [this]() { handle_clip(); });
webServer.onNotFound([this]() { handleCustomNotFound(); });

2. 实现handleCustomNotFound函数，手动匹配并解析动态路径：

void handleCustomNotFound() {
  String path = webServer.uri();
  HTTPMethod method = webServer.method();

  // 匹配 GET /api/{userId}/lights
  if (method == HTTP_GET && path.startsWith("/api/") && path.endsWith("/lights")) {
    int firstSlashPos = path.indexOf('/', 5); // 定位/api/后的第一个/
    if (firstSlashPos != -1 && firstSlashPos == path.length() - 7) { // /lights长度为7
      String userId = path.substring(5, firstSlashPos);
      // 调用处理函数，可将userId传入
      handle_GetState(userId);
      return;
    }
  }
  // 匹配 GET /api/{userId}/lights/{num}
  else if (method == HTTP_GET && path.startsWith("/api/") && path.indexOf("/lights/") != -1) {
    int firstSlashPos = path.indexOf('/', 5);
    int lightsSlashPos = path.indexOf("/lights/");
    if (firstSlashPos != -1 && lightsSlashPos != -1) {
      String userId = path.substring(5, firstSlashPos);
      String num = path.substring(lightsSlashPos + 8); // /lights/长度为8
      handle_GetState(userId, num);
      return;
    }
  }
  // 匹配 PUT /api/{userId}/lights/{num}/state
  else if (method == HTTP_PUT && path.startsWith("/api/") && path.endsWith("/state")) {
    int firstSlashPos = path.indexOf('/', 5);
    int lightsSlashPos = path.indexOf("/lights/");
    int stateSlashPos = path.lastIndexOf('/');
    if (firstSlashPos != -1 && lightsSlashPos != -1 && stateSlashPos != -1) {
      String userId = path.substring(5, firstSlashPos);
      String num = path.substring(lightsSlashPos + 8, stateSlashPos);
      handle_PutState(userId, num);
      return;
    }
  }

  // 未匹配到任何动态路径，返回404
  webServer.send(404, "text/plain", "Not Found");
}

3. 对应修改handle_GetState和handle_PutState，使其支持接收解析后的参数。

方式二：改用支持动态路由的库（推荐） #

使用ESPAsyncWebServer库，它原生支持:param、*通配符等动态路由语法，功能更强大且用法简洁：

1. 安装ESPAsyncWebServer库（可通过Arduino库管理器搜索安装）。
2. 编写路由代码（与你最初的写法几乎一致）：

#include <ESPAsyncWebServer.h>

AsyncWebServer server(80);

void setup() {
  // ... WiFi初始化等代码 ...

  // 注册动态路由，直接获取路径参数
  server.on("/api/:userId/lights", HTTP_GET, [](AsyncWebServerRequest *request) {
    String userId = request->pathParameter("userId");
    // 处理GET请求逻辑
    request->send(200, "text/plain", "Query state for user: " + userId);
  });

  server.on("/api/:userId/lights/:num", HTTP_GET, [](AsyncWebServerRequest *request) {
    String userId = request->pathParameter("userId");
    String num = request->pathParameter("num");
    // 处理指定灯光的查询逻辑
    request->send(200, "text/plain", "Query state for light " + num + " (user: " + userId + ")");
  });

  server.on("/api/:userId/lights/:num/state", HTTP_PUT, [](AsyncWebServerRequest *request) {
    String userId = request->pathParameter("userId");
    String num = request->pathParameter("num");
    // 处理PUT请求的状态更新逻辑
    request->send(200, "text/plain", "Updated state for light " + num + " (user: " + userId + ")");
  });

  server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
    request->send(200, "text/html", "Root page");
  });

  server.on("/debug/clip.html", HTTP_GET, [](AsyncWebServerRequest *request) {
    request->send(200, "text/html", "Clip debug page");
  });

  server.onNotFound([](AsyncWebServerRequest *request) {
    request->send(404, "text/plain", "Not Found");
  });

  server.begin();
}

这个库还支持异步请求处理，适合高并发场景，是ESP平台开发Web服务的首选库之一。

内容的提问来源于stack exchange，提问作者Berlato Matteo