Outrig项目RPC API开发指南：从基础到流式通信

前言

在现代分布式应用开发中，远程过程调用(RPC)是实现前后端高效通信的核心技术。Outrig项目采用双向RPC系统架构，允许Go语言定义的方法能被前端调用，同时前端方法也能被后端调用。本文将详细介绍如何在Outrig项目中添加新的RPC API，包括常规方法和流式方法。

基础RPC方法开发

1. 方法定义规范

在Outrig中定义RPC方法需要遵循以下规范：

• 方法命名必须以Command结尾，这是系统的强制约定
• 第一个参数必须是context.Context类型，用于传递上下文信息
• 可选第二个参数作为输入数据，支持两种形式：
  • 基础数据类型（string、int、bool等）
  • 在rpctypes.go中定义或复用的结构体
• 返回值可以是error或(结果, error)形式，结果同样可以是基础类型或自定义结构体

2. 数据结构定义

所有用于RPC通信的数据结构都需要在rpctypes.go文件中定义或复用。定义时需注意：

• 每个结构体字段必须添加JSON标签
• JSON标签必须全部小写，不能包含大写字母或下划线
• 遵循Go语言的导出规则（首字母大写）

示例：

type UserInfo struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

3. 代码生成与更新

添加新方法后，需要执行代码生成命令更新相关文件：

task generate

此命令会更新以下关键文件：

• 前端调用的TypeScript定义文件(rpctypes.d.ts)
• 客户端API文件(rpcclientapi.ts)
• Go语言端的客户端API文件(rpcclientapi.go)

高级功能：流式RPC开发

1. 流式方法特点

流式RPC适用于需要持续从后端向前端推送数据的场景，如实时通知、进度更新等。与传统RPC不同，流式方法建立的是持久连接，可以持续发送多个响应。

2. 流式方法定义规范

• 方法命名同样必须以Command结尾
• 第一个参数必须是context.Context
• 可选第二个输入参数，必须是rpctypes.go中定义的结构体
• 返回值为接收专用通道(<-chan)，通道元素为RespUnion[T]类型，其中T是响应结构体

示例定义：

StreamUpdatesCommand(ctx context.Context, params UpdateParams) <-chan RespUnion[UpdateResponse]

3. 流式通信数据结构

流式方法使用的数据结构同样需要在rpctypes.go中定义：

type UpdateParams struct {
    Interval int `json:"interval"`
}

type UpdateResponse struct {
    Progress int    `json:"progress"`
    Message  string `json:"message"`
}

4. 代码生成注意事项

添加流式方法后，同样需要执行生成命令：

task generate

系统会自动处理流式通信所需的类型定义和接口更新。

最佳实践建议

1. 命名一致性：保持方法命名清晰且一致，使用动词+名词+Command的格式，如GetUserInfoCommand

2. 错误处理：在方法实现中充分考虑错误场景，返回有意义的错误信息

3. 文档注释：为每个RPC方法和数据结构添加详细的注释说明

4. 性能考量：对于高频调用的方法，注意优化实现逻辑

5. 版本兼容：修改现有方法时考虑向后兼容性

调试技巧

1. 在开发阶段，可以使用日志记录RPC调用的输入输出

2. 对于流式方法，可以先实现简单的定时推送逻辑进行测试

3. 关注生成的TypeScript定义文件，确保前端能获得正确的类型提示

总结

Outrig的RPC系统设计巧妙地将前后端通信统一处理，通过代码生成确保类型安全。开发者只需遵循简单的规范定义方法和数据结构，系统就能自动处理跨语言调用的复杂性。无论是常规的请求-响应模式还是更高级的流式通信，Outrig都提供了清晰一致的开发模式。

掌握这些RPC开发技巧后，你可以在Outrig项目中高效实现各种前后端交互需求，构建响应迅速、实时性强的现代化应用。