从标准库迁移
cybergodev/json 与标准库 encoding/json 100% 兼容——只需替换 import 路径，现有代码无需任何改动即可编译运行。本页帮助你完成迁移，并了解迁移后可用的增量能力。
三步迁移
安装：
bashgo get github.com/cybergodev/json替换 import：将
"encoding/json"替换为"github.com/cybergodev/json"。go// 迁移前 import "encoding/json" // 迁移后 import "github.com/cybergodev/json"完成：编译通过，所有现有代码无需修改。
完全兼容的 API
下表列出 encoding/json 与 cybergodev/json 的对应关系：
| encoding/json | cybergodev/json | 说明 |
|---|---|---|
Marshal(v) | Marshal(v, cfg...) | 签名兼容，额外可选 cfg 参数 |
Unmarshal(data, &v) | Unmarshal(data, &v, cfg...) | 同上 |
MarshalIndent(v, prefix, indent) | 同名 | 完全兼容 |
Compact(dst, src) | 同名 | 完全兼容 |
Indent(dst, src, prefix, indent) | 同名 | 完全兼容 |
HTMLEscape(dst, src) | 同名 | 完全兼容 |
Valid(data) | Valid(data, cfg...) | 签名兼容 |
NewEncoder(w) | NewEncoder(w, cfg...) | 签名兼容 |
NewDecoder(r) | NewDecoder(r, cfg...) | 签名兼容 |
Number | Number | 类型兼容 |
Delim | Delim | 类型兼容 |
Token | Token | 类型兼容 |
可选的 cfg 参数
所有额外的 cfg ...Config 参数都是可选的（variadic）。不传时，行为与标准库完全一致；需要启用安全模式、缓存等增强能力时才传入。
代码示例：只改 import
下面的示例展示「只改 import」的替换效果，编码、解码与结构体标签（struct tag）用法与 encoding/json 完全相同：
go
package main
import (
"fmt"
"github.com/cybergodev/json"
)
func main() {
type User struct {
Name string `json:"name"`
Age int `json:"age"`
Tags []string `json:"tags"`
}
// 编码 — 与 encoding/json 完全相同
user := User{Name: "Alice", Age: 30, Tags: []string{"go", "json"}}
b, err := json.Marshal(user)
if err != nil {
panic(err)
}
fmt.Println(string(b))
// 输出：{"name":"Alice","age":30,"tags":["go","json"]}
// 解码 — 与 encoding/json 完全相同
var u User
if err := json.Unmarshal(b, &u); err != nil {
panic(err)
}
fmt.Printf("%+v\n", u)
// 输出：{Name:Alice Age:30 Tags:[go json]}
}增量能力
迁移后，你在保持标准库兼容的同时，还能按需使用以下标准库做不到的能力：
| 能力 | 示例 | 了解更多 |
|---|---|---|
| 路径查询 | json.GetString(data, "user.name") | 路径表达式语法 |
| 带默认值获取 | json.GetInt(data, "timeout", 30) | 查询获取 |
| 泛型获取 | json.GetTyped[User](data, "user") | 泛型操作 |
| 路径修改 | json.Set(data, "user.name", "Bob") | 修改操作 |
| Schema 验证 | json.ValidateSchema(data, schema) | 验证器 |
| 流式 JSONL | json.StreamLinesInto[T](r, fn) | JSONL 处理 |
| 高性能处理器 | p, _ := json.New() | Processor 入门 |
行为差异
在默认配置下，cybergodev/json 的行为与 encoding/json 完全一致。所有额外能力（安全模式、路径查询、Schema 验证等）都是 opt-in 的——通过 Config 参数显式启用，不会影响现有代码。
换句话说：迁移是零成本的，你获得的是一个「标准库 + 增量能力」的超集。