Apache HTTP 伺服器 2.4 版自 2.2 版以來的 API 變更

可用語言： en

本文檔描述了 Apache HTTPD API 從 2.2 版到 2.4 版的變更，這些變更可能與模組/應用程式開發人員和核心駭客有關。從 2.4 分支的第一個正式版本開始，API 相容性將在 2.4 分支的整個生命週期內得到保留。（2.4 版本的版本說明提供了更多關於 API 相容性的資訊。）

API 變更分為兩類：全新的 API，以及擴展或更改的現有 API。後者又分為所有變更都向後相容（因此現有模組可以忽略它們）和可能需要維護者注意的變更。與從 HTTPD 2.0 到 2.2 的過渡一樣，現有模組和應用程式需要重新編譯，並且可能需要一些關注，但大多數不需要進行任何實質性的更新（儘管有些模組可以利用 API 變更來提供顯著的改進）。

就本文檔而言，API 根據公開的標頭檔進行劃分。這些標頭檔本身就是參考文件，可以使用 make docs 生成可瀏覽的 HTML 參考。

已變更的 API
從 2.2 版升級模組的具體資訊

另請參閱

註釋

已變更的 API

ap_expr（新增！）

引入了一個新的 API 來解析和評估布林和代數表達式，包括提供標準語法和自訂變體。

ap_mpm（已變更）

ap_mpm_run 已被新的 mpm 鉤子取代。此外，ap_graceful_stop_signalled 已消失，並且 ap_mpm_register_timed_callback 是新增的。

ap_regex（已變更）

除了現有的 regexp 封裝器之外，現在還提供了一個新的更高階的 API ap_rxplus。這提供了編譯 Perl 風格表達式（例如 s/regexp/replacement/flags）並針對任意字串執行它們的功能。還添加了對 regexp 反向引用的支援。

ap_parse_htaccess（已變更）

ap_parse_htaccess 的函數簽章已變更。現在必須傳遞允許覆蓋的個別指令的 apr_table_t（覆蓋仍然有效）。

http_config（已變更）

引入了每個模組、每個目錄的日誌級別，包括宏包裝器。
新的 AP_DECLARE_MODULE 宏用於宣告所有模組。
在多檔案模組中，每個模組的日誌級別都需要新的 APLOG_USE_MODULE 宏。
新的 API 可在模組卸載/加載時保留數據
新的 check_config 鉤子
新的 ap_process_fnmatch_configs() 函數用於處理萬用字元
更改 ap_configfile_t、ap_cfg_getline()、ap_cfg_getc() 以返回錯誤代碼，並添加 ap_pcfg_strerror() 以檢索錯誤描述。
任何在 ACCESS_CONF 上下文中允許的配置指令現在都必須通過新的 AllowOverrideList 指令正確處理從 .htaccess 檔案中調用的情況。ap_check_cmd_context() 接受一個新的標誌 NOT_IN_HTACCESS 來檢測這種情況。

http_core（已變更）

已移除 ap_default_type、ap_requires、所有 2.2 版的 authnz API
引入了用於 logio 和 authnz 的可選函數
新的函數 ap_get_server_name_for_url 支援 IPv6 字面量。
新的函數 ap_register_errorlog_handler 用於註冊錯誤日誌格式字串處理程序。
error_log 鉤子的參數已更改。宣告已移至 http_core.h。
新的函數 ap_state_query 用於確定伺服器是否處於初始配置預檢階段。這比在進程池中創建池用戶數據項目的舊方法更容易使用且更正確。
新的函數 ap_get_conn_socket 用於獲取連接的套接字描述符。這應該用於代替直接訪問核心連接配置。

httpd（已變更）

引入每個目錄、每個模組的日誌級別
新的日誌級別 APLOG_TRACEn
引入請求和連接的錯誤日誌 ID
支援 mod_request 的 kept_body
支援緩衝非同步請求的過濾器數據
新的 CONN_STATE 值
函數變更：ap_escape_html 已更新；ap_unescape_all、ap_escape_path_segment_buffer
在 EXEC_ON_READ 配置讀取階段之後加載其他模組的模組需要在其 pre_config 鉤子中調用 ap_reserve_module_slots() 或 ap_reserve_module_slots_directive()。
每個請求的用戶代理 IP 地址現在可以獨立於連接的客戶端 IP 地址進行追蹤，以支援使用負載平衡器的部署。

http_log（已變更）

引入每個目錄、每個模組的日誌級別
新的日誌級別 APLOG_TRACEn
ap_log_*error 成為宏包裝器（如果使用 APLOG_MARK 宏，則向後相容，但不再可以在參數列表中使用 #ifdef）
管道日誌記錄已改進
module_index 已添加到 error_log 鉤子
新函數：ap_log_command_line

http_request（已變更）

新的 auth_internal API 和 auth_provider API
新的 EOR 儲存貯體類型
新的函數 ap_process_async_request
新的標誌 AP_AUTH_INTERNAL_PER_CONF 和 AP_AUTH_INTERNAL_PER_URI
新的 access_checker_ex 鉤子用於應用其他訪問控制和/或繞過身份驗證。
新的函數 ap_hook_check_access_ex、ap_hook_check_access、ap_hook_check_authn、ap_hook_check_authz 接受 AP_AUTH_INTERNAL_PER_* 標誌
已棄用直接使用 ap_hook_access_checker、access_checker_ex、ap_hook_check_user_id、ap_hook_auth_checker

建議盡可能使用 AP_AUTH_INTERNAL_PER_CONF 註冊所有訪問控制鉤子（包括身份驗證和授權鉤子）。如果所有模組的訪問控制鉤子都使用此標誌註冊，那麼每當伺服器處理與初始請求匹配的同一組訪問控制配置指令的內部子請求時（這是常見情況），它可以避免再次調用訪問控制鉤子。

如果您的模組需要舊行為，並且必須對每個與初始請求具有不同 URI 的子請求執行訪問控制檢查，即使該 URI 與同一組訪問控制配置指令匹配，也請使用 AP_AUTH_INTERNAL_PER_URI。

mod_cache（已變更）

在快取提供程序介面中引入了一個 commit_entity() 函數，允許原子寫入快取。添加了一個 cache_status() 鉤子來報告快取決策。所有私有結構和函數都被移除。

mod_core（新增！）

這引入了用於發送任意標頭的低階 API，並公開了用於處理 HTTP OPTIONS 和 TRACE 的函數。

mod_cache_disk（已變更）

更改了磁碟快取的磁碟格式，以支援在不鎖定的情況下進行原子快取更新。主體檔案的裝置/inode 對嵌入在標頭檔案中，允許確認標頭和主體屬於彼此。

mod_disk_cache（已重新命名）

mod_disk_cache 模組已重新命名為 mod_cache_disk，以便與伺服器內其他模組的命名保持一致。

mod_request（新增！）

mod_request 的 API，用於在需要時將輸入數據提供給多個應用程式/處理程序模組，並解析 HTML 表單數據。

mpm_common（已變更）

已移除：accept、lockfile、lock_mech、set_scoreboard（鎖定使用新的 ap_mutex API）
新的 API 用於降低權限（將此平臺相關函數委託給模組）
新的鉤子：mpm_query、timed_callback 和 get_name
已變更的介面：monitor 鉤子、ap_reclaim_child_processes、ap_relieve_child_processes

scoreboard（已變更）

ap_get_scoreboard_worker 已被修改為非向後相容，因為引入了替代版本。添加了 proxy_balancer 支援。子進程狀態內容已改進。

util_mutex（新增！）

httpd 中 APR proc 和全局互斥鎖的包裝器，為底層機制和鎖定檔案的位置提供通用配置。

從 2.2 版升級模組的具體資訊

日誌記錄

為了利用每個模組的日誌級別配置，任何調用 ap_log_* 函數的原始程式檔都應聲明它屬於哪個模組。如果模組的 module_struct 被稱為 foo_module，則可以使用以下代碼來保持與 HTTPD 2.0 和 2.2 的向後相容性

#include <http_log.h> #ifdef APLOG_USE_MODULE APLOG_USE_MODULE(foo); #endif

注意：這對於 C++ 語言模組是絕對必要的。對於 C 語言模組，可以跳過此步驟，但這會破壞沒有它的檔案的模組特定日誌級別支援。

ap_log_* 函數的參數數量和 APLOG_MARK 的定義已更改。通常，更改是完全透明的。但是，如果模組使用 APLOG_MARK 作為其自身函數的參數，或者如果模組在不傳遞 APLOG_MARK 的情況下調用 ap_log_*，則需要進行更改。使用 ap_log_* 周圍的包裝器的模組通常會同時使用這兩種構造。

更改將 APLOG_MARK 傳遞給其自身函數的代碼的最簡單方法是定義並使用一個不同的宏，該宏擴展為這些函數所需的參數，因為 APLOG_MARK 只能在直接調用 ap_log_* 時使用。這樣，代碼將保持與 HTTPD 2.0 和 2.2 的相容性。

在不傳遞 APLOG_MARK 的情況下調用 ap_log_* 的代碼在 2.4 和早期版本之間必然會有所不同，因為 2.4 需要一個新的第三個參數 APLOG_MODULE_INDEX。

/* httpd 2.0/2.2 的代碼 */ ap_log_perror(file, line, APLOG_ERR, 0, p, "無法分配動態鎖定結構"); /* httpd 2.4 的代碼 */ ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "無法分配動態鎖定結構");

ap_log_*error 現在已實現為宏。這意味著不再可以在 ap_log_*error 的參數列表中使用 #ifdef，因為根據 C99，這會導致未定義的行為。

在啟動後調用 ap_log_error() 時，必須傳遞一個 server_rec 指針。這始終是適當的，但在 2.4 中，NULL server_rec 的限制比以前的版本更多。從 2.3.12 開始，全局變量 ap_server_conf 始終可以用作 server_rec 參數，因為它只有在將 NULL 傳遞給 ap_log_error() 有效時才會為 NULL。ap_server_conf 應該只在沒有更合適的 server_rec 可用時使用。

考慮以下更改以利用新的 APLOG_TRACE1..8 日誌級別

檢查 APLOG_DEBUG 的當前用法，並考慮 APLOG_TRACEn 級別之一是否更合適。
如果您的模組目前具有配置除錯日誌記錄量的機制，請考慮消除該機制並依賴使用不同的 APLOG_TRACEn 級別。如果需要根據配置的日誌級別繞過昂貴的追蹤處理，請使用 APLOGtracen 和 APLOGrtracen 巨集首先檢查是否啟用了追蹤。

模組有時會將處理程序 ID 和/或執行緒 ID 添加到其日誌訊息中。這些 ID 現在預設記錄，因此模組可能不需要明確記錄它們。（使用者可以將它們從錯誤日誌格式中刪除，但如果需要診斷問題，可以指示他們將其添加回去。）

如果您的模組使用這些現有的 API...

ap_default_type()

這不再可用；必須明確配置內容類型或由應用程式添加。

ap_get_server_name()

如果返回的伺服器名稱用於 URL 中，請改用 ap_get_server_name_for_url()。這個新函數處理伺服器名稱是 IPv6 文字地址的特殊情況。

ap_get_server_version()

出於記錄目的，在適當的詳細信息時，請使用 ap_get_server_description()。生成輸出時，如果信息量應由 ServerTokens 配置，請使用 ap_get_server_banner()。

ap_graceful_stop_signalled()

替換為呼叫 ap_mpm_query(AP_MPMQ_MPM_STATE) 並檢查狀態 AP_MPMQ_STOPPING。

ap_max_daemons_limit、ap_my_generation 和 ap_threads_per_child

分別使用 ap_mpm_query() 查詢代碼 AP_MPMQ_MAX_DAEMON_USED、AP_MPMQ_GENERATION 和 AP_MPMQ_MAX_THREADS。

ap_mpm_query()

確保在 register-hooks 鉤子完成後才使用它。否則，作為 DSO 構建的 MPM 將沒有機會啟用對此函數的支持。

ap_requires()

核心伺服器現在提供了更好的基礎結構來處理 Require 配置。使用 ap_register_auth_provider() 為每個受支持的實體註冊一個身份驗證提供程序函數。該函數將在 Require 處理期間根據需要被呼叫。（有關詳細示例，請查閱捆綁的模組。）

ap_server_conf->process->pool 使用者資料

可選

如果您的模組使用它來確定正在運行啟動鉤子的哪個階段，請使用 ap_state_query(AP_SQ_MAIN_STATE)。
如果您的模組使用它在卸載和重新加載模組時維護數據，請使用 ap_retained_data_create() 和 ap_retained_data_get()。

apr_global_mutex_create()、apr_proc_mutex_create()

可選：請參閱 ap_mutex_register()、ap_global_mutex_create() 和 ap_proc_mutex_create()；這些允許使用 Mutex 指令配置您的互斥鎖；您還可以刪除模組中用於此類互斥鎖的任何配置機制

CORE_PRIVATE

這現在是不必要的並且被忽略。

dav_new_error() 和 dav_new_error_tag()

以前，這些假設 errno 包含描述故障的信息。現在，必須提供 apr_status_t 參數。如果沒有此類錯誤信息，則傳遞 0/APR_SUCCESS，否則傳遞有效的 apr_status_t 值。

mpm_default.h、DEFAULT_LOCKFILE、DEFAULT_THREAD_LIMIT、DEFAULT_PIDLOG 等。

標頭檔和其中設置的大多數默認配置值不再對模組可見。（大多數仍然可以在構建時覆蓋。）DEFAULT_PIDLOG 和 DEFAULT_REL_RUNTIMEDIR 現在可以通过 ap_config.h 通用。

unixd_config

這已重命名為 ap_unixd_config。

unixd_setup_child()

這已重命名為 ap_unixd_setup_child()，但大多數調用者應調用添加的 ap_run_drop_privileges() 鉤子。

conn_rec->remote_ip 和 conn_rec->remote_addr

這些欄位已重命名，以便區分連接的客戶端 IP 地址和請求的使用者代理 IP 地址（可能被負載平衡器或代理覆蓋）。對這些欄位中的任何一個的引用都必須使用以下選項之一進行更新，以適合模組

當您需要使用者代理的 IP 地址時，該代理可能直接連接到伺服器，或者可能通過透明負載平衡器或代理與伺服器分離，請使用 request_rec->useragent_ip 和 request_rec->useragent_addr。
當您需要直接連接到伺服器的客戶端的 IP 地址時，該客戶端可能是使用者代理，也可能是負載平衡器或代理本身，請使用 conn_rec->client_ip 和 conn_rec->client_addr。

如果您的模組與此功能交互...

suEXEC: 可選：如果您的模組在 ap_unixd_config.suexec_enabled 為 0 時記錄錯誤，則還記錄新欄位 suexec_disabled_reason 的值，其中包含它不可用的原因的說明。
記分板中的擴展狀態數據: 在以前的版本中，ExtendedStatus 必須設置為 On，這反過來又需要加載 mod_status。在 2.4 中，只需在預配置鉤子中將 ap_extended_status 設置為 1，即可使用擴展狀態數據。

您的模組是否...

解析查詢參數: 考慮 ap_args_to_table() 是否會有幫助。
解析表單數據...: 使用 ap_parse_form_data()。
檢查請求標頭欄位 Content-Length 和 Transfer-Encoding 以查看是否指定了主體: 使用 ap_request_has_body()。
實現清除指標變數的清理: 使用 ap_pool_cleanup_set_null()。
創建運行時檔案，例如共享內存檔案、pid 檔案等。: 使用 ap_runtime_dir_relative()，以便遵循此類檔案位置的全局配置，無論是通過 DEFAULT_REL_RUNTIMEDIR 編譯設置還是 DefaultRuntimeDir 指令。 Apache httpd 2.4.2 及更高版本。