在物聯(lián)網(wǎng)項目中，HTTP 是最常用的通信協(xié)議之一。本文以 LuatOS Air780EPM 為例，講解其在 LuatOS 系統(tǒng)下實現(xiàn) HTTP 通信的全過程，并附上可運行示例。

一、HTTP 概述

1.1 什么是 HTTP？

HTTP 全稱為 HyperText Transfer Protocol，中文即“超文本傳輸協(xié)議”。它是一種應用層協(xié)議，采用標準的請求-響應模型，通常運行在 TCP 之上，規(guī)定了客戶端可以向服務器發(fā)送何種消息以及預期得到何種響應，常用于分布式、協(xié)作式和超媒體信息系統(tǒng)。

1.2 什么是 HTTPS？

HTTPS 全稱為 HyperText Transfer Protocol Secure，中文即“超文本傳輸安全協(xié)議”。它并非一種新的協(xié)議，而是在 HTTP 之下插入了一層 SSL/TLS 安全通道，同樣運行在 TCP 之上。通過加密與身份認證，HTTPS 確保客戶端與服務器之間交換的消息不被竊聽或篡改，從而為分布式、協(xié)作式和超媒體信息系統(tǒng)提供了保密性、完整性與身份可驗證的通信基礎。

1.3 HTTP 的工作原理（請求-響應模型）

HTTP 采用請求-響應模型：客戶端（如瀏覽器）向服務器發(fā)送請求，服務器以狀態(tài)碼和對應資源的表示（如 HTML 字節(jié)流）作出響應。

1.3.1 HTTP 請求報文

一個完整的 HTTP 請求包含請求行、請求頭、空行、請求體四部分：

1. Request line（請求行）

Method：請求方式，如GET、POST。

Request-URL：需要訪問的目標路徑，比如/index.html。

HTTP-Version：HTTP 協(xié)議版本號，比如HTTP/1.1。

2. Header Lines（請求頭）

由鍵值對組成，每行一對。請求頭包含關于客戶端環(huán)境和請求正文的重要信息。常見的請求頭有：

Host：指定請求的服務器的域名和端口號（HTTP/1.1 必需字段）。

User-Agent：包含發(fā)起請求的應用程序信息（瀏覽器類型、操作系統(tǒng)等）。

Accept：告知服務器客戶端能夠處理哪些類型的媒體資源（如text/html, application/json）。

Content-Type：（用于有 Body 的請求）請求體的媒體類型（如application/json,application/x-www-form-urlencoded）。

Content-Length：（用于有 Body 的請求）請求體的長度（字節(jié)）。

3. Blank line（空行）

就是一個空行，用來分隔頭部和正文，告訴服務器：“頭部結束，下面是正文了”。

4. Entity Body（請求體）

可選部分，主要用于POST、PUT等需要向服務器發(fā)送數(shù)據(jù)的請求。

內(nèi)容格式由Content-Type頭指定。

常見內(nèi)容：表單數(shù)據(jù)（user=admin&pass=123）、JSON 字符串（{"user":"admin"}）、文件數(shù)據(jù)等。

請求報文示例如下：

1.3.2 HTTP 響應報文

一個完整的 HTTP 響應報文與請求報文幾乎一一對應，也是四部分：

1. Status Line（狀態(tài)行）

HTTP-Version：與請求消息中的版本相匹配，如HTTP/1.1。

Status Code：三位數(shù)字，標識請求的處理結果，如200、404。

Reason-Phrase：狀態(tài)碼的簡短文字描述，如OK、Not Found。

2. Header Lines（響應頭）

一樣每行是一個“鍵值對”，響應頭包含關于響應的附加信息。常見的響應頭有：

Server：包含處理請求的服務器軟件信息。

Date：響應生成的日期和時間。

Content-Type：響應體的媒體類型（如text/html; charset=UTF-8）。

Content-Length：響應體的長度（字節(jié)）。

Content-Encoding：響應體使用的編碼（如gzip），用于壓縮。

Cache-Control：指示響應內(nèi)容應如何被緩存。

3. Blank Line（空行）

響應頭和響應體之間的分隔符，表示響應頭的結束。

4. Response Body（響應體）

可選部分，包含服務器返回的實際資源內(nèi)容。

內(nèi)容格式由Content-Type頭指定。

常見內(nèi)容：HTML 文檔、JSON 數(shù)據(jù)、圖片、CSS、JavaScript 文件等。

響應報文示例如下：

1.4 HTTP 請求方法

HTTP 客戶端發(fā)出請求，告知服務端需要執(zhí)行不同類型的請求命令，這些命令被稱為 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：提交數(shù)據(jù)以處理請求。

HEAD：請求資源的響應頭信息。

HTTP/1.1

HTTP/1.1引入了更多的請求方法：

GET：請求指定的資源。

POST：提交數(shù)據(jù)以處理請求。

HEAD：請求資源的響應頭信息。

PUT：上傳文件或者更新資源。

DELETE：刪除指定的資源。

OPTIONS：請求獲取服務器支持的請求方法。

TRACE：回顯服務器收到的請求，主要用于診斷。

CONNECT：建立一個隧道用于代理服務器的通信，通常用于 HTTPS。

HTTP/2

HTTP/2基本上沿用了HTTP/1.1的方法，但對協(xié)議進行了優(yōu)化，提高了傳輸效率和速度。HTTP/2也引入了新的特性，如多路復用、頭部壓縮和服務器推送等。

HTTP/3

HTTP/3基于 QUIC 協(xié)議實現(xiàn)，繼續(xù)使用HTTP/2的方法。HTTP/3主要改進了傳輸層，使用 UDP 代替 TCP 以提高傳輸速度和可靠性。

1.5 HTTP 狀態(tài)碼

HTTP 狀態(tài)碼由三個十進制數(shù)字組成，第一個十進制數(shù)字定義了狀態(tài)碼的類型，響應分為五類：

二、http 與 httpplus 庫的介紹

注意： LuatOS 僅支持HTTP/1.0和HTTP/1.1。

HTTP 在如下的場景，開發(fā)成本是最低的：

1. 終端和云端交換文件，不用開發(fā)復雜的分包組包協(xié)議；

2. 終端從云端下載各種參數(shù)，或者終端向云端提交各種參數(shù)， 不用設計報文協(xié)議，用 http 的參數(shù)即可，非常方便。

LuatOS 提供了 http 核心庫 和 httpplus 擴展庫 實現(xiàn)了 http 客戶端。

http 核心庫 和 httpplus 擴展庫 的區(qū)別如下：

三、演示功能概述

在使用示例代碼測試時，如果遇到測試域名請求不成功的情況，可以向工作人員進行反饋。

1、http_app：使用 http 核心庫，演示以下幾種應用場景的使用方式

普通的 http get 請求功能演示；

http get 下載壓縮數(shù)據(jù)的功能演示；

http get 下載數(shù)據(jù)保存到文件中的功能演示；

http post 提交表單數(shù)據(jù)功能演示；

http post 提交 json 數(shù)據(jù)功能演示；

http post 提交純文本數(shù)據(jù)功能演示；

http post 提交 xml 數(shù)據(jù)功能演示；

http post 提交原始二進制數(shù)據(jù)功能演示；

http post 文件上傳功能演示；

2、httpplus_app：使用 httpplus 擴展庫，演示以下幾種應用場景的使用方式

普通的 http get 請求功能演示；

http get 下載壓縮數(shù)據(jù)的功能演示；

http post 提交表單數(shù)據(jù)功能演示；

http post 提交 json 數(shù)據(jù)功能演示；

http post 提交純文本數(shù)據(jù)功能演示；

http post 提交 xml 數(shù)據(jù)功能演示；

http post 提交原始二進制數(shù)據(jù)功能演示；

http post 文件上傳功能演示；

3、netdrv_device：配置連接外網(wǎng)使用的網(wǎng)卡，目前支持以下三種選擇（三選一）

(1) netdrv_4g：4G 網(wǎng)卡

(2) netdrv_eth_spi：通過 SPI 外掛 CH390H 芯片的以太網(wǎng)卡

(3) netdrv_multiple：支持以上兩種網(wǎng)卡，可以配置兩種網(wǎng)卡的優(yōu)先級

四、演示硬件環(huán)境

1、Air780EPM V1.3 版本開發(fā)板一塊 + 可上網(wǎng)的 sim 卡一張 +4g 天線一根 + 網(wǎng)線一根：

sim 卡插入開發(fā)板的 sim 卡槽

天線裝到開發(fā)板上

網(wǎng)線一端插入開發(fā)板網(wǎng)口，另外一端連接可以上外網(wǎng)的路由器網(wǎng)口

2、TYPE-C USB 數(shù)據(jù)線一根 + USB 轉(zhuǎn)串口數(shù)據(jù)線一根，Air780EPM V1.3 版本開發(fā)板和數(shù)據(jù)線的硬件接線方式為：

Air780EPM V1.3 版本開發(fā)板通過 TYPE-C USB 口供電；（外部供電/USB 供電 撥動開關 撥到 USB 供電一端）

TYPE-C USB 數(shù)據(jù)線直接插到核心板的 TYPE-C USB 座子，另外一端連接電腦 USB 口；

五、演示軟件環(huán)境

5.1 軟件環(huán)境

1. 燒錄工具：Luatools 下載調(diào)試工具

2. 內(nèi)核固件：Air780EPM V2012 版本固件（理論上，2025 年 8 月 10 日之后發(fā)布的固件都可以）

3. 腳本文件：Air780EPM HTTP 腳本文件

4. LuatOS 運行所需要的 lib 文件：使用 Luatools 燒錄時，勾選 添加默認 lib 選項，使用默認 lib 腳本文件。

準備好軟件環(huán)境之后，接下來查看Air780EPM 產(chǎn)品手冊中“Air780EPM 開發(fā)板使用手冊 -> 使用說明”，將本篇文章中演示使用的項目文件燒錄到 Air780EPM 開發(fā)板中。

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：主程序入口文件，負責初始化系統(tǒng)、啟動網(wǎng)絡驅(qū)動和 HTTP 演示任務。

netdrv_device.lua：網(wǎng)絡設備配置文件。

http_app.lua：http 核心庫的演示文件，包含 13 個示例場景。

httpplus_app.lua：httpplus 擴展庫的演示文件，包含 9 個示例場景。

logo.jpg：供上傳、下載測試使用的素材文件。

netdrv/：網(wǎng)絡驅(qū)動相關文件。

netdrv_4g.lua：4G 網(wǎng)絡驅(qū)動。

netdrv_eth_spi.lua：SPI 以太網(wǎng)驅(qū)動。

netdrv_multiple.lua：多網(wǎng)絡驅(qū)動管理。

七、核心模塊詳解

7.1 主程序 (main.lua)

主程序文件main.lua是整個項目的入口點。它負責初始化系統(tǒng)環(huán)境。

7.1.1 初始化流程

1. 項目和版本定義：

定義PROJECT和VERSION變量。

2. 日志記錄：

使用log.info``("main", PROJECT, VERSION)在日志中打印項目名和版本號。

3. 看門狗初始化（如果支持）：

配置并啟動硬件看門狗，防止程序死循環(huán)卡死。

4. 加載功能模塊：

加載網(wǎng)絡驅(qū)動設備模塊（netdrv_device）。

加載 HTTP 核心庫示例模塊（http_app.lua）。

加載 HTTPPLUS 擴展庫示例模塊（httpplus_app.lua）。

5. 啟動任務調(diào)度器：

調(diào)用sys.run()啟動 LuatOS 的任務調(diào)度器，開始執(zhí)行各個任務。

7.2 網(wǎng)絡驅(qū)動 (netdrv/)

網(wǎng)絡驅(qū)動模塊負責初始化和管理不同的網(wǎng)絡連接方式，如 4G 和以太網(wǎng)。

7.2.1 4G 網(wǎng)絡驅(qū)動 (netdrv_4g.lua)

監(jiān)聽IP_READY和IP_LOSE消息，監(jiān)控網(wǎng)絡連接狀態(tài)。

設置默認網(wǎng)卡為socket.LWIP_GP。

7.2.2 以太網(wǎng)網(wǎng)絡驅(qū)動(netdrv_eth_spi.lua)

通過 SPI 接口外掛 CH390H 芯片實現(xiàn)以太網(wǎng)。

通過控制 GPIO20 引腳使能芯片供電。

配置 SPI0 接口參數(shù)，用于與 CH390H 芯片通信。

通過netdrv.setup函數(shù)配置以太網(wǎng)卡，并開啟 DHCP 動態(tài)獲取 IP 地址。

設置默認網(wǎng)卡為socket.LWIP_ETH。

7.2.3 多網(wǎng)絡驅(qū)動管理 (netdrv_multiple.lua)

管理多個網(wǎng)絡驅(qū)動實例，根據(jù)配置選擇合適的網(wǎng)絡連接方式。

通過exnetif.set_priority_order函數(shù)配置多網(wǎng)卡的控制參數(shù)以及優(yōu)先級。

通過exnetif.notify_status函數(shù)設置網(wǎng)卡狀態(tài)變化通知回調(diào)函數(shù)。

7.3 HTTP 庫演示模塊（http_app.lua）

http_app.lua是 LuatOS 中基于 http 核心庫 所開發(fā)的 HTTP 應用功能模塊。該模塊通過調(diào)用http.request接口演示了 13 種 HTTP 請求場景，這 13 種演示功能如下。

7.3.1 下載回調(diào)函數(shù)

該函數(shù)在下載數(shù)據(jù)過程中被調(diào)用，用于實時監(jiān)控下載進度。參數(shù)包括：

content_len：數(shù)據(jù)總長度。

body_len：已下載的數(shù)據(jù)長度。

userdata：用戶自定義參數(shù)。

7.3.2 HTTP GET 請求功能

1. 普通 GET 請求

http_app_get()函數(shù)演示了三種不同的 GET 請求場景：

1. 基本的 HTTPS GET 請求。

2. 設置超時時間和回調(diào)函數(shù)的 HTTPS GET 請求。

3. 設置短超時和回調(diào)函數(shù)的 HTTP GET 請求。

2. 下載壓縮數(shù)據(jù)

http_app_get_gzip()函數(shù)演示了如何處理壓縮格式的 HTTP 響應：

發(fā)送 GET 請求獲取壓縮的天氣數(shù)據(jù)。

對響應內(nèi)容進行解壓縮處理。

解析解壓后的 JSON 數(shù)據(jù)并提取信息。

3. 下載數(shù)據(jù)到文件

http_app_get_file()函數(shù)演示了如何將 HTTP 響應直接保存到文件：

創(chuàng)建下載目錄。

發(fā)送 GET 請求并設置 dst 參數(shù)指定保存路徑。

驗證下載文件的完整性。

按需刪除臨時文件。

7.3.3 HTTP POST 請求功能

1. 提交表單數(shù)據(jù)

http_app_post_form()函數(shù)演示了如何發(fā)送表單格式的 POST 請求：

構造表單數(shù)據(jù)并進行 URL 編碼。

設置正確的Content-Type（application/x-www-form-urlencoded）。

發(fā)送請求并處理響應。

2. 提交 JSON 數(shù)據(jù)

http_app_post_json()函數(shù)演示了如何發(fā)送 JSON 格式的 POST 請求：

使用json.encode()將 Lua 表轉(zhuǎn)換為 JSON 字符串。

設置正確的Content-Type（application/json）。

發(fā)送請求并處理響應。

3. 提交純文本數(shù)據(jù)

http_app_post_text()函數(shù)演示了如何發(fā)送純文本數(shù)據(jù)格式的 POST 請求：

設置正確的Content-Type（text/plain）。

發(fā)送請求并處理響應。

4. 提交 XML 數(shù)據(jù)

http_app_post_xml()函數(shù)演示了如何發(fā)送 XML 格式的 POST 請求：

使用 Lua 的長字符串語法[=[...]=]定義 XML 內(nèi)容。

設置正確的Content-Type（text/xml）。

發(fā)送請求并處理響應。

5. 提交原始二進制數(shù)據(jù)

http_app_post_binary()函數(shù)演示了如何發(fā)送原始二進制格式的 POST 情況：

使用io.readFile讀取 JPG 圖片文件。

設置正確的Content-Type（application/octet-stream）。

發(fā)送請求并處理響應。

上傳成功后，可以通過指定網(wǎng)址查看上傳的圖片。

7.3.4 文件上傳功能

http_app_post_file()函數(shù)演示了如何通過 HTTP 上傳文件：

調(diào)用輔助函數(shù)post_multipart_form_data()構造multipart/form-data格式請求。

支持單文件、多文件、單文本或多文本上傳。

支持文本字段和文件字段混合上傳。

7.3.5 任務管理機制

1. 主任務函數(shù)

該函數(shù)是模塊的核心控制邏輯，實現(xiàn)了：

網(wǎng)絡連接等待機制：通過循環(huán)檢測socket.adapter(socket.dft())和sys.waitUntil("IP_READY", 1000)等待網(wǎng)絡就緒。

功能調(diào)用序列：按順序調(diào)用所有 HTTP 功能演示函數(shù)。

循環(huán)執(zhí)行策略：每次功能演示完成后等待 60 秒，然后再次開始循環(huán)。

2. 任務啟動

通過sys.taskInit函數(shù)創(chuàng)建并啟動一個新的任務來運行httpplus_app_task_func函數(shù)，使整個模塊的功能在后臺持續(xù)運行。

7.4 HTTPPLUS 庫演示模塊（httpplus_app.lua）

httpplus_app.lua是 LuatOS 中基于httpplus擴展庫所開發(fā)的 HTTP 應用功能模塊。該模塊通過調(diào)用httpplus.request接口演示了 9 種 HTTP 請求場景，這 9 種演示功能如下。

7.4.1 HTTP GET 請求功能

1. 普通 GET 請求

httpplus_app_get()函數(shù)演示了兩種不同的 GET 請求場景：

1. 基本的 HTTPS GET 請求。

2. 設置超時時間的 HTTP GET 請求。

2. 下載壓縮數(shù)據(jù)

httpplus_app_get_gzip()函數(shù)演示了如何處理壓縮格式的 HTTP 響應：

發(fā)送 GET 請求獲取壓縮的天氣數(shù)據(jù)。

對響應內(nèi)容進行解壓縮處理。

解析解壓后的 JSON 數(shù)據(jù)并提取信息。

7.4.2 HTTP POST 請求功能

1. 提交表單數(shù)據(jù)

httpplus_app_post_form()函數(shù)演示了如何發(fā)送表單格式的 POST 請求：

構造表單數(shù)據(jù)并進行 URL 編碼。

存在forms參數(shù)并且不存在 files 參數(shù)，系統(tǒng)自動強制以application/x-www-form-urlencoded形式上傳數(shù)據(jù)。

發(fā)送請求并處理響應。

2. 提交 JSON 數(shù)據(jù)

httpplus_app_post_json()函數(shù)演示了如何發(fā)送 JSON 格式的 POST 請求：

使用json.encode()將 Lua 表轉(zhuǎn)換為 JSON 字符串。

設置正確的Content-Type（application/json）。

發(fā)送請求并處理響應。

3. 提交純文本數(shù)據(jù)

httpplus_app_post_text()函數(shù)演示了如何發(fā)送純文本數(shù)據(jù)格式的 POST 請求：

設置正確的Content-Type（text/plain）。

發(fā)送請求并處理響應。

4. 提交 XML 數(shù)據(jù)

httpplus_app_post_xml()函數(shù)演示了如何發(fā)送 XML 格式的 POST 請求：

使用 Lua 的長字符串語法[=[...]=]定義 XML 內(nèi)容。

設置正確的Content-Type（text/xml）。

發(fā)送請求并處理響應。

5. 提交原始二進制數(shù)據(jù)

http_app_post_binary()函數(shù)演示了如何發(fā)送原始二進制格式的 POST 情況：

使用io.readFile讀取 JPG 圖片文件。

設置正確的Content-Type（application/octet-stream）。

發(fā)送請求并處理響應。

上傳成功后，可以通過指定網(wǎng)址查看上傳的圖片。

7.4.3 文件上傳功能

http_app_post_file()函數(shù)演示了如何通過 HTTP 上傳文件：

使用files參數(shù)上傳文件。

系統(tǒng)會自動將請求設置為POST方法，并以multipart/form-data格式發(fā)送數(shù)據(jù)。

支持單文件、多文件、單文本或多文本上傳。

支持文本字段和文件字段混合上傳。

7.4.4 任務管理機制

1. 主任務函數(shù)

該函數(shù)是模塊的核心控制邏輯，實現(xiàn)了：

網(wǎng)絡連接等待機制：通過循環(huán)檢測socket.adapter(socket.dft())和sys.waitUntil("IP_READY", 1000)等待網(wǎng)絡就緒。

功能調(diào)用序列：按順序調(diào)用所有 HTTP 功能演示函數(shù)。

循環(huán)執(zhí)行策略：每次功能演示完成后等待 60 秒，然后再次開始循環(huán)。

2. 任務啟動

通過sys.taskInit函數(shù)創(chuàng)建并啟動一個新的任務來運行httpplus_app_task_func函數(shù)，使整個模塊的功能在后臺持續(xù)運行。

八、演示功能

8.1 不同網(wǎng)卡切換

Air780EXX 模組支持單 4g 網(wǎng)卡，單 spi 以太網(wǎng)卡，多網(wǎng)卡。

切換網(wǎng)卡為 4G 網(wǎng)卡：

在netdrv_device.lua模塊里只打開netdrv_4g模塊。netdrv_4g.lua模塊中的代碼不需要修改。

Luatools 工具日志打印：

如下圖所示，如出現(xiàn)類似I/user.netdrv_4g.ip_ready_func IP_READY 10.73.217.4 255.255.255.255 0.0.0.0 nil的日志，則表示 4g 網(wǎng)卡連接成功。

切換網(wǎng)卡為以太網(wǎng)卡：

注意：Air780EPM 的以太網(wǎng)卡是通過 SPI 外掛 CH390H 芯片實現(xiàn)的。

在netdrv_device.lua模塊里只打開netdrv_eth_spi模塊。如果是使用開發(fā)板，netdrv_eth_spi模塊中的代碼不需要修改。

Luatools 工具日志打印：

如出現(xiàn)類似I/user.netdrv_eth_spi.ip_ready_func IP_READY 192.168.71.66 255.255.255.0 192.168.71.1 nil的日志，則表示以太網(wǎng)卡聯(lián)網(wǎng)成功。

多網(wǎng)卡自動切換：

如果需要多網(wǎng)卡，打開require "netdrv_multiple"，其余注釋掉； 可根據(jù)自己的需求調(diào)整網(wǎng)卡的優(yōu)先級，以下示例設置為以太網(wǎng)卡是最高優(yōu)先級。

首先在netdrv_device.lua文件中只打開netdrv_multiple模塊。

默認以太網(wǎng)卡進行連接

拔掉網(wǎng)線后，網(wǎng)絡切換為 4g 網(wǎng)卡

8.2 HTTP 請求結果

前面介紹了 HTTP 核心庫演示模塊中演示了 13 種場景的 HTTP 請求，HTTPPLUS 擴展庫演示模塊中演示了 9 種 HTTP 請求。因此我們燒錄程序成功后，在日志中搜索success 200，程序默認每隔 1 分鐘測試一輪，如果每輪出現(xiàn) 22 次success 200，如以下日志所示，就表示成功，如果不夠 22 次，則說明部分域名沒有請求成功，此時可以通過詳細日志所表示的含義，結合代碼自行分析。

九、總結

至此，我們演示了使用不同網(wǎng)卡在 22 種場景下進行 HTTP 請求的全過程，相信聰明的你已經(jīng)完全領悟 HTTP 請求的邏輯了，快來實際操作一下吧！

審核編輯 黃宇