CHANGELOG.md

@@ -1,15 +1,5 @@
 # Changelog
 
-## v1.5.5 (2026-06-21)
-- **JS 对齐**: 重构 JS 导出为具名函数，并引入 `jsmod.MakeError` 动态包装错误以获取调用栈。
-- **依赖更新**: 升级依赖 `jsmod` 至 `v1.5.3`，`cast` 至 `v1.5.3`，`rand` 至 `v1.5.3`，`encoding` 至 `v1.5.4`，`safe` 至 `v1.5.2`。
-
-## v1.5.4 (2026-06-11)
-- **版本对齐**: 基础设施全局对齐 v1.5.4。
-
-## v1.5.3 (2026-06-09)
-- **版本对齐**: 基础设施全局对齐 v1.5.3。
-
 ## v1.5.2 (2026-06-08)
 - **JS 对齐**: 将所有注册到 `jsmod` 的导出方法名统一为 PascalCase（如 `Read`, `Write`, `GetFileInfo`），消除 JS 环境下的调用摩擦。
 

TEST.md

@@ -1,7 +1,7 @@
 # Test Report: @go/file
 
 ## 📋 测试概览
-- **测试时间**: 2026-06-21
+- **测试时间**: 2026-05-06
 - **测试环境**: darwin/amd64
 - **Go 版本**: 1.25.0
 
@@ -17,10 +17,9 @@
 ## 🛡️ 鲁棒性防御 (Robustness)
 - **摩擦消除**：移除 `Must` 系列 API，极大降低了业务逻辑中的错误处理心智负担。
 - **内存虚拟化**：支持透明的内存文件系统操作，与磁盘文件 API 完全一致。
-- **JS 错误调用栈**：JS 桥接层改用具名导出并使用 `jsmod.MakeError` 包裹错误，确保 JS 抛出异常时携带准确的 Go 运行时堆栈。
 
 ## ⚡ 性能基准 (Benchmarks)
 | 函数 | 平均耗时 | 性能分析 |
 | :--- | :--- | :--- |
-| `MarshalFile` | **104568 ns/op** | 包含 IO 写入的高性能序列化。 |
+| `MarshalFile` | **115787 ns/op** | 包含 IO 写入的高性能序列化。 |
-| `UnmarshalFile` | **23580 ns/op** | 高效的反序列化。 |
+| `UnmarshalFile` | **24682 ns/op** | 高效的反序列化。 |

go.mod

@@ -3,15 +3,15 @@ module apigo.cc/go/file
 go 1.25.0
 
 require (
-	apigo.cc/go/cast v1.5.3
+	apigo.cc/go/cast v1.5.0
-	apigo.cc/go/encoding v1.5.4
+	apigo.cc/go/encoding v1.5.0
-	apigo.cc/go/jsmod v1.5.3
+	apigo.cc/go/jsmod v1.5.0
-	apigo.cc/go/safe v1.5.2
+	apigo.cc/go/safe v1.5.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
-	apigo.cc/go/rand v1.5.3
+	apigo.cc/go/rand v1.5.0 // indirect
 	github.com/kr/pretty v0.3.0 // indirect
 	github.com/rogpeppe/go-internal v1.14.1 // indirect
 	golang.org/x/crypto v0.52.0 // indirect

js_export.go

@@ -9,273 +9,157 @@ import (
 func init() {
 	jsmod.Register("file", map[string]any{
 		// 读操作 (映射到私有包装器)
-		"Exists":            jsExists,
+		"Exists": func(ctx context.Context, path string) bool {
-		"Read":              jsRead,
-		"ReadBytes":         jsReadBytes,
-		"ReadLines":         jsReadLines,
-		"ReadDir":           jsReadDir,
-		"GetFileInfo":       jsGetFileInfo,
-
-		// 写操作
-		"Write":             jsWrite,
-		"WriteBytes":        jsWriteBytes,
-		"Remove":            jsRemove,
-		"Mkdir":             jsMkdir,
-		"Copy":              jsCopy,
-		"Move":              jsMove,
-		"Replace":           jsReplace,
-
-		// 序列化
-		"UnmarshalFile":     jsUnmarshalFile,
-		"MarshalFile":       jsMarshalFile,
-		"MarshalFilePretty": jsMarshalFilePretty,
-
-		// 归档
-		"Archive":           jsArchive,
-		"Extract":           jsExtract,
-
-		// 压缩工具
-		"Compress":          jsCompress,
-		"Decompress":        jsDecompress,
-	})
-}
-
-func jsExists(ctx context.Context, path string) bool {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
 				return false
 			}
 			return Exists(p)
-}
+		},
-
+		"Read": func(ctx context.Context, path string) (string, error) {
-func jsRead(ctx context.Context, path string) (string, error) {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return "", jsmod.MakeError(err)
+				return "", err
 			}
-	res, err := Read(p)
+			return Read(p)
-	if err != nil {
+		},
-		return "", jsmod.MakeError(err)
+		"ReadBytes": func(ctx context.Context, path string) ([]byte, error) {
-	}
-	return res, nil
-}
-
-func jsReadBytes(ctx context.Context, path string) ([]byte, error) {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return nil, jsmod.MakeError(err)
+				return nil, err
 			}
-	res, err := ReadBytes(p)
+			return ReadBytes(p)
-	if err != nil {
+		},
-		return nil, jsmod.MakeError(err)
+		"ReadLines": func(ctx context.Context, path string) ([]string, error) {
-	}
-	return res, nil
-}
-
-func jsReadLines(ctx context.Context, path string) ([]string, error) {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return nil, jsmod.MakeError(err)
+				return nil, err
 			}
-	res, err := ReadLines(p)
+			return ReadLines(p)
-	if err != nil {
+		},
-		return nil, jsmod.MakeError(err)
+		"ReadDir": func(ctx context.Context, path string) ([]FileInfo, error) {
-	}
-	return res, nil
-}
-
-func jsReadDir(ctx context.Context, path string) ([]FileInfo, error) {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return nil, jsmod.MakeError(err)
+				return nil, err
 			}
-	res, err := ReadDir(p)
+			return ReadDir(p)
-	if err != nil {
+		},
-		return nil, jsmod.MakeError(err)
+		"GetFileInfo": func(ctx context.Context, path string) *FileInfo {
-	}
-	return res, nil
-}
-
-func jsGetFileInfo(ctx context.Context, path string) *FileInfo {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
 				return nil
 			}
 			return GetFileInfo(p)
-}
+		},
 
-func jsWrite(ctx context.Context, path string, content string) error {
+		// 写操作
+		"Write": func(ctx context.Context, path string, content string) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Write(p, content)
+			return Write(p, content)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"WriteBytes": func(ctx context.Context, path string, content []byte) error {
-	}
-	return nil
-}
-
-func jsWriteBytes(ctx context.Context, path string, content []byte) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = WriteBytes(p, content)
+			return WriteBytes(p, content)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"Remove": func(ctx context.Context, path string) error {
-	}
-	return nil
-}
-
-func jsRemove(ctx context.Context, path string) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Remove(p)
+			return Remove(p)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"Mkdir": func(ctx context.Context, path string) error {
-	}
-	return nil
-}
-
-func jsMkdir(ctx context.Context, path string) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Mkdir(p)
+			return Mkdir(p)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"Copy": func(ctx context.Context, from, to string) error {
-	}
-	return nil
-}
-
-func jsCopy(ctx context.Context, from, to string) error {
 			pFrom, err := VerifyPathForSafeMode(ctx, from)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
 			pTo, err := VerifyPathForSafeMode(ctx, to)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Copy(pFrom, pTo)
+			return Copy(pFrom, pTo)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"Move": func(ctx context.Context, from, to string) error {
-	}
-	return nil
-}
-
-func jsMove(ctx context.Context, from, to string) error {
 			pFrom, err := VerifyPathForSafeMode(ctx, from)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
 			pTo, err := VerifyPathForSafeMode(ctx, to)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Move(pFrom, pTo)
+			return Move(pFrom, pTo)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"Replace": func(ctx context.Context, path, old, new string) error {
-	}
-	return nil
-}
-
-func jsReplace(ctx context.Context, path, old, new string) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Replace(p, old, new)
+			return Replace(p, old, new)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
-	}
-	return nil
-}
 
-func jsUnmarshalFile(ctx context.Context, path string, to any) error {
+		// 序列化
+		"UnmarshalFile": func(ctx context.Context, path string, to any) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = UnmarshalFile(p, to)
+			return UnmarshalFile(p, to)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"MarshalFile": func(ctx context.Context, path string, data any) error {
-	}
-	return nil
-}
-
-func jsMarshalFile(ctx context.Context, path string, data any) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = MarshalFile(p, data)
+			return MarshalFile(p, data)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"MarshalFilePretty": func(ctx context.Context, path string, data any) error {
-	}
-	return nil
-}
-
-func jsMarshalFilePretty(ctx context.Context, path string, data any) error {
 			p, err := VerifyPathForSafeMode(ctx, path)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = MarshalFilePretty(p, data)
+			return MarshalFilePretty(p, data)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
-	}
-	return nil
-}
 
-func jsArchive(ctx context.Context, src, dest string) error {
+		// 归档
+		"Archive": func(ctx context.Context, src, dest string) error {
 			pSrc, err := VerifyPathForSafeMode(ctx, src)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
 			pDest, err := VerifyPathForSafeMode(ctx, dest)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Archive(pSrc, pDest)
+			return Archive(pSrc, pDest)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
+		"Extract": func(ctx context.Context, src, dest string, strip bool) error {
-	}
-	return nil
-}
-
-func jsExtract(ctx context.Context, src, dest string, strip bool) error {
 			pSrc, err := VerifyPathForSafeMode(ctx, src)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
 			pDest, err := VerifyPathForSafeMode(ctx, dest)
 			if err != nil {
-		return jsmod.MakeError(err)
+				return err
 			}
-	err = Extract(pSrc, pDest, strip)
+			return Extract(pSrc, pDest, strip)
-	if err != nil {
+		},
-		return jsmod.MakeError(err)
-	}
-	return nil
-}
 
-func jsCompress(data []byte, cType string) ([]byte, error) {
+		// 压缩工具 (无路径，不校验)
-	res, err := Compress(data, cType)
+		"Compress":   Compress,
-	if err != nil {
+		"Decompress": Decompress,
-		return nil, jsmod.MakeError(err)
+	})
-	}
-	return res, nil
-}
-
-func jsDecompress(data []byte, cType string) ([]byte, error) {
-	res, err := Decompress(data, cType)
-	if err != nil {
-		return nil, jsmod.MakeError(err)
-	}
-	return res, nil
 }