os.OpenFile 追加写日志并保证并发关闭的实现方式

如果 Go 程序要把多条运行日志追加到同一个文件，关键不是只把文件打开成写模式，而是同时处理“写到末尾”和“什么时候允许关闭”两个边界。比较稳妥的单进程方案是：用 os.O_APPEND|os.O_CREATE|os.O_WRONLY 打开文件；每条日志整理成一次写入；再用一把 sync.Mutex 让写入和 Close 互斥。

官方资料入口：https://pkg.go.dev/os#OpenFile、https://pkg.go.dev/os#File、https://pkg.go.dev/sync#Mutex。

本文的封装适合一个 Go 进程内由多个 goroutine 共享一个日志文件的场景。O_APPEND 解决追加定位，互斥锁解决写入与关闭的生命周期；它不是跨进程日志聚合器，也不替代日志轮转。

先把追加语义写对：O_APPEND 不是 O_TRUNC

os.OpenFile 的参数决定了文件对象的基本行为。O_APPEND 表示写入时追加到文件末尾，O_CREATE 只在文件不存在时创建，O_WRONLY 表示只写。追加日志时不要混入 O_TRUNC，否则打开文件就会清空已有内容。

package main

import "os"

func openLog(path string) (*os.File, error) {
	// 追加写：保留旧内容；文件不存在时创建；当前句柄只负责写入。
	return os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
}

权限参数只在创建文件时参与初始权限计算，还会受到系统 umask 影响。打开成功后，调用方仍然要负责关闭文件，并处理写入和关闭返回的错误。

把一条日志组装成一次 Write

并发写日志时，建议先在内存中把时间、级别和消息拼成完整记录，再交给文件执行一次 Write。这样应用层的互斥边界更清楚，也能集中处理“只写入了一部分”的异常。下面的封装把换行补齐，并显式检查短写。

package main

import (
	"errors"
	"io"
	"os"
	"strings"
	"sync"
)

var errLogClosed = errors.New("log writer is closed")

type LogWriter struct {
	mu      sync.Mutex
	file    *os.File
	closed  bool
	closeErr error
}

func NewLogWriter(path string) (*LogWriter, error) {
	// 只在构造阶段打开文件，后续 goroutine 共享同一个句柄。
	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
	if err != nil {
		return nil, err
	}
	return &LogWriter{file: f}, nil
}

func (w *LogWriter) WriteLine(line string) error {
	w.mu.Lock()
	defer w.mu.Unlock()

	// 关闭后拒绝新写入，避免把错误交给已经失效的文件句柄。
	if w.closed {
		return errLogClosed
	}
	if !strings.HasSuffix(line, "\n") {
		line += "\n"
	}

	// 一次写入一条完整记录，并区分短写和普通 I/O 错误。
	n, err := w.file.Write([]byte(line))
	if err != nil {
		return err
	}
	if n != len(line) {
		return io.ErrShortWrite
	}
	return nil
}

用同一把锁管理写入和关闭

官方文档说明 *os.File 的方法可以并发使用，但这不等于业务层可以任意让一个 goroutine 写、另一个 goroutine 同时关闭。Close 会让文件不可再用于 I/O，正在进行的 I/O 也可能返回关闭错误。因此，封装层需要把“检查状态、执行写入”和“设置关闭状态、执行关闭”放进同一把锁。

func (w *LogWriter) Close() error {
	w.mu.Lock()
	defer w.mu.Unlock()

	// 包装层保持幂等，后续 Close 返回第一次关闭的结果。
	if w.closed {
		return w.closeErr
	}
	w.closed = true
	// 记录底层 Close 错误，避免调用方错过落盘或句柄释放失败。
	w.closeErr = w.file.Close()
	return w.closeErr
}

这把锁提供了明确的生命周期边界：WriteLine 拿到锁时，文件仍可写；Close 拿到锁后先把 closed 置为真，之后的新写入直接返回错误。多个 goroutine 同时调用 Close 时，只有第一次会触碰底层文件，后续调用复用同一个结果。

和“直接共享 *os.File”相比，应该怎样选

如果业务还要求写入后尽快落到稳定存储，可以在明确的批次边界调用 Sync，但它会增加 I/O 成本；“追加到文件”与“已经持久化到物理介质”不是同一个保证。对于日志轮转，也不要在锁外直接替换底层 *os.File，应让打开、切换、关闭都遵循同一套生命周期协议。

常见问题

为什么已经使用 O_APPEND，还要加 Mutex？

O_APPEND 只描述文件写入时的追加定位，不负责你的 closed 状态，也不阻止一个 goroutine 在另一个 goroutine 关闭文件后继续调用写入方法。Mutex 保护的是应用对象的生命周期和记录边界。

Close 应该放在每个 goroutine 的 defer 里吗？

不应该。共享句柄由谁创建，就应由谁统一管理关闭；如果每个 goroutine 都 defer 一次 Close，会把“一个任务结束”误当成“整个日志对象不再使用”。更合适的做法是先停止新的日志生产，再等待已有调用返回，最后由拥有者调用一次 Close。

归纳起来，os.OpenFile 的追加标志解决“写到哪里”，完整记录和 Mutex 解决“谁能写、什么时候关”。把这三个问题分开，代码就不会把文件模式、并发安全和日志系统能力混为一谈。