文件操作方法

Processor 提供 JSON 文件读写与流式加载方法，覆盖文件、io.Reader、io.Writer 三类数据源。文件类方法在操作前均进行安全路径校验（见函数参考）。

文件加载

LoadFromFile

签名：func (p *Processor) LoadFromFile(filePath string, cfg ...Config) (string, error)

从文件加载 JSON 数据并返回原始字符串（保留文件字节顺序与空白，不重新编码）。读取字节数受 MaxJSONSize 限制。

data, err := p.LoadFromFile("config.json")
if err != nil {
    panic(err)
}
fmt.Println(data) // 原始 JSON 字符串

LoadFromFileAsData (已私有化)

API 变更说明

LoadFromFileAsData 已转为内部方法（loadFromFileAsData），不再作为公开 API 导出。请使用 LoadFromFile + Parse 组合代替：

jsonStr, err := p.LoadFromFile("data.json")
if err != nil {
    panic(err)
}
var data any
err = p.Parse(jsonStr, &data)
// data 类型为 map[string]any 或 []any
if obj, ok := data.(map[string]any); ok {
    fmt.Println(obj["name"])
}

Reader 加载

LoadFromReader

签名：func (p *Processor) LoadFromReader(reader io.Reader, cfg ...Config) (string, error)

从 io.Reader 加载 JSON 数据并返回原始字符串。读取受 MaxJSONSize 限制，适合 os.File、HTTP Body、管道等流式源。

file, _ := os.Open("data.json")
defer file.Close()

data, err := p.LoadFromReader(file)
if err != nil {
    panic(err)
}

LoadFromReaderAsData (已私有化)

API 变更说明

LoadFromReaderAsData 已转为内部方法（loadFromReaderAsData），不再作为公开 API 导出。请使用 LoadFromReader + Parse 组合代替：

file, _ := os.Open("data.json")
defer file.Close()

jsonStr, err := p.LoadFromReader(file)
if err != nil {
    panic(err)
}
var data any
err = p.Parse(jsonStr, &data)

文件写入

SaveToFile

签名：func (p *Processor) SaveToFile(filePath string, data any, cfg ...Config) error

将数据保存为 JSON 文件。自动创建父目录，采用原子写入（临时文件 + rename）。字符串 / []byte 输入会被预解析避免二次转义。

err := p.SaveToFile("data.json", map[string]any{"name": "CyberGo"})

// 使用 PrettyConfig 保存格式化输出
err = p.SaveToFile("data.json", data, json.PrettyConfig())

完整示例：SaveToFile + LoadFromFile 往返

package main

import (
    "fmt"
    "os"

    "github.com/cybergodev/json"
)

func main() {
    p, err := json.New()
    if err != nil {
        panic(err)
    }
    defer p.Close()

    tmp, err := os.CreateTemp("", "cybergo-*.json")
    if err != nil {
        panic(err)
    }
    path := tmp.Name()
    tmp.Close()
    defer os.Remove(path)

    err = p.SaveToFile(path, map[string]any{"name": "Alice", "age": 30})
    if err != nil {
        panic(err)
    }

    data, err := p.LoadFromFile(path)
    if err != nil {
        panic(err)
    }
    fmt.Println(data)
    // 输出：{"age":30,"name":"Alice"}
}

MarshalToFile

签名：func (p *Processor) MarshalToFile(path string, data any, cfg ...Config) error

将数据编码为 JSON 并写入文件。自动创建父目录，原子写入。与 SaveToFile 的区别：MarshalToFile 直接调用 Marshal / MarshalIndent（不做字符串预解析），适合结构体、map 等 Go 值。

err := p.MarshalToFile("output.json", data)

// 格式化保存
err = p.MarshalToFile("output.json", data, json.PrettyConfig())

完整示例：MarshalToFile + UnmarshalFromFile 结构体往返

package main

import (
    "fmt"
    "os"

    "github.com/cybergodev/json"
)

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

func main() {
    p, err := json.New()
    if err != nil {
        panic(err)
    }
    defer p.Close()

    tmp, err := os.CreateTemp("", "cybergo-*.json")
    if err != nil {
        panic(err)
    }
    path := tmp.Name()
    tmp.Close()
    defer os.Remove(path)

    err = p.MarshalToFile(path, User{Name: "Alice", Age: 30})
    if err != nil {
        panic(err)
    }

    var user User
    err = p.UnmarshalFromFile(path, &user)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%s, %d\n", user.Name, user.Age)
    // 输出：Alice, 30
}

UnmarshalFromFile

签名：func (p *Processor) UnmarshalFromFile(path string, v any, cfg ...Config) error

从文件读取 JSON 并解码到目标变量。读取受 MaxJSONSize 限制。

var config Config
err := p.UnmarshalFromFile("config.json", &config)
if err != nil {
    panic(err)
}

SaveToWriter

签名：func (p *Processor) SaveToWriter(writer io.Writer, data any, cfg ...Config) error

将数据编码为 JSON 并写入 io.Writer。不涉及文件路径，故不做路径校验。

var buf bytes.Buffer
err := p.SaveToWriter(&buf, data, json.PrettyConfig())

完整示例：写入 bytes.Buffer

package main

import (
    "bytes"
    "fmt"

    "github.com/cybergodev/json"
)

func main() {
    p, err := json.New()
    if err != nil {
        panic(err)
    }
    defer p.Close()

    var buf bytes.Buffer
    err = p.SaveToWriter(&buf, map[string]any{"name": "Alice", "age": 30}, json.PrettyConfig())
    if err != nil {
        panic(err)
    }
    fmt.Print(buf.String())
    // 输出：
    // {
    //   "age": 30,
    //   "name": "Alice"
    // }
}

文件迭代

Processor 提供 ForeachFile 系列方法，直接从文件迭代 JSON 集合，是 LoadFromFile + Foreach 的便捷组合：

方法	用途
`ForeachFile(path, fn, cfg...)`	迭代文件根级数组 / 对象
`ForeachFileWithPath(path, pathExpr, fn, cfg...)`	迭代文件中指定路径下的集合
`ForeachFileChunked(path, chunkSize, fn, cfg...)`	按批次迭代大数组
`ForeachFileNested(path, fn, cfg...)`	递归迭代所有嵌套结构

err := p.ForeachFile("users.json", func(key any, item *json.IterableValue) error {
    fmt.Println(item.GetString("name"))
    return nil
})

回调支持 item.Break() 提前终止迭代。流式处理与大文件优化细节见流式处理。

方法选择

场景	推荐方法
需要原始字符串	`LoadFromFile` / `LoadFromReader`
需要解析后数据	`LoadFromFile` + `Parse` / `LoadFromReader` + `Parse`
保存 Go 值到文件	`SaveToFile` / `MarshalToFile`
从文件读取并解码到结构体	`UnmarshalFromFile`
写入到 Writer	`SaveToWriter`
迭代文件中的集合	`ForeachFile` 系列

文件操作方法 ​

文件加载 ​

LoadFromFile ​

LoadFromFileAsData (已私有化) ​

Reader 加载 ​

LoadFromReader ​

LoadFromReaderAsData (已私有化) ​

文件写入 ​

SaveToFile ​

MarshalToFile ​

UnmarshalFromFile ​

SaveToWriter ​

文件迭代 ​

方法选择 ​

相关 ​