Gin Archives - 原立方 https://www.atomic-cube.cn/tag/gin/ 技术栈的流动-从零到∞ Fri, 01 May 2026 08:32:50 +0000 zh-CN hourly 1 https://wordpress.org/?v=7.0.2 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 开发经验总结：从入门到写出生产级代码 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 烦到不行，到现在能熟练应对各种并发场景和代码组织，踩过不少坑，也有一些心得。这篇文章把这些经验整理下来，希望能帮到正在用 Go 的朋友。每个主题都会配上可直接运行的代码示例，你可以边看边跑。 1. 错误处理：不止是 if err != nil 很多刚接触 Go 的人都会被满屏的 if err != nil 吓到。但真正的问题是，很多人只检查了错误，却没做好错误包装和分类。 1.1 用 %w 包装错误，保留上下文 Go 1.13 引入的错误包装功能非常实用。使用 fmt.Errorf 的 %w 动词，可以在每一层添加上下文信息，同时保留原始错误，方便上层用 errors.Is 和 errors.As 判断： 输出：业务判断：用户不存在完整错误：get user 42: not found 这种包装方式让错误信息像堆栈一样层层递进，排查问题时会省很多时间。 1.2 只在不可恢复时使用 panic Go 社区有共识：panic 只应在程序无法继续运行时使用，比如启动时依赖的配置加载失败。业务逻辑中应该用错误返回值，让调用方决定如何处理： 2. 并发编程：goroutine 的正确打开方式 2.1 用 Context 控制 goroutine 生命周期 在 HTTP 服务或长时间运行的任务中，用 context 来控制 goroutine 的启动和停止是最标准的做法： Go 的并发模型很简洁，但用不好容易出 goroutine […]

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 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/filepath 等基础能力，但直接使用仍需处理大量边界条件。本文将封装一个实用的 fileutil 工具包，涵盖常用操作：路径存在判断、目录创建、文件复制、目录复制、移动、删除、遍历、大小统计等。每个方法都有详细的注释和错误处理，可直接集成到项目中。 完整代码可在文末获取，或直接复制使用。 功能概览 核心代码：fileutil 包实现 使用示例 要点说明 函数 注意事项 CopyFile 覆盖已存在的目标文件；保留源文件权限 MoveFile 跨文件系统自动降级为复制+删除 CopyDir 递归复制，目标目录存在时会合并内容 SafeWrite 原子写入，先写临时文件再 rename，防止写一半时进程崩溃导致数据损坏 ListFiles 支持按扩展名过滤，返回绝对路径 EnsureDir 已存在但不是目录时报错，避免误用 这个工具包覆盖了日常开发中 90% 的文件目录操作场景。你可以根据项目需要继续扩展，比如增加压缩/解压、权限批量修改等功能。直接拷贝到项目中使用即可。

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