GFRequestHandlerRegistry¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/common/gf_request_handler_registry.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
7.0.0
单处理器请求调用注册表。 用于表达 “Invoke / TryInvoke” 语义：每个 request_type 至多有一个处理器。 多订阅广播仍应使用 GFTypeEventSystem；本注册表只负责明确的一对一请求调用契约， 不规定请求载荷结构，也不执行业务路由策略。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | handler_registered |
signal handler_registered(request_type: StringName, replaced: bool, metadata: Dictionary) |
| 信号 | handler_unregistered |
signal handler_unregistered(request_type: StringName, metadata: Dictionary) |
| 信号 | request_invoked |
signal request_invoked(request_type: StringName, result: Variant, metadata: Dictionary) |
| 常量 | STATUS_REGISTERED |
const STATUS_REGISTERED: StringName = &"registered" |
| 常量 | STATUS_REPLACED |
const STATUS_REPLACED: StringName = &"replaced" |
| 常量 | STATUS_UNREGISTERED |
const STATUS_UNREGISTERED: StringName = &"unregistered" |
| 常量 | STATUS_DUPLICATE |
const STATUS_DUPLICATE: StringName = &"duplicate" |
| 常量 | STATUS_MISSING |
const STATUS_MISSING: StringName = &"missing" |
| 常量 | STATUS_INVOKED |
const STATUS_INVOKED: StringName = &"invoked" |
| 常量 | STATUS_INVALID |
const STATUS_INVALID: StringName = &"invalid" |
| 常量 | STATUS_MISMATCH |
const STATUS_MISMATCH: StringName = &"mismatch" |
| 常量 | DEFAULT_MAX_RECENT_EVENTS |
const DEFAULT_MAX_RECENT_EVENTS: int = 64 |
| 属性 | max_recent_events |
var max_recent_events: int = DEFAULT_MAX_RECENT_EVENTS: |
| 方法 | register_handler |
func register_handler(request_type: StringName, handler: Callable, options: Dictionary = {}) -> Dictionary: |
| 方法 | unregister_handler |
func unregister_handler( request_type: StringName, handler: Callable = Callable(), metadata: Dictionary = {} ) -> Dictionary: |
| 方法 | invoke |
func invoke(request_type: StringName, payload: Variant = null, context: Dictionary = {}) -> Dictionary: |
| 方法 | try_invoke |
func try_invoke(request_type: StringName, payload: Variant = null, context: Dictionary = {}) -> Dictionary: |
| 方法 | has_handler |
func has_handler(request_type: StringName) -> bool: |
| 方法 | get_handler_ids |
func get_handler_ids() -> Array[StringName]: |
| 方法 | get_handler_snapshot |
func get_handler_snapshot(request_type: StringName) -> Dictionary: |
| 方法 | get_recent_events |
func get_recent_events() -> Array[Dictionary]: |
| 方法 | clear |
func clear() -> void: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
handler_registered¶
- API：
public - 首次版本：
7.0.0
handler 注册或替换时发出。
参数：
| 名称 | 说明 |
|---|---|
request_type |
请求类型。 |
replaced |
是否替换了旧 handler。 |
metadata |
注册元数据。 |
结构：
metadata: Dictionary，调用方定义的 handler 上下文。
handler_unregistered¶
- API：
public - 首次版本：
7.0.0
handler 注销时发出。
参数：
| 名称 | 说明 |
|---|---|
request_type |
请求类型。 |
metadata |
注销元数据。 |
结构：
metadata: Dictionary，调用方定义的 handler 上下文。
request_invoked¶
- API：
public - 首次版本：
7.0.0
请求成功调用时发出。
参数：
| 名称 | 说明 |
|---|---|
request_type |
请求类型。 |
result |
handler 返回值副本。 |
metadata |
调用元数据。 |
结构：
result: Variant，handler 返回值。metadata: Dictionary，包含 request_type、sequence、context 和 handler metadata。
常量¶
STATUS_REGISTERED¶
- API：
public - 首次版本：
7.0.0
handler 已注册。
STATUS_REPLACED¶
- API：
public - 首次版本：
7.0.0
handler 已替换。
STATUS_UNREGISTERED¶
- API：
public - 首次版本：
7.0.0
handler 已注销。
STATUS_DUPLICATE¶
- API：
public - 首次版本：
7.0.0
handler 已存在且不允许替换。
STATUS_MISSING¶
- API：
public - 首次版本：
7.0.0
未找到 handler。
STATUS_INVOKED¶
- API：
public - 首次版本：
7.0.0
请求已调用。
STATUS_INVALID¶
- API：
public - 首次版本：
7.0.0
请求或 handler 无效。
STATUS_MISMATCH¶
- API：
public - 首次版本：
7.0.0
handler 不匹配。
DEFAULT_MAX_RECENT_EVENTS¶
- API：
public - 首次版本：
7.0.0
默认保留的最近调用事件数量。
属性¶
max_recent_events¶
- API：
public - 首次版本：
7.0.0
最近注册/调用事件历史上限。设置为 0 时不保留历史。
方法¶
register_handler¶
- API：
public - 首次版本：
7.0.0
func register_handler(request_type: StringName, handler: Callable, options: Dictionary = {}) -> Dictionary:
注册单处理器请求 handler。 handler 会收到一个 Dictionary 参数，包含 request_type、payload、context、sequence 和 handler_metadata。
参数：
| 名称 | 说明 |
|---|---|
request_type |
稳定请求类型。 |
handler |
处理请求的 Callable，签名为 Callable(request: Dictionary) -> Variant。 |
options |
注册选项，支持 replace、owner_id 和 metadata。 |
返回：注册结果。
结构：
options: Dictionary，包含 replace: bool、owner_id: StringName 和 metadata: Dictionary。return: Dictionary，包含 ok、status、request_type、replaced 和 metadata。
unregister_handler¶
- API：
public - 首次版本：
7.0.0
func unregister_handler( request_type: StringName, handler: Callable = Callable(), metadata: Dictionary = {} ) -> Dictionary:
注销请求 handler。
参数：
| 名称 | 说明 |
|---|---|
request_type |
稳定请求类型。 |
handler |
可选 handler；有效时只有完全匹配才注销。 |
metadata |
注销元数据。 |
返回：注销结果。
结构：
metadata: Dictionary，调用方定义的注销上下文。return: Dictionary with ok, status, request_type, result, error, handler_count, and metadata.
invoke¶
- API：
public - 首次版本：
7.0.0
func invoke(request_type: StringName, payload: Variant = null, context: Dictionary = {}) -> Dictionary:
调用请求 handler。 缺少 handler 会返回 missing 状态；handler 运行时错误由 Godot 按普通 Callable 调用规则报告。
参数：
| 名称 | 说明 |
|---|---|
request_type |
稳定请求类型。 |
payload |
请求载荷。 |
context |
调用上下文。 |
返回：调用结果。
结构：
payload: Variant，调用方定义的请求载荷。context: Dictionary，调用方定义的调用上下文。return: Dictionary，包含 ok、status、request_type、result、context 和 metadata。
try_invoke¶
- API：
public - 首次版本：
7.0.0
func try_invoke(request_type: StringName, payload: Variant = null, context: Dictionary = {}) -> Dictionary:
尝试调用请求 handler。 与 invoke() 相同，但缺少 handler 被视为可预期结果，并在返回值中标记 missing_allowed。
参数：
| 名称 | 说明 |
|---|---|
request_type |
稳定请求类型。 |
payload |
请求载荷。 |
context |
调用上下文。 |
返回：调用结果。
结构：
payload: Variant，调用方定义的请求载荷。context: Dictionary，调用方定义的调用上下文。return: Dictionary，包含 ok、status、request_type、result、context、metadata 和 missing_allowed。
has_handler¶
- API：
public - 首次版本：
7.0.0
判断请求类型是否已注册 handler。
参数：
| 名称 | 说明 |
|---|---|
request_type |
稳定请求类型。 |
返回：已注册且 handler 有效时返回 true。
get_handler_ids¶
- API：
public - 首次版本：
7.0.0
获取已注册请求类型。
返回：请求类型数组。
get_handler_snapshot¶
- API：
public - 首次版本：
7.0.0
获取某个 handler 的快照。
参数：
| 名称 | 说明 |
|---|---|
request_type |
稳定请求类型。 |
返回：handler 快照；未注册时为空字典。
结构：
return: Dictionary，包含 request_type、owner_id、metadata、registered_msec、invocation_count、last_invoked_msec 和 has_valid_handler。
get_recent_events¶
- API：
public - 首次版本：
7.0.0
获取最近注册/调用事件。
返回：最近事件数组。
结构：
return: Array[Dictionary]，每个元素包含 sequence、event_type、request_type、status 和 metadata。
clear¶
- API：
public - 首次版本：
7.0.0
清空全部 handler 和历史事件。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取注册表调试快照。
返回：注册表状态快照。
结构：
return: Dictionary，包含 handler_count、统计计数、handlers 和 recent_events。