github.com/jxskiss/gopkg/v2@v2.14.9-0.20240514120614-899f3e7952b4/README.md (about) 1 # gopkg 2 3 [][godoc] 4 [][goreport] 5 [][issues] 6 [][release] 7 [][license] 8 9 [godoc]: https://pkg.go.dev/github.com/jxskiss/gopkg/v2 10 [goreport]: https://goreportcard.com/report/github.com/jxskiss/gopkg/v2 11 [issues]: https://github.com/jxskiss/gopkg/issues 12 [release]: https://github.com/jxskiss/gopkg/releases 13 [license]: https://github.com/jxskiss/gopkg/blob/master/LICENSE 14 15 This repository contains many frequently used small packages, it is designed 16 to have reasonable trade-off between generic, performance and API friendliness. 17 It helps to make life easier! 18 19 ## Status 20 21 The master branch (v2) requires Go 1.18+, it uses the generics feature available in Go 1.18+. 22 For version compatibility policy, please refer to the following docs. 23 24 The v1 branch contains the legacy code. 25 there shall be no further changes to the v1 APIs. 26 27 ## Code layout 28 29 Packages under `exp` directory are considered experimental and unreliable, 30 the API may change arbitrarily, or even disappear some day without any notice. 31 They do not follow the Go 1 compatibility promise. 32 When a package is tested enough, and the API is considered stable, it may be promoted 33 as "stable" and moved under the top directory. 34 35 Packages under the top directory are considered stable, they follow the 36 Go 1 compatibility promise and the Semantic Versioning spec. 37 Packages under the top directory may depend on `exp` packages but must keep 38 reasonable API compatibility and versioning. 39 40 ## Packages 41 42 1. `collection/heapx` contains a ready-to-use heap implementation based on `container/heap`, 43 and a generic priority queue based on heap data structure. 44 45 1. `collection/set` provides generic set data structures. 46 47 1. `confr` provides a simple yet powerful configuration loader. 48 49 1. `easy` contains many handy utilities as a complementary to the standard library. 50 51 1. `easy/ezdbg` provides easy to use utilities which helps to do quick logging in development. 52 53 1. `easy/ezhttp` contains some utilities to work with HTTP requests. 54 55 1. `easy/ezmap` contains some utilities to manipulate map data structure. 56 57 1. `easy/yamlx` extends the YAML unmarshaler with extra features, such as 58 "reading environment variables" and "file including", 59 "reference using gjson JSON path expression", "reference using named variables", 60 "function calling", etc. 61 62 1. `encrypt/crypto` contains some encryption utilities. 63 64 1. `exp/kvutil` contains experimental utilities to work with key-value cache. 65 66 1. `infra/acache` contains an async cache which can be used to fetch and update the 67 latest data periodically and supports expiring a key if it's unused for a period. 68 69 1. `infra/errcode` provides error code registry to manage error codes and messages. 70 Standardized error codes greatly helps in large scale microservices. 71 72 1. `infra/logid` provides log ID generators to help service observability, such as 73 tracing, metrics, etc. 74 75 1. `perf/bbp` provides efficient byte buffer pools with anti-memory-waste protection. 76 77 1. `perf/gopool` is a fork of `github.com/bytedance/gopkg/util/gopool` 78 with opinionated changes. 79 It's a high-performance goroutine pool which aims to reuse goroutines 80 and limit the number of goroutines. 81 82 1. `perf/json` provides a drop-in replacement of `encoding/json` and extended features. 83 By default, it uses [jsoniter] in underlying, which has better performance than `encoding/json`. 84 The underlying implementation is change-able and change-able on-the-fly. 85 `amd64` users may switch to [bytedance/sonic] implementation for best performance 86 in the cost of a little less maturity. 87 Check [README.md](./perf/json/README.md) for detailed introduction. 88 89 1. `perf/lru` is a high performance implementation of the LRU cache, it features pre-allocation, 90 item expiration, friendly and type-safe APIs for commonly used key types. 91 It also provides a sharded version for heavy lock contention use-case. 92 93 1. `unsafe/forceexport` force exports private types and functions of other packages. As you might 94 expect, this package is unsafe and fragile and shouldn't be used in production, it is 95 mainly for testing purpose. 96 97 1. `unsafe/reflectx` contains many utilities to work with reflection, providing convenient APIs 98 or better performance. 99 100 1. `utils/ptr` provides small functions to work with pointer types, such as copying value as pointer, 101 converting integer to string pointer, or dereference pointer which may be nil, etc. 102 It helps to reduce duplicate code and makes code clearer and simpler. 103 104 1. `utils/retry` implements frequently used strategies and options to do retry when error 105 occurs, with various hooks and circuit breaker to protect system overload. 106 107 1. `utils/sqlutil` provides utilities to work with relational database ORM libraries, 108 it keeps simple and can work with `database/sql` and many ORM libraries. 109 110 1. `utils/structtag` contains some handy utilities to work with struct tags. 111 112 1. `utils/strutil` provides utilities to work with string data as supplement to the standard 113 libraries `strings` and `unicode/utf8`. 114 115 1. `utils/timeutil` provides utilities to process time related things. 116 117 1. `utils/vdutil` helps to do data validation. 118 119 1. `zlog` provides opinionated high-level logging facilities based on go.uber.org/zap. 120 121 See [GoDoc][godoc] for detailed online docs. 122 123 [bytedance/sonic]: https://github.com/bytedance/sonic 124 [jsoniter]: https://github.com/json-iterator/go 125 [zap]: https://github.com/uber-go/zap 126 127 Also note that the following packages, which were originally located in this repository, 128 have been moved to standalone repositories: 129 130 1. `base62` is a compact and high performance implementation of base62 algorithm for Golang. 131 It has been moved to https://github.com/jxskiss/base62. 132 133 1. `mcli` is a minimal but very powerful and magic cli library for Go. 134 It has been moved to https://github.com/jxskiss/mcli.