[对接文档-增强] 支持对接文档生成时，可以根据路由访问权限来控制文档的生成

iohao commented 2 months ago

描述 - 拒绝玩家访问权限的控制

相关文档 - 路由访问权限控制 (yuque.com)

有些 action 只能内部访问，比如增加金币、敏感数值的增加等。这些 action 是不能由外部直接访问的，这里说的外部指的是连接中的玩家（真实玩家）。

var accessAuthenticationHook = ExternalGlobalConfig.accessAuthenticationHook;
// 拒绝主路由为 10 的访问请求
accessAuthenticationHook.addRejectionCmd(10);
// 拒绝主路由为 4、子路由为 10 的访问请求
accessAuthenticationHook.addRejectionCmd(4, 10);

增强描述

在此之前的版本中，生成对接文档时，会把内部 action 一同生成出来；虽然问题不大，但这样会给阅读对接文档的开发者造成一定的干扰，因此该 issue 中将会解决这一问题。

因为框架支持路由访问权限控制 (yuque.com)，所以我们可以复用这些权限数据来控制是否生成对应的文档。

关于对接文档的相关内容

330

iohao commented 2 months ago

实战 - 设置路由访问权限

var accessAuthenticationHook = ExternalGlobalConfig.accessAuthenticationHook;
// 拒绝主路由为 4、子路由为 10 的访问请求
accessAuthenticationHook.addRejectionCmd(4, 10);

预览 - 生成文本文档

没有做控制前的生成

==================== RankAction  ====================
路由: 4 - 1  --- 【listRank】 --- 【RankAction:48】【listRank】
    方法参数: StringValue 排行类型
    方法返回值: ByteValueList<RankUpdate> 玩家排行名次更新

路由: 4 - 10  --- 【玩家排行名次更新】 --- 【RankAction:60】【internalUpdate】
    方法参数: RankUpdate 玩家排行名次更新
    方法返回值: void

加入了访问控制后的生成

我们可以看见，路由为 4-10 的 action 方法没有生成到对接文档中。

==================== RankAction  ====================
路由: 4 - 1  --- 【listRank】 --- 【RankAction:48】【listRank】
方法参数: StringValue 排行类型
方法返回值: ByteValueList<RankUpdate> 玩家排行名次更新

预览 - 生成对接文档

除了文档文档外，框架还支持客户端代码生成，下面使用 SDK TypeScript 客户端代码生成来举例

329

下图是 SDK TypeScript 客户端代码生成的对接 api，左边是没有加路由权限控制的，右边是加了路由访问权限的。可以看出，当我们加了路由访问控制权限后，就不会生成对应的访问 api 。

小结

可以看出，当支持对接文档的路由访问权限控制后有如下优点：

通过路由访问权限来控制文档的生成，这些文档包括文本文档、SDK 联调代码的对接文档 ...等。
可以隐藏内部 action 方法，减少文档阅读者的干扰项。
在使用上是简单的，可以复用路由访问权限控制 (yuque.com)相关数据。

iohao commented 2 months ago

生成相关代码的使用及相关文档

ExternalGlobalConfig.accessAuthenticationHook，相关文档 - 路由访问权限控制 (yuque.com)
IoGameDocumentHelper，相关文档 - 游戏对接文档生成 (yuque.com)

使用示例


public class MyExternalServer {
public static void extractedAccess() {
// https://www.yuque.com/iohao/game/nap5y8p5fevhv99y
var accessAuthenticationHook = ExternalGlobalConfig.accessAuthenticationHook;
... 省略部分代码
// 添加 - 拒绝玩家访问权限的控制
accessAuthenticationHook.addRejectionCmd(RankCmd.cmd, RankCmd.internalUpdate);
}
}

public class TestGenerate { ... 省略部分代码 public static void main(String[] args) { // 对外服访问权限控制 MyExternalServer.extractedAccess(); // （复用）设置文档路由访问权限控制 IoGameDocumentHelper.setDocumentAccessAuthentication(ExternalGlobalConfig.accessAuthenticationHook::reject);

    // ====== 生成对接文档、生成 proto ======

// generateCsharp(); generateTypeScript(); // 生成文档 IoGameDocumentHelper.generateDocument(); // .proto 文件生成 generateProtoFile(); } }

iohao / ioGame