GFRequestEnvelope¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/io/gf_request_envelope.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：事件契约 (
event_contract) - 首次版本：
3.17.0
通用可重放请求描述。 只保存请求方法、地址、载荷、Header、重试与元数据，不绑定具体服务端、 账号、鉴权或业务协议。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | request_id |
var request_id: StringName = &"" |
| 属性 | method |
var method: int = HTTPClient.METHOD_GET |
| 属性 | url |
var url: String = "" |
| 属性 | body |
var body: Dictionary = {} |
| 属性 | headers |
var headers: PackedStringArray = PackedStringArray() |
| 属性 | idempotency_key |
var idempotency_key: String = "" |
| 属性 | created_at_unix |
var created_at_unix: int = 0 |
| 属性 | attempt_count |
var attempt_count: int = 0 |
| 属性 | max_attempts |
var max_attempts: int = 3 |
| 属性 | retry_after_msec |
var retry_after_msec: int = 0 |
| 属性 | last_error |
var last_error: String = "" |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | configure |
func configure( p_method: int, p_url: String, p_body: Dictionary = {}, p_headers: PackedStringArray = PackedStringArray(), p_metadata: Dictionary = {} ) -> GFRequestEnvelope: |
| 方法 | is_valid |
func is_valid() -> bool: |
| 方法 | can_attempt |
func can_attempt(now_msec: int = -1) -> bool: |
| 方法 | is_exhausted |
func is_exhausted() -> bool: |
| 方法 | mark_attempt |
func mark_attempt() -> void: |
| 方法 | mark_failure |
func mark_failure(error: String, retry_delay_msec: int = 0) -> void: |
| 方法 | mark_success |
func mark_success() -> void: |
| 方法 | duplicate_request |
func duplicate_request() -> GFRequestEnvelope: |
| 方法 | to_dict |
func to_dict(json_compatible: bool = false) -> Dictionary: |
| 方法 | apply_dict |
func apply_dict(data: Dictionary, json_compatible: bool = false) -> void: |
| 方法 | get_method_name |
func get_method_name() -> String: |
| 方法 | from_dict |
static func from_dict(data: Dictionary, json_compatible: bool = false) -> GFRequestEnvelope: |
属性¶
request_id¶
- API：
public
请求稳定标识；为空时由 Outbox 入队时生成。
method¶
- API：
public
HTTPClient.Method 数值。即使传输层不是 HTTP，也可把它当作通用动作类型使用。
url¶
- API：
public
请求目标地址或项目自定义端点。
body¶
- API：
public
请求载荷。框架不解释字段含义。
结构：
body: Dictionary，项目传输层持有的请求载荷。
headers¶
- API：
public
请求 Header，使用 Godot HTTPRequest 兼容的 Name: Value 字符串格式。
idempotency_key¶
- API：
public
幂等键；为空时不参与任何框架逻辑。
created_at_unix¶
- API：
public
创建时间，Unix 秒。
attempt_count¶
- API：
public
已尝试次数。
max_attempts¶
- API：
public
最大尝试次数；小于等于 0 表示不限制。
retry_after_msec¶
- API：
public
下一次允许重试的毫秒时间戳，基于 Time.get_ticks_msec()。
last_error¶
- API：
public
最近一次失败原因。
metadata¶
- API：
public
项目自定义元数据。框架不解释该字段。
结构：
metadata: Dictionary，随请求持久化的项目侧元数据。
方法¶
configure¶
- API：
public
func configure( p_method: int, p_url: String, p_body: Dictionary = {}, p_headers: PackedStringArray = PackedStringArray(), p_metadata: Dictionary = {} ) -> GFRequestEnvelope:
配置请求并返回自身。
参数：
| 名称 | 说明 |
|---|---|
p_method |
HTTPClient.Method 数值。 |
p_url |
请求目标地址或项目自定义端点。 |
p_body |
请求载荷。 |
p_headers |
请求 Header。 |
p_metadata |
项目自定义元数据。 |
返回：当前请求描述。
结构：
p_body: Dictionary，项目传输层持有的请求载荷。p_metadata: Dictionary，随请求持久化的项目侧元数据。
is_valid¶
- API：
public
检查请求是否具备最小有效信息。
返回：有效时返回 true。
can_attempt¶
- API：
public
检查当前时刻是否允许再次尝试。
参数：
| 名称 | 说明 |
|---|---|
now_msec |
当前毫秒时间戳；小于 0 时自动读取。 |
返回：可尝试时返回 true。
is_exhausted¶
- API：
public
检查是否已耗尽尝试次数。
返回：已耗尽时返回 true。
mark_attempt¶
- API：
public
记录一次发送尝试。
mark_failure¶
- API：
public
记录失败并安排下一次重试。
参数：
| 名称 | 说明 |
|---|---|
error |
失败原因。 |
retry_delay_msec |
从现在起等待多少毫秒后可重试。 |
mark_success¶
- API：
public
记录成功状态。
duplicate_request¶
- API：
public
复制请求描述。
返回：新请求描述。
to_dict¶
- API：
public
转为字典。
参数：
| 名称 | 说明 |
|---|---|
json_compatible |
为 true 时会把载荷与元数据转换为 JSON 兼容值。 |
返回：请求字典。
结构：
return: Dictionary，包含 request_id、method、method_name、url、body、headers、idempotency_key、重试字段、last_error 和 metadata。
apply_dict¶
- API：
public
从字典恢复。
参数：
| 名称 | 说明 |
|---|---|
data |
请求字典。 |
json_compatible |
为 true 时会先恢复类型化 JSON 值。 |
结构：
data: Dictionary，包含 request_id、method、url、body、headers、idempotency_key、重试字段、last_error 和 metadata。
get_method_name¶
- API：
public
获取方法名称。
返回：方法名称。
from_dict¶
- API：
public
从字典创建请求描述。
参数：
| 名称 | 说明 |
|---|---|
data |
请求字典。 |
json_compatible |
为 true 时会先恢复类型化 JSON 值。 |
返回：请求描述。
结构：
data: Dictionary，包含 request_id、method、url、body、headers、idempotency_key、重试字段、last_error 和 metadata。