forked from jshiffer/matterbridge
82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
|
# [slog](https://pkg.go.dev/log/slog) shim
|
||
|
|
|
||
|
|
[](https://github.com/sagikazarmark/slog-shim/actions/workflows/ci.yaml)
|
||
|
|
[](https://pkg.go.dev/mod/github.com/sagikazarmark/slog-shim)
|
||
|
|
|
||
|
|
[](https://builtwithnix.org)
|
||
|
|
|
||
|
|
Go 1.21 introduced a [new structured logging package](https://golang.org/doc/go1.21#slog), `log/slog`, to the standard library.
|
||
|
|
Although it's been eagerly anticipated by many, widespread adoption isn't expected to occur immediately,
|
||
|
|
especially since updating to Go 1.21 is a decision that most libraries won't make overnight.
|
||
|
|
|
||
|
|
Before this package was added to the standard library, there was an _experimental_ version available at [golang.org/x/exp/slog](https://pkg.go.dev/golang.org/x/exp/slog).
|
||
|
|
While it's generally advised against using experimental packages in production,
|
||
|
|
this one served as a sort of backport package for the last few years,
|
||
|
|
incorporating new features before they were added to the standard library (like `slices`, `maps` or `errors`).
|
||
|
|
|
||
|
|
This package serves as a bridge, helping libraries integrate slog in a backward-compatible way without having to immediately update their Go version requirement to 1.21. On Go 1.21 (and above), it acts as a drop-in replacement for `log/slog`, while below 1.21 it falls back to `golang.org/x/exp/slog`.
|
||
|
|
|
||
|
|
**How does it achieve backwards compatibility?**
|
||
|
|
|
||
|
|
Although there's no consensus on whether dropping support for older Go versions is considered backward compatible, a majority seems to believe it is.
|
||
|
|
(I don't have scientific proof for this, but it's based on conversations with various individuals across different channels.)
|
||
|
|
|
||
|
|
This package adheres to that interpretation of backward compatibility. On Go 1.21, the shim uses type aliases to offer the same API as `slog/log`.
|
||
|
|
Once a library upgrades its version requirement to Go 1.21, it should be able to discard this shim and use `log/slog` directly.
|
||
|
|
|
||
|
|
For older Go versions, the library might become unstable after removing the shim.
|
||
|
|
However, since those older versions are no longer supported, the promise of backward compatibility remains intact.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```shell
|
||
|
|
go get github.com/sagikazarmark/slog-shim
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
Import this package into your library and use it in your public API:
|
||
|
|
|
||
|
|
```go
|
||
|
|
package mylib
|
||
|
|
|
||
|
|
import slog "github.com/sagikazarmark/slog-shim"
|
||
|
|
|
||
|
|
func New(logger *slog.Logger) MyLib {
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
When using the library, clients can either use `log/slog` (when on Go 1.21) or `golang.org/x/exp/slog` (below Go 1.21):
|
||
|
|
|
||
|
|
```go
|
||
|
|
package main
|
||
|
|
|
||
|
|
import "log/slog"
|
||
|
|
|
||
|
|
// OR
|
||
|
|
|
||
|
|
import "golang.org/x/exp/slog"
|
||
|
|
|
||
|
|
mylib.New(slog.Default())
|
||
|
|
```
|
||
|
|
|
||
|
|
**Make sure consumers are aware that your API behaves differently on different Go versions.**
|
||
|
|
|
||
|
|
Once you bump your Go version requirement to Go 1.21, you can drop the shim entirely from your code:
|
||
|
|
|
||
|
|
```diff
|
||
|
|
package mylib
|
||
|
|
|
||
|
|
- import slog "github.com/sagikazarmark/slog-shim"
|
||
|
|
+ import "log/slog"
|
||
|
|
|
||
|
|
func New(logger *slog.Logger) MyLib {
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
The project is licensed under a [BSD-style license](LICENSE).
|