升级PAHO MQTT至v2：回调方法应添加在何处？

问题背景 #

我维护着一份他人编写的代码（此前我为它提供过Dockerfile），原作者已停止支持，现在需要将其升级到Paho MQTT v2版本。根据Paho官方文档，升级到v2版本必须添加mqtt.CallbackAPIVersion.VERSION1参数，我参考了相关问题有了初步修改思路，但由于并非Python专家，不确定回调方法的具体添加位置是否正确。

原代码 #

#===========================================================================
#
# Broker connection
#
#===========================================================================
from . import config
import paho.mqtt.client as mqtt

#===========================================================================
class Client( mqtt.Client ):
   """Logging client
   """
   def __init__( self, log=None ):
      mqtt.Client.__init__(mqtt.CallbackAPIVersion.VERSION1, self )
      self._logger = log
      # Restore callbacks overwritten by stupid mqtt library
      self.on_log = Client.on_log
      
   def on_log( self, userData, level, buf ):
      if self._logger:
         self._logger.log( level, buf )

#===========================================================================
def connect( configDir, log, client=None ):
   cfg = config.parse( configDir )

   if client is None:
      client = Client( log )

   if cfg.user:
      client.username_pw_set( cfg.user, cfg.password )

   if cfg.ca_certs:
      client.tls_set( cfg.ca_certs, cfg.certFile, cfg.keyFile )

   log.info( "Connecting to broker at %s:%d" % ( cfg.host, cfg.port ) )
   client.connect( cfg.host, cfg.port, cfg.keepAlive )

   return client

#===========================================================================

我的修改思路 #

我认为要适配v2客户端，需将Client类修改为如下代码，想确认这个思路是否正确：

class Client( mqtt.Client ):
   """Logging client
   """
   def __init__( self, log=None ):
      mqtt.Client.__init__(mqtt.CallbackAPIVersion.VERSION1, self )
      self._logger = log
      # Restore callbacks overwritten by stupid mqtt library
      self.on_log = Client.on_log
      
   def on_log( self, userData, level, buf ):
      if self._logger:
         self._logger.log( level, buf )

无效的AI生成代码 #

我曾询问ChatGPT，得到的代码并无帮助：

class Client(mqtt.Client):
    """Logging client"""
    def __init__(self, log=None):
        super().__init__(protocol=mqtt.MQTTv31, transport="tcp", clean_session=True, userdata=None,
                         protocol_version=mqtt.PROTOCOL_V31, callback=None)
        self._logger = log

    def on_log(self, userData, level, buf):
        if self._logger:
            self._logger.log(level, buf)

我还要求它“使用v2版本库重写代码”，得到如下内容，但不确定是否正确：

class Client(mqtt.Client):
    """Logging client"""
    def __init__(self, log=None):
        super().__init__(protocol=mqtt.MQTTv5)  # Specify MQTT version 5
        self._logger = log

    def on_log(self, userdata, level, buf):
        if self._logger:
            self._logger.log(level, buf)

正确的适配方案 #

你的核心思路是对的——通过传入CallbackAPIVersion.VERSION1来兼容旧版回调格式，但需要修正父类构造函数的参数顺序，否则会引发参数传递错误。

修正后的代码（两种写法均可） #

写法一：使用super()（推荐）

class Client(mqtt.Client):
    """Logging client"""
    def __init__(self, log=None):
        # 传入CallbackAPIVersion.VERSION1，兼容旧版回调格式
        super().__init__(mqtt.CallbackAPIVersion.VERSION1)
        self._logger = log
        # 恢复被MQTT库覆盖的on_log回调
        self.on_log = self.on_log
        
    def on_log(self, userdata, level, buf):
        if self._logger:
            self._logger.log(level, buf)

写法二：显式调用父类构造函数

class Client(mqtt.Client):
    """Logging client"""
    def __init__(self, log=None):
        # 注意参数顺序：self必须作为第一个参数传入父类__init__
        mqtt.Client.__init__(self, mqtt.CallbackAPIVersion.VERSION1)
        self._logger = log
        self.on_log = Client.on_log
        
    def on_log(self, userdata, level, buf):
        if self._logger:
            self._logger.log(level, buf)

关键说明 #

1. 参数顺序修正：你之前的代码中mqtt.Client.__init__(mqtt.CallbackAPIVersion.VERSION1, self )参数顺序错误，Python调用父类构造函数时，self必须是第一个参数，之后才是其他参数（这里是回调API版本）。
2. 回调兼容性：传入CallbackAPIVersion.VERSION1后，你的on_log回调函数参数格式（userdata, level, buf）完全符合v2版本对VERSION1回调的要求，不需要修改回调函数的参数结构。
3. 回调绑定：保留self.on_log = Client.on_log或self.on_log = self.on_log是为了确保自定义的回调方法被正确绑定，避免被Paho客户端默认的回调覆盖。

内容的提问来源于stack exchange，提问作者Evan R.