.profile/README.md

@go 模块开发导航 (INDEX)

本项目旨在提供一套极致精简、安全可靠、高性能的 Go 开发基础设施。本索引用于 AI 在开发时快速决策选型。

模块概览索引

项目	版本	核心能力	依赖	详细技术手册
go/cast	v1.0.3	基础类型强转; 泛型工具; 序列化	-	./cast/AI.md
go/convert	v1.0.3	深度数据映射; 智能类型穿透	cast	./convert/AI.md
go/time	v1.0.3	时间解析; DSL 加减计算; 归一化时区	cast	./time/AI.md
go/rand	v1.0.3	高并发随机; 闭区间生成; 洗牌	-	./rand/AI.md
go/crypto	v1.0.3	主流算法; 混合加密; 内存防御	safe, encoding	./crypto/AI.md
go/crypto-sm	v1.0.3	国密 (SM2/3/4); 内存安全实现	crypto, encoding, safe	./crypto-sm/AI.md
go/encoding	v1.0.3	Hex/Base64/Int 编解码	-	./encoding/AI.md
go/id	v1.0.3	分布式 ID; 数据库优化	encoding, rand	./id/AI.md
go/file	v1.0.3	高性能 IO; 智能序列化; 内存资源加密	convert, encoding, safe	./file/AI.md
go/safe	v1.0.3	内存保护; 防 Dump; 安全擦除; 混淆	rand	./safe/AI.md

---

模块深度 API 指南

1. cast (类型转换与泛型工具)

• 意图: 处理类型不确定数据，提供零错误处理、静默失败的转换机制。
• 限制/禁忌: 严禁在 Struct 使用 JSON tag；仅适用于非核心金融逻辑的数据处理。
• API: If, Switch, In, FixPtr, Int, Int64, Uint, Uint64, Float, Float64, String, StringP, Bool, Ints, Strings, Duration, Json, JsonP, JsonBytes, JsonBytesP, UnJson, UnJsonBytes, Yaml, UnYaml, SplitTrim, SplitArgs, GetLowerName, GetUpperName, StringPtr, IntPtr, Int64Ptr, BoolPtr

2. convert (深度映射与平展)

• 意图: 智能递归对象映射，支持单值/切片穿透，Key 大小写模糊匹配。
• 限制/禁忌: 避免深层循环引用；大数据高频场景下关注反射性能。
• API: To, Convert, FlatStruct, FlatStructWithUnexported

3. time (时区与DSL处理)

• 意图: 解析归一化为 time.Local，通过 DSL 执行时间算术。
• 限制/禁忌: 解析失败返回 time.Now()，必须清楚此行为是否符合业务预期。
• API: Parse, Format, Add, Now, Today, Yesterday, Tomorrow

4. rand (高性能并发随机)

• 意图: 闭区间、高并发场景下的随机数与字节生成。
• 限制/禁忌: QPS > 1000 强制使用 Fast 系列；禁止引入 math/rand。
• API: Int, FastInt, Float, FastFloat, Byte, Bytes, Perm, Shuffle

5. crypto (通用加解密与Hash)

• 意图: 混合加密体系，强制执行内存安全与资源闭环。
• 限制/禁忌: 任何构造的对象必须 defer Close()；敏感数据首选 SafeBuf。
• API: NewSymmetric, NewSymmetricAndEraseKey, NewAESCBC, NewAESGCM, NewAsymmetric, NewRSA, NewECDSA, NewED25519, NewX25519, EncryptBytes, MustEncrypt, DecryptBytes, MustDecrypt, TryDecrypt, Sign, MustSign, Verify, MustVerify, GenerateKeyPair, MD5, Sha256, Sha512, HmacSha256, Pkcs5Padding, AnsiX923Padding

6. crypto-sm (国密专项)

• 意图: 完全对齐 go/crypto 接口，覆盖 SM2/3/4 国密标准。
• 限制/禁忌: 必须确保与 crypto 行为一致，涉及敏感数据强制使用 SafeBuf。
• API: NewSM2, NewSM2AndEraseKey, GenerateSM2KeyPair, Sm3, Sm3ToHex, Sm3ToBase64, NewSM4CBC, NewSM4GCM, Encrypt, Decrypt

7. encoding (编解码引擎)

• 意图: 语义明确的编解码工具，支持二进制链路与整数填充编码。
• 限制/禁忌: 优先使用 MustUnXxx 系列实现静默逻辑；数据链路优先使用 []byte。
• API: Hex, HexToString, MustUnHex, MustUnHexFromString, Base64, Base64ToString, UrlBase64, UrlBase64ToString, MustUnBase64, MustUnUrlBase64, UrlEncode, MustUnUrlEncode, HtmlEscape, MustUnHtmlEscape, Utf8Valid, NewIntEncoder, EncodeInt, AppendInt, DecodeInt, FillInt, ExchangeInt, HashInt

8. id (分布式与数据库ID)

• 意图: 生成唯一标识符，包含针对 MySQL/PostgreSQL 的写入性能优化。
• 限制/禁忌: 数据库主键生成必须区分 GetForMysql 与 GetForPostgreSQL。
• API: NewIdMaker, MakeId, Get, GetForMysql, GetForPostgreSQL

9. file (IO 与 内存文件系统)

• 意图: 高性能磁盘 IO、智能序列化及嵌入式资源管理。
• 限制/禁忌: IO 路径必须归一化；归档提取等流操作必须确保 Close()。
• API: Exists, ReadBytes, MustReadBytes, Read, MustRead, ReadLines, WriteBytes, Write, Copy, CopyToFile, Remove, Move, Replace, Search, ReadDir, UnmarshalFile, MarshalFile, MarshalFilePretty, PatchFile, Compress, Decompress, Archive, Extract, AddFileToMemory, SafeLoadFileToMemory, LoadFilesToMemoryFromB64, LoadFilesToMemoryFromJson

10. safe (内存安全闭环)

• 意图: 提供底层内存保护、防核心转储及敏感数据安全擦除。
• 限制/禁忌: 凡是 Open() 必 defer Close()；严禁对 SafeBuf 重复锁定。
• API: NewSafeBuf, NewSafeBufAndErase, NewSafeString, Open, Close, LockMemory, UnlockMemory, DisableCoreDump, ZeroMemory, MakeSafeToken, EncryptChaCha20, DecryptChaCha20