Apache HTTP Server 2.4 自 2.2 版本以来的 API 变更

可用语言: en

本文档描述了 Apache HTTPD API 从版本 2.2 到 2.4 的变更，这些变更可能对模块/应用程序开发人员和核心黑客感兴趣。从 2.4 分支的第一个 GA 版本开始，API 兼容性将保留在 2.4 分支的整个生命周期中。（VERSIONING 描述了 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（已更改）

除了现有的正则表达式包装器之外，现在还提供了一个新的高级 API ap_rxplus。这提供了编译类似于 s/regexp/replacement/flags 的 Perl 风格表达式并将它们执行到任意字符串的能力。还添加了对正则表达式反向引用的支持。

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 保留的正文
支持为异步请求缓冲过滤器数据
新的 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 传递给其自身函数的代码的最简单方法是定义和使用一个不同的宏，该宏扩展为这些函数所需的 parameters，因为 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, "Failed to allocate dynamic lock structure"); /* httpd 2.4 的代码 */ ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

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() 时才是有效的。ap_server_conf 应该只在没有更合适的 server_rec 时使用。

请考虑以下更改，以利用新的APLOG_TRACE1..8日志级别。

检查当前APLOG_DEBUG的使用情况，并考虑是否可以使用APLOG_TRACEn级别之一更合适。
如果您的模块当前具有配置调试日志记录量的机制，请考虑消除该机制，并依赖于使用不同的APLOG_TRACEn级别。如果需要根据配置的日志级别绕过昂贵的跟踪处理，请使用APLOGtracen和APLOGrtracen宏来首先检查是否启用了跟踪。

模块有时会将其进程 ID 和/或线程 ID 添加到其日志消息中。这些 ID 现在默认情况下会被记录，因此模块可能不需要显式记录它们。（用户可以从错误日志格式中删除它们，但可以指示他们在需要进行问题诊断时将其添加回来。）

如果您的模块使用以下现有 API...

ap_default_type()

此 API 现已不再可用；必须显式配置 Content-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()

确保在注册钩子钩子完成之后才使用它。否则，作为 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

此 API 现已不再需要，并且会被忽略。

dav_new_error() 和 dav_new_error_tag()

以前，这些 API 假设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

此 API 已重命名为 ap_unixd_config。

unixd_setup_child()

此 API 已重命名为 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 及更高版本。