博客
LuatOS Air780EPM 開發實戰：HTTP 請求的實現與應用
||
一、HTTP 概述1.1 什么是 HTTP？
HTTP 全稱為 HyperText Transfer Protocol，中文即“超文本傳輸協議”。它是一種應用層協議，采用標準的請求-響應模型，通常運行在 TCP 之上，規定了客戶端可以向服務器發送何種消息以及預期得到何種響應，常用于分布式、協作式和超媒體信息系統。
1.2 什么是 HTTPS？HTTPS 全稱為 HyperText Transfer Protocol Secure，中文即“超文本傳輸安全協議”。它并非一種新的協議，而是在 HTTP 之下插入了一層 SSL/TLS 安全通道，同樣運行在 TCP 之上。通過加密與身份認證，HTTPS 確保客戶端與服務器之間交換的消息不被竊聽或篡改，從而為分布式、協作式和超媒體信息系統提供了保密性、完整性與身份可驗證的通信基礎。
1.3 HTTP 的工作原理（請求-響應模型）HTTP 采用請求-響應模型：客戶端（如瀏覽器）向服務器發送請求，服務器以狀態碼和對應資源的表示（如 HTML 字節流）作出響應。
1.3.1 HTTP 請求報文
一個完整的 HTTP 請求包含請求行、請求頭、空行、請求體四部分：
1. Request line（請求行）
Method：請求方式，如 GET、POST。
Request-URL：需要訪問的目標路徑，比如 /index.html。
HTTP-Version：HTTP 協議版本號，比如 HTTP/1.1。
2. Header Lines（請求頭）
由鍵值對組成，每行一對。請求頭包含關于客戶端環境和請求正文的重要信息。常見的請求頭有：
Host：指定請求的服務器的域名和端口號（HTTP/1.1 必需字段）。
User-Agent：包含發起請求的應用程序信息（瀏覽器類型、操作系統等）。
Accept：告知服務器客戶端能夠處理哪些類型的媒體資源（如 text/html, application/json）。
Content-Type：（用于有 Body 的請求）請求體的媒體類型（如 application/json, application/x-www-form-urlencoded）。
Content-Length：（用于有 Body 的請求）請求體的長度（字節）。
3. Blank line（空行）
就是一個空行，用來分隔頭部和正文，告訴服務器：“頭部結束，下面是正文了”。
4. Entity Body（請求體）
可選部分，主要用于 POST、PUT 等需要向服務器發送數據的請求。
內容格式由 Content-Type 頭指定。
常見內容：表單數據（user=admin&pass=123）、JSON 字符串（{"user":"admin"}）、文件數據等。
請求報文示例如下：
1.3.2 HTTP 響應報文
一個完整的 HTTP 響應報文與請求報文幾乎一一對應，也是四部分：
1. Status Line（狀態行）
HTTP-Version：與請求消息中的版本相匹配，如 HTTP/1.1。
Status Code：三位數字，標識請求的處理結果，如 200、404。
Reason-Phrase：狀態碼的簡短文字描述，如 OK、Not Found。
2. Header Lines（響應頭）
一樣每行是一個“鍵值對”，響應頭包含關于響應的附加信息。常見的響應頭有：
Server：包含處理請求的服務器軟件信息。
Date：響應生成的日期和時間。
Content-Type：響應體的媒體類型（如 text/html; charset=UTF-8）。
Content-Length：響應體的長度（字節）。
Content-Encoding：響應體使用的編碼（如 gzip），用于壓縮。
Cache-Control：指示響應內容應如何被緩存。
3. Blank Line（空行）
響應頭和響應體之間的分隔符，表示響應頭的結束。
4. Response Body（響應體）
可選部分，包含服務器返回的實際資源內容。
內容格式由 Content-Type 頭指定。
常見內容：HTML 文檔、JSON 數據、圖片、CSS、JavaScript 文件等。
響應報文示例如下：
1.4 HTTP 請求方法
HTTP 客戶端發出請求，告知服務端需要執行不同類型的請求命令，這些命令被稱為 HTTP 方法。
1.4.1 常見 HTTP 請求方法下表展示的是常見的 HTTP 請求方法：
1.4.2 各版本定義的 HTTP 請求方法
HTTP 標準目前有 HTTP/1.0、HTTP/1.1、HTTP/2 、 HTTP/3 四個版本，介紹如下：
HTTP/1.0
HTTP/1.0 定義了以下三種請求方法：
GET：請求指定的資源。
POST：提交數據以處理請求。
HEAD：請求資源的響應頭信息。
HTTP/1.1
HTTP/1.1 引入了更多的請求方法：
GET：請求指定的資源。
POST：提交數據以處理請求。
HEAD：請求資源的響應頭信息。
PUT：上傳文件或者更新資源。
DELETE：刪除指定的資源。
OPTIONS：請求獲取服務器支持的請求方法。
TRACE：回顯服務器收到的請求，主要用于診斷。
CONNECT：建立一個隧道用于代理服務器的通信，通常用于 HTTPS。
HTTP/2
HTTP/2 基本上沿用了 HTTP/1.1 的方法，但對協議進行了優化，提高了傳輸效率和速度。HTTP/2 也引入了新的特性，如多路復用、頭部壓縮和服務器推送等。
HTTP/3
HTTP/3 基于 QUIC 協議實現，繼續使用 HTTP/2 的方法。HTTP/3 主要改進了傳輸層，使用 UDP 代替 TCP 以提高傳輸速度和可靠性。
1.5 HTTP 狀態碼HTTP 狀態碼由三個十進制數字組成，第一個十進制數字定義了狀態碼的類型，響應分為五類：
二、http 與 httpplus 庫的介紹
注意： LuatOS 僅支持 HTTP/1.0 和 HTTP/1.1。
HTTP 在如下的場景，開發成本是最低的：
1. 終端和云端交換文件，不用開發復雜的分包組包協議；
2. 終端從云端下載各種參數，或者終端向云端提交各種參數， 不用設計報文協議，用 http 的參數即可，非常方便。
LuatOS 提供了 http 核心庫 和 httpplus 擴展庫 實現了 http 客戶端。
http 核心庫 和 httpplus 擴展庫 的區別如下：
三、演示功能概述
在使用示例代碼測試時，如果遇到測試域名請求不成功的情況，可以向工作人員進行反饋。
1、http_app：使用 http 核心庫，演示以下幾種應用場景的使用方式
普通的 http get 請求功能演示；
http get 下載壓縮數據的功能演示；
http get 下載數據保存到文件中的功能演示；
http post 提交表單數據功能演示；
http post 提交 json 數據功能演示；
http post 提交純文本數據功能演示；
http post 提交 xml 數據功能演示；
http post 提交原始二進制數據功能演示；
http post 文件上傳功能演示；
2、httpplus_app：使用 httpplus 擴展庫，演示以下幾種應用場景的使用方式
普通的 http get 請求功能演示；
http get 下載壓縮數據的功能演示；
http post 提交表單數據功能演示；
http post 提交 json 數據功能演示；
http post 提交純文本數據功能演示；
http post 提交 xml 數據功能演示；
http post 提交原始二進制數據功能演示；
http post 文件上傳功能演示；
3、netdrv_device：配置連接外網使用的網卡，目前支持以下三種選擇（三選一）
(1) netdrv_4g：4G 網卡
(2) netdrv_eth_spi：通過 SPI 外掛 CH390H 芯片的以太網卡
(3) netdrv_multiple：支持以上兩種網卡，可以配置兩種網卡的優先級
四、演示硬件環境
1、Air780EPM V1.3 版本開發板一塊 + 可上網的 sim 卡一張 +4g 天線一根 + 網線一根：
sim 卡插入開發板的 sim 卡槽
天線裝到開發板上
網線一端插入開發板網口，另外一端連接可以上外網的路由器網口
2、TYPE-C USB 數據線一根 + USB 轉串口數據線一根，Air780EPM V1.3 版本開發板和數據線的硬件接線方式為：
Air780EPM V1.3 版本開發板通過 TYPE-C USB 口供電；（外部供電/USB 供電 撥動開關 撥到 USB 供電一端）
TYPE-C USB 數據線直接插到核心板的 TYPE-C USB 座子，另外一端連接電腦 USB 口；
1. 燒錄工具：Luatools 下載調試工具
2. 內核固件：Air780EPM V2012 版本固件（理論上，2025 年 8 月 10 日之后發布的固件都可以）
3. 腳本文件：Air780EPM HTTP 腳本文件
4. LuatOS 運行所需要的 lib 文件：使用 Luatools 燒錄時，勾選 添加默認 lib 選項，使用默認 lib 腳本文件。
準備好軟件環境之后，接下來查看 Air780EPM 產品手冊中“Air780EPM 開發板使用手冊 -> 使用說明”，將本篇文章中演示使用的項目文件燒錄到 Air780EPM 開發板中。
5.2 API 介紹sys 庫：https://docs.openluat.com/osapi/core/sys/
http 庫：https://docs.openluat.com/osapi/core/http/
httpplu 庫：https://docs.openluat.com/osapi/ext/httpplus/
6.1 文件說明
main.lua：主程序入口文件，負責初始化系統、啟動網絡驅動和 HTTP 演示任務。
netdrv_device.lua：網絡設備配置文件。
http_app.lua：http 核心庫的演示文件，包含 13 個示例場景。
httpplus_app.lua：httpplus 擴展庫的演示文件，包含 9 個示例場景。
logo.jpg：供上傳、下載測試使用的素材文件。
netdrv/：網絡驅動相關文件。
netdrv_4g.lua：4G 網絡驅動。
netdrv_eth_spi.lua：SPI 以太網驅動。
netdrv_multiple.lua：多網絡驅動管理。
主程序文件 main.lua 是整個項目的入口點。它負責初始化系統環境。
7.1.1 初始化流程1. 項目和版本定義：
定義 PROJECT 和 VERSION 變量。
2. 日志記錄：
使用 log.info``("main", PROJECT, VERSION) 在日志中打印項目名和版本號。
3. 看門狗初始化（如果支持）：
配置并啟動硬件看門狗，防止程序死循環卡死。
4. 加載功能模塊：
加載網絡驅動設備模塊（netdrv_device）。
加載 HTTP 核心庫示例模塊（http_app.lua）。
加載 HTTPPLUS 擴展庫示例模塊（httpplus_app.lua）。
5. 啟動任務調度器：
調用 sys.run() 啟動 LuatOS 的任務調度器，開始執行各個任務。
7.2 網絡驅動 (netdrv/)
網絡驅動模塊負責初始化和管理不同的網絡連接方式，如 4G 和以太網。
7.2.1 4G 網絡驅動 (netdrv_4g.lua)監聽 IP_READY 和 IP_LOSE 消息，監控網絡連接狀態。
設置默認網卡為 socket.LWIP_GP。
7.2.2 以太網網絡驅動(netdrv_eth_spi.lua)
通過 SPI 接口外掛 CH390H 芯片實現以太網。
通過控制 GPIO20 引腳使能芯片供電。
配置 SPI0 接口參數，用于與 CH390H 芯片通信。
通過 netdrv.setup 函數配置以太網卡，并開啟 DHCP 動態獲取 IP 地址。
設置默認網卡為 socket.LWIP_ETH。
7.2.3 多網絡驅動管理 (netdrv_multiple.lua)
管理多個網絡驅動實例，根據配置選擇合適的網絡連接方式。
通過 exnetif.set_priority_order 函數配置多網卡的控制參數以及優先級。
通過 exnetif.notify_status 函數設置網卡狀態變化通知回調函數。
7.3 HTTP 庫演示模塊（http_app.lua）
http_app.lua 是 LuatOS 中基于 http 核心庫 所開發的 HTTP 應用功能模塊。該模塊通過調用 http.request 接口演示了 13 種 HTTP 請求場景，這 13 種演示功能如下。
7.3.1 下載回調函數
該函數在下載數據過程中被調用，用于實時監控下載進度。參數包括：
content_len：數據總長度。
body_len：已下載的數據長度。
userdata：用戶自定義參數。
7.3.2 HTTP GET 請求功能
1. 普通 GET 請求
http_app_get() 函數演示了三種不同的 GET 請求場景：
1. 基本的 HTTPS GET 請求。
2. 設置超時時間和回調函數的 HTTPS GET 請求。
3. 設置短超時和回調函數的 HTTP GET 請求。
2. 下載壓縮數據
http_app_get_gzip() 函數演示了如何處理壓縮格式的 HTTP 響應：
發送 GET 請求獲取壓縮的天氣數據。
對響應內容進行解壓縮處理。
解析解壓后的 JSON 數據并提取信息。
3. 下載數據到文件
http_app_get_file() 函數演示了如何將 HTTP 響應直接保存到文件：
創建下載目錄。
發送 GET 請求并設置 dst 參數指定保存路徑。
驗證下載文件的完整性。
按需刪除臨時文件。
7.3.3 HTTP POST 請求功能
1. 提交表單數據
http_app_post_form() 函數演示了如何發送表單格式的 POST 請求：
構造表單數據并進行 URL 編碼。
設置正確的 Content-Type（application/x-www-form-urlencoded）。
發送請求并處理響應。
2. 提交 JSON 數據
http_app_post_json() 函數演示了如何發送 JSON 格式的 POST 請求：
使用 json.encode() 將 Lua 表轉換為 JSON 字符串。
設置正確的 Content-Type（application/json）。
發送請求并處理響應。
3. 提交純文本數據
http_app_post_text() 函數演示了如何發送純文本數據格式的 POST 請求：
設置正確的 Content-Type（text/plain）。
發送請求并處理響應。
4. 提交 XML 數據
http_app_post_xml() 函數演示了如何發送 XML 格式的 POST 請求：
使用 Lua 的長字符串語法 [=[...]=] 定義 XML 內容。
設置正確的 Content-Type（text/xml）。
發送請求并處理響應。
5. 提交原始二進制數據
http_app_post_binary() 函數演示了如何發送原始二進制格式的 POST 情況：
使用 io.readFile 讀取 JPG 圖片文件。
設置正確的 Content-Type（application/octet-stream）。
發送請求并處理響應。
上傳成功后，可以通過指定網址查看上傳的圖片。
7.3.4 文件上傳功能
http_app_post_file() 函數演示了如何通過 HTTP 上傳文件：
調用輔助函數 post_multipart_form_data() 構造 multipart/form-data 格式請求。
支持單文件、多文件、單文本或多文本上傳。
支持文本字段和文件字段混合上傳。
7.3.5 任務管理機制
1. 主任務函數
該函數是模塊的核心控制邏輯，實現了：
網絡連接等待機制：通過循環檢測 socket.adapter(socket.dft()) 和 sys.waitUntil("IP_READY", 1000) 等待網絡就緒。
功能調用序列：按順序調用所有 HTTP 功能演示函數。
循環執行策略：每次功能演示完成后等待 60 秒，然后再次開始循環。
2. 任務啟動
通過 sys.taskInit 函數創建并啟動一個新的任務來運行 httpplus_app_task_func 函數，使整個模塊的功能在后臺持續運行。
7.4 HTTPPLUS 庫演示模塊（httpplus_app.lua）httpplus_app.lua 是 LuatOS 中基于 httpplus 擴展庫所開發的 HTTP 應用功能模塊。該模塊通過調用 httpplus.request 接口演示了 9 種 HTTP 請求場景，這 9 種演示功能如下。
7.4.1 HTTP GET 請求功能1. 普通 GET 請求
httpplus_app_get() 函數演示了兩種不同的 GET 請求場景：
1. 基本的 HTTPS GET 請求。
2. 設置超時時間的 HTTP GET 請求。
2. 下載壓縮數據
httpplus_app_get_gzip() 函數演示了如何處理壓縮格式的 HTTP 響應：
發送 GET 請求獲取壓縮的天氣數據。
對響應內容進行解壓縮處理。
解析解壓后的 JSON 數據并提取信息。
7.4.2 HTTP POST 請求功能
1. 提交表單數據
httpplus_app_post_form() 函數演示了如何發送表單格式的 POST 請求：
構造表單數據并進行 URL 編碼。
存在 forms 參數并且不存在 files 參數，系統自動強制以 application/x-www-form-urlencoded 形式上傳數據。
發送請求并處理響應。
2. 提交 JSON 數據
httpplus_app_post_json() 函數演示了如何發送 JSON 格式的 POST 請求：
使用 json.encode() 將 Lua 表轉換為 JSON 字符串。
設置正確的 Content-Type（application/json）。
發送請求并處理響應。
3. 提交純文本數據
httpplus_app_post_text() 函數演示了如何發送純文本數據格式的 POST 請求：
設置正確的 Content-Type（text/plain）。
發送請求并處理響應。
4. 提交 XML 數據
httpplus_app_post_xml() 函數演示了如何發送 XML 格式的 POST 請求：
使用 Lua 的長字符串語法 [=[...]=] 定義 XML 內容。
設置正確的 Content-Type（text/xml）。
發送請求并處理響應。
5. 提交原始二進制數據
http_app_post_binary() 函數演示了如何發送原始二進制格式的 POST 情況：
使用 io.readFile 讀取 JPG 圖片文件。
設置正確的 Content-Type（application/octet-stream）。
發送請求并處理響應。
上傳成功后，可以通過指定網址查看上傳的圖片。
7.4.3 文件上傳功能
http_app_post_file() 函數演示了如何通過 HTTP 上傳文件：
使用 files 參數上傳文件。
系統會自動將請求設置為 POST 方法，并以 multipart/form-data 格式發送數據。
支持單文件、多文件、單文本或多文本上傳。
支持文本字段和文件字段混合上傳。
7.4.4 任務管理機制
1. 主任務函數
該函數是模塊的核心控制邏輯，實現了：
網絡連接等待機制：通過循環檢測 socket.adapter(socket.dft()) 和 sys.waitUntil("IP_READY", 1000) 等待網絡就緒。
功能調用序列：按順序調用所有 HTTP 功能演示函數。
循環執行策略：每次功能演示完成后等待 60 秒，然后再次開始循環。
2. 任務啟動
通過 sys.taskInit 函數創建并啟動一個新的任務來運行 httpplus_app_task_func 函數，使整個模塊的功能在后臺持續運行。
8.1 不同網卡切換
Air780EXX 模組支持單 4g 網卡，單 spi 以太網卡，多網卡。
切換網卡為 4G 網卡：
在 netdrv_device.lua 模塊里只打開 netdrv_4g 模塊。netdrv_4g.lua 模塊中的代碼不需要修改。
Luatools 工具日志打印：
如下圖所示，如出現類似 I/user.netdrv_4g.ip_ready_func IP_READY 10.73.217.4 255.255.255.255 0.0.0.0 nil 的日志，則表示 4g 網卡連接成功。
切換網卡為以太網卡：
注意：Air780EPM 的以太網卡是通過 SPI 外掛 CH390H 芯片實現的。
在 netdrv_device.lua 模塊里只打開 netdrv_eth_spi 模塊。如果是使用開發板，netdrv_eth_spi 模塊中的代碼不需要修改。
Luatools 工具日志打印：
如出現類似 I/user.netdrv_eth_spi.ip_ready_func IP_READY 192.168.71.66 255.255.255.0 192.168.71.1 nil 的日志，則表示以太網卡聯網成功。
多網卡自動切換：
如果需要多網卡，打開 require "netdrv_multiple"，其余注釋掉； 可根據自己的需求調整網卡的優先級，以下示例設置為以太網卡是最高優先級。
首先在 netdrv_device.lua 文件中只打開 netdrv_multiple 模塊。
默認以太網卡進行連接
拔掉網線后，網絡切換為 4g 網卡
8.2 HTTP 請求結果
前面介紹了 HTTP 核心庫演示模塊中演示了 13 種場景的 HTTP 請求，HTTPPLUS 擴展庫演示模塊中演示了 9 種 HTTP 請求。因此我們燒錄程序成功后，在日志中搜索 success 200 ，程序默認每隔 1 分鐘測試一輪，如果每輪出現 22 次 success 200，如以下日志所示，就表示成功，如果不夠 22 次，則說明部分域名沒有請求成功，此時可以通過詳細日志所表示的含義，結合代碼自行分析。
九、總結
至此，我們演示了使用不同網卡在 22 種場景下進行 HTTP 請求的全過程，相信聰明的你已經完全領悟 HTTP 請求的邏輯了，快來實際操作一下吧！
