|
1 | | -# compressjson |
| 1 | +# compressjson: High-Performance JSON Transcoder (Zstd + Base64) |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The compressjson library provides a high-throughput, type-safe solution for converting Go structs to a compact, text-safe string representation and vice-versa. |
| 6 | +This tool is designed for low-latency, high-throughput scenarios and is ideal for: |
| 7 | +1. High-Speed Caching (e.g., Redis, Memcached) where decompression speed is critical for read latency. |
| 8 | +2. Storage Optimization for large JSON objects in databases. |
| 9 | +3. Efficient Data Transfer in high-load, distributed systems. |
| 10 | + |
| 11 | + |
| 12 | +## Operating Pipeline |
| 13 | +### The encode/decode process is an optimized three-stage chain: |
| 14 | + |
| 15 | +| Step | Operation | Library / Settings | Purpose | |
| 16 | +|------|------------------|----------------------------------------|---------------------------------------------------| |
| 17 | +| 1 | Serialization | `goccy/go-json` | Ultra-fast conversion of Go structs ↔ bytes | |
| 18 | +| 2 | Compression | `klauspost/compress/zstd` <br> `SpeedFastest` | Maximum compression/decompression speed | |
| 19 | +| 3 | Encoding | `encoding/base64` (std lib) | Convert binary data to transport-safe ASCII string | |
| 20 | + |
| 21 | + |
| 22 | +# Usage |
| 23 | +### Installation |
| 24 | +```bash |
| 25 | + go get github.com/spacemagneto/compressjson |
| 26 | +``` |
| 27 | + |
| 28 | +## Example Code |
| 29 | + |
| 30 | +```go |
| 31 | +package main |
| 32 | + |
| 33 | +import ( |
| 34 | + "log" |
| 35 | + |
| 36 | + "github.com/spacemagneto/compressjson" |
| 37 | +) |
| 38 | + |
| 39 | +type User struct { |
| 40 | + ID int `json:"id"` |
| 41 | + Name string `json:"name"` |
| 42 | + Role string `json:"role"` |
| 43 | +} |
| 44 | + |
| 45 | +func main() { |
| 46 | + transcoder := compressjson.NewTranscoder[[]User]() |
| 47 | + |
| 48 | + users := []User{ |
| 49 | + {ID: 1, Name: "Alice", Role: "admin"}, |
| 50 | + {ID: 2, Name: "Bob", Role: "user"}, |
| 51 | + {ID: 3, Name: "Charlie", Role: "moderator"}, |
| 52 | + } |
| 53 | + |
| 54 | + encoded, err := transcoder.Encode(users) |
| 55 | + if err != nil { |
| 56 | + log.Fatalf("encode failed: %v", err) |
| 57 | + } |
| 58 | + |
| 59 | + var decoded []User |
| 60 | + decoded, err = transcoder.Decode(encoded) |
| 61 | + if err != nil { |
| 62 | + log.Fatalf("decode failed: %v", err) |
| 63 | + } |
| 64 | + |
| 65 | + ... |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +### Testing Support |
| 70 | + |
| 71 | +For users integrating and testing compressjson in various scenarios (e.g., handling specific errors, simulating compression/decompression outcomes), the repository includes a dedicated transcoder mock pkg that provides the MockTranscoder implementation. This facilitates robust unit testing and integration testing without requiring actual Zstd operations. |
0 commit comments