GFNetworkContract

API Reference / Network / 类索引

• 路径：addons/gf/extensions/network/contracts/gf_network_contract.gd
• 模块：Network
• 继承：Resource
• API：public
• 类别：资源定义 (resource_definition)
• 首次版本：3.17.0

网络消息契约集合。 契约集合用于集中描述一组 GFNetworkMessage 的 message_type、字段和默认通道， 方便项目生成强类型辅助代码或在运行前校验消息结构。

成员概览

类型	名称	签名
属性	contract_id	var contract_id: StringName = &""
属性	display_name	var display_name: String = ""
属性	messages	var messages: Array[GFNetworkContractMessage] = []
属性	metadata	var metadata: Dictionary = {}
方法	get_display_name	func get_display_name() -> String:
方法	set_message_contract	func set_message_contract(message_contract: GFNetworkContractMessage) -> void:
方法	get_message_contract	func get_message_contract(message_type: StringName) -> GFNetworkContractMessage:
方法	has_message_contract	func has_message_contract(message_type: StringName) -> bool:
方法	make_message	func make_message(message_type: StringName, values: Dictionary = {}, options: Dictionary = {}) -> GFNetworkMessage:
方法	validate_message	func validate_message(message: GFNetworkMessage) -> Dictionary:
方法	validate_contract	func validate_contract() -> Dictionary:
方法	describe	func describe() -> Dictionary:

属性

contract_id

• API：public

var contract_id: StringName = &""

契约稳定标识。

display_name

• API：public

var display_name: String = ""

编辑器展示名称。

messages

• API：public

var messages: Array[GFNetworkContractMessage] = []

消息契约列表。

结构：

• messages: Array[GFNetworkContractMessage]，按声明顺序保存消息契约。

metadata

• API：public

var metadata: Dictionary = {}

项目自定义元数据。框架不解释该字段。

结构：

• metadata: Dictionary，保存项目自定义契约元数据。

方法

get_display_name

• API：public

func get_display_name() -> String:

获取展示名称。

返回：展示名称。

set_message_contract

• API：public

func set_message_contract(message_contract: GFNetworkContractMessage) -> void:

设置或替换一个消息契约。

参数：

名称	说明
message_contract	消息契约。

get_message_contract

• API：public

func get_message_contract(message_type: StringName) -> GFNetworkContractMessage:

获取消息契约。

参数：

名称	说明
message_type	消息类型。

返回：消息契约；不存在时返回 null。

has_message_contract

• API：public

func has_message_contract(message_type: StringName) -> bool:

检查消息契约是否存在。

参数：

名称	说明
message_type	消息类型。

返回：存在返回 true。

make_message

• API：public

func make_message(message_type: StringName, values: Dictionary = {}, options: Dictionary = {}) -> GFNetworkMessage:

按消息契约创建 GFNetworkMessage。

参数：

名称	说明
message_type	消息类型。
values	字段值字典。
options	可选元信息。

返回：网络消息；契约不存在时返回 null。

结构：

• values: Dictionary[StringName|String, Variant]，字段名到字段值的映射。
• options: Dictionary，支持 include_defaults、sequence、tick、sender_id、channel_id。

validate_message

• API：public

func validate_message(message: GFNetworkMessage) -> Dictionary:

校验网络消息是否匹配本契约集合。

参数：

名称	说明
message	网络消息。

返回：校验报告字典。

结构：

• return: Dictionary，GFValidationReportDictionary 格式，包含 ok、issues、issue_count 和 next_actions。

validate_contract

• API：public

func validate_contract() -> Dictionary:

校验契约定义是否完整。

返回：校验报告字典。

结构：

• return: Dictionary，GFValidationReportDictionary 格式，包含 ok、issues、issue_count 和 next_actions。

describe

• API：public

func describe() -> Dictionary:

描述契约集合。

返回：描述字典。

结构：

• return: Dictionary，包含 contract_id、display_name、message_count、messages、metadata。