github.com/go-haru/field@v0.0.2/README.md (about) 1 # Field 2 3 [![Go Reference](https://pkg.go.dev/badge/github.com/go-haru/field.svg)](https://pkg.go.dev/github.com/go-haru/field) 4 [![License](https://img.shields.io/github/license/go-haru/field)](./LICENSE) 5 [![Release](https://img.shields.io/github/v/release/go-haru/field.svg?style=flat-square)](https://github.com/go-haru/field/releases) 6 [![Go Test](https://github.com/go-haru/field/actions/workflows/go.yml/badge.svg)](https://github.com/go-haru/field/actions) 7 [![Go Report Card](https://goreportcard.com/badge/github.com/go-haru/field)](https://goreportcard.com/report/github.com/go-haru/field) 8 9 provides key-value list for instant json generation, which drives data collecting feature in [`log`](https://github.com/go-haru/log) and [`errors`](https://github.com/go-haru/errors). 10 11 ## Usage 12 13 When observing or debug with complicated transaction with changeable data, we always need on-site data for metric or analysing purpose. 14 15 With this repo, we can describe named data as `field` and append id to log or error 16 17 ### field 18 19 consists of a string name and arbitrary type content, it can be encoded as json bytes or write to a buffer: 20 21 ```go 22 type Field struct { 23 Key string // name 24 Content // wrapped value 25 } 26 27 func (f Field) EncodeJSON(buffer Buffer) error { ... } 28 29 func (f Field) MarshalJSON() ([]byte, error) { ... } 30 ``` 31 32 We made different functions for common data types, so you need care noting about wrapping value 33 34 ```go 35 func Bool(key string, val bool) Field 36 37 func Bools(key string, valArr []bool) Field 38 39 func Error(key string, err error) Field 40 41 func Float64(key string, val float64) Field 42 43 // ... refer to go doc for more impl 44 ``` 45 Now, we can add field to logger or error (refer to their repo for more info): 46 47 ```go 48 // data for logger 49 logger.With(field.String("traceId", id)).Debug("data created") 50 51 // data for error 52 errors.Note(err, field.String("traceId", id)) 53 54 ``` 55 56 ### fields 57 58 is list of `field`, which provides simple map-like operation and can be encoded to json object 59 60 ```go 61 type Fields []Field 62 63 func (f Fields) Unique() []Field 64 func (f Fields) Has(key string) bool 65 func (f Fields) Get(key string) (Field, bool) 66 func (f Fields) Export() map[string]any 67 func (f Fields) EncodeJSON(buf Buffer) (err error) 68 func (f Fields) MarshalJSON() (dst []byte, err error) 69 ``` 70 71 ## Testing 72 73 All types of field are supposed to be finely tested in [field_test.go](./field_test.go). you ca run test with command: 74 75 ```shell 76 go test ./... 77 ``` 78 [Github Action](https://github.com/go-haru/field/actions) is also enabled for main branch, every release shall pass all tests. 79 80 ## Contributing 81 82 For convenience of PM, please commit all issue to [Document Repo](https://github.com/go-haru/go-haru/issues). 83 84 ## License 85 86 This project is licensed under the `Apache License Version 2.0`. 87 88 Use and contributions signify your agreement to honor the terms of this [LICENSE](./LICENSE). 89 90 Commercial support or licensing is conditionally available through organization email.