Go-zero Archives - 原立方 https://www.atomic-cube.cn/tag/go-zero/ 技术栈的流动-从零到∞ Sat, 23 May 2026 07:53:49 +0000 zh-Hans hourly 1 https://wordpress.org/?v=7.0 Go深度指南：从基础到高级的全面解析 https://www.atomic-cube.cn/go%e6%b7%b1%e5%ba%a6%e6%8c%87%e5%8d%97%ef%bc%9a%e4%bb%8e%e5%9f%ba%e7%a1%80%e5%88%b0%e9%ab%98%e7%ba%a7%e7%9a%84%e5%85%a8%e9%9d%a2%e8%a7%a3%e6%9e%90/ https://www.atomic-cube.cn/go%e6%b7%b1%e5%ba%a6%e6%8c%87%e5%8d%97%ef%bc%9a%e4%bb%8e%e5%9f%ba%e7%a1%80%e5%88%b0%e9%ab%98%e7%ba%a7%e7%9a%84%e5%85%a8%e9%9d%a2%e8%a7%a3%e6%9e%90/#respond Sat, 23 May 2026 07:25:58 +0000 https://www.atomic-cube.cn/?p=2098 Go 语言自推出以来，因其简洁性、并发支持和高效性能，在云计算、微服务和分布式系统中广泛应用。作为开发者，面试 […]

The post Go深度指南：从基础到高级的全面解析 appeared first on 原立方.

]]> Go 语言自推出以来，因其简洁性、并发支持和高效性能，在云计算、微服务和分布式系统中广泛应用。作为开发者，面试时往往需要面对一系列技术问题，这些常被称为“八股文”的题目，虽然有时显得高级特性，力求每个解释都严谨实用，避免空话套话。让我们从最基础的部分开始。

第一章：基础概念与语法

变量与类型系统

Go 是静态类型语言，类型安全且编译时检查。变量声明使用 var 关键字，或短变量声明 :=。基础类型包括整型、浮点型、布尔型和字符串等。理解零值概念至关重要：未初始化的变量会赋予其类型的零值，例如整型为 0，字符串为空字符串””。

package main

import "fmt"

func main() {
    var a int      // 声明整型变量，零值为0
    b := 10        // 短变量声明，类型推断为int
    var s string   // 字符串零值为""
    fmt.Printf("a: %d, b: %d, s: %s\n", a, b, s) // 输出: a: 0, b: 10, s: 
}

类型转换必须是显式的，Go 不支持隐式类型转换。例如，将 int 转换为 float64 需要使用 float64(x)。这有助于避免意外错误。

控制结构

Go 的控制结构包括 if、for、switch 等，设计简洁。for 循环是唯一的循环结构，但可以模拟 while 循环。if 语句可以包含初始化语句，增强可读性。

package main

import "fmt"

func main() {
    // for循环示例
    for i := 0; i < 5; i++ {
        fmt.Println(i)
    }
    // 类似while循环
    j := 0
    for j < 3 {
        fmt.Println(j)
        j++
    }
    // if带初始化
    if x := 10; x > 5 {
        fmt.Println("x大于5")
    }
}

switch 语句在 Go 中更为灵活，case 表达式可以是常量、变量或函数调用，且默认不需要 break。

函数

函数是 Go 的一等公民，支持多返回值，这在错误处理中尤为常见。函数可以定义为方法，与类型关联。理解值传递和引用传递的区别很重要：Go 中所有参数都是值传递，但对于切片、映射和通道等引用类型，传递的是底层数据的引用。

package main

import "fmt"

// 多返回值函数
func divide(a, b int) (int, error) {
    if b == 0 {
        return 0, fmt.Errorf("除数不能为零")
    }
    return a / b, nil
}

func main() {
    result, err := divide(10, 2)
    if err != nil {
        fmt.Println("错误:", err)
    } else {
        fmt.Println("结果:", result) // 输出: 结果: 5
    }
}

第二章：并发编程核心

Go 的并发模型基于 goroutine 和 channel，是其最强大的特性之一。面试中常深入探讨这方面。

goroutine

goroutine 是轻量级线程，由 Go 运行时管理。使用 go 关键字启动，开销小，可轻松创建成千上万个。但需要注意，goroutine 的执行顺序不确定，依赖于调度器。

package main

import (
    "fmt"
    "time"
)

func sayHello(name string) {
    for i := 0; i < 3; i++ {
        fmt.Println("Hello,", name)
        time.Sleep(100 * time.Millisecond)
    }
}

func main() {
    go sayHello("Alice")  // 启动goroutine
    go sayHello("Bob")
    time.Sleep(1 * time.Second) // 等待goroutine完成，实际应用中应使用同步机制
}

channel

channel 是 goroutine 间的通信管道，可以传递数据并同步执行。分为有缓冲和无缓冲两种。无缓冲 channel 要求发送和接收同时就绪，否则会阻塞；有缓冲 channel 在缓冲区满或空时阻塞。

package main

import "fmt"

func main() {
    // 无缓冲channel
    ch := make(chan int)
    go func() {
        ch <- 42 // 发送数据
    }()
    value := <-ch // 接收数据
    fmt.Println("接收值:", value) // 输出: 接收值: 42

    // 有缓冲channel
    bufferedCh := make(chan string, 2)
    bufferedCh <- "hello"
    bufferedCh <- "world"
    fmt.Println(<-bufferedCh, <-bufferedCh) // 输出: hello world
}

同步原语

除了 channel，Go 的 sync 包提供了 Mutex、WaitGroup 等同步工具。在共享资源访问时，使用 Mutex 避免数据竞争。WaitGroup 用于等待一组 goroutine 完成。

package main

import (
    "fmt"
    "sync"
    "time"
)

var counter int
var mu sync.Mutex

func increment(wg *sync.WaitGroup) {
    defer wg.Done()
    mu.Lock()
    counter++
    mu.Unlock()
}

func main() {
    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go increment(&wg)
    }
    wg.Wait()
    fmt.Println("最终计数器值:", counter) // 应该输出1000
}

第三章：高级特性与设计模式

接口与多态

Go 的接口是隐式实现的：类型只需实现接口所有方法，就自动满足该接口。这促进了松耦合设计。接口常用于定义行为，如 io.Reader 和 io.Writer。

package main

import "fmt"

// 定义接口
type Speaker interface {
    Speak() string
}

// 结构体实现接口
type Dog struct{}

func (d Dog) Speak() string {
    return "Woof!"
}

type Cat struct{}

func (c Cat) Speak() string {
    return "Meow!"
}

func makeSound(s Speaker) {
    fmt.Println(s.Speak())
}

func main() {
    dog := Dog{}
    cat := Cat{}
    makeSound(dog) // 输出: Woof!
    makeSound(cat) // 输出: Meow!
}

空接口 interface{} 可以表示任何类型，但使用时应谨慎，通常与类型断言结合。

错误处理

Go 的错误处理通过返回值实现，而非异常。标准库提供了 error 接口。建议使用 errors.New 或 fmt.Errorf 创建错误，并通过 if err != nil 检查。defer、panic 和 recover 用于处理异常情况，但 panic 应仅用于不可恢复错误。

package main

import (
    "errors"
    "fmt"
)

func process(value int) (int, error) {
    if value < 0 {
        return 0, errors.New("值不能为负")
    }
    return value * 2, nil
}

func safeProcess() {
    defer func() {
        if r := recover(); r != nil {
            fmt.Println("恢复panic:", r)
        }
    }()
    panic("测试panic")
}

func main() {
    result, err := process(5)
    if err != nil {
        fmt.Println("错误:", err)
    } else {
        fmt.Println("结果:", result) // 输出: 结果: 10
    }
    safeProcess() // 输出: 恢复panic: 测试panic
}

反射与元编程

反射通过 reflect 包实现，允许程序在运行时检查类型和值。尽管强大，但反射性能开销大，应仅在必要时使用，如序列化或通用函数中。

package main

import (
    "fmt"
    "reflect"
)

func inspectType(v interface{}) {
    t := reflect.TypeOf(v)
    fmt.Printf("类型: %v, 种类: %v\n", t, t.Kind())
}

func main() {
    var x int = 42
    inspectType(x) // 输出: 类型: int, 种类: int
    inspectType("hello") // 输出: 类型: string, 种类: string
}

第四章：内存管理与性能优化

指针与值语义

Go 有指针，但不像 C 那样复杂。指针允许直接操作内存地址，常用于避免大结构体复制的开销。值语义和引用语义的选择依赖于场景：值语义更安全，引用语义更高效。

package main

import "fmt"

type Person struct {
    Name string
    Age  int
}

// 值接收者
func (p Person) String() string {
    return fmt.Sprintf("%s (%d岁)", p.Name, p.Age)
}

// 指针接收者，可修改结构体
func (p *Person) Birthday() {
    p.Age++
}

func main() {
    p1 := Person{"Alice", 30}
    p1.Birthday() // 即使p1是值，Go会自动取地址
    fmt.Println(p1.String()) // 输出: Alice (31岁)
}

垃圾回收

Go 使用并发标记清除垃圾回收器，自动管理内存。开发者无需手动释放内存，但应注意避免内存泄漏，如未关闭的资源或全局变量引用。通过 runtime 包可以监控 GC 行为。

性能调优

性能优化包括减少分配、使用 sync.Pool 重用对象、避免不必要的反射等。工具如 pprof 用于分析 CPU 和内存使用。

package main

import (
    "fmt"
    "sync"
)

var pool = sync.Pool{
    New: func() interface{} {
        return make([]byte, 1024)
    },
}

func main() {
    buf := pool.Get().([]byte)
    // 使用buf...
    fmt.Println("缓冲区长度:", len(buf))
    pool.Put(buf) // 放回池中以重用
}

第五章：标准库与实战问题

常用标准库

Go 标准库丰富，面试常问 net/http、encoding/json、testing 等。例如，HTTP 服务器实现简单：

package main

import (
    "fmt"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello, %s!", r.URL.Path[1:])
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

JSON 序列化和反序列化：

package main

import (
    "encoding/json"
    "fmt"
)

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    user := User{"Bob", 25}
    data, err := json.Marshal(user)
    if err != nil {
        fmt.Println("错误:", err)
        return
    }
    fmt.Println(string(data)) // 输出: {"name":"Bob","age":25}
    var newUser User
    json.Unmarshal(data, &newUser)
    fmt.Println(newUser) // 输出: {Bob 25}
}

常见面试题解析

面试中常出现的问题包括：goroutine 泄漏如何避免、channel 死锁场景、接口设计原则等。例如，goroutine 泄漏通常因未正确关闭 channel 或忽略错误导致，解决方案是使用 context 包进行取消。

package main

import (
    "context"
    "fmt"
    "time"
)

func worker(ctx context.Context, ch chan int) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("worker停止")
            return
        case val := <-ch:
            fmt.Println("处理值:", val)
        }
    }
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    ch := make(chan int)
    go worker(ctx, ch)
    ch <- 1
    time.Sleep(1 * time.Second)
    cancel() // 取消worker，避免泄漏
    time.Sleep(100 * time.Millisecond)
}

第六章：最佳实践与总结

在 Go 开发中，遵循最佳实践能提升代码质量：使用 go fmt 统一格式、编写单元测试、依赖管理使用 go mod、避免全局状态等。测试是 Go 文化的一部分，内置 testing 包支持表格驱动测试。

package main

import (
    "testing"
)

func Add(a, b int) int {
    return a + b
}

func TestAdd(t *testing.T) {
    tests := []struct {
        a, b, expected int
    }{
        {1, 2, 3},
        {0, 0, 0},
        {-1, 1, 0},
    }
    for _, tt := range tests {
        result := Add(tt.a, tt.b)
        if result != tt.expected {
            t.Errorf("Add(%d, %d) = %d; 期望 %d", tt.a, tt.b, result, tt.expected)
        }
    }
}

总结来说，Go 需要对语言特性的深刻理解。通过本文的梳理，我们希望读者能掌握从基础语法到并发模型、从接口设计到性能优化的核心点。实际编码中，多实践、多阅读优秀源码是提升的关键。持续学习才能应对不断变化的技术挑战。

The post Go深度指南：从基础到高级的全面解析 appeared first on 原立方.

]]> https://www.atomic-cube.cn/go%e6%b7%b1%e5%ba%a6%e6%8c%87%e5%8d%97%ef%bc%9a%e4%bb%8e%e5%9f%ba%e7%a1%80%e5%88%b0%e9%ab%98%e7%ba%a7%e7%9a%84%e5%85%a8%e9%9d%a2%e8%a7%a3%e6%9e%90/feed/ 0 Go 语言文件处理 https://www.atomic-cube.cn/go-%e8%af%ad%e8%a8%80%e6%96%87%e4%bb%b6%e5%a4%84%e7%90%86/ https://www.atomic-cube.cn/go-%e8%af%ad%e8%a8%80%e6%96%87%e4%bb%b6%e5%a4%84%e7%90%86/#respond Tue, 28 Apr 2026 23:37:11 +0000 https://www.atomic-cube.cn/?p=1952 文件处理是 Go 语言中最常见的操作之一——读取配置、写入日志、数据持久化都离不开它。Go 的标准库提供了一套简洁而强大的文件 I/O 接口，覆盖从单次读写到流式处理的各种场景

The post Go 语言文件处理 appeared first on 原立方.

]]> 文件处理是 Go 语言中最常见的操作之一——读取配置、写入日志、数据持久化都离不开它。Go 的标准库提供了一套简洁而强大的文件 I/O 接口，覆盖从单次读写到流式处理的各种场景。

与文件处理相关的核心包有 5 个，各有分工：

版本提示：ioutil 包在 Go 1.16 已弃用，其功能已迁移到 os（如 os.ReadFile、os.WriteFile）和 io（如 io.ReadAll）。新代码应直接使用 os 和 io 包。

1. 文件创建

os.Create 创建一个新文件。如果文件已存在，会被截断（清空内容）。返回的文件对象必须关闭以释放系统资源：

package main

import (
        "log"
        "os"
)

func main() {
        // os.Create 创建文件（已存在则清空）
        file, err := os.Create("test.txt")
        if err != nil {
                log.Fatal(err)
        }
        defer file.Close() // defer 确保函数结束时关闭文件

        // 写入内容验证创建成功
        file.WriteString("文件创建成功\n")
        log.Println("文件创建成功")
}

defer file.Close() 是 Go 文件操作的最佳实践。defer 会确保即使后续代码出现 panic，文件也会被正确关闭，避免文件描述符泄漏。

2. 文件打开与关闭

os 包提供三种打开文件的方式，适用于不同场景：

函数模式说明
os.Open(name)只读最简单的方式，只读打开
os.Create(name)读写 + 创建/截断创建新文件或清空已有文件
os.OpenFile(name, flag, perm)自定义可指定读写、追加、创建等标志
package main

import (
        "fmt"
        "os"
)

func main() {
        // 方式1：只读打开
        file, err := os.Open("example.txt")
        if err != nil {
                fmt.Println("打开失败:", err)
                return
        }
        defer file.Close()
        fmt.Println("文件打开成功")

        // 方式2：OpenFile 自定义模式
        // os.O_WRONLY  只写
        // os.O_CREATE  不存在则创建
        // os.O_APPEND  追加模式
        // os.O_TRUNC   存在则截断
        f, err := os.OpenFile("log.txt",
                os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0644)
        if err != nil {
                fmt.Println("打开失败:", err)
                return
        }
        defer f.Close()
        f.WriteString("追加一行日志\n")
}

OpenFile 标志位说明

标志说明
os.O_RDONLY只读（默认）
os.O_WRONLY只写
os.O_RDWR读写
os.O_APPEND追加模式，写入内容追加到文件末尾
os.O_CREATE文件不存在时创建
os.O_TRUNC打开时清空文件内容
os.O_EXCL与 CREATE 配合，文件已存在时报错

3. 文件读取

Go 提供了三种主要的文件读取方式，根据文件大小和处理需求选择：

3.1 一次性读取（小文件推荐）

os.ReadFile 是最简洁的方式——自动打开、读取、关闭文件，一步到位：

package main

import (
        "fmt"
        "log"
        "os"
)

func main() {
        // 一次性读取整个文件（Go 1.16+）
        data, err := os.ReadFile("config.json")
        if err != nil {
                log.Fatal(err)
        }

        fmt.Println(string(data))
}

3.2 逐行读取（大文件推荐）

对于大文件，使用 bufio.Scanner 逐行处理，避免一次性加载到内存：

package main

import (
        "bufio"
        "fmt"
        "log"
        "os"
)

func main() {
        file, err := os.Open("large-file.log")
        if err != nil {
                log.Fatal(err)
        }
        defer file.Close()

        // 逐行扫描
        scanner := bufio.NewScanner(file)
        lineNum := 0
        for scanner.Scan() {
                lineNum++
                line := scanner.Text() // 获取当前行内容
                fmt.Printf("第 %d 行: %s\n", lineNum, line)
        }

        // 检查扫描过程中是否出错
        if err := scanner.Err(); err != nil {
                log.Fatal("读取错误:", err)
        }
}

注意：bufio.Scanner 默认最大行长度为 64KB。如果文件中有超长行，需要在调用 Scan() 前设置 scanner.Buffer(make([]byte, 0), maxSize) 来增大缓冲区。

3.3 使用 io.ReadAll 读取

当你已经有一个打开的 io.Reader（如网络响应、已打开的文件），可以使用 io.ReadAll：

package main

import (
        "fmt"
        "io"
        "log"
        "os"
)

func main() {
        file, err := os.Open("example.txt")
        if err != nil {
                log.Fatal(err)
        }
        defer file.Close()

        // 从 Reader 读取所有数据
        data, err := io.ReadAll(file)
        if err != nil {
                log.Fatal(err)
        }

        fmt.Println(string(data))
}

4. 文件写入

Go 提供了多种写入方式，从简单的一次性写入到高性能的缓冲写入：

4.1 一次性写入

os.WriteFile 将数据一次性写入文件（覆盖原有内容）：

package main

import (
        "log"
        "os"
)

func main() {
        content := []byte("Hello, Go!\n这是第二行\n")

        // 0644: 所有者读写，其他用户只读
        err := os.WriteFile("output.txt", content, 0644)
        if err != nil {
                log.Fatal(err)
        }
        log.Println("写入成功")
}

4.2 使用 File 对象写入

通过文件对象写入，可以分多次写入内容：

package main

import (
        "fmt"
        "log"
        "os"
)

func main() {
        file, err := os.Create("output.txt")
        if err != nil {
                log.Fatal(err)
        }
        defer file.Close()

        // 方式1：写入字符串
        file.WriteString("直接写入字符串\n")

        // 方式2：写入字节切片
        data := []byte("写入字节切片\n")
        file.Write(data)

        // 方式3：格式化写入
        fmt.Fprintf(file, "格式化写入: %d + %d = %d\n", 3, 4, 7)
}

4.3 缓冲写入（大量数据推荐）

bufio.Writer 会先将数据写入内存缓冲区，攒够后再批量写入磁盘，显著减少 I/O 次数。务必在结束前调用 Flush()：

package main

import (
        "bufio"
        "log"
        "os"
)

func main() {
        file, err := os.Create("buffered-output.txt")
        if err != nil {
                log.Fatal(err)
        }
        defer file.Close()

        // 创建带缓冲的写入器
        writer := bufio.NewWriter(file)

        // 写入多行（先进入缓冲区，不会立即写磁盘）
        for i := 0; i < 1000; i++ {
                writer.WriteString("这是第 " + itoa(i) + " 行\n")
        }

        // Flush 将缓冲区剩余数据写入文件
        if err := writer.Flush(); err != nil {
                log.Fatal("刷新缓冲区失败:", err)
        }
        log.Println("缓冲写入完成")
}

// 简单的 int 转 string 辅助函数
func itoa(n int) string {
        return fmt.Sprintf("%d", n)
}

5. 文件追加写入

使用 os.O_APPEND 标志在文件末尾追加内容，而不覆盖已有数据：

package main

import (
        "log"
        "os"
        "time"
)

func main() {
        // O_APPEND: 追加模式
        // O_CREATE: 不存在则创建
        // O_WRONLY: 只写
        file, err := os.OpenFile("app.log",
                os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
        if err != nil {
                log.Fatal(err)
        }
        defer file.Close()

        // 每次运行都会追加，不会覆盖
        timestamp := time.Now().Format("2006-01-02 15:04:05")
        file.WriteString("[" + timestamp + "] 应用启动\n")
}

对比：os.Create 会清空已有内容；os.OpenFile 配合 O_APPEND 会追加内容。日志场景务必使用追加模式。

6. 文件删除与重命名

package main

import (
        "log"
        "os"
)

func main() {
        // 重命名 / 移动文件
        err := os.Rename("old.txt", "new.txt")
        if err != nil {
                log.Fatal("重命名失败:", err)
        }
        log.Println("重命名成功")

        // 删除文件
        err = os.Remove("temp.txt")
        if err != nil {
                log.Fatal("删除失败:", err)
        }
        log.Println("删除成功")
}

7. 文件信息与检查

7.1 获取文件信息

package main

import (
        "fmt"
        "log"
        "os"
)

func main() {
        info, err := os.Stat("test.txt")
        if err != nil {
                log.Fatal(err)
        }

        fmt.Println("文件名:    ", info.Name())
        fmt.Println("大小:      ", info.Size(), "字节")
        fmt.Println("权限:      ", info.Mode())
        fmt.Println("修改时间:  ", info.ModTime())
        fmt.Println("是目录吗:  ", info.IsDir())
}

7.2 检查文件是否存在

Go 没有专门的”文件存在”函数，通过 os.Stat + os.IsNotExist 判断：

package main

import (
        "fmt"
        "os"
)

// fileExists 检查文件是否存在
func fileExists(path string) bool {
        _, err := os.Stat(path)
        return !os.IsNotExist(err)
}

func main() {
        if fileExists("test.txt") {
                fmt.Println("文件存在")
        } else {
                fmt.Println("文件不存在")
        }
}

8. 目录操作

package main

import (
        "fmt"
        "log"
        "os"
)

func main() {
        // 创建单个目录
        err := os.Mkdir("newdir", 0755)
        if err != nil {
                log.Fatal(err)
        }

        // 递归创建多级目录（父目录不存在也会自动创建）
        err = os.MkdirAll("path/to/deep/dir", 0755)
        if err != nil {
                log.Fatal(err)
        }

        // 读取目录内容
        entries, err := os.ReadDir(".")
        if err != nil {
                log.Fatal(err)
        }
        for _, entry := range entries {
                mark := "📄"
                if entry.IsDir() {
                        mark = "📁"
                }
                fmt.Printf("%s %s\n", mark, entry.Name())
        }

        // 删除空目录
        os.Remove("newdir")

        // 递归删除目录及其所有内容（⚠ 谨慎使用）
        os.RemoveAll("path")
}

9. 高级操作

9.1 文件复制

使用 io.Copy 在两个文件之间高效复制数据：

package main

import (
        "io"
        "log"
        "os"
)

// copyFile 复制文件的通用函数
func copyFile(src, dst string) (int64, error) {
        srcFile, err := os.Open(src)
        if err != nil {
                return 0, err
        }
        defer srcFile.Close()

        dstFile, err := os.Create(dst)
        if err != nil {
                return 0, err
        }
        defer dstFile.Close()

        // io.Copy 自动管理缓冲区，高效复制
        return io.Copy(dstFile, srcFile)
}

func main() {
        n, err := copyFile("source.txt", "destination.txt")
        if err != nil {
                log.Fatal(err)
        }
        log.Printf("复制完成，共 %d 字节", n)
}

9.2 临时文件与目录

package main

import (
        "fmt"
        "log"
        "os"
)

func main() {
        // 创建临时文件（自动命名，前缀为 "app-"）
        tmpFile, err := os.CreateTemp("", "app-*.txt")
        if err != nil {
                log.Fatal(err)
        }
        defer os.Remove(tmpFile.Name()) // 用完后清理
        fmt.Println("临时文件:", tmpFile.Name())

        // 创建临时目录
        tmpDir, err := os.MkdirTemp("", "app-*")
        if err != nil {
                log.Fatal(err)
        }
        defer os.RemoveAll(tmpDir) // 用完后清理
        fmt.Println("临时目录:", tmpDir)
}

9.3 递归遍历目录

filepath.Walk 可以递归遍历目录树中的所有文件和子目录：

package main

import (
        "fmt"
        "log"
        "os"
        "path/filepath"
)

func main() {
        root := "." // 从当前目录开始遍历

        err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
                if err != nil {
                        return err // 遇到错误时可以选择跳过或返回
                }

                // 打印路径和大小
                size := ""
                if !info.IsDir() {
                        size = fmt.Sprintf(" (%d bytes)", info.Size())
                }
                fmt.Println(path + size)
                return nil
        })

        if err != nil {
                log.Fatal(err)
        }
}

9.4 跨平台路径拼接

永远不要用字符串拼接路径（如 dir + "/" + file），使用 filepath.Join 确保跨平台兼容：

// 错误：Windows 上路径分隔符是 \<br>path := "dir" + "/" + "file.txt"<br><br>// 正确：自动适配当前操作系统<br>path := filepath.Join("dir", "file.txt")<br><br>

场景速查表

场景推荐方式关键代码
读取小文件os.ReadFiledata, err := os.ReadFile("file.txt")
逐行读取大文件bufio.Scannerscanner := bufio.NewScanner(file)
写入小文件os.WriteFileos.WriteFile("f.txt", data, 0644)
大量数据写入bufio.Writerwriter := bufio.NewWriter(file)
追加日志os.OpenFile + O_APPENDos.OpenFile("log", os.O_APPEND|os.O_WRONLY, 0644)
文件复制io.Copyio.Copy(dst, src)
遍历目录filepath.Walkfilepath.Walk(".", callback)
路径拼接filepath.Joinfilepath.Join("dir", "file.txt")
检查文件存在os.Stat + os.IsNotExist_, err := os.Stat(path)
创建临时文件os.CreateTempos.CreateTemp("", "prefix-*.txt")

文件权限说明：0644 表示所有者可读写（6=4+2），组和其他用户只读（4）。目录通常使用 0755（多了执行权限，否则无法进入目录）。

The post Go 语言文件处理 appeared first on 原立方.

]]> https://www.atomic-cube.cn/go-%e8%af%ad%e8%a8%80%e6%96%87%e4%bb%b6%e5%a4%84%e7%90%86/feed/ 0 Go 文件和文件夹工具类：一个开箱即用的 fileutil 包v2 https://www.atomic-cube.cn/go-%e6%96%87%e4%bb%b6%e5%92%8c%e6%96%87%e4%bb%b6%e5%a4%b9%e5%b7%a5%e5%85%b7%e7%b1%bb%ef%bc%9a%e4%b8%80%e4%b8%aa%e5%bc%80%e7%ae%b1%e5%8d%b3%e7%94%a8%e7%9a%84-fileutil-%e5%8c%85v2/ https://www.atomic-cube.cn/go-%e6%96%87%e4%bb%b6%e5%92%8c%e6%96%87%e4%bb%b6%e5%a4%b9%e5%b7%a5%e5%85%b7%e7%b1%bb%ef%bc%9a%e4%b8%80%e4%b8%aa%e5%bc%80%e7%ae%b1%e5%8d%b3%e7%94%a8%e7%9a%84-fileutil-%e5%8c%85v2/#respond Mon, 20 Apr 2026 00:00:00 +0000 https://www.atomic-cube.cn/?p=1516 基于 Go 1.25 的新特性，我将之前的工具包进行了全面重构和升级。 新版主要引入了 os.Roo […]

The post Go 文件和文件夹工具类：一个开箱即用的 fileutil 包v2 appeared first on 原立方.

]]> 基于 Go 1.25 的新特性，我将之前的工具包进行了全面重构和升级。

Go 文件和文件夹工具类：一个开箱即用的 fileutil 包

新版主要引入了 os.Root 保障文件操作安全，使用迭代器和泛型提升代码的现代感与复用性，并整合了 testing/fstest 优化测试体验。

  • 安全升级：os.Root 防御路径穿越：使用 Go 1.24 引入的 os.Root 防范路径穿越攻击，安全地处理文件操作，同时也保留了不依赖此功能的传统方法。
  • 迭代器模式：利用 Go 1.23 引入的 iter.Seq，为 ListFiles 等方法设计了迭代器版本，实现内存友好的流式处理。
  • 泛型与类型安全：在迭代器和 BatchProcessor 中应用泛型，在编译时提供更强的类型安全保障。
  • 测试辅助：集成了 testing/fstest.MapFS，方便构建基于内存的模拟文件系统进行单元测试。
  • 结构化管理与并发：引入 FileUtil 结构体封装基础路径，统一管理操作上下文。BatchProcessor 结构体则用于对目录下的文件进行并发的批量处理。

一、新版 fileutil 包代码

// Package fileutil 提供基于 Go 1.24+ 新特性的文件/目录操作工具。
package fileutil

import (
	"context"
	"errors"
	"fmt"
	"io"
	"io/fs"
	"iter"
	"os"
	"path/filepath"
	"runtime"
	"strings"
	"sync"
)

// ============================================
// 1. 基础工具与常量
// ============================================

// Exists 判断路径是否存在。
func Exists(path string) bool {
	_, err := os.Stat(path)
	return !errors.Is(err, fs.ErrNotExist)
}

// IsDir 判断路径是否为目录。
func IsDir(path string) (bool, error) {
	info, err := os.Stat(path)
	if err != nil {
		return false, err
	}
	return info.IsDir(), nil
}

// IsFile 判断路径是否为普通文件。
func IsFile(path string) (bool, error) {
	info, err := os.Stat(path)
	if err != nil {
		return false, err
	}
	return !info.IsDir(), nil
}

// EnsureDir 确保目录存在，否则递归创建。
func EnsureDir(path string) error {
	if Exists(path) {
		isDir, err := IsDir(path)
		if err != nil {
			return err
		}
		if !isDir {
			return fmt.Errorf("path exists but is not a directory: %s", path)
		}
		return nil
	}
	return os.MkdirAll(path, 0755)
}

// ============================================
// 2. 核心结构：FileUtil (基于 os.Root)
// ============================================

// FileUtil 文件操作工具的核心结构体，封装了 os.Root。
type FileUtil struct {
	root *os.Root
	path string // 基础路径，用于日志或显示
}

// NewFileUtil 创建一个新的 FileUtil 实例。
// basePath 是所有后续操作受限的根目录。
func NewFileUtil(basePath string) (*FileUtil, error) {
	root, err := os.OpenRoot(basePath)
	if err != nil {
		return nil, fmt.Errorf("failed to open root %q: %w", basePath, err)
	}
	return &FileUtil{root: root, path: basePath}, nil
}

// Close 释放 FileUtil 持有的资源。
func (fu *FileUtil) Close() error {
	if fu.root != nil {
		return fu.root.Close()
	}
	return nil
}

// BasePath 返回 FileUtil 的根路径。
func (fu *FileUtil) BasePath() string {
	return fu.path
}

// ============================================
// 3. 安全的文件/目录操作 (使用 os.Root)
// ============================================

// SafeReadFile 安全地读取文件内容。
func (fu *FileUtil) SafeReadFile(relPath string) ([]byte, error) {
	return fu.root.ReadFile(relPath)
}

// SafeWriteFile 安全地将数据写入文件。
func (fu *FileUtil) SafeWriteFile(relPath string, data []byte, perm fs.FileMode) error {
	return fu.root.WriteFile(relPath, data, perm)
}

// SafeMkdirAll 安全地创建多级目录。
func (fu *FileUtil) SafeMkdirAll(relPath string, perm fs.FileMode) error {
	return fu.root.MkdirAll(relPath, perm)
}

// SafeRemove 安全地移除文件或空目录。
func (fu *FileUtil) SafeRemove(relPath string) error {
	return fu.root.Remove(relPath)
}

// ============================================
// 4. 传统文件/目录操作 (不使用 os.Root)
// ============================================

// CopyFile 复制文件从 src 到 dst。
func CopyFile(src, dst string) error {
	srcFile, err := os.Open(src)
	if err != nil {
		return fmt.Errorf("open source file: %w", err)
	}
	defer srcFile.Close()

	srcInfo, err := srcFile.Stat()
	if err != nil {
		return fmt.Errorf("stat source file: %w", err)
	}

	dstFile, err := os.Create(dst)
	if err != nil {
		return fmt.Errorf("create destination file: %w", err)
	}
	defer dstFile.Close()

	if _, err := io.Copy(dstFile, srcFile); err != nil {
		return fmt.Errorf("copy content: %w", err)
	}

	if err := dstFile.Sync(); err != nil {
		return fmt.Errorf("sync destination file: %w", err)
	}
	return os.Chmod(dst, srcInfo.Mode())
}

// MoveFile 移动文件。
func MoveFile(src, dst string) error {
	err := os.Rename(src, dst)
	if err == nil {
		return nil
	}
	// 跨文件系统降级处理
	if err := CopyFile(src, dst); err != nil {
		return fmt.Errorf("copy file during move: %w", err)
	}
	return os.Remove(src)
}

// CopyDir 递归复制整个目录。
func CopyDir(src, dst string) error {
	srcInfo, err := os.Stat(src)
	if err != nil {
		return fmt.Errorf("stat source directory: %w", err)
	}
	if !srcInfo.IsDir() {
		return fmt.Errorf("source is not a directory: %s", src)
	}

	if err := os.MkdirAll(dst, srcInfo.Mode()); err != nil {
		return fmt.Errorf("create destination directory: %w", err)
	}

	entries, err := os.ReadDir(src)
	if err != nil {
		return fmt.Errorf("read source directory: %w", err)
	}

	for _, entry := range entries {
		srcPath := filepath.Join(src, entry.Name())
		dstPath := filepath.Join(dst, entry.Name())
		if entry.IsDir() {
			if err := CopyDir(srcPath, dstPath); err != nil {
				return err
			}
		} else {
			if err := CopyFile(srcPath, dstPath); err != nil {
				return err
			}
		}
	}
	return nil
}

// DeleteDir 删除整个目录 (类似 rm -rf)。
func DeleteDir(path string) error {
	if !Exists(path) {
		return nil
	}
	return os.RemoveAll(path)
}

// ReadString 快速将文件内容读取为字符串。
func ReadString(path string) (string, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return "", err
	}
	return string(data), nil
}

// WriteString 快速将字符串写入文件。
func WriteString(path, content string) error {
	return os.WriteFile(path, []byte(content), 0644)
}

// ============================================
// 5. 迭代器与流式处理
// ============================================

// Lines 返回一个迭代器，用于逐行读取文件内容。
func Lines(path string) (iter.Seq[string], func() error) {
	file, err := os.Open(path)
	if err != nil {
		return func(yield func(string) bool) {
			return
		}, func() error { return err }
	}

	return func(yield func(string) bool) {
			defer file.Close()
			scanner := bufio.NewScanner(file)
			for scanner.Scan() {
				if !yield(scanner.Text()) {
					return
				}
			}
		}, func() error {
			defer file.Close()
			scanner := bufio.NewScanner(file)
			for scanner.Scan() {
				// 消耗迭代器以检查错误
			}
			return scanner.Err()
		}
}

// ListFilesIter 返回一个迭代器，流式地遍历目录下的文件。
func ListFilesIter(dir string, extensions []string) (iter.Seq[string], func() error) {
	var walkErr error
	seq := func(yield func(string) bool) {
		walkErr = filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
			if err != nil {
				return err
			}
			if d.IsDir() {
				return nil
			}
			if len(extensions) > 0 {
				ext := strings.ToLower(filepath.Ext(path))
				matched := false
				for _, e := range extensions {
					if strings.ToLower(e) == ext {
						matched = true
						break
					}
				}
				if !matched {
					return nil
				}
			}
			if !yield(path) {
				return filepath.SkipAll
			}
			return nil
		})
	}
	return seq, func() error { return walkErr }
}

// DirSize 计算目录总大小。
func DirSize(path string) (int64, error) {
	var size int64
	err := filepath.WalkDir(path, func(_ string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		if !d.IsDir() {
			info, err := d.Info()
			if err != nil {
				return err
			}
			size += info.Size()
		}
		return nil
	})
	return size, err
}

// ============================================
// 6. 原子写入与批量处理
// ============================================

// SafeWrite 原子性地将数据写入文件。
func SafeWrite(path string, data []byte, perm fs.FileMode) error {
	dir, filename := filepath.Split(path)
	tmpFile, err := os.CreateTemp(dir, ".tmp-*"+filename)
	if err != nil {
		return err
	}
	tmpName := tmpFile.Name()
	defer os.Remove(tmpName)

	if _, err := tmpFile.Write(data); err != nil {
		tmpFile.Close()
		return err
	}
	if err := tmpFile.Sync(); err != nil {
		tmpFile.Close()
		return err
	}
	if err := tmpFile.Close(); err != nil {
		return err
	}
	if err := os.Chmod(tmpName, perm); err != nil {
		return err
	}
	return os.Rename(tmpName, path)
}

// BatchProcessor 用于并发处理目录下的一系列文件。
type BatchProcessor[T any] struct {
	workers int
}

// NewBatchProcessor 创建一个新的批量处理器。
func NewBatchProcessor[T any](workers int) *BatchProcessor[T] {
	if workers <= 0 {
		workers = runtime.NumCPU()
	}
	return &BatchProcessor[T]{workers: workers}
}

// Process 对目录 dir 下匹配扩展名的所有文件，并发执行处理函数。
func (bp *BatchProcessor[T]) Process(ctx context.Context, dir string, extensions []string, handler func(string) (T, error)) ([]T, []error) {
	fileSeq, errFn := ListFilesIter(dir, extensions)
	var wg sync.WaitGroup
	fileCh := make(chan string)
	resultCh := make(chan T)
	errCh := make(chan error)

	// 启动 workers
	for i := 0; i < bp.workers; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for file := range fileCh {
				select {
				case <-ctx.Done():
					return
				default:
					if res, err := handler(file); err != nil {
						errCh <- fmt.Errorf("file %s: %w", file, err)
					} else {
						resultCh <- res
					}
				}
			}
		}()
	}

	// 发送文件路径
	go func() {
		for file := range fileSeq {
			select {
			case <-ctx.Done():
				break
			case fileCh <- file:
			}
		}
		close(fileCh)
	}()

	// 等待并收集结果
	go func() {
		wg.Wait()
		close(resultCh)
		close(errCh)
	}()

	var results []T
	var errs []error
	for {
		select {
		case res, ok := <-resultCh:
			if !ok {
				resultCh = nil
			} else {
				results = append(results, res)
			}
		case err, ok := <-errCh:
			if !ok {
				errCh = nil
			} else {
				errs = append(errs, err)
			}
		}
		if resultCh == nil && errCh == nil {
			break
		}
	}

	if walkErr := errFn(); walkErr != nil {
		errs = append(errs, fmt.Errorf("walk error: %w", walkErr))
	}

	return results, errs
}

// ============================================
// 7. 测试辅助 (testing/fstest)
// ============================================

// NewTestFS 创建一个用于测试的内存文件系统。
func NewTestFS() fstest.MapFS {
	return make(fstest.MapFS)
}

// AddTestFile 向测试文件系统添加一个文件。
func AddTestFile(fsys fstest.MapFS, path, content string) {
	fsys[path] = &fstest.MapFile{Data: []byte(content)}
}

二、使用示例

func main() {
	// 1. 使用 os.Root 进行安全操作
	fu, err := fileutil.NewFileUtil("./data")
	if err != nil {
		log.Fatal(err)
	}
	defer fu.Close()

	if err := fu.SafeMkdirAll("logs", 0755); err != nil {
		log.Fatal(err)
	}
	
	if err := fu.SafeWriteFile("config.json", []byte(`{"key": "value"}`), 0644); err != nil {
		log.Fatal(err)
	}
	
	data, err := fu.SafeReadFile("config.json")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(data))

	// 2. 使用迭代器逐行读取
	linesSeq, errFn := fileutil.Lines("./data/large.log")
	var count int
	for line := range linesSeq {
		_ = line
		count++
	}
	if err := errFn(); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Total lines: %d\n", count)

	// 3. 批量处理文件
	bp := fileutil.NewBatchProcessor[string](4)
	results, errs := bp.Process(context.Background(), "./data", []string{".log"}, func(path string) (string, error) {
		return fileutil.ReadString(path)
	})
	for _, err := range errs {
		log.Printf("Error: %v", err)
	}
	fmt.Printf("Processed %d files\n", len(results))
}

三、关键优化点详解

  1. os.Root：安全的文件操作基础
    通过 os.OpenRoot(basePath) 创建一个安全的根，后续所有操作（如 ReadFile）都会自动被限制在这个根目录内。这从根本上杜绝了路径穿越攻击，是处理来自用户输入的文件路径时最推荐的做法。
  2. 迭代器：内存友好的流式处理
    对于大文件或包含海量文件的目录，一次性加载所有内容可能导致内存溢出。迭代器模式允许你以流式方式逐行或逐个文件地处理数据，例如 Lines 函数逐行返回内容，内存占用极低。
  3. 泛型批处理器：复用并发处理逻辑
    BatchProcessor[T] 是一个通用的批处理器，它封装了并发遍历、处理文件并收集结果的复杂逻辑。你只需指定返回类型 T 和核心处理函数，而无需关心 goroutine 管理、channel 同步等细节。
  4. testing/fstest：轻量级单元测试
    传统的文件系统单元测试往往依赖真实文件，过程繁琐且易出错。testing/fstest 允许在内存中轻松构建一个模拟的文件系统，让测试变得快速、可靠且易于管理。

希望这个融合了 Go 新特性的工具包能让你的开发工作更高效、更安全。

The post Go 文件和文件夹工具类：一个开箱即用的 fileutil 包v2 appeared first on 原立方.

]]> https://www.atomic-cube.cn/go-%e6%96%87%e4%bb%b6%e5%92%8c%e6%96%87%e4%bb%b6%e5%a4%b9%e5%b7%a5%e5%85%b7%e7%b1%bb%ef%bc%9a%e4%b8%80%e4%b8%aa%e5%bc%80%e7%ae%b1%e5%8d%b3%e7%94%a8%e7%9a%84-fileutil-%e5%8c%85v2/feed/ 0  Go 开发经验总结：从入门到写出生产级代码 https://www.atomic-cube.cn/go-%e5%bc%80%e5%8f%91%e7%bb%8f%e9%aa%8c%e6%80%bb%e7%bb%93%ef%bc%9a%e4%bb%8e%e5%85%a5%e9%97%a8%e5%88%b0%e5%86%99%e5%87%ba%e7%94%9f%e4%ba%a7%e7%ba%a7%e4%bb%a3%e7%a0%81/ https://www.atomic-cube.cn/go-%e5%bc%80%e5%8f%91%e7%bb%8f%e9%aa%8c%e6%80%bb%e7%bb%93%ef%bc%9a%e4%bb%8e%e5%85%a5%e9%97%a8%e5%88%b0%e5%86%99%e5%87%ba%e7%94%9f%e4%ba%a7%e7%ba%a7%e4%bb%a3%e7%a0%81/#respond Sat, 18 Apr 2026 00:00:00 +0000 https://www.atomic-cube.cn/?p=1455 用 Go 语言写后端已经好多年了。从最初被 if err != nil 烦到不行，到现在能 […]

The post  Go 开发经验总结：从入门到写出生产级代码 appeared first on 原立方.

]]> 用 Go 语言写后端已经好多年了。从最初被 if err != nil 烦到不行，到现在能熟练应对各种并发场景和代码组织，踩过不少坑，也有一些心得。这篇文章把这些经验整理下来，希望能帮到正在用 Go 的朋友。每个主题都会配上可直接运行的代码示例，你可以边看边跑。

1. 错误处理：不止是 if err != nil

很多刚接触 Go 的人都会被满屏的 if err != nil 吓到。但真正的问题是，很多人只检查了错误，却没做好错误包装和分类。

1.1 用 %w 包装错误，保留上下文

Go 1.13 引入的错误包装功能非常实用。使用 fmt.Errorf 的 %w 动词，可以在每一层添加上下文信息，同时保留原始错误，方便上层用 errors.Is 和 errors.As 判断：

package main

import (
    "errors"
    "fmt"
)

// 定义业务错误常量
var ErrNotFound = errors.New("not found")

// 模拟底层操作
func fetchFromDB(id int) (string, error) {
    return "", ErrNotFound
}

// 中间层：包装错误，添加上下文
func getUser(id int) (string, error) {
    name, err := fetchFromDB(id)
    if err != nil {
        return "", fmt.Errorf("get user %d: %w", id, err)
    }
    return name, nil
}

func main() {
    _, err := getUser(42)
    if err != nil {
        // 使用 errors.Is 判断错误类型
        if errors.Is(err, ErrNotFound) {
            fmt.Printf("业务判断：用户不存在\n")
        }
        // 完整错误信息包含所有上下文
        fmt.Printf("完整错误：%v\n", err)
    }
}

输出：
业务判断：用户不存在
完整错误：get user 42: not found

这种包装方式让错误信息像堆栈一样层层递进，排查问题时会省很多时间。

1.2 只在不可恢复时使用 panic

Go 社区有共识：panic 只应在程序无法继续运行时使用，比如启动时依赖的配置加载失败。业务逻辑中应该用错误返回值，让调用方决定如何处理：

// ❌ 错误：滥用 panic
func readConfig() string {
    data, err := os.ReadFile("config.yaml")
    if err != nil {
        panic(err)  // 直接崩溃，调用方无法处理
    }
    return string(data)
}

// ✅ 正确：返回错误
func readConfig() (string, error) {
    data, err := os.ReadFile("config.yaml")
    if err != nil {
        return "", fmt.Errorf("read config: %w", err)
    }
    return string(data), nil
}

2. 并发编程：goroutine 的正确打开方式

2.1 用 Context 控制 goroutine 生命周期

在 HTTP 服务或长时间运行的任务中，用 context 来控制 goroutine 的启动和停止是最标准的做法：

Go 的并发模型很简洁，但用不好容易出 goroutine 泄漏、数据竞争等问题。

package main

import (
    "context"
    "fmt"
    "time"
)

func worker(ctx context.Context, id int) {
    for {
        select {
        case <-ctx.Done():
            fmt.Printf("worker %d 收到取消信号，退出\n", id)
            return
        default:
            fmt.Printf("worker %d 工作中...\n", id)
            time.Sleep(1 * time.Second)
        }
    }
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())

    // 启动 3 个 worker
    for i := 1; i <= 3; i++ {
        go worker(ctx, i)
    }

    // 5 秒后取消所有 worker
    time.Sleep(5 * time.Second)
    cancel()

    // 给 worker 一点时间退出
    time.Sleep(500 * time.Millisecond)
    fmt.Println("main 退出")
}

2.2 Channel + Actor 模型：通信共享内存，而非共享内存通信

Go 的哲学是“不要通过共享内存来通信，而要通过通信来共享内存”。把共享状态封装在一个 goroutine 内，通过 channel 传递操作指令，可以彻底避免数据竞争：

package main

import (
    "fmt"
    "time"
)

// Counter 将计数状态封装在独立的 goroutine 中
type Counter struct {
    ops chan func(*int) // 操作函数队列
}

func NewCounter() *Counter {
    c := &Counter{
        ops: make(chan func(*int)),
    }
    go c.loop()
    return c
}

func (c *Counter) loop() {
    var value int
    for op := range c.ops {
        op(&value)
    }
}

// Increment 增加计数
func (c *Counter) Increment() {
    done := make(chan struct{})
    c.ops <- func(v *int) {
        *v++
        close(done)
    }
    <-done // 等待操作完成
}

// Value 获取当前值
func (c *Counter) Value() int {
    done := make(chan int)
    c.ops <- func(v *int) {
        done <- *v
    }
    return <-done
}

func main() {
    counter := NewCounter()

    // 并发增加计数
    for i := 0; i < 100; i++ {
        go counter.Increment()
    }

    time.Sleep(100 * time.Millisecond)
    fmt.Printf("最终计数: %d\n", counter.Value())
}

这种模式本质上是 Actor 模型的 Go 实现，完全不用锁，代码也清晰易读。

2.3 Worker Pool 模式

当有大量任务需要并发处理时，用 worker pool 控制并发数可以避免资源耗尽：

package main

import (
    "fmt"
    "sync"
    "time"
)

func worker(id int, jobs <-chan int, results chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()
    for job := range jobs {
        fmt.Printf("worker %d 处理任务 %d\n", id, job)
        time.Sleep(500 * time.Millisecond) // 模拟耗时操作
        results <- job * 2
    }
}

func main() {
    const numJobs = 10
    const numWorkers = 3

    jobs := make(chan int, numJobs)
    results := make(chan int, numJobs)
    var wg sync.WaitGroup

    // 启动 worker 池
    for w := 1; w <= numWorkers; w++ {
        wg.Add(1)
        go worker(w, jobs, results, &wg)
    }

    // 发送任务
    for j := 1; j <= numJobs; j++ {
        jobs <- j
    }
    close(jobs)

    // 等待所有 worker 完成
    go func() {
        wg.Wait()
        close(results)
    }()

    // 收集结果
    for res := range results {
        fmt.Printf("结果: %d\n", res)
    }
}

3. 项目结构：告别代码混乱

随着项目变大，代码组织会成为头痛的问题。业界普遍参考 Standard Go Project Layout，但不必全盘照搬，可以按需取用。

推荐一个中小型项目的结构：

myproject/
├── cmd/
│   └── api/
│       └── main.go          # 应用入口，尽量精简
├── internal/
│   ├── handler/             # HTTP 处理器
│   │   └── user.go
│   ├── service/             # 业务逻辑
│   │   └── user.go
│   ├── repository/          # 数据访问
│   │   └── user.go
│   └── model/               # 数据模型
│       └── user.go
├── pkg/                     # 可被外部引用的公共库
│   └── utils/
├── go.mod
└── go.sum

要点：

  • cmd/ 下放 main.go，每个子目录对应一个可执行程序
  • internal/ 下的代码只有本项目能引用，Go 编译器会强制保证这一点
  • pkg/ 放可以被其他项目引用的公共代码
  • main 函数尽量简短，业务逻辑都放在 internal 中

internal/ 内部按功能分层是一个经典做法，但如果你偏好 Clean Architecture，也可以按领域组织：

internal/
├── user/           # 用户领域的所有代码
│   ├── delivery.go  # HTTP handler
│   ├── service.go   # 业务逻辑
│   └── repository.go # 数据层
└── order/          # 订单领域
    └── ...

选择哪种结构取决于团队习惯和项目规模，关键是保持一致。

4. Gin 框架：快速构建 Web 服务

Gin 是 Go 生态里使用最广泛的 Web 框架之一，性能好，中间件机制也很方便。

4.1 基础用法

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func main() {
    r := gin.Default()

    // 路由分组
    v1 := r.Group("/api/v1")
    {
        v1.GET("/ping", func(c *gin.Context) {
            c.JSON(http.StatusOK, gin.H{"message": "pong"})
        })

        v1.GET("/users/:id", func(c *gin.Context) {
            id := c.Param("id")
            c.JSON(http.StatusOK, User{ID: 1, Name: "张三"})
        })

        v1.POST("/users", func(c *gin.Context) {
            var user User
            if err := c.ShouldBindJSON(&user); err != nil {
                c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
                return
            }
            // 处理业务...
            c.JSON(http.StatusCreated, user)
        })
    }

    r.Run(":8080")
}

4.2 自定义中间件

中间件是 Gin 的精华，可以用它来做日志、鉴权、限流等：

package main

import (
    "log"
    "time"
    "github.com/gin-gonic/gin"
)

// 日志中间件：记录请求耗时和状态码
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        path := c.Request.URL.Path

        c.Next() // 执行后续处理器

        latency := time.Since(start)
        status := c.Writer.Status()

        log.Printf("[%s] %s %d %v", c.Request.Method, path, status, latency)
    }
}

// 鉴权中间件：简单 token 校验
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token != "Bearer secret-token" {
            c.JSON(401, gin.H{"error": "未授权"})
            c.Abort() // 中断请求链
            return
        }
        c.Next()
    }
}

func main() {
    r := gin.Default()

    // 全局中间件
    r.Use(LoggerMiddleware())

    // 需要鉴权的路由组
    authGroup := r.Group("/api")
    authGroup.Use(AuthMiddleware())
    {
        authGroup.GET("/profile", func(c *gin.Context) {
            c.JSON(200, gin.H{"user": "张三"})
        })
    }

    r.Run(":8080")
}

中间件执行顺序遵循“先进后出”：最后注册的中间件最先执行前置逻辑，最先执行后置逻辑。理解这个机制可以帮助你写出更灵活的中间件组合。

5. 常见坑点与最佳实践

5.1 nil 的判断陷阱

Go 中，接口类型的 nil 和具体类型的 nil 并不等价，这是最常见的坑之一：

package main

import "fmt"

type MyError struct{}

func (e *MyError) Error() string {
    return "my error"
}

func returnError() error {
    var err *MyError = nil
    return err // 返回的 error 接口不为 nil！
}

func main() {
    err := returnError()
    if err != nil {
        fmt.Printf("err 不为 nil: %v\n", err) // 这里会执行！
    }
}

解决方案：函数返回错误时，直接 return nil，而不是返回一个值为 nil 的变量。

5.2 循环变量捕获

在 for 循环中启动 goroutine 时，要注意闭包捕获的是同一个循环变量：

// ❌ 错误：所有 goroutine 都会打印最后一个值
for i := 0; i < 5; i++ {
    go func() {
        fmt.Println(i)
    }()
}

// ✅ 正确：通过参数传递当前值
for i := 0; i < 5; i++ {
    go func(n int) {
        fmt.Println(n)
    }(i)
}

5.3 依赖显式化，避免全局变量

日志、配置等依赖应该通过构造函数注入，而不是使用全局变量，这样代码更易于测试和维护：

// ❌ 依赖隐式全局
var logger = log.New(os.Stdout, "", log.LstdFlags)

type Service struct{}

func (s *Service) DoSomething() {
    logger.Println("doing something") // 无法替换 logger
}

// ✅ 依赖显式注入
type Service struct {
    logger *log.Logger
}

func NewService(logger *log.Logger) *Service {
    return &Service{logger: logger}
}

func (s *Service) DoSomething() {
    s.logger.Println("doing something") // 可控、可测
}

6. 开发效率工具

6.1 必备命令

几个几乎每天都会用到的命令：

# 格式化代码（必须，团队协作的底线）
gofmt -w .

# 静态检查，发现潜在 bug
go vet ./...

# 竞态检测，并发测试必开
go test -race ./...

# 整理依赖
go mod tidy

# 查看逃逸分析
go build -gcflags="-m"

6.2 用好 pprof 做性能分析

Go 自带的 pprof 是性能调优的利器：

package main

import (
    "log"
    "net/http"
    _ "net/http/pprof"
)

func main() {
    // 启动 pprof HTTP 服务
    go func() {
        log.Println(http.ListenAndServe("localhost:6060", nil))
    }()

    // 你的业务代码...
    select {}
}

运行后访问 http://localhost:6060/debug/pprof/ 就能看到 CPU、内存、goroutine 等各项指标。

总结

Go 语言的魅力在于简洁和务实。写 Go 多年，最大的感悟是：好的 Go 代码不是玩出花活，而是让读代码的人一眼能看懂、改起来不害怕。最后送大家一句话：Go 爱诚实的人，别藏着掖着，也别假装看不见错误。

The post  Go 开发经验总结：从入门到写出生产级代码 appeared first on 原立方.

]]> https://www.atomic-cube.cn/go-%e5%bc%80%e5%8f%91%e7%bb%8f%e9%aa%8c%e6%80%bb%e7%bb%93%ef%bc%9a%e4%bb%8e%e5%85%a5%e9%97%a8%e5%88%b0%e5%86%99%e5%87%ba%e7%94%9f%e4%ba%a7%e7%ba%a7%e4%bb%a3%e7%a0%81/feed/ 0 微服务全套docker-compose.yaml https://www.atomic-cube.cn/%e5%be%ae%e6%9c%8d%e5%8a%a1%e5%85%a8%e5%a5%97docker-compose-yaml/ https://www.atomic-cube.cn/%e5%be%ae%e6%9c%8d%e5%8a%a1%e5%85%a8%e5%a5%97docker-compose-yaml/#respond Fri, 17 Apr 2026 12:11:58 +0000 https://www.atomic-cube.cn/?p=1417 go-zero微服务开发，本地微服务开发环境

The post 微服务全套docker-compose.yaml appeared first on 原立方.

]]> 这份 docker-compose.yml 定义了一套完整的 go-zero 微服务开发环境，覆盖了服务发现、消息队列、数据存储、监控追踪、日志中心等核心基础设施。它让开发者无需在本地繁琐安装配置，即可快速启动一套微服务所需的所有中间件，专注于业务代码开发

该项目存在的意义，旨在于本地docker快速搭建微服务环境

github地址：https://github.com/EvansYe2/microservice-docker-compose-deploy

一、服务发现（etcd）

容器：etcd

  • 作用：etcd 是分布式键值存储，在 go-zero 中充当 服务注册与发现中心。每个微服务启动时将自己注册到 etcd，其他服务通过 etcd 获取对方地址，实现自动路由。
  • 配置：单节点模式，对外暴露 2379 端口供客户端（go-zero 服务）访问。
  • 协作：go-zero 服务通过 etcd 客户端连接 etcd:2379 完成注册与发现。

二、消息队列

1. Kafka 生态（Kafka + Zookeeper + Kafka-UI）

  • Zookeeper：Kafka 依赖 ZooKeeper 管理集群元数据、Broker 选举等。
  • Kafka：高吞吐量分布式消息队列，用于 异步解耦、削峰填谷、事件驱动。go-zero 中的异步任务（如发邮件、订单状态变更）可通过 Kafka 生产消费。
  • Kafka-UI：Web 管理界面，可查看 Topic、消息、消费者组状态，便于开发调试。
  • 协作：go-zero 服务作为生产者将消息投递到 Kafka，消费者从 Kafka 拉取处理；Kafka-UI 连接 Kafka 和 Zookeeper 提供可视化。

2. Beanstalkd 生态（Beanstalkd + Beanstalkd-Console）

  • Beanstalkd：轻量级 延迟队列，专门处理延时任务（如订单超时未支付自动取消）。
  • Beanstalkd-Console：Web 管理界面，查看队列、任务统计。
  • 协作：go-zero 服务可将延时任务投递到 Beanstalkd，消费者在指定时间后取出执行。

三、数据库与缓存

  • MySQL：关系型数据库，存储业务数据（用户、订单等）。
  • Redis：高性能内存数据库，用作 缓存、分布式锁、会话存储、计数器 等。
  • 协作：go-zero 服务通过 GORM 或原生 SQL 操作 MySQL，通过 go-redis 操作 Redis。

四、监控与可观测性

1. Prometheus + Grafana

  • Prometheus：时序数据库，从 go-zero 服务抓取指标（请求量、延迟、错误率），存储为时间序列数据。
    • 配置文件 prometheus.yml 和 targets.json 定义了抓取规则和目标（需列出具体服务端点）。
  • Grafana：可视化面板，连接 Prometheus 展示图表、仪表盘，便于分析系统状态。
  • 协作：go-zero 服务暴露 /metrics 端点，Prometheus 定期拉取；Grafana 读取 Prometheus 数据并展示。

2. Jaeger（链路追踪）

  • Jaeger：分布式链路追踪系统，跟踪一个请求在多个微服务间的完整调用链，帮助定位性能瓶颈和故障点。
  • 存储：将链路数据写入 Elasticsearch（通过 SPAN_STORAGE_TYPE=elasticsearch 配置）。
  • 协作：go-zero 服务通过 OpenTelemetry 或 Jaeger 客户端将 trace 数据发送到 Jaeger 收集器（端口 14250/14268），Jaeger UI（端口 16686）提供查询界面。

五、日志中心（ELK + Filebeat + go-stash）

日志流完整路径：

Docker 容器日志 → Filebeat → Kafka → go-stash → Elasticsearch → Kibana

1. Filebeat（日志采集）

  • 读取宿主机 Docker 容器日志（/var/lib/docker/containers/*/*.log），将日志发送到 Kafka 的 go-zero-logs Topic。
  • 配置文件 filebeat.yml 定义了输出目标（Kafka 地址、Topic 等）。

2. Kafka（日志缓冲）

  • 作为日志中转站，削峰填谷，确保日志不会因突发流量丢失。

3. go-stash（日志处理与写入）

  • 从 Kafka 消费日志，按照配置规则处理后写入 Elasticsearch。
  • 配置 config.yaml 中指定了 Kafka 和 Elasticsearch 地址、索引格式（如 go-zero-logs-2006.01.02）。

4. Elasticsearch（日志存储）

  • 分布式搜索引擎，存储日志数据，支持快速检索。

5. Kibana（日志可视化）

  • Elasticsearch 的 Web 界面，用于查询、分析、可视化日志。

协作总结

  • 所有微服务的日志（通过 stdout/stderr）被 Docker 捕获，Filebeat 采集后发往 Kafka；go-stash 消费并写入 ES；开发者通过 Kibana 统一查看、搜索日志。

六、整体协作关系图（数据流）

阶段组件说明
服务启动go-zero 服务 → etcd注册自己
业务调用go-zero 服务 → MySQL / Redis数据读写
异步任务go-zero 服务 → Kafka / Beanstalkd发送消息或延时任务
监控Prometheus → go-zero 服务拉取 /metrics
链路追踪go-zero 服务 → Jaeger发送 trace
日志Filebeat → Kafka → go-stash → Elasticsearch → Kibana采集、传输、存储、展示
version: '3.8'

networks:
  go-zero-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

volumes:
  etcd-data:
  mysql-data:
  redis-data:
  kafka-data:
  prometheus-data:
  grafana-data:
  jaeger-data:
  elasticsearch-data:
  go-stash:

services:
  # ==================== Service Discovery ====================
  etcd:
    image: quay.io/coreos/etcd:v3.5.10
    container_name: etcd
    restart: unless-stopped
    environment:
      - ETCD_NAME=etcd0
      - ETCD_DATA_DIR=/etcd-data
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
      - ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379
      - ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
      - ETCD_INITIAL_ADVERTISE_PEER_URLS=http://etcd:2380
      - ETCD_INITIAL_CLUSTER=etcd0=http://etcd:2380
      - ETCD_INITIAL_CLUSTER_TOKEN=etcd-cluster
      - ETCD_INITIAL_CLUSTER_STATE=new
    ports:
      - "2379:2379"
      - "2380:2380"
    volumes:
      - ./etcd-data:/etcd-data
    networks:
      - go-zero-network

  # ==================== Message Queue ====================
  #Kafka 依赖 ZooKeeper 来管理集群元数据、选举控制器等。它本身不参与业务消息，但却是 Kafka 正常工作的基础。
  zookeeper:
    image: zookeeper:3.9.5
    container_name: zookeeper
    restart: unless-stopped
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
      ZOO_MY_ID: 1
    ports:
      - "2181:2181"
    volumes:
      - ./zk-data:/var/lib/zookeeper/data
      - ./zk-datalog:/var/lib/zookeeper/log
    networks:
      - go-zero-network

  #Kafka 是一个高吞吐量分布式消息队列，用于 异步解耦、削峰填谷、事件驱动。go-zero 中的异步任务（如发送通知、订单处理）可以通过 Kafka 生产消费。
  kafka:
    image: apache/kafka:4.0.2
    container_name: kafka
    restart: unless-stopped
    depends_on:
      - zookeeper
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      # 外部访问监听端口为 9092，容器内部使用不同的端口 9094
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9094,CONTROLLER://localhost:9093,PLAINTEXT_CONTAINER://kafka:9092
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9094,PLAINTEXT_CONTAINER://kafka:9092
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_CONTAINER:PLAINTEXT
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_NUM_PARTITIONS: 3
    ports:
      - "9092:9092"  # 容器内部之间使用的监听端口
      - "9094:9094"  # 容器外部访问监听端口
    volumes:
      - ./kafka-data:/var/lib/kafka/data
    networks:
      - go-zero-network

  #Kafka 的可视化 Web 管理界面，用于查看主题、消息、消费者组状态，方便开发和调试。
  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    container_name: kafka-ui
    restart: unless-stopped
    depends_on:
      - kafka
    environment:
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
      KAFKA_CLUSTERS_0_ZOOKEEPER: zookeeper:2181
    ports:
      - "8080:8080"
    networks:
      - go-zero-network

  #Beanstalkd 是一个轻量级的 延迟队列，专门用于处理延时任务（如订单超时未支付自动取消）。
  beanstalkd:
    image: schickling/beanstalkd:latest
    container_name: beanstalkd
    restart: unless-stopped
    command: -l 0.0.0.0
    ports:
      - "11300:11300"
    networks:
      - go-zero-network

  #Beanstalkd 的 Web 管理界面，查看队列状态、任务统计等。
  beanstalkd-console:
    image: agaveapi/beanstalkd-console:latest
    container_name: beanstalkd-console
    restart: unless-stopped
    depends_on:
      - beanstalkd
    environment:
      BEANSTALKD_HOST: beanstalkd
      BEANSTALKD_PORT: 11300
    ports:
      - "8081:8080"
    networks:
      - go-zero-network

  # ==================== Database & Cache ====================
  mysql:
    image: mysql:8.0
    container_name: mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: 123456
      MYSQL_DATABASE: go_zero
      MYSQL_USER: go_zero
      MYSQL_PASSWORD: go_zero123
    ports:
      - "3306:3306"
    volumes:
      - ./mysql-data:/var/lib/mysql
    networks:
      - go-zero-network

  redis:
    image: redis:7.2-alpine
    container_name: redis
    restart: unless-stopped
    command: redis-server --requirepass 123456
    ports:
      - "6379:6379"
    volumes:
      - ./redis-data:/data
    networks:
      - go-zero-network

  

  # ==================== Monitoring & Observability 监控业务====================
  #时序数据库，从 go-zero 服务抓取指标（请求量、延迟、错误率等），并存储为时间序列数据。
  #挂载了 prometheus.yml（抓取规则）和 targets.json（服务发现目标）。
  #targets.json 中应列出需要监控的服务端点（如 user-api:9081）。
  prometheus:
    image: prom/prometheus:v2.48.0
    container_name: prometheus
    restart: unless-stopped
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./prometheus/targets.json:/etc/prometheus/targets.json:ro
      - ./prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.enable-lifecycle'
    ports:
      - "9090:9090"
    networks:
      - go-zero-network

  #prometheus 的 ui 很难看，用来显示 prometheus 收集来的数据，查看prometheus监控数据
  #可视化面板，从 Prometheus 读取数据并展示为图表、仪表盘。
  grafana:
    image: grafana/grafana:10.2.0
    container_name: grafana
    restart: unless-stopped
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_INSTALL_PLUGINS=grafana-piechart-panel
    volumes:
      - ./grafana-data:/var/lib/grafana
      - ./grafana/datasources:/etc/grafana/provisioning/datasources:ro
      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards:ro
    ports:
      - "3000:3000"
    networks:
      - go-zero-network

  #jaeger链路追踪 — Jaeger for tracing
  #分布式链路追踪系统，用于跟踪一个请求在多个微服务之间的完整调用链，定位性能瓶颈。
  #将链路数据存储在 Elasticsearch 中（SPAN_STORAGE_TYPE=elasticsearch）。
  jaeger:
    image: jaegertracing/all-in-one:1.53
    container_name: jaeger
    restart: unless-stopped
    environment:
      - COLLECTOR_OTLP_ENABLED=true
      - SPAN_STORAGE_TYPE=elasticsearch
      - ES_SERVER_URLS=http://elasticsearch:9200
    ports:
      - "5775:5775/udp"
      - "6831:6831/udp"
      - "6832:6832/udp"
      - "5778:5778"
      - "16686:16686"
      - "14268:14268"
      - "14250:14250"
      - "9411:9411"
    networks:
      - go-zero-network

  # ==================== Logging Stack ====================
  #存储收集的日志，分布式搜索引擎，用于存储和索引日志数据，支持快速检索。
  #Docker 容器日志 → Filebeat → Kafka → (go-stash/Logstash) → Elasticsearch → Kibana
  elasticsearch:
    image: elasticsearch:7.17.15
    container_name: elasticsearch
    restart: unless-stopped
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
      - xpack.security.enabled=false
    ports:
      - "9200:9200"
      - "9300:9300"
    volumes:
      - ./elasticsearch-data:/usr/share/elasticsearch/data
    networks:
      - go-zero-network

  #显示 elasticsearch日志，Elasticsearch 的可视化界面，用于查询、分析日志。
  kibana:
    image: kibana:7.17.15
    container_name: kibana
    restart: unless-stopped
    environment:
      ELASTICSEARCH_HOSTS: http://elasticsearch:9200
    ports:
      - "5601:5601"
    networks:
      - go-zero-network

  #消费kafka中filebeat收集的数据输出到es - The data output collected by FileBeat in Kafka is output to ES
  go-stash:
    image: kevinwan/go-stash:1.1.1
    container_name: go-stash
    environment:
      # 时区上海 - Time zone Shanghai (Change if needed)
      TZ: Asia/Shanghai
    restart: always
    volumes:
      - ./go-stash/etc:/app/etc
    networks:
      - go-zero-network
    depends_on:
      - elasticsearch
      - kafka


  #收集业务数据，收集日志到 kafka
  #轻量级日志采集器，读取 Docker 容器的日志（/var/lib/docker/containers/*/*.log），并将日志发送到 Kafka。
  #挂载了 filebeat.yml 定义输出目标（Kafka topic go-zero-logs）。
  #Docker 容器日志 → Filebeat → Kafka → (go-stash/Logstash) → Elasticsearch → Kibana
  filebeat:
    image: docker.elastic.co/beats/filebeat:7.17.15
    container_name: filebeat
    restart: unless-stopped
    user: root
    volumes:
      - ./filebeat/filebeat.yml:/usr/share/filebeat/filebeat.yml:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - go-zero-network

Prometheus 配置文件 (prometheus/prometheus.yml)

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'file_ds'
    file_sd_configs:
      - files:
          - /etc/prometheus/targets.json
        refresh_interval: 30s

Prometheus 服务发现目标 (prometheus/targets.json)

[
  {
    "targets": ["user-api:9081"],
    "labels": {
      "job": "user-api",
      "app": "user-api",
      "env": "test"
    }
  },
  {
    "targets": ["user-rpc:9091"],
    "labels": {
      "job": "user-rpc",
      "app": "user-rpc",
      "env": "test"
    }
  },
  {
    "targets": ["order-api:9082"],
    "labels": {
      "job": "order-api",
      "app": "order-api",
      "env": "test"
    }
  },
  {
    "targets": ["order-rpc:9092"],
    "labels": {
      "job": "order-rpc",
      "app": "order-rpc",
      "env": "test"
    }
  }
]

Grafana 数据源配置 (grafana/datasources/prometheus.yaml)

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true

Filebeat 配置文件 (filebeat/filebeat.yml)

filebeat.inputs:
  - type: container
    paths:
      - /var/lib/docker/containers/*/*.log

output.kafka:
  hosts: ["kafka:9092"]
  topic: "go-zero-logs"
  partition.round_robin:
    reachable_only: true

logging.level: info

go-stash/etc/config.yaml

Clusters:
  - Input:
      Kafka:
        Name: gostash
        Brokers:
          - kafka:9092
        Topics:
          - go-zero-logs
        Group: go-stash-group
        Consumer:
          Offset: first
    Output:
      ElasticSearch:
        Hosts:
          - http://elasticsearch:9200
        Index: go-zero-logs-{{yyyy-MM-dd}}
        # 可选：索引滚动策略等

Go-zero 服务配置示例 (config.yaml)

# 服务发现
Etcd:
  Hosts:
    - etcd:2379
  Key: user.rpc

# 链路追踪
Telemetry:
  Name: user-api
  Endpoint: http://jaeger:14268/api/traces
  Sampler: 1.0
  Batcher: jaeger

# Prometheus 监控
Prometheus:
  Host: 0.0.0.0
  Port: 9081
  Path: /metrics

# MySQL
DB:
  DataSource: root:123456@tcp(mysql:3306)/go_zero?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai

# Redis
Redis:
  Host: redis:6379
  Pass: 123456
  Type: node

# Kafka 配置
Kafka:
  Brokers:
    - kafka:9092
  GroupID: go-zero-group
  Topic: order-topic

# Beanstalkd 配置
Beanstalkd:
  Endpoint: beanstalkd:11300
  Tube: delay-tube
# 创建配置文件目录
mkdir -p prometheus grafana/datasources filebeat

# 将上述配置文件写入对应目录
# 启动所有容器
docker-compose up -d

验证服务状态
docker-compose ps

访问各服务 UI

服务地址说明
etcdhttp://localhost:2379服务注册发现（etcd API）
Kafka UIhttp://localhost:8080Kafka 管理界面
Beanstalkd Consolehttp://localhost:8081延迟队列管理界面
Redis Commanderhttp://localhost:8082Redis 管理界面
Prometheushttp://localhost:9090监控指标收集
Grafanahttp://localhost:3000监控可视化（admin/admin）从 Prometheus 读取数据并展示为图表、仪表盘。
Jaeger UIhttp://localhost:16686链路追踪查询
Kibanahttp://localhost:5601日志分析,查看es日志
MySQLlocalhost:3306数据库
Redislocalhost:6379缓存
etcd-keeperhttp://localhost:8080

访问 kibana http://127.0.0.1:5601/ ， 创建日志索引

点击左上角菜单(三个横线那个东东)，找到 Analytics – > 点击 discover

然后在当前页面，Create index pattern->输入 go-zero-logs-* -> Next Step ->选择 @timestamp->Create index pattern

然后点击左上角菜单，找到 Analytics->点击 discover ，日志都显示了 （如果不显示，就去排查 filebeat、go-stash，使用 docker logs -f filebeat 查看）

The post 微服务全套docker-compose.yaml appeared first on 原立方.

]]> https://www.atomic-cube.cn/%e5%be%ae%e6%9c%8d%e5%8a%a1%e5%85%a8%e5%a5%97docker-compose-yaml/feed/ 0 使用Go语言实现Redis分布式锁（附有看门狗自动续期机制） https://www.atomic-cube.cn/%e4%bd%bf%e7%94%a8go%e8%af%ad%e8%a8%80%e5%ae%9e%e7%8e%b0redis%e5%88%86%e5%b8%83%e5%bc%8f%e9%94%81%ef%bc%88%e9%99%84%e6%9c%89%e7%9c%8b%e9%97%a8%e7%8b%97%e8%87%aa%e5%8a%a8%e7%bb%ad%e6%9c%9f%e6%9c%ba/ https://www.atomic-cube.cn/%e4%bd%bf%e7%94%a8go%e8%af%ad%e8%a8%80%e5%ae%9e%e7%8e%b0redis%e5%88%86%e5%b8%83%e5%bc%8f%e9%94%81%ef%bc%88%e9%99%84%e6%9c%89%e7%9c%8b%e9%97%a8%e7%8b%97%e8%87%aa%e5%8a%a8%e7%bb%ad%e6%9c%9f%e6%9c%ba/#respond Thu, 26 Mar 2026 12:52:00 +0000 https://www.atomic-cube.cn/?p=1446 Redis我们日常开发经常使用，而分布式锁的一个重要实现就是通过Redis完成，分布式锁要解决的核心问题是防止 […]

The post 使用Go语言实现Redis分布式锁（附有看门狗自动续期机制） appeared first on 原立方.

]]> Redis我们日常开发经常使用，而分布式锁的一个重要实现就是通过Redis完成，分布式锁要解决的核心问题是防止对某个资源进行重复或者过度请求，例如我们在分布式系统中创建订单之前，必须获取分布式锁才能创建订单，其要解决的主要问题有两个：

1）如果用户重复点击提交订单按钮，可以通过分布式锁避免重复创建订单

2）商品库存有限，通过分布式锁能够解决超卖问题

Redis实现分布式锁

由于Redis中set nx命令的原子性，只有在键值不存在的时候才能设置值，因此可以通过set nx实现分布式锁，但是它有弊端就是：

如果业务还没有执行完，那么会导致业务没有执行完，锁就被释放了

因此延伸出了基于Redis延伸的Redisson分布式锁框架，它实现的原理在于使用Redis单线程模型执行SET NX命令lua脚本确保获取锁操作原子性，同时它内置了更为丰富的看门狗机制，满足了在业务执行过程中，自动续期锁

Go语言实现分布式锁

上面都是基于理论介绍，接下来就实现基于Redis的分布式锁

明确原子性操作

在实现之前，我们要明确加锁、释放锁与续期锁的机制：

加锁：设置键值与过期时间，通过setnx px实现，如果键值已经存在直接返回错误

释放锁：我们一定要确保释放的锁是自己加的锁，因此要判断value值是否是之前设置的value值，只有判断正确才能够释放锁

续期锁：与释放锁同理，只有当前锁是自己加的锁才续期

package utils

import (
	"context"
	"errors"
	"fmt"
	"sync"
	"time"

	"github.com/google/uuid"
	"github.com/redis/go-redis/v9"
)

// 预定义错误，便于调用方进行错误判断
var (
	// ErrLockNotHeld 释放锁时发现锁不属于当前实例
	ErrLockNotHeld = errors.New("lock not held")
	// ErrLockAcquireFailed 加锁失败（因已被他人持有或超时）
	ErrLockAcquireFailed = errors.New("failed to acquire lock")
	// ErrLockLost 锁在持有期间丢失（续期失败），此时业务应中断
	ErrLockLost = errors.New("lock lost during hold")
)

// Logger 可注入的日志接口，便于集成各类日志库
type Logger interface {
	Printf(format string, v ...interface{})
}

// defaultLogger 默认日志实现，输出到标准输出
type defaultLogger struct{}

func (l *defaultLogger) Printf(format string, v ...interface{}) {
	fmt.Printf(format+"\n", v...)
}

// RenewFailedCallback 续期失败时的回调函数，用于通知业务方锁已丢失
type RenewFailedCallback func(key string, err error)

// RetryStrategy 重试策略类型，用于自定义获取锁失败时的等待行为
type RetryStrategy func(attempt int) time.Duration

// Mutex 基于 Redis 的分布式锁，内置看门狗自动续期。
// 每个实例仅允许一次 Lock → Unlock 生命周期，不可复用。
type Mutex struct {
	client redis.UniversalClient // Redis 客户端，支持单机、哨兵、集群
	key    string                // Redis 中锁的键名
	value  string                // 锁持有者唯一标识（UUID）
	ttl    time.Duration         // 锁的过期时间

	// 状态保护
	mu     sync.Mutex
	locked bool   // 是否已成功加锁
	lost   bool   // 锁是否已丢失（续期失败导致），丢失后不应再尝试释放
	stopCh chan struct{} // 通知看门狗退出的通道
	wg     sync.WaitGroup

	// 看门狗启动保护
	watchdogOnce sync.Once // 确保看门狗只启动一次

	// 配置项
	retryStrategy     RetryStrategy      // 自定义重试策略
	minRenewInterval  time.Duration      // 最小续期间隔，防止高频续期
	renewTimeout      time.Duration      // 续期操作的超时时间
	logger            Logger             // 日志接口
	renewFailedCb     RenewFailedCallback // 续期失败回调
}

// Option 函数式配置选项
type Option func(*Mutex)

// WithRetryDelay 设置固定间隔的重试策略（简单场景）
func WithRetryDelay(d time.Duration) Option {
	return func(m *Mutex) {
		m.retryStrategy = func(attempt int) time.Duration {
			return d
		}
	}
}

// WithExponentialBackoff 设置指数退避重试策略
// 初始间隔为 initial，最大间隔为 max，每次重试间隔翻倍
func WithExponentialBackoff(initial, max time.Duration) Option {
	return func(m *Mutex) {
		m.retryStrategy = func(attempt int) time.Duration {
			d := initial
			for i := 0; i < attempt; i++ {
				d *= 2
				if d > max {
					return max
				}
			}
			return d
		}
	}
}

// WithMinRenewInterval 设置看门狗最小续期间隔，避免高频续期（默认 200ms）
func WithMinRenewInterval(d time.Duration) Option {
	return func(m *Mutex) {
		m.minRenewInterval = d
	}
}

// WithRenewTimeout 设置单次续期操作的超时时间（默认 2s）
func WithRenewTimeout(d time.Duration) Option {
	return func(m *Mutex) {
		m.renewTimeout = d
	}
}

// WithLogger 注入自定义日志实现
func WithLogger(l Logger) Option {
	return func(m *Mutex) {
		m.logger = l
	}
}

// WithRenewFailedCallback 设置续期失败回调
func WithRenewFailedCallback(cb RenewFailedCallback) Option {
	return func(m *Mutex) {
		m.renewFailedCb = cb
	}
}

// NewMutex 创建一个新的分布式锁实例
// client: Redis 客户端
// key: 锁的键名，建议使用业务唯一标识，如 "order:lock:123"
// ttl: 锁的过期时间，建议设置为业务处理时间的 2~3 倍
func NewMutex(client redis.UniversalClient, key string, ttl time.Duration, opts ...Option) *Mutex {
	if ttl <= 0 {
		ttl = 30 * time.Second
	}
	m := &Mutex{
		client:           client,
		key:              key,
		value:            uuid.New().String(), // 生成唯一持有者标识
		ttl:              ttl,
		stopCh:           make(chan struct{}),
		retryStrategy:    func(attempt int) time.Duration { return 50 * time.Millisecond }, // 默认固定 50ms
		minRenewInterval: 200 * time.Millisecond,
		renewTimeout:     2 * time.Second,
		logger:           &defaultLogger{},
	}
	for _, opt := range opts {
		opt(m)
	}
	return m
}

// Lock 阻塞式获取锁，直到成功或 ctx 超时/取消。
// 成功获取锁后自动启动看门狗进行续期。
func (m *Mutex) Lock(ctx context.Context) error {
	attempt := 0
	for {
		ok, err := m.tryAcquire(ctx)
		if err != nil {
			return err
		}
		if ok {
			// 加锁成功，启动看门狗
			m.startWatchdog()
			return nil
		}

		// 未获取到锁，计算等待时间
		delay := m.retryStrategy(attempt)
		attempt++

		select {
		case <-ctx.Done():
			return fmt.Errorf("lock %s acquire timeout: %w", m.key, ctx.Err())
		case <-time.After(delay):
			// 继续重试
		}
	}
}

// TryLock 非阻塞尝试获取一次锁，立即返回结果。
// 若成功获取，会自动启动看门狗。
func (m *Mutex) TryLock(ctx context.Context) (bool, error) {
	ok, err := m.tryAcquire(ctx)
	if err != nil {
		return false, err
	}
	if ok {
		m.startWatchdog()
		return true, nil
	}
	return false, nil
}

// Unlock 释放锁，并停止看门狗。
// 只有锁的当前持有者才能成功释放，否则返回 ErrLockNotHeld。
// 若锁在持有期间已丢失（续期失败），则返回 ErrLockLost。
func (m *Mutex) Unlock(ctx context.Context) error {
	// 先停止看门狗，确保不再有续期操作
	m.stopWatchdog()

	m.mu.Lock()
	defer m.mu.Unlock()

	if m.lost {
		return ErrLockLost
	}
	if !m.locked {
		return ErrLockNotHeld
	}

	err := m.releaseLock(ctx)
	if err == nil {
		m.locked = false
	}
	return err
}

// IsHeld 检查当前实例是否仍持有锁（通过 Redis 实时验证）
func (m *Mutex) IsHeld(ctx context.Context) (bool, error) {
	val, err := m.client.Get(ctx, m.key).Result()
	if err == redis.Nil {
		return false, nil
	}
	if err != nil {
		return false, err
	}
	return val == m.value, nil
}

// tryAcquire 执行一次加锁尝试，内部更新 locked 状态
func (m *Mutex) tryAcquire(ctx context.Context) (bool, error) {
	m.mu.Lock()
	defer m.mu.Unlock()

	if m.locked {
		return false, fmt.Errorf("mutex already locked")
	}

	ok, err := m.client.SetNX(ctx, m.key, m.value, m.ttl).Result()
	if err != nil {
		return false, err
	}
	if ok {
		m.locked = true
		m.lost = false
		return true, nil
	}
	return false, nil
}

// releaseLock 执行 Redis 释放锁的 Lua 脚本，确保原子性
func (m *Mutex) releaseLock(ctx context.Context) error {
	script := `
		if redis.call("GET", KEYS[1]) == ARGV[1] then
			return redis.call("DEL", KEYS[1])
		else
			return 0
		end
	`
	result, err := m.client.Eval(ctx, script, []string{m.key}, m.value).Result()
	if err != nil {
		return fmt.Errorf("redis eval error: %w", err)
	}
	if result.(int64) == 0 {
		return ErrLockNotHeld
	}
	return nil
}

// startWatchdog 启动后台续期协程（内部使用 Once 保证只启动一次）
func (m *Mutex) startWatchdog() {
	m.watchdogOnce.Do(func() {
		m.wg.Add(1)
		go m.watchdogLoop()
	})
}

// watchdogLoop 看门狗主循环，定期续期
func (m *Mutex) watchdogLoop() {
	defer m.wg.Done()

	// 计算续期间隔：TTL 的 1/3，且不小于最小间隔
	interval := m.ttl / 3
	if interval < m.minRenewInterval {
		interval = m.minRenewInterval
	}

	ticker := time.NewTicker(interval)
	defer ticker.Stop()

	for {
		select {
		case <-ticker.C:
			if err := m.renew(); err != nil {
				// 续期失败，标记锁已丢失，并通知外部
				m.markLost()
				m.logger.Printf("watchdog renew failed for key %s: %v", m.key, err)
				if m.renewFailedCb != nil {
					m.renewFailedCb(m.key, err)
				}
				return
			}
		case <-m.stopCh:
			// 收到停止信号，正常退出
			return
		}
	}
}

// renew 执行一次续期操作，使用 Lua 脚本验证持有者身份并延长 TTL
func (m *Mutex) renew() error {
	ctx, cancel := context.WithTimeout(context.Background(), m.renewTimeout)
	defer cancel()

	script := `
		if redis.call("GET", KEYS[1]) == ARGV[1] then
			return redis.call("EXPIRE", KEYS[1], ARGV[2])
		else
			return 0
		end
	`
	result, err := m.client.Eval(ctx, script, []string{m.key}, m.value, int64(m.ttl.Seconds())).Result()
	if err != nil {
		return err
	}
	if result.(int64) == 0 {
		return errors.New("lock not held or key missing")
	}
	return nil
}

// markLost 标记锁已丢失，由续期失败时调用
func (m *Mutex) markLost() {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.lost = true
	m.locked = false // 丢失后即认为不再持有锁
}

// stopWatchdog 停止看门狗协程并等待其退出
func (m *Mutex) stopWatchdog() {
	// 关闭 stopCh 通知看门狗退出（使用 select 避免重复关闭）
	select {
	case <-m.stopCh:
		// 已经关闭
	default:
		close(m.stopCh)
	}
	// 等待看门狗协程完全退出
	m.wg.Wait()
}

完整测试用例：

测试依赖 miniredis 模拟 Redis 服务，请先安装：

go get github.com/alicebob/miniredis/v2

测试文件：mutex_test.go

package redislock

import (
    "context"
    "sync"
    "testing"
    "time"

    "github.com/alicebob/miniredis/v2"
    "github.com/redis/go-redis/v9"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

// 创建测试用的 Redis 客户端（基于 miniredis）
func setupTestRedis(t *testing.T) (*redis.Client, *miniredis.Miniredis) {
    mr, err := miniredis.Run()
    require.NoError(t, err)

    client := redis.NewClient(&redis.Options{
        Addr: mr.Addr(),
    })
    return client, mr
}

// 测试：正常加锁和解锁流程
func TestMutex_LockUnlock(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    mutex := NewMutex(client, "test:lock", 5*time.Second)
    ctx := context.Background()

    // 加锁
    err := mutex.Lock(ctx)
    require.NoError(t, err)

    // 验证 Redis 中确实存在该 key
    val, err := client.Get(ctx, "test:lock").Result()
    require.NoError(t, err)
    assert.Equal(t, mutex.value, val)

    // 解锁
    err = mutex.Unlock(ctx)
    require.NoError(t, err)

    // 验证 key 已被删除
    _, err = client.Get(ctx, "test:lock").Result()
    assert.ErrorIs(t, err, redis.Nil)
}

// 测试：TryLock 非阻塞获取
func TestMutex_TryLock(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    mutex1 := NewMutex(client, "test:trylock", 5*time.Second)
    mutex2 := NewMutex(client, "test:trylock", 5*time.Second)

    ctx := context.Background()

    // 第一个实例获取锁应成功
    ok, err := mutex1.TryLock(ctx)
    require.NoError(t, err)
    assert.True(t, ok)

    // 第二个实例获取锁应失败（已被占用）
    ok, err = mutex2.TryLock(ctx)
    require.NoError(t, err)
    assert.False(t, ok)

    // 释放锁后，第二个实例应能获取
    err = mutex1.Unlock(ctx)
    require.NoError(t, err)

    ok, err = mutex2.TryLock(ctx)
    require.NoError(t, err)
    assert.True(t, ok)
}

// 测试：阻塞等待超时
func TestMutex_LockTimeout(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    // 先占用锁
    holder := NewMutex(client, "test:timeout", 10*time.Second)
    err := holder.TryLock(context.Background())
    require.NoError(t, err)
    defer holder.Unlock(context.Background())

    // 第二个实例尝试获取，设置较短超时
    waiter := NewMutex(client, "test:timeout", 10*time.Second)
    ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
    defer cancel()

    start := time.Now()
    err = waiter.Lock(ctx)
    elapsed := time.Since(start)

    assert.Error(t, err)
    assert.Contains(t, err.Error(), "acquire timeout")
    assert.True(t, elapsed >= 500*time.Millisecond)
    assert.True(t, elapsed < 1*time.Second)
}

// 测试：看门狗自动续期
func TestMutex_WatchdogRenew(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    // 设置较短的 TTL 和续期间隔，加快测试
    mutex := NewMutex(
        client,
        "test:watchdog",
        2*time.Second,
        WithMinRenewInterval(200*time.Millisecond),
    )

    ctx := context.Background()
    err := mutex.Lock(ctx)
    require.NoError(t, err)

    // 快进 Redis 时间，模拟 3 秒过去（超过原始 TTL）
    mr.FastForward(3 * time.Second)

    // 锁应该仍然存在（被看门狗续期）
    val, err := client.Get(ctx, "test:watchdog").Result()
    require.NoError(t, err)
    assert.Equal(t, mutex.value, val)

    // 释放锁
    err = mutex.Unlock(ctx)
    require.NoError(t, err)
}

// 测试：续期失败回调
func TestMutex_RenewFailedCallback(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    callbackCalled := make(chan error, 1)
    mutex := NewMutex(
        client,
        "test:callback",
        2*time.Second,
        WithMinRenewInterval(100*time.Millisecond),
        WithRenewFailedCallback(func(key string, err error) {
            callbackCalled <- err
        }),
    )

    ctx := context.Background()
    err := mutex.Lock(ctx)
    require.NoError(t, err)

    // 模拟锁被外部删除（如手动 DEL）
    client.Del(ctx, "test:callback")

    // 等待回调被触发（续期时会发现锁不存在）
    select {
    case err := <-callbackCalled:
        assert.Error(t, err)
    case <-time.After(2 * time.Second):
        t.Fatal("续期失败回调未被调用")
    }

    // 解锁时应返回 ErrLockLost
    err = mutex.Unlock(ctx)
    assert.ErrorIs(t, err, ErrLockLost)
}

// 测试：锁持有者身份校验（防止误解锁）
func TestMutex_IdentityProtection(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    mutex1 := NewMutex(client, "test:identity", 5*time.Second)
    mutex2 := NewMutex(client, "test:identity", 5*time.Second)

    ctx := context.Background()

    // mutex1 加锁
    err := mutex1.Lock(ctx)
    require.NoError(t, err)

    // mutex2 尝试解锁应失败
    err = mutex2.Unlock(ctx)
    assert.ErrorIs(t, err, ErrLockNotHeld)

    // mutex1 解锁应成功
    err = mutex1.Unlock(ctx)
    assert.NoError(t, err)
}

// 测试：IsHeld 实时状态查询
func TestMutex_IsHeld(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    mutex := NewMutex(client, "test:isheld", 5*time.Second)
    ctx := context.Background()

    // 加锁前
    held, err := mutex.IsHeld(ctx)
    require.NoError(t, err)
    assert.False(t, held)

    // 加锁后
    err = mutex.Lock(ctx)
    require.NoError(t, err)
    held, err = mutex.IsHeld(ctx)
    require.NoError(t, err)
    assert.True(t, held)

    // 解锁后
    err = mutex.Unlock(ctx)
    require.NoError(t, err)
    held, err = mutex.IsHeld(ctx)
    require.NoError(t, err)
    assert.False(t, held)
}

// 测试：并发竞争场景
func TestMutex_Concurrent(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    const goroutines = 20
    var wg sync.WaitGroup
    counter := 0
    var mu sync.Mutex // 仅用于保护 counter 的本地累加

    for i := 0; i < goroutines; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()

            mutex := NewMutex(client, "test:concurrent", 5*time.Second)
            ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
            defer cancel()

            if err := mutex.Lock(ctx); err != nil {
                t.Logf("goroutine 获取锁失败: %v", err)
                return
            }
            defer mutex.Unlock(context.Background())

            // 临界区：安全地修改共享资源
            mu.Lock()
            counter++
            mu.Unlock()

            // 模拟业务处理
            time.Sleep(50 * time.Millisecond)
        }()
    }

    wg.Wait()

    // 最终 counter 应等于成功获取锁的 goroutine 数量（即 goroutines）
    assert.Equal(t, goroutines, counter)
}

// 测试：指数退避重试策略
func TestMutex_ExponentialBackoff(t *testing.T) {
    client, mr := setupTestRedis(t)
    defer mr.Close()
    defer client.Close()

    // 先占用锁
    holder := NewMutex(client, "test:backoff", 10*time.Second)
    err := holder.TryLock(context.Background())
    require.NoError(t, err)
    defer holder.Unlock(context.Background())

    // 第二个实例使用指数退避
    waiter := NewMutex(
        client,
        "test:backoff",
        10*time.Second,
        WithExponentialBackoff(50*time.Millisecond, 1*time.Second),
    )

    ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
    defer cancel()

    start := time.Now()
    err = waiter.Lock(ctx)
    elapsed := time.Since(start)

    assert.Error(t, err)
    // 验证确实等待了一段时间（由于退避，总等待时间应大于最小间隔）
    assert.True(t, elapsed > 100*time.Millisecond)
}

运行测试

go test -v -race ./...

-race 标志会启用数据竞争检测，确保并发安全。


注意事项

  1. miniredis 时间快进：mr.FastForward() 会推进 Redis 内部时钟，用于模拟过期时间，这对测试看门狗续期非常有用。
  2. 测试并发安全：使用 -race 运行测试可发现潜在的竞态条件。
  3. 生产环境日志：示例中的 Logger 接口可以替换为 *slog.Logger 或 logrus 实现，方便集成。
  4. 上下文传递：建议业务层在调用 Lock 时传入带有 trace_id 的 context，便于问题追踪。

The post 使用Go语言实现Redis分布式锁（附有看门狗自动续期机制） appeared first on 原立方.

]]> https://www.atomic-cube.cn/%e4%bd%bf%e7%94%a8go%e8%af%ad%e8%a8%80%e5%ae%9e%e7%8e%b0redis%e5%88%86%e5%b8%83%e5%bc%8f%e9%94%81%ef%bc%88%e9%99%84%e6%9c%89%e7%9c%8b%e9%97%a8%e7%8b%97%e8%87%aa%e5%8a%a8%e7%bb%ad%e6%9c%9f%e6%9c%ba/feed/ 0 Go 文件和文件夹工具类：一个开箱即用的 fileutil 包 https://www.atomic-cube.cn/go-%e6%96%87%e4%bb%b6%e5%92%8c%e6%96%87%e4%bb%b6%e5%a4%b9%e5%b7%a5%e5%85%b7%e7%b1%bb%ef%bc%9a%e4%b8%80%e4%b8%aa%e5%bc%80%e7%ae%b1%e5%8d%b3%e7%94%a8%e7%9a%84-fileutil-%e5%8c%85/ https://www.atomic-cube.cn/go-%e6%96%87%e4%bb%b6%e5%92%8c%e6%96%87%e4%bb%b6%e5%a4%b9%e5%b7%a5%e5%85%b7%e7%b1%bb%ef%bc%9a%e4%b8%80%e4%b8%aa%e5%bc%80%e7%ae%b1%e5%8d%b3%e7%94%a8%e7%9a%84-fileutil-%e5%8c%85/#respond Fri, 20 Mar 2026 07:28:00 +0000 https://www.atomic-cube.cn/?p=1510 在日常开发中，文件与目录操作是高频需求。虽然 Go 标准库已经提供了 os、path/filepat […]

The post Go 文件和文件夹工具类：一个开箱即用的 fileutil 包 appeared first on 原立方.

]]> 在日常开发中，文件与目录操作是高频需求。虽然 Go 标准库已经提供了 os、path/filepath 等基础能力，但直接使用仍需处理大量边界条件。本文将封装一个实用的 fileutil 工具包，涵盖常用操作：路径存在判断、目录创建、文件复制、目录复制、移动、删除、遍历、大小统计等。每个方法都有详细的注释和错误处理，可直接集成到项目中。

完整代码可在文末获取，或直接复制使用。

功能概览

核心代码：fileutil 包实现

// Package fileutil 提供文件和目录操作的常用工具函数
package fileutil

import (
    "fmt"
    "io"
    "os"
    "path/filepath"
    "strings"
)

// Exists 判断路径是否存在（文件或目录均适用）
func Exists(path string) bool {
    _, err := os.Stat(path)
    return err == nil || !os.IsNotExist(err)
}

// IsDir 判断给定路径是否为目录
func IsDir(path string) (bool, error) {
    info, err := os.Stat(path)
    if err != nil {
        return false, err
    }
    return info.IsDir(), nil
}

// IsFile 判断给定路径是否为普通文件
func IsFile(path string) (bool, error) {
    info, err := os.Stat(path)
    if err != nil {
        return false, err
    }
    return !info.IsDir(), nil
}

// EnsureDir 确保目录存在，如果不存在则递归创建。
// 若已存在但不是目录，返回错误。
func EnsureDir(path string) error {
    if Exists(path) {
        isDir, err := IsDir(path)
        if err != nil {
            return err
        }
        if !isDir {
            return fmt.Errorf("path exists but is not a directory: %s", path)
        }
        return nil
    }
    return os.MkdirAll(path, 0755)
}

// CopyFile 复制单个文件从 src 到 dst。
// 如果 dst 已存在，默认会被覆盖。
// 复制时会保留源文件的权限模式。
func CopyFile(src, dst string) error {
    // 打开源文件
    srcFile, err := os.Open(src)
    if err != nil {
        return fmt.Errorf("open source file: %w", err)
    }
    defer srcFile.Close()

    // 获取源文件信息（用于保留权限）
    srcInfo, err := srcFile.Stat()
    if err != nil {
        return fmt.Errorf("stat source file: %w", err)
    }

    // 创建目标文件
    dstFile, err := os.Create(dst)
    if err != nil {
        return fmt.Errorf("create destination file: %w", err)
    }
    defer dstFile.Close()

    // 复制内容
    if _, err := io.Copy(dstFile, srcFile); err != nil {
        return fmt.Errorf("copy content: %w", err)
    }

    // 同步写入到磁盘
    if err := dstFile.Sync(); err != nil {
        return fmt.Errorf("sync destination file: %w", err)
    }

    // 保留源文件的权限模式
    return os.Chmod(dst, srcInfo.Mode())
}

// MoveFile 移动文件（也可用于重命名）。
// 如果跨文件系统移动失败，会自动降级为复制后删除。
func MoveFile(src, dst string) error {
    // 先尝试直接 rename（同一文件系统内最快）
    err := os.Rename(src, dst)
    if err == nil {
        return nil
    }

    // 跨文件系统时，采用复制+删除
    if err := CopyFile(src, dst); err != nil {
        return fmt.Errorf("copy file during move: %w", err)
    }
    if err := os.Remove(src); err != nil {
        // 复制成功但删除失败，目标文件已存在，记录错误但不回滚（避免数据丢失）
        return fmt.Errorf("remove source file after copy: %w", err)
    }
    return nil
}

// CopyDir 递归复制整个目录从 src 到 dst。
// 如果 dst 已存在且是目录，内容会合并；否则会先创建。
func CopyDir(src, dst string) error {
    // 获取源目录信息
    srcInfo, err := os.Stat(src)
    if err != nil {
        return fmt.Errorf("stat source directory: %w", err)
    }
    if !srcInfo.IsDir() {
        return fmt.Errorf("source is not a directory: %s", src)
    }

    // 创建目标目录（保留源目录权限）
    if err := os.MkdirAll(dst, srcInfo.Mode()); err != nil {
        return fmt.Errorf("create destination directory: %w", err)
    }

    // 遍历源目录
    entries, err := os.ReadDir(src)
    if err != nil {
        return fmt.Errorf("read source directory: %w", err)
    }

    for _, entry := range entries {
        srcPath := filepath.Join(src, entry.Name())
        dstPath := filepath.Join(dst, entry.Name())

        if entry.IsDir() {
            // 递归复制子目录
            if err := CopyDir(srcPath, dstPath); err != nil {
                return err
            }
        } else {
            // 复制文件
            if err := CopyFile(srcPath, dstPath); err != nil {
                return err
            }
        }
    }
    return nil
}

// DeleteDir 删除目录及其所有内容（类似 rm -rf）
func DeleteDir(path string) error {
    if !Exists(path) {
        return nil // 幂等：已不存在即成功
    }
    return os.RemoveAll(path)
}

// ListFiles 递归列出目录下所有文件的绝对路径。
// 如果指定了 extensions（例如 []string{".go", ".txt"}），则只返回匹配的文件。
// 传 nil 或空切片则返回所有文件。
func ListFiles(dir string, extensions []string) ([]string, error) {
    var files []string
    err := filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() {
            return nil
        }

        // 过滤扩展名
        if len(extensions) > 0 {
            ext := strings.ToLower(filepath.Ext(path))
            matched := false
            for _, e := range extensions {
                if strings.ToLower(e) == ext {
                    matched = true
                    break
                }
            }
            if !matched {
                return nil
            }
        }

        absPath, err := filepath.Abs(path)
        if err != nil {
            return err
        }
        files = append(files, absPath)
        return nil
    })
    return files, err
}

// DirSize 计算目录占用磁盘总大小（递归包含子目录）
func DirSize(path string) (int64, error) {
    var size int64
    err := filepath.WalkDir(path, func(_ string, d os.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if !d.IsDir() {
            info, err := d.Info()
            if err != nil {
                return err
            }
            size += info.Size()
        }
        return nil
    })
    return size, err
}

// ReadString 快速读取整个文件为字符串
func ReadString(path string) (string, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return "", err
    }
    return string(data), nil
}

// WriteString 快速将字符串写入文件（覆盖写入，权限 0644）
func WriteString(path, content string) error {
    return os.WriteFile(path, []byte(content), 0644)
}

// AppendString 追加字符串到文件末尾，如果文件不存在则创建
func AppendString(path, content string) error {
    f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        return err
    }
    defer f.Close()
    _, err = f.WriteString(content)
    return err
}

// SafeWrite 原子性写入：先写临时文件，再 rename 替换，避免写入中途崩溃导致文件损坏。
func SafeWrite(path string, data []byte, perm os.FileMode) error {
    // 在同目录下创建临时文件
    tmpFile, err := os.CreateTemp(filepath.Dir(path), ".tmp-*")
    if err != nil {
        return err
    }
    tmpName := tmpFile.Name()

    // 写入数据
    if _, err := tmpFile.Write(data); err != nil {
        tmpFile.Close()
        os.Remove(tmpName)
        return err
    }
    if err := tmpFile.Sync(); err != nil {
        tmpFile.Close()
        os.Remove(tmpName)
        return err
    }
    if err := tmpFile.Close(); err != nil {
        os.Remove(tmpName)
        return err
    }

    // 设置权限
    if err := os.Chmod(tmpName, perm); err != nil {
        os.Remove(tmpName)
        return err
    }

    // 原子替换
    return os.Rename(tmpName, path)
}

使用示例

package main

import (
    "fmt"
    "log"
    "path/to/fileutil" // 替换为你的实际导入路径
)

func main() {
    // 1. 判断路径是否存在
    fmt.Println("存在:", fileutil.Exists("/tmp/test"))

    // 2. 确保目录存在
    if err := fileutil.EnsureDir("./data/logs"); err != nil {
        log.Fatal(err)
    }

    // 3. 写入文件
    if err := fileutil.WriteString("./data/config.txt", "Hello, Gopher!"); err != nil {
        log.Fatal(err)
    }

    // 4. 安全写入（原子操作）
    if err := fileutil.SafeWrite("./data/important.dat", []byte("atomic write"), 0644); err != nil {
        log.Fatal(err)
    }

    // 5. 复制文件
    if err := fileutil.CopyFile("./data/config.txt", "./data/backup/config_copy.txt"); err != nil {
        log.Fatal(err)
    }

    // 6. 复制目录
    if err := fileutil.CopyDir("./data", "./data_backup"); err != nil {
        log.Fatal(err)
    }

    // 7. 列出所有 .go 文件
    goFiles, err := fileutil.ListFiles(".", []string{".go"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("找到 %d 个 Go 文件\n", len(goFiles))

    // 8. 计算目录大小
    size, err := fileutil.DirSize("./data")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("目录大小: %.2f MB\n", float64(size)/1024/1024)

    // 9. 移动文件
    if err := fileutil.MoveFile("./data/old.txt", "./data/archive/new.txt"); err != nil {
        log.Fatal(err)
    }

    // 10. 删除目录
    if err := fileutil.DeleteDir("./data_backup"); err != nil {
        log.Fatal(err)
    }
}

要点说明

函数注意事项
CopyFile覆盖已存在的目标文件；保留源文件权限
MoveFile跨文件系统自动降级为复制+删除
CopyDir递归复制，目标目录存在时会合并内容
SafeWrite原子写入，先写临时文件再 rename，防止写一半时进程崩溃导致数据损坏
ListFiles支持按扩展名过滤，返回绝对路径
EnsureDir已存在但不是目录时报错，避免误用

这个工具包覆盖了日常开发中 90% 的文件目录操作场景。你可以根据项目需要继续扩展，比如增加压缩/解压、权限批量修改等功能。直接拷贝到项目中使用即可。

The post Go 文件和文件夹工具类：一个开箱即用的 fileutil 包 appeared first on 原立方.

]]> https://www.atomic-cube.cn/go-%e6%96%87%e4%bb%b6%e5%92%8c%e6%96%87%e4%bb%b6%e5%a4%b9%e5%b7%a5%e5%85%b7%e7%b1%bb%ef%bc%9a%e4%b8%80%e4%b8%aa%e5%bc%80%e7%ae%b1%e5%8d%b3%e7%94%a8%e7%9a%84-fileutil-%e5%8c%85/feed/ 0