Telegram4J 常见错误处理指南

• 1. 处理 telegram4j.mtproto.RpcException: channels.getFullChannel returned code: 420, message: FLOOD_WAIT_6 错误
  • 错误原因
  • 解决办法
• 2. 解决 WARN t.c.e.DefaultUpdatesManager.warn:299 - Incorrect get difference parameters, pts: -1, qts: -1, date: 1734221299 警告
  • 问题分析
  • 解决方案
  • 详细解释 pts、qts 和 date
• 3. 优化状态存储：使用数据库替代本地文件
  • 解决办法
  • 数据库表结构
  • Java 实现
  • 配置使用 DbStateStoreService
  • 优势
• 4. 总结与建议

在使用 Telegram4J 库与 Telegram 服务器进行交互时，开发者可能会遇到一些常见错误和警告。本文将详细分析这些问题的原因，并提供相应的解决方案，帮助您优化应用的稳定性和性能。

---

1. 处理 telegram4j.mtproto.RpcException: channels.getFullChannel returned code: 420, message: FLOOD_WAIT_6 错误

错误原因

• 错误代码 420 和消息 FLOOD_WAIT_6：这是 Telegram 服务器返回的标准错误，表示客户端在短时间内发送了过多请求，触发了速率限制（Rate Limiting）。具体来说，FLOOD_WAIT_6 意味着客户端需要等待 6 秒 后才能重新发送相关请求。

• 与 Telegram 服务器有关：此错误直接来自 Telegram 服务器，表明在调用 channels.getFullChannel 方法时，客户端超过了服务器设定的请求频率限制。服务器通过速率限制机制保护自身资源，确保服务的稳定性。

解决办法

1. 降低请求频率：

   • 确保应用在一定时间内不发送过多的 channels.getFullChannel 请求。可以通过引入请求节流机制（如限制每分钟的请求次数）来实现。

2. 处理 FLOOD_WAIT 错误：

   • 在代码中捕获此类错误，并根据服务器指示的等待时间（例如 6 秒）进行适当的延迟再重试请求。

   try {
       // 调用 channels.getFullChannel 方法
   } catch (RpcException e) {
       if (e.getMessage().startsWith("FLOOD_WAIT_")) {
           int waitTime = Integer.parseInt(e.getMessage().split("_")[2]);
           Thread.sleep(waitTime * 1000L);
           // 重新尝试请求
       } else {
           throw e;
       }
   }

3. 优化请求逻辑：

   • 检查是否存在不必要的重复请求，或者是否可以合并多个请求以减少总的请求次数。例如，批量获取多个频道的信息，而不是逐个请求。

---

2. 解决 WARN t.c.e.DefaultUpdatesManager.warn:299 - Incorrect get difference parameters, pts: -1, qts: -1, date: 1734221299 警告

问题分析

此警告信息指出在调用 getDifference 方法时，传入的参数 pts 和 qts 均为 -1，而 date 为异常值 1734221299。这些参数的初始值为 -1，表示状态尚未正确初始化。导致此警告的可能原因包括：

1. 状态未初始化或初始化失败：

   • DefaultUpdatesManager 在启动时通过 fillGap() 方法尝试从本地存储或服务器获取当前状态。如果此过程失败，pts 和 qts 将保持为 -1。

2. 本地存储中缺少有效状态：

   • 如果本地存储（如默认的 t4j-bot.bin 文件）不存在或损坏，客户端无法加载之前保存的状态，导致参数未被正确设置。

3. 并发或时序问题：

   • 在状态初始化完成之前，某些更新处理逻辑已经尝试调用 getDifference 方法，使用了默认的无效参数。

4. 错误的状态应用逻辑：

   • 即使成功获取到状态，applyStateLocal 方法可能未能正确应用这些状态，导致参数依旧无效。

解决方案

1. 确保状态初始化成功：

   • 检查 fillGap() 方法是否成功从本地存储或服务器获取并应用状态。可以通过增加日志来确认初始化过程是否顺利完成。

2. 验证本地存储机制：

   • 确保本地存储（如 t4j-bot.bin 文件）能够正确保存和加载 State 对象。如果存储文件损坏，可以尝试删除文件，让客户端重新从服务器获取状态。

3. 处理并发问题：

   • 确保在状态初始化完成之前，不会有其他更新处理逻辑试图调用 getDifference。可以通过同步机制或调整初始化顺序来避免此类问题。

4. 优化状态存储：

   • 考虑使用数据库来存储状态信息，替代默认的本地文件存储，提升数据的持久性和可靠性。

详细解释 pts、qts 和 date

• pts（Persistent Timestamp）：

  • 用于跟踪普通聊天（包括私聊和群聊）中的更新状态，确保客户端能够同步所有未处理的更新。

• qts（Queue Timestamp）：

  • 用于跟踪加密聊天（如秘密聊天）和某些特定类型的更新，确保这些更新能够独立且准确地同步。

• date：

  • 表示服务器当前的时间戳，用于标识更新的时间点，帮助客户端理解更新的顺序和时效性。

---

3. 优化状态存储：使用数据库替代本地文件

默认情况下，Telegram4J 会将频道信息缓存到内存中，并通过本地文件（如 t4j-bot.bin）进行持久化存储。然而，使用本地文件存储可能存在数据损坏或并发访问问题。为了提高数据的可靠性和管理的便捷性，建议使用数据库来存储状态信息。

解决办法

1. 删除默认存储文件：

   • 删除 t4j-bot.bin 文件后，客户端会再次从服务器获取最新的状态信息。这适用于初始设置或恢复状态的场景。

2. 使用数据库存储 State：

   • 通过数据库存储 pts、qts 和 date，确保状态信息的持久性和一致性。

数据库表结构

使用以下 SQL 语句创建用于存储 Telegram 状态的表：

DROP TABLE IF EXISTS telegram_state;
CREATE TABLE telegram_state (
  id BIGINT PRIMARY KEY,
  pts INT,
  qts INT,
  date INT,
  seq INT,
  unread_count INT,
  creator VARCHAR(64) DEFAULT '',
  create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updater VARCHAR(64) DEFAULT '',
  update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  deleted SMALLINT NOT NULL DEFAULT 0,
  tenant_id BIGINT NOT NULL DEFAULT 0
);

Java 实现

创建一个实现 DbStateStoreService 接口的类，用于与数据库交互：

package nexus.io.telegram.bots.service;

import nexus.io.db.activerecord.Db;
import nexus.io.db.activerecord.Row;
import nexus.io.telegram.store.service.DbStateStoreService;
import telegram4j.tl.updates.ImmutableState;

public class DbStateStoreServiceImpl implements DbStateStoreService {

  public static final String tableName = "telegram_state";
  protected volatile long selfId;

  @Override
  public void setSelfId(long selfId) {
    if (!Db.exists(tableName, "id", selfId)) {
      Db.save(tableName, Row.by("id", selfId));
    }
    this.selfId = selfId;
  }

  @Override
  public long getSelfId() {
    return this.selfId;
  }

  @Override
  public ImmutableState getCurrentState() {
    Row row = Db.findById(tableName, selfId);
    if (row != null) {
      Integer pts = row.getInt("pts");
      Integer qts = row.getInt("qts");
      Integer date = row.getInt("date");
      Integer seq = row.getInt("seq");
      Integer unread_count = row.getInt("unread_count");
      return ImmutableState.of(pts, qts, date, seq, unread_count);
    } else {
      return null;
    }
  }

  @Override
  public void updateState(ImmutableState state) {
    int pts = state.pts();
    int qts = state.qts();
    int date = state.date();
    int seq = state.seq();
    int unreadCount = state.unreadCount();
    Row row = Row.by("id", selfId)
                 .set("pts", pts)
                 .set("qts", qts)
                 .set("date", date)
                 .set("seq", seq)
                 .set("unread_count", unreadCount);
    Db.update(tableName, row);
  }
}

配置使用 DbStateStoreService

在初始化 Telegram 客户端时，配置使用数据库存储服务：

import nexus.io.telegram.bots.service.DbStateStoreServiceImpl;
import nexus.io.telegram.store.service.DbChannelStoreService;
import nexus.io.telegram.store.service.DbStateStoreService;
import telegram4j.MTProtoBootstrap;
import telegram4j.MTProtoTelegramClient;

// 创建并连接 MTProto Telegram 客户端
MTProtoBootstrap bootstrap = MTProtoTelegramClient.create(apiId, apiHash, botAuthToken);

// 实例化数据库存储服务
DbChannelStoreService dbChannelStoreService = new DbChannelStoreServiceImpl();
DbStateStoreService dbStateStoreService = new DbStateStoreServiceImpl();

// 配置 StoreLayout
DbStoreLayoutImpl storeLayoutImpl = new DbStoreLayoutImpl(Function.identity());
storeLayoutImpl.setDbChannelStoreService(dbChannelStoreService);
storeLayoutImpl.setDbStateStoreService(dbStateStoreService);

// 使用文件存储布局，同时结合数据库存储
FileStoreLayout storeLayout = new FileStoreLayout(storeLayoutImpl, Path.of("t4j-bot_" + botId + ".bin"));
bootstrap.setStoreLayout(storeLayout);

// 启动客户端
bootstrap.start();

说明：

• DbStateStoreServiceImpl：实现了 DbStateStoreService 接口，负责从数据库中读取和更新状态信息。
• DbStoreLayoutImpl：自定义的 StoreLayout 实现，整合了数据库存储服务。
• FileStoreLayout：尽管使用了数据库存储，但仍保留文件存储布局以备不时之需。

优势

• 数据持久性：数据库能够更可靠地保存状态信息，避免因文件损坏导致的数据丢失。
• 并发处理：数据库天然支持并发访问，减少了多线程环境下的数据一致性问题。
• 可扩展性：随着应用规模的扩大，数据库能够更高效地管理大量的状态数据。

---

4. 总结与建议

在开发基于 Telegram4J 的应用时，合理处理错误和优化状态存储至关重要。以下是关键要点：

1. 理解 Telegram 服务器的速率限制：

   • 避免频繁请求，合理安排请求节奏，处理 FLOOD_WAIT 错误，确保应用的稳定性。

2. 确保状态信息的正确初始化：

   • 通过本地存储或数据库持久化状态，避免因状态未初始化导致的同步问题。

3. 优化存储机制：

   • 优先考虑使用数据库存储状态信息，以提升数据的可靠性和管理的便捷性。

4. 增加日志和监控：

   • 通过详细的日志记录，及时发现并解决潜在的问题，提升应用的可维护性。

5. 处理并发和时序问题：

   • 确保状态初始化完成后再进行更新处理，避免因并发导致的状态不一致。

通过以上方法，您可以有效地应对 Telegram4J 开发过程中常见的错误和警告，提升应用的稳定性和用户体验。