diff --git a/README.md b/README.md index d3ad5ca..de82fa3 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,103 @@ -# @go 开发指引 (INDEX) +[English](README.md) | [简体中文](README_zh-CN.md) -本项目旨在提供一套极致精简、消除摩擦、安全可靠、高性能的 Go 开发基础设施。 +# @go Development Guide (INDEX) -## 模块索引 +## Design Philosophy & Principles -| 项目 | 版本 | 核心能力 | 依赖 | 详细技术手册 | -| :--- | :--- | :--- | :--- | :--- | -| **go/cast** | v1.2.8 | 语义化强转; 万能转换; 泛型工具; 智能序列化; 时区和时间万能转化; 深度合并覆盖等 | - | [./cast/README.md](https://apigo.cc/go/cast) | -| **go/timer** | v1.0.6 | 高性能时间流管控引擎; 耗时打点; 退避重试; 时间轮; 防抖节流; 超时监控 | cast | [./timer/README.md](https://apigo.cc/go/timer) | -| **go/rand** | v1.0.5 | 高并发随机; 闭区间生成; 洗牌 | - | [./rand/README.md](https://apigo.cc/go/rand) | -| **go/encoding** | v1.0.6 | Hex/Base64/URL/Int 编解码; 消除摩擦 | cast | [./encoding/README.md](https://apigo.cc/go/encoding) | -| **go/safe** | v1.0.6 | 内存保护; 防 Dump; 安全擦除; 混淆 | rand | [./safe/README.md](https://apigo.cc/go/safe) | -| **go/crypto** | v1.1.0 | 主流算法; 混合加密; 内存防御; 消除摩擦 | safe, encoding, cast | [./crypto/README.md](https://apigo.cc/go/crypto) | -| **go/crypto-sm** | v1.1.0 | 国密 (SM2/3/4); 内存安全实现; 消除摩擦 | crypto, encoding, safe, cast | [./crypto-sm/README.md](https://apigo.cc/crypto-sm) | -| **go/id** | v1.0.5 | 分布式 ID; 数据库优化 | encoding, rand | [./id/README.md](https://apigo.cc/id) | -| **go/file** | v1.0.7 | 高性能 IO; 智能序列化; 内存资源加密; 消除摩擦 | cast, convert, encoding, safe | [./file/README.md](https://apigo.cc/file) | -| **go/shell** | v1.0.5 | 终端样式; 命令执行; 命令链管道 | cast | [./shell/README.md](https://apigo.cc/go/shell) | -| **go/config** | v1.0.7 | 文件配置加载; 环境覆盖; 结构映射 | cast, convert, file | [./config/README.md](https://apigo.cc/go/config) | -| **go/log** | v1.1.9 | 高性能 Meta 驱动日志; JSON 数组序列化; 脱敏; 独立可视化工具 (logv) | cast, config, shell | [./log/README.md](https://apigo.cc/go/log) | -| **go/http** | v1.0.10 | 高性能 HTTP 客户端; 泛型绑定; 自动透传; 流式 Multipart 上传 | cast, convert, file, log | [./http/README.md](https://apigo.cc/go/http) | -| **go/db** | v1.0.10 | 极简数据库抽象; 自动绑定; 读写分离; 自动 ID 生成 | cast, config, convert, crypto, id, log, rand, safe, shell | [./db/README.md](https://apigo.cc/go/db) | -| **go/redis** | v1.0.8 | 高性能 Redis 客户端; 分布式 ID; 发布订阅 | cast, config, crypto, id, log, safe | [./redis/README.md](https://apigo.cc/go/redis) | -| **go/discover** | v1.0.9 | 服务发现与负载均衡; 自动透传; H2C/WS 支持 | cast, config, http, log, redis | [./service/README.md](https://apigo.cc/go/discover) | -| **go/service** | v1.0.3 | 核心微服务框架; 自动参数注入; 路由反射; WebSocket/静态文件/代理支持 | cast, config, discover, http, id, log, redis | [./service/README.md](https://apigo.cc/go/service) | -| **go/watch** | v1.1.1 | 高性能、AI 友好的文件监听库; 递归监听; 灵活过滤 | file, timer | [./watch/README.md](https://apigo.cc/go/watch) | -| **go/api** | v1.0.1 | 极致精简的第三方 API 调度引擎; 接口驱动; 自动配置注入; 内置多级继承与防泄漏机制 | cast, config, crypto, encoding, http | [./api/README.md](https://apigo.cc/go/api) | -... -### service (微服务核心框架) -- **意图**: 极简、自动化的 Web 与 WebSocket 服务框架，实现极致的依赖注入与路由映射。 -- **API**: - - **核心注册**: Register, Restful, RegisterWebsocket - - **生命周期**: Start, AsyncStart, Stop, Wait, CheckCmd, AddCmd - - **组件**: IDMaker (语义化分布式 ID 生成) - - **插件管理**: Static, Rewrite, Proxy, SetAuthChecker, SetInFilter, SetOutFilter - - **工具**: MakeIDForMysql, MakeIDForPostgreSQL, VerifyStruct - - **对象**: Request, Response, Result, CodeResult +This project provides an ultra-lean, friction-free, secure, and high-performance Go development infrastructure. -### api (第三方 API 调度引擎) -- **意图**: 消除对接第三方服务的 SDK 摩擦，实现配置自动化回填与接口化动态签名，确保引擎无状态。 -- **API**: - - **核心调度**: Call[T] - - **动作接口 (鸭子类型)**: Action, SignerAction, ConfigurableAction, URLAction, MethodAction, ValidatableAction - - **配置加载**: Load, GetActionConfig, SetEncryptKeys - - **签名系统**: RegisterSigner, GetSigner +- **Unity**: Standardized toolset to reduce cognitive load. +- **Ease of Use**: Simplified APIs for rapid development. +- **Reliability & Security**: Security-first approach in encryption and memory management. +- **Performance**: Optimized for execution efficiency. +- **Problem Solving**: Focuses on core friction points like type conversion and service discovery. -### watch (高性能文件监听) +--- +## Module Inventory & API Reference -## API 指南 +Docs: https://apigo.cc/go/ -### watch (高性能文件监听) -- **意图**: AI 友好的文件系统事件监控，支持复杂的包含/排除过滤。 -- **API**: - - **核心**: Start, EasyStart - - **对象**: Event (Path, Type, IsDir), Watcher (Add, Remove, Stop, WatchList) +### go/cast v1.3.0 +Semantic type conversion and generic utilities. +- **API**: `To`, `Convert`, `As`, `ToMap`, `ToSlice`, `FillMap`, `FillSlice`, `ToJSON`, `FromJSON`, `UnmarshalJSON`, `ParseTime`, `FormatTime`, `Int`, `String`, `Bool`, `Duration` -### discover (服务发现与负载均衡) -- **意图**: 极简、自动化的服务发现与微服务调用层。 -- **API**: - - **核心控制**: Start, EasyStart, Stop, AddExternalApp, SetNode - - **服务调用**: NewCaller, Get, Post, Put, Delete, Head, Do, Open (WS) - - **扩展配置**: SetLoadBalancer, SetRoute - - **透传列表**: RelayHeaders +### go/rand v1.3.0 +High-concurrency random generation. +- **API**: `Int`, `FastInt`, `Float`, `Byte`, `Bytes`, `Perm`, `Shuffle` +### go/timer v1.3.0 +Time stream control and retries. +- **API**: `Retry`, `Start`, `WithBackoff`, `WithMaxRetries`, `NewDebouncer`, `NewThrottler`, `NewTimeWheel` -### 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 +### go/safe v1.3.0 +Memory protection and secure erasure. +- **API**: `NewSafeBuf`, `NewSafeString`, `LockMemory`, `UnlockMemory`, `DisableCoreDump`, `ZeroMemory`, `EncryptChaCha20`, `DecryptChaCha20` +### go/encoding v1.3.0 +Standard and integer encoding. +- **API**: `Hex`, `Base64`, `UrlEncode`, `HtmlEscape`, `NewIntEncoder`, `EncodeInt`, `DecodeInt`, `HashInt` -### redis (高性能 Redis 客户端) -- **意图**: 极简、安全的 Redis 交互层。自动处理连接池、序列化与重试，集成高性能分布式 ID 与发布订阅。 -- **API**: - - **核心**: GetRedis, NewRedis, Do - - **结果绑定**: To[T], Int, String, Bool, ResultMap - - **扩展能力**: Subscribe, PUBLISH, NewIDMaker +### go/crypto v1.3.0 +Mainstream and hybrid encryption. +- **API**: `NewAESGCM`, `NewRSA`, `NewECDSA`, `NewED25519`, `NewX25519`, `EncryptBytes`, `DecryptBytes`, `Sign`, `Verify`, `MD5`, `Sha256`, `HmacSha256` -### convert (深度映射与平展) -- **意图**: 智能递归对象映射，支持单值/切片穿透，Key 大小写模糊匹配。 -- **API**: - - **转换入口**: To - - **结构平展**: FlatStruct, FlatStructWithUnexported, FlattenStruct +### go/crypto-sm v1.3.0 +National Cryptographic Standard (SM2/3/4). +- **API**: `NewSM2`, `Sm3`, `Sm3ToHex`, `NewSM4CBC`, `NewSM4GCM`, `Encrypt`, `Decrypt` -### time (时区与DSL处理) -- **意图**: 基于 TimeZone 上下文的时区解析、DSL 加减计算、高性能计时与时长格式化。 -- **API**: - - **时区上下文**: New, Parse, Format, Add, Now - - **计时工具**: Start, Record, Pause, Resume, Stop, Summarize, Describe - - **时长处理**: DescribeDuration +### go/id v1.3.0 +Distributed and DB-optimized IDs. +- **API**: `NewIDMaker`, `Get8Bytes4KPerSecond`, `Get12BytesUltraPerSecond`, `GetForMysql` -### rand (高性能并发随机) -- **意图**: 闭区间、高并发场景下的随机数与字节生成。 -- **API**: Int, FastInt, Float, FastFloat, Byte, Bytes, Perm, Shuffle +### go/file v1.3.0 +High-performance IO and memory files. +- **API**: `Exists`, `Read`, `Write`, `Copy`, `Move`, `Remove`, `Search`, `UnmarshalFile`, `MarshalFile`, `Archive`, `Compress`, `LoadFileToMemory` -### crypto (通用加解密与Hash) -- **意图**: 混合加密体系，强制执行内存安全与资源闭环。 -- **API**: NewSymmetric, NewSymmetricAndEraseKey, NewAESCBC, NewAESGCM, NewAESCBCByPassword, NewAESGCMByPassword, NewAsymmetric, NewRSA, NewECDSA, NewED25519, NewX25519, NewRSAByPassword, NewECDSAByPassword, NewED25519ByPassword, NewX25519ByPassword, EncryptBytes, DecryptBytes, TryDecrypt, Sign, Verify, GenerateRSAKeyPair, GenerateECDSAKeyPair, GenerateEd25519KeyPair, GenerateX25519KeyPair, MD5, Sha256, Sha512, HmacSha256, Pkcs5Padding, AnsiX923Padding +### go/shell v1.3.0 +Terminal styling and command execution. +- **API**: `Run`, `Pipeline`, `Style`, `Red`, `Green`, `Blue`, `Yellow` -### crypto-sm (国密专项) -- **意图**: 完全对齐 `go/crypto` 接口，覆盖 SM2/3/4 国密标准。 -- **API**: NewSM2, NewSM2AndEraseKey, NewSM2ByPassword, GenerateSM2KeyPair, Sm3, Sm3ToHex, Sm3ToBase64, NewSM4CBC, NewSM4GCM, NewSM4CBCByPassword, NewSM4GCMByPassword, Encrypt, Decrypt +### go/config v1.3.0 +Configuration loading with env overrides. +- **API**: `Load` -### encoding (编解码引擎) -- **意图**: 语义明确的编解码工具，支持二进制链路与整数填充编码。 -- **API**: Hex, HexToString, UnHex, UnHexFromString, Base64, Base64ToString, UnBase64, UnBase64FromString, UrlBase64, UrlBase64ToString, UnUrlBase64, UnUrlBase64FromString, UrlEncode, UnUrlEncode, HtmlEscape, HtmlUnescape, Utf8Valid, SortJoin, NewIntEncoder, EncodeInt, AppendInt, DecodeInt, FillInt, ExchangeInt, HashInt +### go/log v1.3.0 +Meta-driven asynchronous logging. +- **API**: `Debug`, `Info`, `Warning`, `Error`, `New`, `SetLevel`, `Viewable`, `GetEntry`, `PutEntry` -### id (分布式与数据库ID) -- **意图**: 生成唯一标识符，包含针对 MySQL/PostgreSQL 的写入性能优化，支持语义化并发规模配置。 -- **API**: NewIDMaker, Get8Bytes4KPerSecond, Get9Bytes90KPerSecond, Get10Bytes14MPerSecond, Get11Bytes900MPerSecond, Get12BytesUltraPerSecond, GetForMysql, GetForPostgreSQL +### go/http v1.3.0 +High-performance HTTP client. +- **API**: `NewClient`, `NewClientH2C`, `Get`, `Post`, `Put`, `Delete`, `Do`, `Result`, `Multipart` -### file (IO 与 内存文件系统) -- **意图**: 高性能磁盘 IO、智能序列化及嵌入式资源管理。 -- **API**: Exists, ReadBytes, Read, ReadLines, WriteBytes, Write, Copy, CopyToFile, Remove, Move, Replace, Search, ReadDir, UnmarshalFile, MarshalFile, MarshalFilePretty, PatchFile, Compress, Decompress, Archive, Extract, AddFileToMemory, SafeLoadFileToMemory, LoadFilesToMemoryFromB64, LoadFilesToMemoryFromJSON +### go/redis v1.3.0 +Redis client with Pub/Sub. +- **API**: `GetRedis`, `NewRedis`, `Do`, `Subscribe`, `PUBLISH`, `NewIDMaker` -### safe (内存安全闭环) -- **意图**: 提供底层内存保护、防核心转储及敏感数据安全擦除。 -- **API**: NewSafeBuf, NewSafeBufAndErase, NewSafeString, Open, Close, LockMemory, UnlockMemory, DisableCoreDump, ZeroMemory, MakeSafeToken, EncryptChaCha20, DecryptChaCha20 +### go/db v1.3.0 +Lean database abstraction. +- **API**: `GetDB`, `Sync`, `Insert`, `Update`, `Delete`, `Query`, `Exec`, `Begin` -### config (配置加载) -- **意图**: 从文件（JSON/YAML）加载配置并支持环境变量重写，支持嵌套映射。 -- **API**: Load +### go/discover v1.3.0 +Service discovery and load balancing. +- **API**: `Start`, `NewCaller`, `Get`, `Post`, `SetLoadBalancer`, `SetRoute` -### log (日志系统) -- **意图**: 高性能异步日志记录，内置敏感数据脱敏与多渠道（Console/File/ES）分发。 -- **API**: - - **Logger**: Debug, Info, Warning, Error (带堆栈), Log (通用), DB (带耗时与错误堆栈), Request, Task, Monitor, Statistic - - **管理**: New (创建子 Logger), SetLevel, SetDesensitization - - **显示**: Viewable (格式化为彩色文本) - - **对象池**: GetEntry, PutEntry, WithEntry (支持泛型，极致性能) +### go/service v1.3.0 +Core microservice framework. +- **API**: `Start`, `AsyncStart`, `Register`, `Restful`, `RegisterWebsocket`, `Static`, `Proxy`, `VerifyStruct` -### http (高性能 HTTP 客户端) -- **意图**: 极致精简的请求封装，支持分段下载、泛型绑定与微服务 Header 自动透传。 -- **API**: - - **客户端**: NewClient, NewClientH2C - - **请求**: Get, Post, Put, Delete, Head, MPost (Multipart) - - **响应 (Result)**: String, Bytes, To, ToT (泛型), Save - - **工具**: RelayHeaders (透传列表) +### go/watch v1.3.0 +AI-friendly file watching. +- **API**: `Start`, `EasyStart`, `Watcher` -### 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 -oKV +### go/keys v1.3.0 +Secret management and cross-language encryption tool. +- **API**: `GenerateKey`, `Encrypt`, `Decrypt`, `ExportGo`, `ExportJS`, `ExportPython`, `ExportJava`, `ExportPHP` + +### go/starter v1.3.0 +Service lifecycle and background management. +- **API**: `SetInfo`, `SetPidFile`, `SetLogFile`, `OnStart`, `OnStop`, `OnReload`, `Run`, `AddCmd` + +### go/api v1.3.0 +Third-party API orchestration engine. +- **API**: `Call[T]`, `Load`, `RegisterSigner`, `GetSigner`, `Action` diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..02dbc14 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,103 @@ +[English](README.md) | [简体中文](README.zh-CN.md) + +# @go 开发指引 (INDEX) + +## 设计哲学与原则 + +本项目致力于构建一套**极致精简、消除摩擦、安全可靠、高性能**的 Go 开发基础设施。我们的核心设计理念包括： + +* **统一性**: 提供一套标准化的工具集，减少跨库切换的认知负担。 +* **易用性**: 极简 API 设计，降低门槛，加速开发。 +* **可靠与安全**: 预置安全最佳实践（如加密、内存擦除），确保代码稳健。 +* **高性能**: 深度利用 Go 特性，追求卓越的运行效率。 +* **解决痛点**: 专注于消除类型转换、错误处理、服务发现等过程中的摩擦。 + +--- + +## 模块清单与 API 参考 + +详细文档: https://apigo.cc/go/ + +### go/cast v1.2.10 +语义化类型强转与泛型工具。 +- **API**: `To`, `Convert`, `As`, `ToMap`, `ToSlice`, `FillMap`, `FillSlice`, `ToJSON`, `FromJSON`, `UnmarshalJSON`, `ParseTime`, `FormatTime`, `Int`, `String`, `Bool`, `Duration` + +### go/rand v1.0.6 +高并发场景下的随机数与字节生成。 +- **API**: `Int`, `FastInt`, `Float`, `Byte`, `Bytes`, `Perm`, `Shuffle` + +### go/timer v1.0.7 +高性能时间流管控与退避重试。 +- **API**: `Retry`, `Start`, `WithBackoff`, `WithMaxRetries`, `NewDebouncer`, `NewThrottler`, `NewTimeWheel` + +### go/safe v1.0.7 +内存保护、安全擦除与防核心转储。 +- **API**: `NewSafeBuf`, `NewSafeString`, `LockMemory`, `UnlockMemory`, `DisableCoreDump`, `ZeroMemory`, `EncryptChaCha20`, `DecryptChaCha20` + +### go/encoding v1.1.2 +标准及整数填充编解码。 +- **API**: `Hex`, `Base64`, `UrlEncode`, `HtmlEscape`, `NewIntEncoder`, `EncodeInt`, `DecodeInt`, `HashInt` + +### go/crypto v1.1.1 +主流加解密算法与混合加密体系。 +- **API**: `NewAESGCM`, `NewRSA`, `NewECDSA`, `NewED25519`, `NewX25519`, `EncryptBytes`, `DecryptBytes`, `Sign`, `Verify`, `MD5`, `Sha256`, `HmacSha256` + +### go/crypto-sm v1.1.1 +国密 (SM2/3/4) 标准实现。 +- **API**: `NewSM2`, `Sm3`, `Sm3ToHex`, `NewSM4CBC`, `NewSM4GCM`, `Encrypt`, `Decrypt` + +### go/id v1.0.7 +分布式与数据库性能优化的 ID 生成。 +- **API**: `NewIDMaker`, `Get8Bytes4KPerSecond`, `Get12BytesUltraPerSecond`, `GetForMysql` + +### go/file v1.0.8 +高性能磁盘 IO 与嵌入式内存文件。 +- **API**: `Exists`, `Read`, `Write`, `Copy`, `Move`, `Remove`, `Search`, `UnmarshalFile`, `MarshalFile`, `Archive`, `Compress`, `LoadFileToMemory` + +### go/shell v1.0.6 +终端样式美化与命令链管道执行。 +- **API**: `Run`, `Pipeline`, `Style`, `Red`, `Green`, `Blue`, `Yellow` + +### go/config v1.0.8 +支持环境变量覆盖的配置文件加载。 +- **API**: `Load` + +### go/log v1.1.16 +高性能 Meta 驱动的异步脱敏日志。 +- **API**: `Debug`, `Info`, `Warning`, `Error`, `New`, `SetLevel`, `Viewable`, `GetEntry`, `PutEntry` + +### go/http v1.0.11 +极致精简的高性能 HTTP 客户端。 +- **API**: `NewClient`, `NewClientH2C`, `Get`, `Post`, `Put`, `Delete`, `Do`, `Result`, `Multipart` + +### go/redis v1.0.9 +集成 Pub/Sub 的高性能 Redis 客户端。 +- **API**: `GetRedis`, `NewRedis`, `Do`, `Subscribe`, `PUBLISH`, `NewIDMaker` + +### go/db v1.0.11 +意图优先的极简数据库抽象层。 +- **API**: `GetDB`, `Sync`, `Insert`, `Update`, `Delete`, `Query`, `Exec`, `Begin` + +### go/discover v1.0.11 +极简的服务发现与负载均衡调用。 +- **API**: `Start`, `NewCaller`, `Get`, `Post`, `SetLoadBalancer`, `SetRoute` + +### go/service v1.1.1 +核心微服务框架，支持自动注入与路由映射。 +- **API**: `Start`, `AsyncStart`, `Register`, `Restful`, `RegisterWebsocket`, `Static`, `Proxy`, `VerifyStruct` + +### go/watch v1.1.2 +高性能、AI 友好的文件变动监听。 +- **API**: `Start`, `EasyStart`, `Watcher` + +### go/keys v1.0.1 +密钥管理与跨语言加固加密工具。 +- **API**: `GenerateKey`, `Encrypt`, `Decrypt`, `ExportGo`, `ExportJS`, `ExportPython`, `ExportJava`, `ExportPHP` + +### go/starter v1.0.0 +服务生命周期与后台运行管控。 +- **API**: `SetInfo`, `SetPidFile`, `SetLogFile`, `OnStart`, `OnStop`, `OnReload`, `Run`, `AddCmd` + +### go/api v1.0.4 +第三方 API 调度引擎，消除 SDK 摩擦。 +- **API**: `Call[T]`, `Load`, `RegisterSigner`, `GetSigner`, `Action`