126 lines
8.2 KiB
Markdown
126 lines
8.2 KiB
Markdown
# @go 开发指引 (INDEX)
|
||
|
||
本项目旨在提供一套极致精简、消除摩擦、安全可靠、高性能的 Go 开发基础设施。
|
||
|
||
## 模块索引
|
||
|
||
| 项目 | 版本 | 核心能力 | 依赖 | 详细技术手册 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| **go/cast** | v1.2.6 | 语义化强转; 万能转换; 泛型工具; 智能序列化; 时区和时间万能转化; 深度合并覆盖等 | - | [./cast/README.md](https://apigo.cc/go/cast) |
|
||
| **go/timer** | v1.0.5 | 高性能时间流管控引擎; 耗时打点; 退避重试; 时间轮; 防抖节流; 超时监控 | cast | [./timer/README.md](https://apigo.cc/go/timer) |
|
||
| **go/rand** | v1.0.4 | 高并发随机; 闭区间生成; 洗牌 | - | [./rand/README.md](https://apigo.cc/go/rand) |
|
||
| **go/encoding** | v1.0.4 | Hex/Base64/Int 编解码 | - | [./encoding/README.md](https://apigo.cc/go/encoding) |
|
||
| **go/safe** | v1.0.4 | 内存保护; 防 Dump; 安全擦除; 混淆 | rand | [./safe/README.md](https://apigo.cc/go/safe) |
|
||
| **go/crypto** | v1.0.4 | 主流算法; 混合加密; 内存防御 | safe, encoding | [./crypto/README.md](https://apigo.cc/go/crypto) |
|
||
| **go/crypto-sm** | v1.0.4 | 国密 (SM2/3/4); 内存安全实现 | crypto, encoding, safe | [./crypto-sm/README.md](https://apigo.cc/crypto-sm) |
|
||
| **go/id** | v1.0.4 | 分布式 ID; 数据库优化 | encoding, rand | [./id/README.md](https://apigo.cc/id) |
|
||
| **go/file** | v1.0.4 | 高性能 IO; 智能序列化; 内存资源加密 | convert, encoding, safe | [./file/README.md](https://apigo.cc/file) |
|
||
| **go/shell** | v1.0.4 | 终端样式; 命令执行; 命令链管道 | cast | [./shell/README.md](https://apigo.cc/go/shell) |
|
||
| **go/config** | v1.0.4 | 文件配置加载; 环境覆盖; 结构映射 | cast, convert, file | [./config/README.md](https://apigo.cc/go/config) |
|
||
| **go/log** | v1.1.0 | 高性能日志; 脱敏; 多输出渠道 | cast, config, shell | [./log/README.md](https://apigo.cc/go/log) |
|
||
| **go/http** | v1.0.3 | 高性能 HTTP 客户端; 泛型绑定; 自动透传 | cast, convert, file, log | [./http/README.md](https://apigo.cc/go/http) |
|
||
| **go/db** | v1.0.4 | 极简数据库抽象; 自动绑定; 读写分离; 自动 ID 生成 | cast, config, convert, crypto, id, log, rand, safe, shell | [./db/README.md](https://apigo.cc/go/db) |
|
||
| **go/redis** | v1.0.2 | 高性能 Redis 客户端; 分布式 ID; 发布订阅 | cast, config, crypto, id, log, safe | [./redis/README.md](https://apigo.cc/go/redis) |
|
||
| **go/discover** | v1.0.0 | 服务发现与负载均衡; 自动透传; H2C/WS 支持 | cast, config, http, log, redis | [./discover/README.md](https://apigo.cc/go/discover) |
|
||
|
||
---
|
||
|
||
## API 指南
|
||
|
||
### discover (服务发现与负载均衡)
|
||
- **意图**: 极简、自动化的服务发现与微服务调用层。
|
||
- **API**:
|
||
- **核心控制**: Start, EasyStart, Stop, AddExternalApp, SetNode
|
||
- **服务调用**: NewCaller, Get, Post, Put, Delete, Head, Do, Open (WS)
|
||
- **扩展配置**: SetLoadBalancer, SetRoute
|
||
- **透传列表**: RelayHeaders
|
||
|
||
|
||
### cast (语义化类型转换与泛型工具)
|
||
- **意图**: 彻底消除类型摩擦。
|
||
- **API**:
|
||
- **核心语义**: To[T], Convert, As
|
||
- **容器转换**: ToMap, ToSlice, FillMap, FillSlice
|
||
- **序列化与构建**: ToJSON, ToJSONBytes, FromJSON, UnmarshalJSON, ToJSONDesensitizeBytes, PrettyToJSON
|
||
- **泛型工具**: If, In, Ptr, ArrayToBoolMap
|
||
- **时间处理**: ParseTime, FormatTime, AddTime, SetDefaultTimeZone
|
||
- **基础转换**: Int, Int64, Uint, Uint64, Float, Float64, String, Bool, Duration
|
||
- **辅助工具**: Split, SplitArgs, UniqueAppend, JoinArgs, RealValue, GetLowerName, GetUpperName, FixUpperCase
|
||
|
||
|
||
### redis (高性能 Redis 客户端)
|
||
- **意图**: 极简、安全的 Redis 交互层。自动处理连接池、序列化与重试，集成高性能分布式 ID 与发布订阅。
|
||
- **API**:
|
||
- **核心**: GetRedis, NewRedis, Do
|
||
- **结果绑定**: To[T], Int, String, Bool, ResultMap
|
||
- **扩展能力**: Subscribe, PUBLISH, NewIDMaker
|
||
|
||
### convert (深度映射与平展)
|
||
- **意图**: 智能递归对象映射，支持单值/切片穿透，Key 大小写模糊匹配。
|
||
- **API**:
|
||
- **转换入口**: To
|
||
- **结构平展**: FlatStruct, FlatStructWithUnexported, FlattenStruct
|
||
|
||
### time (时区与DSL处理)
|
||
- **意图**: 基于 TimeZone 上下文的时区解析、DSL 加减计算、高性能计时与时长格式化。
|
||
- **API**:
|
||
- **时区上下文**: New, Parse, Format, Add, Now
|
||
- **计时工具**: Start, Record, Pause, Resume, Stop, Summarize, Describe
|
||
- **时长处理**: DescribeDuration
|
||
|
||
### rand (高性能并发随机)
|
||
- **意图**: 闭区间、高并发场景下的随机数与字节生成。
|
||
- **API**: Int, FastInt, Float, FastFloat, Byte, Bytes, Perm, Shuffle
|
||
|
||
### crypto (通用加解密与Hash)
|
||
- **意图**: 混合加密体系，强制执行内存安全与资源闭环。
|
||
- **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
|
||
|
||
### crypto-sm (国密专项)
|
||
- **意图**: 完全对齐 `go/crypto` 接口，覆盖 SM2/3/4 国密标准。
|
||
- **API**: NewSM2, NewSM2AndEraseKey, GenerateSM2KeyPair, Sm3, Sm3ToHex, Sm3ToBase64, NewSM4CBC, NewSM4GCM, Encrypt, Decrypt
|
||
|
||
### encoding (编解码引擎)
|
||
- **意图**: 语义明确的编解码工具，支持二进制链路与整数填充编码。
|
||
- **API**: Hex, HexToString, MustUnHex, MustUnHexFromString, Base64, Base64ToString, UrlBase64, UrlBase64ToString, MustUnBase64, MustUnUrlBase64, UrlEncode, MustUnUrlEncode, HtmlEscape, MustUnHtmlEscape, Utf8Valid, NewIntEncoder, EncodeInt, AppendInt, DecodeInt, FillInt, ExchangeInt, HashInt
|
||
|
||
### id (分布式与数据库ID)
|
||
- **意图**: 生成唯一标识符，包含针对 MySQL/PostgreSQL 的写入性能优化。
|
||
- **API**: NewIDMaker, MakeID, Get, GetForMysql, GetForPostgreSQL
|
||
|
||
### file (IO 与 内存文件系统)
|
||
- **意图**: 高性能磁盘 IO、智能序列化及嵌入式资源管理。
|
||
- **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
|
||
|
||
### safe (内存安全闭环)
|
||
- **意图**: 提供底层内存保护、防核心转储及敏感数据安全擦除。
|
||
- **API**: NewSafeBuf, NewSafeBufAndErase, NewSafeString, Open, Close, LockMemory, UnlockMemory, DisableCoreDump, ZeroMemory, MakeSafeToken, EncryptChaCha20, DecryptChaCha20
|
||
|
||
### config (配置加载)
|
||
- **意图**: 从文件（JSON/YAML）加载配置并支持环境变量重写，支持嵌套映射。
|
||
- **API**: Load
|
||
|
||
### log (日志系统)
|
||
- **意图**: 高性能异步日志记录，内置敏感数据脱敏与多渠道（Console/File/ES）分发。
|
||
- **API**:
|
||
- **Logger**: Debug, Info, Warning, Error (带堆栈), Log (通用), DB (带耗时与错误堆栈), Request, Task, Monitor, Statistic
|
||
- **管理**: New (创建子 Logger), SetLevel, SetDesensitization
|
||
- **显示**: Viewable (格式化为彩色文本)
|
||
- **对象池**: GetEntry, PutEntry, WithEntry (支持泛型，极致性能)
|
||
|
||
### http (高性能 HTTP 客户端)
|
||
- **意图**: 极致精简的请求封装，支持分段下载、泛型绑定与微服务 Header 自动透传。
|
||
- **API**:
|
||
- **客户端**: NewClient, NewClientH2C
|
||
- **请求**: Get, Post, Put, Delete, Head, MPost (Multipart)
|
||
- **响应 (Result)**: String, Bytes, To, ToT (泛型), Save
|
||
- **工具**: RelayHeaders (透传列表)
|
||
|
||
### db (极简数据库抽象)
|
||
- **意图**: 意图优先的数据库交互层。自动处理结果绑定、连接池、读写分离与自动 ID/版本管理。
|
||
- **API**:
|
||
- **核心**: GetDB, GetDBWithoutCache, SetEncryptKeys, Sync (DSL)
|
||
- **操作**: Insert, Replace, Update, Delete, Exec, Query, Prepare, Begin
|
||
- **自动特性**: autoVersion (乐观锁), 自动随机 ID (char(8-14)), 影子删除
|
||
- **结果绑定**: To, MapResults, SliceResults, StringMapResults, StringSliceResults, MapOnR1, StringMapOnR1, IntsOnC1, StringsOnC1, IntOnR1C1, FloatOnR1C1, StringOnR1C1, ToKV
|