3、组件接口设计：输入输出规范、配置参数定义、错误处理接口

接口设计，说白了就是定规矩。

你想想看，一个Pipeline组件，别人拿来用，总得知道怎么往里塞数据、怎么把结果取出来、怎么调参数吧？我刚开始写组件那会儿，觉得功能实现就完事了，接口随便搞搞。结果呢？同事用我的组件，传参传错了，报错信息看不懂，跑来问我，我还得帮他查代码。嗯，从那以后，我深刻理解了——接口设计，是组件开发的第一张名片。

3.1 输入输出规范：数据怎么进，结果怎么出

每个组件，本质上就是个黑盒子。数据从左边进来，处理完从右边出去。这个进出通道，必须标准化。

输入规范，我一般遵循几个原则：

• 单一数据源：一个组件只接受一种主要数据类型。比如文本处理组件，就别同时接收图片路径。混着来，逻辑容易乱。
• 明确的格式声明：输入是字符串、JSON对象、还是文件流？必须在接口文档里写清楚。我在项目中遇到过，有人传了个Python的dict进来，但组件内部期望的是JSON字符串，结果直接报错。
• 可选参数与必填参数分离：必填的放前面，可选的放后面，用默认值兜底。

输出规范，同样重要：

• 输出格式统一：不管输入是什么，输出结构要稳定。比如统一返回一个包含 status、data、message 的字典。
• 避免副作用：组件执行完，别偷偷改全局变量或写临时文件。输出就是输出，干净利落。

3.2 配置参数定义：让组件变得灵活

一个写死的组件，基本没什么用。配置参数，就是组件的旋钮和开关。

我个人习惯把配置参数分成三类：

类型	说明	示例
运行参数	控制组件行为，比如阈值、模式选择	threshold: 0.5、mode: "strict"
路径参数	指定输入输出文件或目录的位置	input_path: "./data/in"
资源参数	控制内存、线程数等资源消耗	max_workers: 4

定义配置参数时，有几点要注意：

• 参数名要有语义：别用 p1、p2 这种。用 batch_size、enable_logging，一看就懂。
• 提供合理的默认值：让组件开箱即用。我曾经写过一个组件，默认线程数设成了CPU核心数，结果在服务器上直接跑满，把别人吓一跳。后来改成默认4，稳多了。
• 做参数校验：配置加载时，就检查参数是否合法。别等到运行时才报错，那会儿排查起来很痛苦。

3.3 错误处理接口：出了问题，别让用户猜

组件肯定会出错。文件找不到、格式不对、内存不够……关键是，出错时怎么告诉调用方？

我建议设计一套统一的错误处理接口：

• 返回错误码 + 错误信息：不要只返回 False 或 None。返回一个结构化的错误对象，包含错误码（比如 ERR_FILE_NOT_FOUND）和人类可读的描述。
• 区分可恢复错误和不可恢复错误：可恢复的（比如重试一次就能好），返回警告；不可恢复的（比如配置错误），直接抛出异常。
• 日志记录：组件内部用日志记录详细堆栈，但对外只返回精简信息。避免把内部实现细节暴露给用户。

# 错误处理接口示例
class ComponentError(Exception):
    def __init__(self, code, message):
        self.code = code
        self.message = message
        super().__init__(f"[{code}] {message}")

# 使用
def process(data):
    if not data:
        raise ComponentError("ERR_EMPTY_INPUT", "输入数据不能为空")
    # ... 处理逻辑

3.4 接口设计总览图

下面这张图，把组件接口设计的核心逻辑串起来了。你可以把它当作一个检查清单：

这张图里，组件被三个核心接口包围着。左边是输入规范，右边是输出规范，上面是配置参数，下面是错误处理。任何一个接口设计不到位，整个组件的可用性都会打折扣。

好了，关于组件接口设计，我就聊这么多。记住一句话：接口是给别人用的，不是给自己看的。多站在调用方的角度思考，你的组件才会受欢迎。