Python 封装通用 API 客户端实践

**

在 Python 项目中，对接外部接口几乎是常态。无论是行情数据、统计服务，还是内部微服务通信，如果请求逻辑分散在各个业务模块中，随着系统规模扩大，维护成本会明显上升。因此，我通常会在项目早期就封装一个统一的 API Client，用来集中处理超时、异常、日志和重试逻辑。

一、基础客户端结构设计

一个简单的客户端可以基于 requests 封装：

import requests
import time

class ApiClient:
    def __init__(self, base_url, timeout=5):
        self.base_url = base_url
        self.session = requests.Session()
        self.timeout = timeout

    def request(self, method, path, **kwargs):
        url = self.base_url + path
        response = self.session.request(
            method,
            url,
            timeout=self.timeout,
            **kwargs
        )
        response.raise_for_status()
        return response.json()

使用 Session 可以复用连接，提高性能。

二、加入重试机制

在网络波动或对方接口偶发错误时，简单重试可以提升成功率：

def request_with_retry(self, method, path, retries=3, **kwargs):
    for i in range(retries):
        try:
            return self.request(method, path, **kwargs)
        except Exception as e:
            if i == retries - 1:
                raise
            time.sleep(2 ** i)

指数退避能避免短时间内频繁重试。

三、统一异常处理

不建议直接把 requests 的异常透传到业务层。可以定义统一异常：

class ApiError(Exception):
    pass

在捕获异常后转换为业务可识别的错误类型，使系统结构更清晰。

四、结合实际接口场景

在实际项目中，我对接过一些实时数据接口，请求频率较高，如果没有统一封装，容易出现：

• 某个模块忘记设置超时

• 某个接口没做状态码判断

• 错误日志分散

通过集中封装后，所有接口调用逻辑统一管理，后续维护和问题排查会轻松很多。

接口封装本质上是一种工程治理手段。当接口数量增长到几十甚至上百时，这种结构化方式的价值会越来越明显。

本作品采用《CC 协议》，转载必须注明作者和本文链接