Go on 蛋蛋忧桑

Go 错误处理指北

Thu, 20 Nov 2025 18:52:06 +0800

直接跳转查看错误处理最佳实践。

参考文章

Go 错误处理指北：Error vs Exception vs ErrNo

Go 错误处理指北：pkg/errors 源码解读

Go 错误处理指北：如何优雅的处理错误？

回顾错误处理

Exception 派系

Exception 派系的错误处理机制有Java、Python、C#、JavaScript等主流的高级语言，他们错误处理的特点在于抛出异常、处理异常、异常兜底。

异常兜底的处理方式简化了代码编写，我们不需要在每一处函数调用处都对异常进行处理，下层函数在遇到错误时直接向上抛出即可。同样的，我们处理错误也只需要在最上层做一次异常处理即可。这里举一个Python代码的例子。

def a():
 ...

def b():
 ...

def c():
 ...

def main():
 try:
 a()
 b()
 c()
 except Exception as e:
 logging.error(e)
 else:
 print("success")
 finally:
 print("release resources")

这种方式极大的简化的错误编写，但是因为有异常兜底，开发者在写代码时就会更加随心所欲，程序会更加的不可控制。开发者会倾向于不将错误思考的那么细致，不再仔细思考什么情况会遇到什么错误。如果开发者滥用异常兜底（如 catch Exception 或 except Exception，把所有异常一网打尽，然后继续执行），原本用于表示严重问题的异常就被当成普通流程分支，导致真正的错误被悄悄吞掉。这样会隐藏失败、丢失错误的严重级别、让日志缺失、使程序在错误状态下继续运行，并让业务逻辑变得不可预测。

C错误处理

由于C语言只能返回一个返回值，所以说通常情况下，有三种方法进行错误处理：

返回值既表示结果也表示错误，比如 fopen 函数。我们用该函数来打开一个文件，其返回值 file 可能是 FILE* 表示文件描述符，也可能是 NULL 表示函数出错。所以我们需要通过 if (file == NULL) 来判断打开文件是否出错，如果出错，全局变量 errno 会被赋值，使用 perror 函数或者 strerror(errno) 可以读取错误码对应的错误描述信息。这样的返回值就具有二义性，会存在一些问题，比如说让人忘记错误检查。
返回值为错误，结果作为参数，用参数列表传递结果指针。例如int div(int a, int b, int *result)，div 函数还是单返回值，不过这个返回值只代表错误，返回 0 表示成功，返回 -1 表示失败。div 函数计算结果通过参数的形式，被存储在指针所指向的变量 int *result 中。但这种用参数接收计算结果的方式，语义不够清晰。
C 函数支持返回结构体指针，将错误和结果统一放在结构体。这种方式代码实现比较复杂，不过多赘述。

Go错误处理

得益于 Go 函数支持多返回值，所以 Go 就不再需要 errno 了。Go 定义了一个 error 类型，专门用来表示错误，使用 errors.New 可以轻松构建一个错误对象。

因此我们就有了 Go 中经典的错误处理：

if err != nil {
 return nil, err
}

我们将在之后的篇幅中讲Go错误处理的最佳实现。

一些错误处理思想

暂存错误状态（AND）

在使用 Builder 模式、链式调用或者 for 循环等场景下，暂存中间过程所出现的错误，有助于简化代码，使编写出的代码逻辑更加连贯。

例如以下代码：

// Get takes name of the pod, and returns the corresponding pod object, and an error if there is any.
func (c *pods) Get(ctx context.Context, name string, options metav1.GetOptions) (result *v1.Pod, err error) {
 result = &v1.Pod{}
 err = c.client.Get().
 Namespace(c.ns).
 Resource("pods").
 Name(name).
 VersionedParams(&options, scheme.ParameterCodec).
 Do(ctx).
 Into(result)
 return
}

// Namespace applies the namespace scope to a request (/[ns//])
func (r *Request) Namespace(namespace string) *Request {
 if r.err != nil {
 return r
 }
 if r.namespaceSet {
 r.err = fmt.Errorf("namespace already set to %q, cannot change to %q", r.namespace, namespace)
 return r
 }
 if msgs := IsValidPathSegmentName(namespace); len(msgs) != 0 {
 r.err = fmt.Errorf("invalid namespace %q: %v", namespace, msgs)
 return r
 }
 r.namespaceSet = true
 r.namespace = namespace
 return r
}

其中的*Request.Namespace 方法首先会通过 if r.err != nil 判断是否存在错误，如果存在则直接返回，不再继续执行。如果不存在错误，则接下来每次可能出现错误的调用，都会将错误信息暂存到 r.err 属性中。每个链上的函数都是这种执行逻辑，简化了调用过程出现错误的错误处理。

这种方式类似于AND逻辑，其中有一个err就中止执行，记录错误最后返回。

Try Sequence（OR）

刚刚我们提到的暂存错误状态适用于AND的逻辑，即一系列函数，其中有一个err就中止执行，记录错误最后返回。

我们也可能会遇到OR的逻辑，比如说我希望一系列函数，只要有一个成功就不报错，只有所有失败才报错，那这时我们会用Try Sequence来简化代码逻辑，如下所示。

func TryOr(funcs ...func() (string, error)) (string, error) {
 var errs []error

 for _, f := range funcs {
 v, err := f()
 if err == nil { // 有一个成功就直接返回
 return v, nil
 }
 errs = append(errs, err)
 }

 // 都失败：把错误合并返回
 //（取决于你自己，如果你只想返回最后一个错误，不用err list，只用err记录最后一个即可）
 return "", fmt.Errorf("all failed: %v", errs)
}

错误只应处理一次

虽然，不应该忽略你的错误，但错误也不应该被重复处理，你应该只处理一次错误。

处理错误意味着检查错误值并做出决定。也就是说，根据能否处理错误，我们实际上只有两种选择：

不能处理：直接向上传递错误，自身不对错误做任何假设，也就是 Opaque error。
可以处理：降级处理，并向上返回 nil，因为自己已经处理了错误，表示不再有错误了，上层不应该继续拿到这个错误。

记录日志也属于处理错误，如果每次错误传递时都记录日志，那么最终看到的日志将会有非常多的重复内容。

何时记录错误日志

记录日志其实是一个比较大的话题，并且存在一定争议。何时记录、记录什么以及如何更好的记录都是比较复杂的问题。更糟糕的是，对于不同项目，可能会有不同的答案。

所以，这里只提一种可能适用的记录日志准则。

其实核心还是一句话：错误只应处理一次。

只在调用函数的最上层记录一次错误日志，调用链中间遇到错误直接返回，不做任何处理（或附加当前调用处的错误信息后返回）。
如果遇到服务降级的情况（为了防止主要功能受影响，我们会临时关闭非核心功能或使用简化的替代方案），我们也可以记录日志，并返回 nil，不再继续向上报告当前错误。
最好将错误堆栈也记录到错误中，在记录错误日志时用 %+v 打印。

不要做冗余的错误检查

不要写出这种代码：

func Foo() error {
 err := Bar()
 if err != nil {
 return err
 }
 return nil
}

正确写法如下：

func Foo() error {
 return Bar()
}

我们无需编写这种代码：

func Bar() error {
 err := Foo()
 if err != nil {
 return errors.WithMessage(err, "bar")
 }
 return nil
}

可以直接去掉那冗余的错误检查：

func Bar() error {
 err := Foo()
 return errors.WithMessage(err, "bar")
}

这不对执行结果造成任何影响。

我们无需判断 err 是否为 nil，因为 pkg/errors 内部的方法帮我们做好了这项检查：

func WithMessage(err error, message string) error {
 if err == nil {
 return nil
 }
 return &withMessage{
 cause: err,
 msg: message,
 }
}

对于 errors.Wrap/errors.WithStack 同样如此。

错误处理最佳实践

这里给出一套错误处理的最佳实践。

package main

import (
	"fmt"
	"github.com/pkg/errors"
)

func C() error {
	return errors.New("root error") // 这里返回一个错误，其同时记录了错误消息和错误堆栈
	// return fmt.Errorf("root error") // 这里返回一个错误，但不包含堆栈信息
}

func B() error {
	if err := C(); err != nil {
		// return err // 直接返回错误，不做修改
		// return errors.Wrap(err, "error in B") // 这里可以选择包装错误，添加消息和堆栈信息
		return errors.WithMessage(err, "error in B") // 这里可以选择只添加消息
		// return errors.WithStack(err) // 这里可以选择只添加堆栈信息
	}
	return nil
}

func A() error {
	if err := B(); err != nil {
		// return err // 直接返回错误，不做修改
		// return errors.Wrap(err, "error in A") // 这里可以选择包装错误，添加消息和堆栈信息
		return errors.WithMessage(err, "error in A") // 这里可以选择只添加消息
		// return errors.WithStack(err) // 这里可以选择只添加堆栈信息
	}
	return nil
}

func main() {
	err := A()
	fmt.Printf("%+v\n", err) // %+v 会打印错误消息和错误堆栈，%v 、 %q 和 %s 只打印错误消息
}

在错误最底层时，使用errors.New，同时记录了错误消息和错误堆栈，方便排查问题。
在中间层时，使用errors.WithMessage包装或return err直接返回错误，避免堆栈信息过多干扰排查错误日志。
在最上层时，使用%+v打印，这样可以同时打印错误消息和错误堆栈，方便排查错误日志。

注，如果想采用格式化字符串作为错误消息，可将方法分别替换成：

errors.New → **errors.Errorf**
errors.Wrap → **errors.Wrapf**
errors.WithMessage → **errors.WithMessagef**

httpclient与hertzclient在处理Host header时的差别

Fri, 22 Aug 2025 16:41:32 +0800

本文中的Host header、request.header.host、req.Header[“Host”]都指的是请求头中的“Host”字段。

问题提出

在请求转发的过程中，需要从原请求中拿到一些信息来构造新的转发出去的请求，其中就有Host header的问题。一开始我使用的是httpclient，复制请求头的逻辑就是清除一些字段后直接全部复制过去（Host header不在清除范围内），此时程序正常运行。

c.Request.Header.VisitAll(func(key, value []byte) {
		req.Header.Add(string(key), string(value))
	})

当我将httpclient切换成hertzclient后，发现一模一样的复制请求头的逻辑遇到了404的错误。经过一番排查发现是httpclient和hertzclient两者对于request.header.host的处理方式不同。对于hertzclient来说，正确的方式应该是不复制请求头中的Host字段。

c.Request.Header.VisitAll(func(key, value []byte) {
		if string(key) != "Host" {	 // hertz框架中的client不会更改header.Host，所以不能用原来的Host
			req.Header.Add(string(key), string(value))
		}
	})

httpclient

httpclient请求最终发送的 Host header 并不是取自 req.Header[“Host”]，而是由 req.Host 字段决定，如果 req.Host 为空，则默认为 req.URL.Host。

所以说虽然我一开始直接把原始的、错误的 Host header 复制了过去，但是httpclient对请求的 Host header 进行了替换，没有用我设置的 Host header ，所以并没有出现问题。

hertzclient

hertzclient最后发送的 Host header 就是取自 req.Header[“Host”] 的，所以说当我将原来的 request.header.host 写到新请求中后，hertzclient发送请求直接使用的是我设置的 Host header ，所以出现404的问题。

如果说依然使用完整复制的方法，在最后需要用req.Header.SetHost()替换原始的、错误的 Host header 。注意不是req.SetHost()，这个方法是设置建立连接的主机地址。

Host header作用

那话说回来，为什么使用错误的Host header会出现404的问题呢？Host header究竟是起到什么样的作用呢？

当一个网络请求发出去之后，网址会经过DNS解析为ip地址并建立连接，当连接到服务器后，则会用到 Host header 进行虚拟主机分流。

而虚拟主机（Virtual Host）是一种服务器技术，它允许在同一台物理服务器（同一个IP地址）上运行多个网站。换句话说，你可以用一台服务器托管多个不同域名的网站，而不需要每个网站都分配一个独立的服务器。区分用户到底访问的是哪个网站的方式就是使用 Host header 进行分流。

总体来说，一个请求的流程是：域名 → DNS 解析 → IP 地址 → 建立 TCP/SSL 连接 → 发送 HTTP 请求头 (Host) → 虚拟主机分流。

这里举一个Nginx配置规则进行分流的例子：

server {
 listen 80;
 server_name www.example.com;
 root /var/www/example;
}

server {
 listen 80;
 server_name www.test.com;
 root /var/www/test;
}

listen 80; → 表示监听 HTTP 默认端口 80。
server_name → 表示这个虚拟主机匹配的域名。
root → 表示网站的根目录，也就是请求 / 时返回的文件位置。

Nginx 的分流步骤可以总结为：

根据端口匹配 server 块

这里两个 server 都监听 80，所以都在候选列表中。

根据 Host 匹配 server_name

Nginx 会查找与请求 Host 最匹配的 server 块。

匹配成功 → 使用该 server 块的 root 和配置处理请求
没有匹配 → 使用默认 server

Nginx 会选择 listen 指令中第一个或 default_server 标记的 server 作为默认返回。

apollo配置实时生效：监听器与channel实现

Wed, 20 Aug 2025 17:04:14 +0800

问题提出

Apollo 是携程开源的分布式配置管理中心，用于统一管理和动态更新应用配置，支持多环境、多命名空间、高可用部署，应用通过客户端 SDK 实现实时拉取和热刷新配置，无需重启即可生效，广泛应用于微服务架构中。本文主要就是探讨两种实现热刷新配置的方法：监听器与channel实现。两者主要的区别是：可以把监听器理解为“事件推送”，channel 理解为“事件拉取”

监听器

监听器的方式就是在主函数中注册监听器，apollo配置改变时通知调用监听器，执行是同步还是异步自行斟酌。

// 监听器类型，接收 key 和 change
type ConfigChangeListener func(key string, change *agollo.Change)

// 全局监听器
type ListenerManager struct {
	listenersMu sync.RWMutex
	listeners []ConfigChangeListener
}

var globalListenerManager = &ListenerManager{}

// 注册监听器
func RegisterListener(listener ConfigChangeListener) {
 globalListenerManager.listenersMu.Lock()
 defer globalListenerManager.listenersMu.Unlock()
 globalListenerManager.listeners = append(globalListenerManager.listeners, listener)
}

// 通知监听器
func notifyListeners(key string, change *agollo.Change) {
 globalListenerManager.listenersMu.RLock()
 defer globalListenerManager.listenersMu.RUnlock()
 for _, listener := range globalListenerManager.listeners {
 // 调用每个监听器
 listener(key, change)
 }
}

// 注册配置变更监听器
apollo.RegisterListener(func(key string, change *agollo.Change) {
 if key == consts.HttpClientConfigKey {
			// 执行更新操作
 }
})

channel实现

用 channel 事件消费机制来实现，是将配置变化封装为事件发送到 channel，客户端通过读取 channel 主动获取并处理配置更新。

type ConfigChangeEvent struct {
 Key string
 Change agollo.ConfigChange
}

var configChangeChan = make(chan ConfigChangeEvent, 100)

// 将 evt 发送到 channel
evt := ConfigChangeEvent{
 Key: key,
 Change: change,
 }
configChangeChan <- evt

// 将 evt 从 channel 中取出
go func() {
 for evt := range configChangeChan {
 if evt.Key == consts.HttpClientConfigKey {
 // 执行更新操作
 }
 }
}()

在 Golang 中复用 HTTP 连接

Wed, 20 Aug 2025 16:31:52 +0800

问题提出

最近在实现一个转发大模型调用请求的中转功能，涉及到要构造client发送请求的内容，一开始我每次都是新建一个client来发送请求，这样的代码实现存在一些问题——每次都要构造新的client，并且要重新建立连接。后面了解到在Go中使用 HTTP 客户端（http.Client）可以实现连接复用，做到提高性能并减少 TCP 连接的重复建立。

// 原始做法
client := &http.Client{
		Timeout: consts.GetRequestTimeout(), // 设置请求超时时间
	}
	resp, err := client.Do(req)
defer resp.Body.Close()

// 修改后做法
resp, err := sharedHttpClient.Do(req)
defer resp.Body.Close()// 必须关闭 Body 才能复用连接

原理探寻

在 Go 中，HTTP 客户端默认会复用 TCP 连接，只要使用同一个 http.Client 实例，并且服务端支持 Keep-Alive。

原因是 http.Transport 内部维护了一个 连接池。只要满足以下条件就可以进行连接复用：

使用同一个 http.Client。
响应的 Body 被正确关闭。
请求的 Host 相同。

Transport 会根据空闲连接数和超时管理复用，可根据需求调整Transport相关的参数。

流式与非流式有什么区别

Wed, 20 Aug 2025 15:59:58 +0800

问题提出

最近在实现一个转发大模型调用请求的中转功能，因为现在的大模型都支持流式与非流式调用，所以我在实现的时候自然而然的想到了要不要区分两种调用方式，使用不同的代码逻辑。一开始写的时候分开了两个调用方式来写，后来发现这两种方式对于服务端来说实际没有区别，重点在于客户端的使用。

原理探寻

首先看一下两种调用方式实际返回的数据。

==== 非流式调用返回 ====
{
 "choices": [
 {
 "finish_reason": "stop",
 "index": 0,
 "logprobs": null,
 "message": {
 "content": "Hello! How can I help you today?",
 "reasoning_content": "用户现在打招呼说Hello!，我要友好回应。所以回复“Hello! How can I help you today?” 这样友好又开放，邀请用户说明需求。",
 "role": "assistant"
 }
 }
 ],
 "created": 1755675226,
 "id": "021755675225006530d45f3e18d6c5c13bff8621e54f4f6ee920a",
 "model": "doubao-1-5-thinking-vision-pro-250428",
 "service_tier": "default",
 "object": "chat.completion",
 "usage": {
 "completion_tokens": 45,
 "prompt_tokens": 70,
 "total_tokens": 115,
 "prompt_tokens_details": {
 "cached_tokens": 0
 },
 "completion_tokens_details": {
 "reasoning_tokens": 36
 }
 }
}

==== 流式调用返回 ====
data: {"choices":[{"delta":{"content":"","reasoning_content":"用户","role":"assistant"},"index":0}],"created":1755675226,"id":"021755675226374530d45f3e18d6c5c13bff8621e54f4f6ec4025","model":"doubao-1-5-thinking-vision-pro-250428","service_tier":"default","object":"chat.completion.chunk","usage":null}

data: {"choices":[{"delta":{"content":"","reasoning_content":"现在","role":"assistant"},"index":0}],"created":1755675226,"id":"021755675226374530d45f3e18d6c5c13bff8621e54f4f6ec4025","model":"doubao-1-5-thinking-vision-pro-250428","service_tier":"default","object":"chat.completion.chunk","usage":null}

...........

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":"stop","index":0}],"created":1755675226,"id":"021755675226374530d45f3e18d6c5c13bff8621e54f4f6ec4025","model":"doubao-1-5-thinking-vision-pro-250428","service_tier":"default","object":"chat.completion.chunk","usage":null}

data: [DONE]

可以看出，两种请求返回的格式是不一样的，非流式请求返回的是完整的json，而流式请求则是返回分块的json。

服务端

在服务端的实现中，实际上我们可以不用在意是流式还是非流式，我们可以统一采用流的方法返回请求体，是否真是流式形式实际上是取决于约定的返回格式以及客户端处理方式。

// 设置响应头
	for k, v := range resp.Header {
		for _, vv := range v {
			c.Header(k, vv)
		}
	}
	// 设置状态码
	c.Status(resp.StatusCode)

	// 流式转发响应体
	_, err = io.Copy(c.Response.BodyWriter(), resp.Body)
	if err != nil {
		// 处理错误
		hlog.CtxErrorf(ctx, "Error copying response body: %v", err)
		c.String(http.StatusInternalServerError, "Error copying response body: %v", err)
		return
	}

当然，由于我们此处是实现转发的功能，因此可以采用统一的方式。在原始的返回代码中，实际上会有些不同。

//----------非流式输出：传统请求处理----------//
app.get('/api/user-data', (req, res) => {
 // 同步获取所有数据（可能造成阻塞）
 const userData = fetchUserDataFromDB();
 const analytics = generateUserAnalytics(userData);
 const preferences = getUserPreferences(userData.id);
 
 // 一次性返回完整JSON
 res.json({ 
 userData, 
 analytics,
 preferences
 });
});

//----------流式输出：实时数据分块传输----------//
app.get('/api/real-time-updates', (req, res) => {
 // 1. 设置流式响应头
 res.setHeader('Content-Type', 'text/event-stream');
 res.setHeader('Cache-Control', 'no-cache');
 res.setHeader('Connection', 'keep-alive');
 
 // 2. 立即发送初始数据
 res.write('event: init\ndata: Connection established\n\n');
 
 // 3. 创建数据流
 const dataStream = createRealTimeDataStream();
 
 // 4. 分块发送数据
 dataStream.on('data', (chunk) => {
 res.write(`data: ${JSON.stringify(chunk)}\n\n`);
 });
 
 // 5. 处理连接关闭
 req.on('close', () => {
 dataStream.destroy();
 res.end();
 });
});

客户端

客户端的处理方式就是有明显分别了。

//----------非流式输出：传统请求处理（传统Fetch API使用）----------//
async function loadUserData() {
 try {
 const response = await fetch('/api/user-data');
 const fullData = await response.json();
 
 // 一次性渲染所有数据
 renderUserProfile(fullData.userData);
 renderAnalytics(fullData.analytics);
 updatePreferencesUI(fullData.preferences);
 
 } catch (error) {
 showErrorToast('Failed to load data');
 }
}

//----------流式输出：实时数据处理技术（使用EventSource）----------//
const eventSource = new EventSource('/api/real-time-updates');

eventSource.addEventListener('init', (event) => {
 showConnectionStatus('Connected to real-time feed');
});

eventSource.onmessage = (event) => {
 const data = JSON.parse(event.data);
 updateLiveDashboard(data);
};

eventSource.onerror = () => {
 showConnectionStatus('Connection lost - attempting to reconnect...');
 eventSource.close();
};

参考资料

流式输出 vs 非流式输出 - 技术栈