云信令（原实时消息）最佳实践

本文包括调用云信令 RESTful API 及集成云信令 SDK 时的最佳实践。

切换域名

为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供切换域名的方案。

切换域名操作

1. 根据你的业务服务器所在地设置主域名：
   • 业务服务器 DNS 地址位于中国大陆时，设置主域名为 api.sd-rtn.com。
   • 业务服务器 DNS 地址位于中国大陆以外的国家或地区时，设置主域名为 api.agora.io。
2. 当使用主域名发起 RESTful API 请求失败时，使用该域名重试一次。
3. 如果步骤 2 的重试依然失败，使用备用的主域名重试：
   • 如果当前设置的主域名为 api.sd-rtn.com，备用的主域名指 api.agora.io。
   • 如果当前设置的主域名为 api.agora.io，备用的主域名指 api.sd-rtn.com。
4. 如果步骤 3 的重试依然失败，使用与当前解析区域相邻的区域域名重试。
   举例说明：假设你的业务服务器位于欧洲，你设置主域名为 api.agora.io，而且业务服务器解析主域名解析到德国。德国位于欧洲中部 api-eu-central-1.agora.io，查域名信息表可知，相邻区域为欧洲西部 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com。因此，出现网络故障且步骤 2、3 的重试失败时，请使用 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com 域名重试。

注意事项

• 为避免重试请求过于频繁，超过声网服务所规定的 QPS（每秒请求数），声网建议你使用退避策略。例如，第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试。
• 如果是网络问题而非 DNS 解析域名问题导致的请求失败，声网建议你跳过步骤 3，直接进行步骤 4。
• 切换至区域域名前，请确保你使用的业务（例如，云端录制、云信令、频道管理等 REST 服务）在该区域有部署服务。

域名信息

定时更新 Token

(所有 SDK) RTM Token 的有效期是 24 小时。声网建议你定时（例如每小时）从服务端生成 Token 并调用 renewToken 方法更新 SDK 的 Token，保证 SDK 的 Token 一直处于有效状态。关于如何在服务端生成 Token，参考生成 RTM Token。

下面的示例代码展示了如何定时更新 Token。

// C++
// 监听 Token 过期回调
class MyHandler : public IRtmServiceEventHandler {
public:
  void onRenewTokenResult(const char* token, RENEW_TOKEN_ERR_CODE errorCode)
  {
    if (errorCode == RENEW_TOKEN_ERR_OK) {
      token_ = errorCode;
    }
    else {
      token_ = "";
    }
  }

  void setToken(const std::string& token) {
    token_ = token;
  }

  std::string getNewToken()
  {
    return token_;
  }
private:
  std::string token_;
};

// 获取服务端生成的 Token 并通过 renewToken 方法更新 SDK 的 Token
void renewTokenDemoCode() {
  auto client = createRtmService();
  std::string appId = "";
  std::string token = "";
  std::string userId = "";
  bool stopped = false;
  MyHandler handler;
  handler.setToken(token);
  client->initialize("appId", &handler);
  client->login(token.c_str(), userId.c_str());
  // 等待登录成功
  sleep(10);

  // 在单线程中更新 Token
  while(!stopped) {
    // 每小时更新一次
    sleep(60 * 60);
    // 错误处理
    if (handler.getNewToken().empty()) {
      break;
    }
    client->renewToken(handler.getNewToken().c_str());
  }
  client->logout();
  client->release();
}

合理进行资源管理

及时释放不需要的资源

(C++ SDK, Java SDK) 不及时释放创建的资源可能导致内存泄漏。虽然 Java 的 GC (Garbage Collection) 机制可以回收上层 Java 对象，但是 Java SDK 的底层 C++ API 仍然使用 Java 对象进行回调，因此会造成崩溃。

声网建议你主动调用 release 方法释放客户端对象和频道对象。

不要再访问已释放的资源

(所有 SDK) 如果你已经释放了 RTM 客户端对象，声网建议你不要再请求相关的资源。另外，你也无法在 RTM 客户端对象释放后使用 RtmCallManager 的相关资源。

不要在频道对象的回调中释放回调

(C++ SDK, Java SDK, Objective-C SDK) 如果你在频道对象的回调方法中，调用 release 方法释放频道对象，由于回调方法会对对象加锁，release 方法会请求同一把锁，造成应用卡住。

注意管理资源的生命周期

(C++ SDK) 如果你为 IRtmService 对象和 IChannel 对象设置了相应的监听器，即 IRtmServiceEventHandler 和 IChannelEventHandler，你需要保证监听器的生命周期长于对象的生命周期。否则对象可能会调用已经释放的监听器，造成崩溃。

(1.4.1 版之前的 Objective-C SDK) AgoraRtmChannel 的生命周期需要长于 AgoraRtmKit。否则 AgoraRtmKit 会使用已经释放的 AgoraRtmChannel，造成崩溃。

避免回调阻塞

(所有 SDK)声网建议你及时执行回调，并尽量减少回调的运行时间。否则可能会阻塞后面的回调，或造成回调丢失。

每一个 RTM 客户端实例的回调都是运行在同一个线程上的。后一个回调会等待前一个回调执行完成后再开始执行。 如果前一个回调的运行时间比较长，会使之后的回调不能及时触发，同时等待处理的回调队列越来越长。

• 对于 RTM Native SDK，达到队列长度限制之后，额外的回调事件会被丢弃。
• 对于 RTM Web SDK 和微信小程序 SDK，虽然队列长度没有限制，但是过长的回调队列会造成性能问题。

注意处理 SIGPIPE 信号

(Linux C++ /Linux Java SDK) RTM 的 Linux 服务端 SDK 没有屏蔽 SIGPIPE 信号。你需要根据实际情况，选择是否屏蔽 SIGPIPE 信号。一般情况下，你需要屏蔽此信号，否则，客户端进程在收到此信号后会默认退出。

处理与 RTC SDK 共同使用时的问题

AgoraRtmAreaCode 枚举产生的命名冲突

• (1.4.2 及之后版本的 C++ SDK) 使用 AGORA_SDK_BOTH_RTM_AND_RTC 宏。
• (1.4.3 及之后版本的 Objective-C SDK) 无论你的开发语言是 Objective-C 还是 Swift，声网都建议你使用 SDK 包中提供的 AgoraRtmKit_swift.h 文件。

SDK 初始化和销毁顺序

你需要在初始化和销毁 RTC 与 RTM SDK 时，遵循“先进后出”的栈操作顺序，即后初始化的 SDK 先销毁，例如：
RTC 初始化 → RTM 初始化 → RTM 销毁 → RTC 销毁
或者
RTM 初始化 → RTC 初始化 → RTC 销毁 → RTM 销毁