对外服协议

介绍

ExternalMessage 是统一交的互协议，也称为游戏对外服协议，其主要作用是与游戏客户端交互的统一协议。

在 ioGame 中，协议这部分的概念划分为两种：

统一的交互协议，主要作用是与游戏客户端交互的统一协议，也就是 ExternalMessage。
通用的包装协议，主要作用是解决协议碎片问题，可帮助开发者减少巨大工作量。

提示

如果使用了 ioGame SDK，则不需要了解这部分的内容。

协议文件

提示

请把这个 .proto 协议文件给到游戏前端开发者，如果使用了 ioGame SDK 则可以不需要。

协议文件中除了主要的 ExternalMessage，还提供了几个包装类协议。

syntax = "proto3";
package com.iohao.message;
// ExternalMessage. cn: 对外服数据协议
message ExternalMessage {
  // Request command type: 0 heartbeat, 1 business .
  // cn: 请求命令类型: 0 心跳，1 业务
  int32 cmd_code = 1;
  // Protocol switch, used for protocol-level switch control, such as security encryption verification, etc. : 0 no verification
  // cn: 协议开关，用于一些协议级别的开关控制，比如 安全加密校验等。 : 0 不校验
  optional int32 protocol_switch = 2;
  // Business routing (high 16 bits for main, low 16 bits for sub)
  // cn: 业务路由（高16为主, 低16为子）
  optional int32 cmd_merge = 3;
  // Response code: 0: success, others indicate errors
  // cn: 响应码: 0:成功, 其他为有错误
  optional sint32 response_status = 4;
  // Verification message (error message, exception message), usually when responseStatus == -1001, there will be a value
  // 验证信息（错误消息、异常消息），通常情况下 responseStatus == -1001 时， 会有值
  optional string valid_msg = 5;
  // Business request data
  // 业务请求数据
  optional bytes data = 6;
  // Message tag number; set by the front-end when requesting, and will be carried by the server when responding; (similar to transparent transmission parameters)
  // 消息标记号；由前端请求时设置，服务器响应时会携带上；（类似透传参数）
  optional int32 msg_id = 7;
}

// int wrapper class. cn: int 包装类
message IntValue {
  sint32 value = 1;
}

// int list wrapper class. cn: int list 包装类
message IntValueList {
  // intList、intArray
  repeated sint32 values = 1;
}

// long wrapper class. cn: long 包装类
message LongValue {
  sint64 value = 1;
}

// long list wrapper class. cn: long list 包装类
message LongValueList {
  // longList、longArray
  repeated sint64 values = 1;
}

// string wrapper class. cn: string 包装类
message StringValue {
  string value = 1;
}

// bool wrapper class. cn: string list 包装类
message StringValueList {
  // stringList、stringArray
  repeated string values = 1;
}

// bool wrapper class. cn: bool 包装类
message BoolValue {
  bool value = 1;
}

// bool list wrapper class. cn: bool list 包装类
message BoolValueList {
  // boolList、boolArray
  repeated bool values = 1;
}

// pb object list wrapper class. cn: 对象 list 包装类
message ByteValueList {
  // pb object List、pb object Array
  // pb 对象 List、pb 对象 Array
  repeated bytes values = 1;
}

关于透传参数 msg_id

注意

默认情况下，只有在 request/response 模式下才生效，就是 action 有返回值的方法。

ExternalMessage.msg_id 是类似透传参数。see [#99]。如果实际中没有这个需求的，可以忽略这个字段。

游戏前端可以给游戏对外服协议添加一个 msg_id，当 ioGame 接收到请求并处理完请求后，会在响应时将 msg_id 回传给请求端。如果使用了 ioGame SDK，则可以忽略，因为 SDK 会在每次请求时分配 msg_id。

ExternalMessage

ExternalMessage 是统一交的互协议，也称为游戏对外服协议，其主要作用是与游戏客户端交互的统一协议。

游戏客户端向服务器发起的请求时，分为两种类型，分别是

心跳请求
业务请求

当为心跳请求时，必填属性是 cmd_code = 0，其他属性请忽略。

当为业务请求时，必填属性是 cmd_code = 1、cmd_merge，其他为选填，详细见下表

请求时描述

当发起【业务请求】时的使用说明
属性名	是否必填	描述
cmd_code	✅	cmd_code 必须为 1。
protocol_switch	忽略	给开发者预留的字段。
cmd_merge	✅	路由。
response_status	忽略	服务器响应数据时，如果为 0 则表示成功，其他值表示有错误码。
valid_msg	忽略	默认情况下，服务器是不会传递错误消息的，不传递错误消息的原因。特殊情况，当 response_status == -1001 时，框架会传递错误消息。
data	按需	业务参数，会被服务器接收到。
msg_id	按需	msg_id 是类似透传参数。see [#99]，如果实际中没有这个需求的，可以忽略这个字段。客户端发起请求时，msg_id 填的什么值，服务器在响应请求时，会原样返回该值。

响应时描述

我们在编写 action 时，下面的 newHelloMessage 对象会赋值到 ExternalMessage.data 中，这一步骤是在游戏对外服中处理的。

@ActionController(1)
public class DemoAction {
    @ActionMethod(0)
    public HelloMessage here(HelloMessage message) {
        HelloMessage newHelloMessage = ...
        return newHelloMessage;
    }
}

响应【业务请求】时的说明
属性名	描述
cmd_code	值为 1
cmd_merge	取当前 action 的路由值
response_status	服务器响应数据时，如果为 0 则表示成功，其他值表示有错误码。
valid_msg	默认情况下，服务器是不会传递错误消息的，不传递错误消息的原因。特殊情况，当 response_status == -1001 时，框架会传递错误消息。
data	action 中 return 的对象会放到该属性中。
msg_id	msg_id 是类似透传参数。see [#99]。如果实际中没有这个需求的，可以忽略这个字段。客户端发起请求时，msg_id 填的什么值，服务器在响应请求时，会原样返回该值。

xxxValue 通用的包装协议

xxxValue 是框架提供的包装（协议）类，主要作用是解决协议碎片问题。

syntax = "proto3";

message IntValue {
  sint32 value = 1;
}

message IntValueList {
  repeated sint32 values = 1;
}

message LongValue {
  sint64 value = 1;
}

message LongValueList {
  repeated sint64 values = 1;
}

message StringValue {
  string value = 1;
}

message StringValueList {
  repeated string values = 1;
}

message BoolValue {
  bool value = 1;
}

message BoolValueList {
  repeated bool values = 1;
}

message ByteValueList {
  repeated bytes values = 1;
}

小结

详细的介绍了 ExternalMessage 统一交互协议和通用包装协议。

通用包装协议，主要作用是解决协议碎片问题，可帮助开发者减少巨大工作量。

如果没有特殊情况，建议使用框架提供的 ExternalMessage 与前端交互。当我们使用 pb 传输时，ExternalMessage 的字段是赋值多少就占用多少字节。如果字段没有使用，在传输时将不会占用字节。

提示

如果使用了 ioGame SDK，则不需要了解这部分的内容。

介绍​

协议文件​

关于透传参数 msg_id​

ExternalMessage​

请求时描述​

响应时描述​

xxxValue 通用的包装协议​

小结​

介绍