事件规范

事件是整个框架的驱动核心，主要分为外域网事件和内域网事件。通常外域事件是一个特定结构 JSON 对象，用来访问具体实现的逻辑，然后使用统一的 JSON 格式返回结果。这里没有采用传统 Restful API 规范，而是使用自定义的 JSON 结构，以适应更多的外域服务协议，避免绑定 HTTP。内域事件通过特定的客户端对象封装调用，每个事件的调用参数和返回格式有区别，请仔细查看响应的文档说明使用。

外域事件

属性说明

参数名	类型	必填	说明
id	string	是	事件唯一标识
project	string	是	项目名称
version	string	是	版本号
context	string	是	上下文环境
entity	string	是	实体名称
event	string	是	事件类型
params	string	是	事件参数，JSON 字符串格式
accessToken	string	是	访问令牌
source	string	是	事件来源，理论上支持任意种客户来源，通过登录后得到对应的 token 访问即可。
sign	string	是	签名，参考后端签名算法
createdAt	number	是	创建时间戳（毫秒）

具体示例

{
  "id": "01JRA7C2BE95A46GPH346BA5FB",
  "project": "event",
  "version": "0.1.0",
  "context": "gateway",
  "entity": "entity",
  "event": "list",
  "params": "{\"page\":1,\"pageSize\":10, \"deleted\":false}",
  "accessToken": "xxx",
  "source": "web_api",
  "sign": "457cfbd554b0a913b1cdde56dd547b9b2b5a62ed",
  "createdAt": 1744100002158
}

JSON Schema 验证

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Event Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "事件的唯一标识符"
    },
    "project": {
      "type": "string",
      "description": "项目号，标识事件所属项目"
    },
    "version": {
      "type": "string",
      "description": "版本号，标识事件所属版本"
    },
    "context": {
      "type": "string",
      "description": "上下文号，标识事件所属上下文环境"
    },
    "entity": {
      "type": "string",
      "description": "实体号，标识事件所属实体"
    },
    "event": {
      "type": "string",
      "description": "事件号，标识事件类型"
    },
    "source": {
      "type": "string",
      "description": "事件来源，标识事件发起者"
    },
    "params": {
      "type": "string",
      "description": "事件参数，JSON格式字符串"
    },
    "accessToken": {
      "type": "string",
      "description": "访问令牌，用于权限验证"
    },
    "createdAt": {
      "type": "integer",
      "description": "创建时间戳",
      "format": "int64"
    },
    "sign": {
      "type": "string",
      "description": "签名，用于验证事件完整性"
    }
  },
  "required": [
    "id",
    "project",
    "version",
    "context",
    "entity",
    "event",
    "source",
    "params",
    "accessToken",
    "createdAt",
    "sign"
  ],
  "additionalProperties": false
}

外域事件-响应结果

每个事件返回的响应结果都是统一的，具体如下：

属性说明

参数名	类型	必填	说明
code	string	是	响应状态码，如："ok"
createdAt	number	是	响应时间戳（毫秒）
message	string	是	响应消息
list	array	否	数据列表
total	number	否	数据总数
size	number	否	每页数量
page	number	否	当前页码

具体示例

{
  "code": "ok",
  "createdAt": 1744100002187,
  "message": "查询成功",
  "list": [],
  "total": 0,
  "size": 0,
  "page": 1
}

JSON Schema 验证

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JSON Response Schema",
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "响应码，表示操作结果状态"
    },
    "createdAt": {
      "type": "integer",
      "description": "响应创建时间戳（毫秒）",
      "format": "int64"
    },
    "message": {
      "type": "string",
      "description": "响应消息，对状态的文字描述"
    },
    "list": {
      "type": "array",
      "description": "响应数据列表",
      "items": {}
    },
    "total": {
      "type": "integer",
      "description": "数据总数（用于分页）",
      "format": "int64"
    },
    "size": {
      "type": "integer",
      "description": "当前页数据大小"
    },
    "page": {
      "type": "integer",
      "description": "当前页码"
    }
  },
  "required": ["code", "createdAt", "message", "list", "total", "size", "page"],
  "additionalProperties": false
}

内域事件

内域事件基于内部自定义的 RPC 协议，Gateway 和 Worker 都通过接口dispatcher.Event调用，返回结果为 ResponseMessage 对象。

调用方法

功能描述

dispatcher.Event函数用于处理内域事件请求，并将请求发送到指定的端点。该函数会检查请求的调用链，防止循环调用。

参数说明

参数名	类型	描述
`endpoint`	`string`	目标端点的 URL，表示请求将要发送到的地址
`typz`	`types.INTRANET_EVENT_TYPE`	事件类型，表示请求的事件类型
`params`	`string` `object`	请求参数，表示要发送的请求参数，通常为字符串或对象
`request`	`serverx.RequestContext`	请求上下文，包含请求的调用链和事件信息

返回值

返回值	类型	描述
`response`	`gnetx.ResponseMessage`	返回的响应消息，表示从目标端点返回的响应
`err`	`error`	返回的错误信息，表示在请求过程中发生的任何错误

ResponseMessage 结构

// ResponseMessage 定义服务器响应的消息结构
// 包含响应的状态码、内容类型和数据
type ResponseMessage struct {
    Status      int                  `json:"s"`  // 状态码，同HTTP协议
    MessageType serverx.CONTENT_TYPE `json:"mt"` // 响应内容类型：PING、JSON或STRING
    Data        string               `json:"d"`  // 响应内容，可能是JSON字符串或普通文本
}

使用示例

response, err := dispatcher.Event(
    "https://api.example.com/endpoint",
    types.EVENT_TYPE_EXAMPLE,
    `{"key": "value"}`,
    requestContext,
)
if err != nil {
    // 处理错误
}
// 使用response

常用响应状态码

个别状态可能有变更，以当前版本里 constant/response_code.go 里定义的常量为准。

代码常量	响应码	说明
SUCCESS	ok	操作成功
WORKER_ENDPOINT	worker_endpoint	worker 地址
FAIL_TO_CREATE	fail_to_create	创建失败
FAIL_TO_QUERY	fail_to_query	查询失败
FAIL_TO_UPDATE	fail_to_update	更新失败
FAIL_TO_DELETE	fail_to_delete	删除失败
FAIL_TO_PROCESS	fail_to_process	处理失败
INVALID_SIGN	invalid_sign	无效的签名
INVALID_PARAM	invalid_param	无效的参数
INVALID_TOKEN	invalid_token	登录信息无效
INVALID_PASSWORD	invalid_password	账号信息错误
MISSING_PARAM	missing_param	缺少必要参数
ALREADY_EXIST	already_exist	数据已存在
USER_EXIST	user_exist	用户已存在
USER_BANNED	user_banned	用户已被禁止
USER_NOT_EXIST	user_not_exist	无效的账号或密码
USER_SIGN_TIMEOUT	user_sign_timeout	用户签名超时
USER_UNAUTHORIZED	user_unauthorized	用户未授权
EVENT_TIMEOUT	event_timeout	事件超时
EVENT_NOT_EXIST	event_not_exist	事件不存在
ENTITY_NOT_EXIST	entity_not_exist	实体不存在
UNSUPPORTED_EVENT	unsupported_event	不支持的事件
UNSUPPORTED_CLIENT	unsupported_client	不支持的客户端
UNHANDLED_ERROR	unhandled_error	未处理的错误
UNKNOWN_DATA	unknown_data	未知数据格式
EMPTY_DATA	empty_data	数据为空
DATA_EXIST	data_exist	数据已存在
TOO_MANY_REQUESTS	TOO_MANY_REQUESTS	请求过于频繁
LIMIT_REACHED	limit_reached	达到最大上限
FORBIDDEN_CALL	forbidden_call	禁止的调用方式
TASK_PENDING	task_pending	任务已添加
TASK_IN_PROGRESS	task_in_progress	任务进行中
TASK_FAILED	task_failed	任务失败
TASK_TIMEOUT	task_timeout	任务超时
TASK_UNKNOWN	task_unknown	任务未知
TASK_LIMIT_REACHED	task_limit_reached	任务达到最大上限
SERVICE_UNAVAILABLE	service_unavailable	服务不可用
REQUEST_TIMEOUT	request_timeout	请求超时
CONFLICT	conflict	资源冲突
NOT_IMPLEMENTED	not_implemented	功能未实现

外域事件​

属性说明​

具体示例​

JSON Schema 验证​

外域事件-响应结果​

属性说明​

具体示例​

JSON Schema 验证​

内域事件​

调用方法​

ResponseMessage 结构​

使用示例​

常用响应状态码​

外域事件

属性说明

具体示例

JSON Schema 验证

外域事件-响应结果

属性说明

具体示例

JSON Schema 验证

内域事件

调用方法

ResponseMessage 结构

使用示例

常用响应状态码