 

第一次写 Go 服务的时候，我特别自信。不就是调个支付接口吗？`http.Post` 一把梭，搞定。代码能跑，测试能过，上线也没出啥问题。我当时觉得，这有什么好纠结的。

直到三个月后，产品说：“我们要换一家支付服务商。”

那一刻我才发现，我的代码里，`http.Post` 散落在十几个文件里，每个地方都在拼 URL、设 Header、解析响应。换一家支付商意味着我要把这十几个地方全找出来，一个个改。而且因为每家 API 的请求格式、字段名、错误码都不一样，我几乎是在重写整个支付模块。

那是我第一次意识到：**调用外部 API 这件事，如果不在第一天把它设计好，后面一定会加倍还回来。**

后来我试过三种不同的写法。第一种很自然，但最后把自己写进了死胡同。第二种干净了一点，但抽象过了头。第三种——也是我现在唯一会用的方式——终于让我觉得“对了”。

下面我把这三种写法和它们的翻车时刻都讲一遍。

---

## 写法一：把 HTTP 逻辑包成一个结构体

这是大多数人本能会做的第一步。把调用同一家外部服务的逻辑集中到一个 struct 里，注入一个 `http.Client`，完事。

```go
type PaymentClient struct {
    baseURL    string
    apiKey     string
    httpClient *http.Client
}

func NewPaymentClient(baseURL, apiKey string) *PaymentClient {
    return &PaymentClient{
        baseURL:    baseURL,
        apiKey:     apiKey,
        httpClient: &http.Client{Timeout: 10 * time.Second},
    }
}

func (c *PaymentClient) Charge(ctx context.Context, orderID int, amount string) error {
    // 拼 URL、设 Header、发请求、解析响应
    // ... 大概 30 行代码
}
```

比直接 `http.Post` 好多了。HTTP 逻辑集中了，可以 mock 了，超时和 base URL 也能配置了。

**什么时候翻车？**

```go
type OrderService struct {
    orders  OrderRepo
    payment *PaymentClient  // 依赖的是具体类型
}
```

问题出在这里：`OrderService` 直接依赖了 `*PaymentClient`——一个具体类型，不是一个接口。写单元测试的时候，我想 mock 支付服务，但我没有办法把 `*PaymentClient` 替换成一个假实现。除非我改 `OrderService` 的签名，或者用一个笨重的 HTTP 测试服务器。

更麻烦的是，如果哪天我想换一家支付商，我不仅得写新的客户端，还得改 `OrderService` 的代码——但 `OrderService` 里压根没有业务逻辑变化，它只是“调用支付”而已。

---

## 写法二：给每个客户端定义一个接口

直觉告诉我：用接口啊！依赖接口，不依赖具体类型。

```go
type PaymentClient interface {
    Charge(ctx context.Context, orderID int, amount string) error
}

type OrderService struct {
    orders  OrderRepo
    payment PaymentClient  // 依赖接口，好多了
}
```

现在可以 mock 了，测试好写了，也可以换实现了。

**什么时候翻车？**

接口的定义放在了 `payment` 包里——也就是基础设施层。而 `OrderService` 在业务层，它import 了基础设施层的代码。

在整洁架构（Clean Architecture）里，依赖方向应该是**业务层 ← 基础设施层**，而不是反过来。业务层不应该知道“有个东西叫 PaymentClient”，它只应该知道“我需要处理一笔支付”。

如果你的业务层 import 了 `payment` 包，那哪天你想换支付商的时候，依然要改 `OrderService` 的 import 语句。接口确实解耦了实现，但没有解耦“支付这个概念本身”。

---

## 写法三：接口属于业务层，而不是基础设施层

这是真正解决问题的写法。它叫 **端口与适配器（Ports and Adapters）**。核心思想一句话：**接口定义在业务层，用业务语言命名，由基础设施层去实现它。**

```go
// domain/payment.go —— 业务层定义端口
type PaymentService interface {
    Pay(ctx context.Context, orderID int, amount decimal.Decimal) (string, error)
}
```

这里没有 `Charge`，没有 `Currency`，没有 `API Key`。只有业务语言：“支付这笔订单，返回一个参考号”。

```go
// infrastructure/stripe_adapter.go —— 基础设施层实现端口
type stripeAdapter struct {
    baseURL  string
    apiKey   string
    currency string
}

func (a *stripeAdapter) Pay(ctx context.Context, orderID int, amount decimal.Decimal) (string, error) {
    // Stripe 的 HTTP 调用、JSON 序列化、错误处理全在这里
    // 返回的就是业务层需要的参考号
}
```

现在 `OrderService` 长这样：

```go
type OrderService struct {
    orders  OrderRepo
    payment domain.PaymentService  // 依赖的是业务层的接口
}

func (s *OrderService) ConfirmOrder(ctx context.Context, orderID int) error {
    order, _ := s.orders.Find(ctx, orderID)
    ref, err := s.payment.Pay(ctx, orderID, order.Amount)
    if err != nil {
        return err
    }
    order.MarkPaid(ref)
    return s.orders.Update(ctx, order)
}
```

`OrderService` 不知道 Stripe 是什么，不知道 HTTP 是什么，不知道货币是什么。它只知道一件事：**“我需要调用支付服务来确认这笔订单。”**

换支付商的时候，我只需要写一个新的 adapter（比如 `midtrans_adapter.go`），然后在启动代码里把依赖注入换掉就行——`OrderService` 一行都不用改。

---

## 错误处理：别把 HTTP 状态码漏到业务层

很多人写着写着就容易把 HTTP 状态码往上抛。这是不对的。

业务层只关心“支付被拒了”、“支付服务挂了”、“支付成功了”这三件事。它不关心 402、503 还是 200。

```go
// 在 adapter 里做翻译
switch resp.StatusCode {
case 402, 422:
    return "", domain.ErrPaymentDeclined
case 503, 504:
    return "", domain.ErrPaymentProviderDown
case 200:
    // 继续解析
default:
    return "", fmt.Errorf("unexpected status: %d", resp.StatusCode)
}
```

业务层拿到的是 `domain.ErrPaymentDeclined`，而不是 `http.StatusPaymentRequired`。这样它才能做有意义的业务决策。

---

## 测试：终于不用搭 HTTP 服务器了

因为 `OrderService` 只依赖接口，测试的时候就很简单了：

```go
type mockPayment struct {
    payFunc func(orderID int, amount decimal.Decimal) (string, error)
}

func (m *mockPayment) Pay(ctx context.Context, orderID int, amount decimal.Decimal) (string, error) {
    return m.payFunc(orderID, amount)
}

func TestOrderService_PaymentFailed(t *testing.T) {
    svc := OrderService{
        payment: &mockPayment{
            payFunc: func(_, _) (string, error) {
                return "", domain.ErrPaymentDeclined
            },
        },
    }
    err := svc.ConfirmOrder(ctx, 123)
    if !errors.Is(err, domain.ErrPaymentDeclined) {
        t.Fatal("expected declined error")
    }
}
```

不需要启动一个假的 HTTP 服务器，不需要设置环境变量，不需要担心网络超时。纯粹的业务逻辑测试，跑得飞快。

---

## 总结

三种写法，三代进化：

| 写法 | 优点 | 痛点 |
|---|---|---|
| 封装成 struct | 逻辑集中，能配置 | 业务层依赖具体类型，换实现得改业务代码 |
| 接口放基础设施层 | 能 mock，解耦实现 | 业务层还是知道“支付客户端”的存在，依赖方向不对 |
| 接口放业务层 | 业务层干干净净，换实现不改业务代码 | 需要多想一步“接口应该属于谁” |

第三种写法最大的好处，不是“技术正确”，而是**让你在半年后换支付商的时候，不用在十几个文件里搜索 `http.Post`，然后挨个改。**

这种“不给自己留坑”的设计，才是一个 Go 服务能持续活下去的原因。

第一次写 Go 服务的时候，我特别自信。不就是调个支付接口吗？http.Post 一把梭，搞定。代码能跑，测试能过，上线也没出啥问题。我当时觉得，这有什么好纠结的。

Go 里调用外部 API 到底该怎么写？第三种方式真香。。

编程语言

后端

架构设计

用端口与适配器模式定义支付接口，业务层只依赖抽象不依赖具体实现，换支付商零改动，错误处理统一翻译领域错误，测试用mock无需HTTP服务器，避免散落http.Post代码带来的维护灾难。

HTTP服务器

测试服务

单元测试

代码解释

服务器

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Go 里调用外部 API 到底该怎么写？第三种方式真香。。-腾讯云开发者社区-腾讯云

Go 里调用外部 API 到底该怎么写？第三种方式真香。。

Go 里调用外部 API 到底该怎么写？第三种方式真香。。

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐