Python开发同时支持CLI运行与库调用的代码时，如何实现可插拔输出扩展？

整体采用统一接口约束 + 插件注册表的设计，既避免零散散函数带来的维护混乱，又同时兼顾CLI独立运行、第三方库调用两种场景，核心类代码完全不绑定具体输出逻辑，新增输出能力时无需修改现有核心代码。

调整后的项目目录结构 #

将零散的输出逻辑抽成独立的插件模块，和核心业务代码解耦：

main.py                  # CLI入口，仅负责参数解析和启动
ipdisco/
  __init__.py
  ipdisco.py             # 核心业务类，负责管理插件和调度
  handlers/              # 输出插件存放目录
    __init__.py
    base.py              # 统一接口规范，所有输出插件必须实现
    stdout.py             # 内置：默认标准输出
    json.py               # 内置：JSON格式输出
    csv.py                # 内置：CSV格式输出
    png.py                # 内置：PNG图片输出

核心模块实现 #

1. 定义统一输出接口（handlers/base.py） #

通过抽象基类约束所有输出插件的行为，避免裸函数调用出现的签名不兼容、参数缺失问题：

from abc import ABC, abstractmethod

class BaseOutputHandler(ABC):
    """所有输出插件必须遵循的统一接口"""
    name: str  # 插件唯一标识，用于CLI选择、库调用时索引插件

    @abstractmethod
    def process(self, data):
        """
        接收核心类传递的原始待处理数据，完成输出逻辑
        :param data: 核心类收集的业务数据
        """
        pass

2. 内置插件实现示例 #

以默认stdout输出、JSON输出为例，每个插件就是一个独立的文件，实现抽象基类的接口即可：

# handlers/stdout.py - 默认标准输出插件
from .base import BaseOutputHandler

class StdoutHandler(BaseOutputHandler):
    name = "stdout"
    def process(self, data):
        print(data)

# handlers/json.py - JSON格式输出插件
import json
from .base import BaseOutputHandler

class JsonHandler(BaseOutputHandler):
    name = "json"
    def process(self, data):
        print(json.dumps({"content": data}, ensure_ascii=False))

后续要新增CSV、PNG等输出能力，只需要在该目录下新增对应文件实现接口即可，无需修改其他现有代码。

3. 核心业务类实现（ipdisco/ipdisco.py） #

核心类内置插件注册表，提供对外的插件注册、调用能力，不硬编码具体输出逻辑：

from .handlers.base import BaseOutputHandler
from .handlers.stdout import StdoutHandler

class IPDisco:
    def __init__(self):
        self.test = "a string"
        # 插件注册表：key为插件名，value为插件实例
        self._handlers: dict[str, BaseOutputHandler] = {}
        # 自动注册默认的stdout插件
        self.register_handler(StdoutHandler())

    def register_handler(self, handler: BaseOutputHandler):
        """
        对外暴露的插件注册入口，内置插件、用户自定义插件都通过该方法注册
        自动校验插件是否符合接口规范，避免无效对象传入
        """
        if not isinstance(handler, BaseOutputHandler):
            raise TypeError(
                f"输出插件必须继承BaseOutputHandler基类，当前传入类型：{type(handler)}"
            )
        self._handlers[handler.name] = handler

    def generate_output(self, output_name: str = "stdout"):
        """
        按插件名调用对应输出逻辑
        :param output_name: 已注册的插件名称，默认使用stdout
        """
        if output_name not in self._handlers:
            available = "、".join(self._handlers.keys())
            raise ValueError(
                f"未找到名为{output_name}的输出插件，当前可用插件：{available}"
            )
        # 将业务数据传递给对应插件执行
        self._handlers[output_name].process(self.test)

两种场景的调用方式 #

1. 作为第三方库被其他Python应用调用 #

用户既可以直接调用内置插件，也可以自由注册自己的自定义输出逻辑，无需修改库源码：

import ipdisco
from ipdisco.handlers.base import BaseOutputHandler

# 用户自定义输出插件
class BeautyPrintHandler(BaseOutputHandler):
    name = "beauty_print"
    def process(self, data):
        print(f"Here is a beautiful string : {data}")

# 初始化核心类
disco = ipdisco.IPDisco()
# 注册自定义插件
disco.register_handler(BeautyPrintHandler())

# 默认stdout输出
disco.generate_output()  # 输出：a string
# 调用自定义插件输出
disco.generate_output("beauty_print")  
# 输出：Here is a beautiful string : a string

2. 作为CLI独立应用运行 #

main.py仅作为CLI入口，自动扫描所有内置插件，支持通过参数选择输出格式，无需在脚本层写零散的输出处理函数：

import argparse
import pkgutil
import importlib
import ipdisco
from ipdisco.handlers.base import BaseOutputHandler

# 自动扫描handlers目录下所有内置插件并注册
def load_builtin_handlers(disco_instance):
    for _, module_name, _ in pkgutil.iter_modules(ipdisco.handlers.__path__):
        # 跳过基类文件
        if module_name in ["base", "__init__"]:
            continue
        # 动态导入插件模块
        module = importlib.import_module(f"ipdisco.handlers.{module_name}")
        # 遍历模块内的类，自动识别符合接口的插件
        for _, obj in vars(module).items():
            if (
                isinstance(obj, type) 
                and issubclass(obj, BaseOutputHandler) 
                and obj != BaseOutputHandler
            ):
                disco_instance.register_handler(obj())

def main():
    # 初始化核心类
    disco = ipdisco.IPDisco()
    # 加载所有内置插件
    load_builtin_handlers(disco)

    # 解析CLI参数
    parser = argparse.ArgumentParser(description="IPDisco 命令行工具")
    available_handlers = list(disco._handlers.keys())
    parser.add_argument(
        "--output",
        default="stdout",
        choices=available_handlers,
        help=f"指定输出格式，可选值：{available_handlers}"
    )
    args = parser.parse_args()

    # 执行输出
    disco.generate_output(args.output)

if __name__ == "__main__":
    main()

CLI启动时可以直接指定输出格式，比如python main.py --output json即可切换为JSON输出，新增内置插件后CLI会自动识别新的可选值，无需修改main.py的逻辑。

方案的优势 #

• 完全解耦：核心业务代码不感知具体输出逻辑，新增输出能力仅需新增插件文件，不改动现有核心代码
• 强约束：抽象基类保证所有插件行为一致，避免裸函数调用出现的参数不兼容问题；相比直接传函数的设想，类插件形式更适合复杂输出场景（比如需要配置文件路径、图片分辨率、CSV分隔符等参数时），不会导致函数入参越来越混乱
• 复用性高：所有输出逻辑都是模块化的，不管是CLI入口还是第三方库调用，都可以复用同一套插件代码
• 可扩展：后续如果需要支持外部插件目录加载、插件自定义配置参数，只需在现有注册逻辑上扩展即可，无需重构整体架构

内容的提问来源于stack exchange，提问作者Rian