Arduino for ESP8266&ESP32适用库ESPAsyncWebServer：事件处理绑定_espasyncwebserver 表单处理

目的

WebServer一般是用来被动处理客户端的请求的，所以使用时首先需要注册相应的事件和绑定处理该事件的回调函数。这篇文章将对ESPAsyncWebServer中涉及的一些内容进行简单说明。

本文中各例程演示均在ESP32中进行。

事件处理绑定

想要正确接收处理客户端发出的HTTP请求首先需要对各个请求绑定其触发时处理的回调函数，最常用的就是 AsyncWebServer 对象的 on() 方法了：

AsyncWebServer server(80); 

void callback(AsyncWebServerRequest *request){request->send(200);} // 回调函数

void setup()
{
	// 下面的on()方法最常用的方式，参数分别填入url、http_method、onRequest_callback
	// 其中http_method可选HTTP_GET、HTTP_POST、HTTP_DELETE、HTTP_PUT HTTP_PATCH、HTTP_HEAD、HTTP_OPTIONS、HTTP_ANY 
	server.on("/url", HTTP_ANY, callback);
}
1
2
3
4
5
6
7
8
9
10

上面方法中填入的回调函数使用时通常只涉及到HTTP请求请求行和请求头的内容，如果HTTP请求中带有其它附加数据的话需要单独绑定回调函数处理。比如带有HTTP请求带有文件上传：

AsyncWebServer server(80); 

void upload(AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool final){
  if(!index){
    Serial.printf("UploadStart: %s\n", filename.c_str());
  }
  for(size_t i=0; i<len; i++){
    Serial.write(data[i]);
  }
  if(final){
    Serial.printf("UploadEnd: %s, %u B\n", filename.c_str(), index+len);
  }
}

void callback(AsyncWebServerRequest *request){request->send(200);}

void setup()
{
	server.on("/", HTTP_POST, callback, upload); // 增加onUpload时回调函数
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

再或者请求中有其它形式数据在主体中：

AsyncWebServer server(80); 

void upload(AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool final){}

void body(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total){
  if(!index){
    Serial.printf("BodyStart: %u B\n", total);
  }
  for(size_t i=0; i<len; i++){
    Serial.write(data[i]);
  }
  if(index + len == total){
    Serial.printf("BodyEnd: %u B\n", total);
  }
}

void callback(AsyncWebServerRequest *request){request->send(200);}

void setup()
{
	server.on("/", HTTP_POST, callback, upload, body); // 增加onUpload时和onBody时回调函数
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

上面演示了onUpload和onBody的情况，更进一步的现在很多时候body中收到的数据都是 json 形式的，面对这种形式的数据，除了直接在onBody中读取解析外还有别的方式可以处理：

#include <ArduinoJson.h>
#include <AsyncJson.h>

syncWebServer server(80); 

AsyncCallbackJsonWebHandler* handler = new AsyncCallbackJsonWebHandler("/url", [](AsyncWebServerRequest *request, JsonVariant &json) {
  JsonObject& jsonObj = json.as<JsonObject>();
  // ...
});

void setup()
{
	server.addHandler(handler);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

ESPAsyncWebServer中对于json的处理用到了ArduinoJson，需要另外安装，其安装使用说明可以参考下面文章：
《C++ Json库ArduinoJson介绍及使用说明》

上面所有情况都是已经确定了URL的情况，如果URL不确定，想要提供一种通用的方案的话可以使用下面的几个方法：

// 下面几个方法需要填入各自对应形式的回调函数
  server.onNotFound(onRequestCallBack);
  server.onFileUpload(onUploadCallBack);
  server.onRequestBody(onBodyCallBack);
1
2
3
4

URL重写

AsyncWebServer对象提供了rewrite()方法用来重写URL，实现服务器内部的跳转：

server.rewrite("/", "/lalala"); // 用户访问"/"时，服务器内部会执行"/lalala"的回调函数

server.on("/lalala", HTTP_GET, [](AsyncWebServerRequest *request){request->send(200, "text/plain", "lalala~~~");});
1
2
3

除了上面给出的方式对url的重写以外还可以自定义重写规则，相关的说明可以参考项目官方文档中 Param Rewrite With Matching 章节。

过滤器

ESPAsyncWebServer有过滤器（filters）功能，可以对客户端发起的HTTP请求进行选择性执行：

server.on("/", HTTP_GET, callback1).setFilter(ON_AP_FILTER); // ESP32工作在AP模式时起效
server.on("/", HTTP_GET, callback2).setFilter(ON_STA_FILTER); // ESP32工作在STA模式时起效

server.rewrite("/", "/ap").setFilter(ON_AP_FILTER); // ESP32工作在AP模式时起效
server.rewrite("/", "/sta").setFilter(ON_STA_FILTER); // ESP32工作在STA模式时起效

bool userFilter(AsyncWebServerRequest *request){return true;} // 自定义规则
server.on("/", HTTP_GET, callback).setFilter(userFilter); // 当userFilter返回true时起效
1
2
3
4
5
6
7
8

移除事件处理和重写

如果想要移除已绑定过的事件处理和重写可以使用以下方式：

// save callback for particular URL path
auto handler = server.on("/some/path", [](AsyncWebServerRequest *request){
  //do something useful
});
// when you don't need handler anymore remove it
server.removeHandler(&handler);

// same with rewrites
server.removeRewrite(&someRewrite);

server.onNotFound([](AsyncWebServerRequest *request){
  request->send(404);
});

// remove server.onNotFound handler
server.onNotFound(NULL);

// remove all rewrites, handlers and onNotFound/onFileUpload/onRequestBody callbacks
server.reset();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

需要特别注意一点的是某个链接如果已经绑定过回调函数，想要更换回调函数的话必须按照上面方式先删除先前的绑定，然后再绑定新的回调函数。

总结

ESPAsyncWebServer事件处理绑定基础的就是上面这些内容，更多内容可以查看项目官方的文档和例程，或者我的其他ESPAsyncWebServer的文章：
ESPAsyncWebServer项目地址：https://github.com/me-no-dev/ESPAsyncWebServer
《Arduino for ESP8266&ESP32适用库ESPAsyncWebServer：快速入门》
《Arduino for ESP8266&ESP32适用库ESPAsyncWebServer：事件处理绑定》
《Arduino for ESP8266&ESP32适用库ESPAsyncWebServer：请求与响应》
《Arduino for ESP8266&ESP32适用库ESPAsyncWebServer：静态文件和模板引擎》
《Arduino for ESP8266&ESP32适用库ESPAsyncWebServer：WebSocket和EventSource》