mapset/基于golangci-lint修改代码;

cmd/http-reflect-server/go.mod

@@ -0,0 +1,8 @@
+module git.blauwelle.com/go/crate/cmd/http-reflect-server
+
+go 1.20
+
+require (
+	git.blauwelle.com/go/crate/exegroup v0.3.0
+	git.blauwelle.com/go/crate/log v0.6.0
+)

cmd/http-reflect-server/go.sum

@@ -0,0 +1,4 @@
+git.blauwelle.com/go/crate/exegroup v0.3.0 h1:TBLygDztECKc67NeIIBsFDxlA4KcJpbOmafqqRuKRcM=
+git.blauwelle.com/go/crate/exegroup v0.3.0/go.mod h1:DJoID54YI5WFHGHoTCjBao8oS3HFRzwbWMZW6P57AIQ=
+git.blauwelle.com/go/crate/log v0.6.0 h1:s/TeJUaV/Y8hHaz/3FumdbwQWCbRMmOx8prrNmByJHs=
+git.blauwelle.com/go/crate/log v0.6.0/go.mod h1:jfVfpRODZTA70A8IkApVeGsS1zfLk1D77sLWZM/w+L0=

cmd/http-reflect-server/handler.go

@@ -0,0 +1,155 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"git.blauwelle.com/go/crate/log"
+)
+
+func newHandler() http.HandlerFunc {
+	return func(rw http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+
+		var response Response
+
+		response.Request.TransferEncoding = r.TransferEncoding
+		response.Request.Proto = r.Proto
+		response.Request.Host = r.Host
+		response.Request.Method = r.Method
+		response.Request.URL = r.URL.String()
+		response.Request.RemoteAddr = r.RemoteAddr
+		response.Request.RequestURI = r.RequestURI
+		response.Request.Header = r.Header
+		response.Request.ContentLength = r.ContentLength
+
+		ctx := r.Context()
+
+		duration := time.Since(start)
+		code := http.StatusOK
+		var message string
+
+		if r.ContentLength > 0 {
+			if body, err := readBody(ctx, r); err != nil {
+				response.Error = err.Error()
+			} else {
+				response.Request.Body = body
+			}
+		}
+
+		rw.Header().Set("Content-Type", "application/json")
+		rw.WriteHeader(code)
+
+		end := time.Now()
+		response.ServeDuration = end.Sub(start).String()
+		encoder := json.NewEncoder(rw)
+		encoder.SetEscapeHTML(true)
+		encoder.SetIndent("", "  ")
+		err := encoder.Encode(response)
+		if err != nil {
+			log.Errorf(ctx, "json marshal: %s", err.Error())
+		}
+
+		log.WithFields(
+			log.Field("code", code),
+			log.Field("duration", duration.String()),
+		).Info(ctx, message)
+
+	}
+}
+
+type Response struct {
+	Error         string          `json:"error,omitempty"`
+	ServeDuration string          `json:"serveDuration"`
+	Request       ResponseRequest `json:"request"`
+}
+
+type MultipartFormFileInfo struct {
+	MIMEHeader map[string][]string `json:"mimeHeader"`
+	Filename   string              `json:"filename"`
+	Size       int64               `json:"size"`
+}
+
+type MultipartForm struct {
+	Values map[string][]string                `json:"values"`
+	Files  map[string][]MultipartFormFileInfo `json:"files"`
+}
+
+type ResponseRequest struct {
+	Header           http.Header `json:"header"`
+	Body             any         `json:"body"`
+	Proto            string      `json:"proto"`
+	Host             string      `json:"host"`
+	Method           string      `json:"method"`
+	URL              string      `json:"url"`
+	RemoteAddr       string      `json:"remoteAddr"`
+	RequestURI       string      `json:"requestUri"`
+	TransferEncoding []string    `json:"transferEncoding"`
+	ContentLength    int64       `json:"contentLength"`
+}
+
+func readBody(ctx context.Context, r *http.Request) (any, error) {
+	contentType := r.Header.Get("Content-Type")
+	switch {
+	case contentType == "":
+		return nil, nil
+	case strings.HasPrefix(contentType, "application/json"):
+		b, err := io.ReadAll(r.Body)
+		if err != nil {
+			err = fmt.Errorf("read: %w", err)
+			log.Error(ctx, err.Error())
+			return nil, err
+		}
+		if err := json.Unmarshal(b, new(any)); err != nil {
+			log.Error(ctx, err.Error())
+			return nil, err
+		}
+		return json.RawMessage(b), nil
+	case contentType == "application/x-www-form-urlencoded":
+		fallthrough
+	case strings.HasPrefix(contentType, "application/xml"):
+		fallthrough
+	case strings.HasPrefix(contentType, "text/"):
+		b, err := io.ReadAll(r.Body)
+		if err != nil {
+			panic(err)
+		}
+		return string(b), nil
+		//case :
+	case strings.HasPrefix(contentType, "multipart/form-data"):
+		if err := r.ParseMultipartForm(16 * 1024 * 1024); err != nil {
+			log.Error(ctx, err.Error())
+			return nil, err
+		}
+		body := MultipartForm{
+			Values: make(map[string][]string),
+			Files:  make(map[string][]MultipartFormFileInfo),
+		}
+		body.Values = r.MultipartForm.Value
+		for k, fs := range r.MultipartForm.File {
+			for _, f := range fs {
+				body.Files[k] = append(body.Files[k], MultipartFormFileInfo{
+					Filename:   f.Filename,
+					MIMEHeader: f.Header,
+					Size:       f.Size,
+				})
+			}
+		}
+		return body, nil
+	}
+	b, err := io.ReadAll(r.Body)
+	if err != nil {
+		err = fmt.Errorf("read: %w", err)
+		log.Error(ctx, err.Error())
+		return nil, err
+	}
+	if len(b) > 96 {
+		b = b[:96]
+	}
+	return b, nil
+}

cmd/http-reflect-server/main.go

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"net/http"
+
+	"git.blauwelle.com/go/crate/exegroup"
+	"git.blauwelle.com/go/crate/log"
+	"git.blauwelle.com/go/crate/log/logsdk"
+	"git.blauwelle.com/go/crate/log/logsdk/logjson"
+)
+
+var port = flag.Int("port", 8080, "HTTP Port")
+
+func main() {
+	flag.Parse()
+	log.Logger().AddProcessor(logsdk.AllLevels, logjson.New())
+	g := exegroup.Default()
+	mux := http.NewServeMux()
+	var handler http.Handler = mux
+	mux.HandleFunc("/", newHandler())
+	g.New().WithGoStop(exegroup.HttpListenAndServe(*port, handler))
+	log.Infof(context.Background(), "listening %d", *port)
+	log.Error(context.Background(), "exit: ", g.Run(context.Background()))
+}

exegroup/.golangci.yaml

@@ -0,0 +1,141 @@
+## 基于 golangci-lint@v1.52.2
+run:
+  timeout: 1m
+  build-tags: [ ]
+  skip-dirs: [ ]
+  skip-files: [ ]
+linters:
+  disable-all: true
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - typecheck
+    - unused
+    - asasalint
+    - asciicheck
+    - bidichk
+    - bodyclose
+    - containedctx
+    - cyclop
+    - dupl
+    - durationcheck
+    - errname
+    - errorlint
+    - exhaustive
+    - exportloopref
+    - funlen
+    - gocheckcompilerdirectives
+    - gochecknoinits
+    - goconst
+    - gocritic
+    - gocyclo
+    - goimports
+    - gomnd
+    - goprintffuncname
+    - gosec
+    - lll
+    - loggercheck
+    - makezero
+    - nakedret
+    - nestif
+    - nilnil
+    - noctx
+    - nolintlint
+    - prealloc
+    - predeclared
+    - promlinter
+    - reassign
+    - revive
+    - rowserrcheck
+    - stylecheck
+    - tenv
+    - testableexamples
+    - testpackage
+    - tparallel
+    - unconvert
+    - unparam
+    - usestdlibvars
+    - wastedassign
+    - whitespace
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+    exclude-functions: [ ]
+  govet:
+    enable-all: true
+    disable: [ ]
+  cyclop:
+    max-complexity: 10
+    package-average: 0.0
+  dupl:
+    threshold: 150
+  exhaustive:
+    check:
+      - switch
+      - map
+  funlen:
+    lines: 100
+    statements: 60
+  gocritic:
+    disabled-checks:
+      - commentFormatting
+    settings:
+      captLocal:
+        paramsOnly: false
+      underef:
+        skipRecvDeref: false
+  gocyclo:
+    min-complexity: 20
+  gomnd:
+    ignored-functions:
+      - os.Chmod
+      - os.Mkdir
+      - os.MkdirAll
+      - os.OpenFile
+      - os.WriteFile
+      - prometheus.ExponentialBuckets
+      - prometheus.ExponentialBucketsRange
+      - prometheus.LinearBuckets
+  lll:
+    line-length: 240
+  nakedret:
+    max-func-lines: 10
+  nestif:
+    min-complexity: 5
+  predeclared:
+    ignore: ""
+    q: false
+  reassign:
+    patterns:
+      - ".*"
+  rowserrcheck:
+    packages:
+      - github.com/jmoiron/sqlx
+  tenv:
+    all: true
+  usestdlibvars:
+    time-month: true
+    time-layout: true
+    crypto-hash: true
+    default-rpc-path: true
+    os-dev-null: true
+    sql-isolation-level: true
+    tls-signature-scheme: true
+    constant-kind: true
+    syslog-priority: true
+issues:
+  max-same-issues: 10
+  exclude-rules:
+    - source: "//noinspection"
+      linters: [ gocritic ]
+    - path: "_test\\.go"
+      linters:
+        - bodyclose
+        - dupl
+        - funlen
+        - goconst
+        - gosec
+        - noctx

exegroup/group.go

@@ -123,8 +123,8 @@ func (g *Group) start(ctx context.Context, c chan error) {
 	}
 }
 
-func (g *Group) wait(c chan error, cancel context.CancelFunc) (err error) {
+func (g *Group) wait(c chan error, cancel context.CancelFunc) error {
-	err = <-c
+	err := <-c
 	cancel()
 	ctx := context.Background()
 	if g.cfg.stopTimeout > 0 {
@@ -144,10 +144,10 @@ func (g *Group) wait(c chan error, cancel context.CancelFunc) (err error) {
 		select {
 		case <-c:
 		case <-ctx.Done():
-			return
+			return err
 		}
 	}
-	return
+	return err
 }
 
 type config struct {

exegroup/group_test.go

@@ -2,8 +2,9 @@ package exegroup_test
 
 import (
 	"context"
-	"git.blauwelle.com/go/crate/exegroup"
 	"log"
+
+	"git.blauwelle.com/go/crate/exegroup"
 )
 
 func Example_defaultGroup() {
@@ -13,4 +14,5 @@ func Example_defaultGroup() {
 		return ctx.Err()
 	})
 	log.Println("exit:", g.Run(context.Background()))
+	// Output:
 }

exegroup/httpserver.go

@@ -2,14 +2,20 @@ package exegroup
 
 import (
 	"context"
-	"fmt"
+	"net"
 	"net/http"
+	"strconv"
 	"sync/atomic"
+	"time"
 )
 
-// HttpListenAndServe 提供 [http.Server] 的启动和停止函数;
+// HTTPListenAndServe 提供 [http.Server] 的启动和停止函数;
-func HttpListenAndServe(port int, handler http.Handler) (func(ctx context.Context) error, func(ctx context.Context)) {
+func HTTPListenAndServe(port int, handler http.Handler) (func(ctx context.Context) error, func(ctx context.Context)) {
-	server := &http.Server{Addr: fmt.Sprintf(":%d", port), Handler: handler}
+	server := &http.Server{
+		Addr:              net.JoinHostPort("", strconv.Itoa(port)),
+		Handler:           handler,
+		ReadHeaderTimeout: time.Second,
+	}
 	inShutdown := &atomic.Bool{}
 	c := make(chan error, 1)
 	goFunc := func(_ context.Context) error {

log/.golangci.yaml

@@ -0,0 +1,141 @@
+## 基于 golangci-lint@v1.52.2
+run:
+  timeout: 1m
+  build-tags: [ ]
+  skip-dirs: [ ]
+  skip-files: [ ]
+linters:
+  disable-all: true
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - typecheck
+    - unused
+    - asasalint
+    - asciicheck
+    - bidichk
+    - bodyclose
+    - containedctx
+    - cyclop
+    - dupl
+    - durationcheck
+    - errname
+    - errorlint
+    - exhaustive
+    - exportloopref
+    - funlen
+    - gocheckcompilerdirectives
+    - gochecknoinits
+    - goconst
+    - gocritic
+    - gocyclo
+    - goimports
+    - gomnd
+    - goprintffuncname
+    - gosec
+    - lll
+    - loggercheck
+    - makezero
+    - nakedret
+    - nestif
+    - nilnil
+    - noctx
+    - nolintlint
+    - prealloc
+    - predeclared
+    - promlinter
+    - reassign
+    - revive
+    - rowserrcheck
+    - stylecheck
+    - tenv
+    - testableexamples
+    - testpackage
+    - tparallel
+    - unconvert
+    - unparam
+    - usestdlibvars
+    - wastedassign
+    - whitespace
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+    exclude-functions: [ ]
+  govet:
+    enable-all: true
+    disable: [ ]
+  cyclop:
+    max-complexity: 10
+    package-average: 0.0
+  dupl:
+    threshold: 150
+  exhaustive:
+    check:
+      - switch
+      - map
+  funlen:
+    lines: 100
+    statements: 60
+  gocritic:
+    disabled-checks:
+      - commentFormatting
+    settings:
+      captLocal:
+        paramsOnly: false
+      underef:
+        skipRecvDeref: false
+  gocyclo:
+    min-complexity: 20
+  gomnd:
+    ignored-functions:
+      - os.Chmod
+      - os.Mkdir
+      - os.MkdirAll
+      - os.OpenFile
+      - os.WriteFile
+      - prometheus.ExponentialBuckets
+      - prometheus.ExponentialBucketsRange
+      - prometheus.LinearBuckets
+  lll:
+    line-length: 240
+  nakedret:
+    max-func-lines: 10
+  nestif:
+    min-complexity: 5
+  predeclared:
+    ignore: ""
+    q: false
+  reassign:
+    patterns:
+      - ".*"
+  rowserrcheck:
+    packages:
+      - github.com/jmoiron/sqlx
+  tenv:
+    all: true
+  usestdlibvars:
+    time-month: true
+    time-layout: true
+    crypto-hash: true
+    default-rpc-path: true
+    os-dev-null: true
+    sql-isolation-level: true
+    tls-signature-scheme: true
+    constant-kind: true
+    syslog-priority: true
+issues:
+  max-same-issues: 10
+  exclude-rules:
+    - source: "//noinspection"
+      linters: [ gocritic ]
+    - path: "_test\\.go"
+      linters:
+        - bodyclose
+        - dupl
+        - funlen
+        - goconst
+        - gosec
+        - noctx

log/README.md

@@ -0,0 +1,98 @@
+# log 日志
+
+安装: `go get git.blauwelle.com/go/crate/log`
+
+简单使用方式
+
+```go
+package main
+
+import (
+	"context"
+
+	"git.blauwelle.com/go/crate/log"
+	"git.blauwelle.com/go/crate/log/logsdk"
+	"git.blauwelle.com/go/crate/log/logsdk/logjson"
+)
+
+func main() {
+	log.Logger().AddProcessor(logsdk.AllLevels, logjson.New()) // 添加日志处理器, 默认没有处理器(日志生成后会被忽略)
+	log.Info(context.Background(), "hello world")              // 打印日志, Context 会被传递给日志处理器
+}
+```
+
+`log` 模块包含日志处理的代码, 由 3 个包组成:
+
+1. [logsdk](./logsdk): 日志实现;
+2. [logjson](./logsdk/logjson): 控制台 JSON 日志处理器(`Processor`);
+3. [log](.): 根目录, 提供全局 `Logger`, 把 `Logger` / `Entry` 相关的方法封装成函数.
+
+## 基本概念
+
+`logsdk` 由 `Logger`, `Entry`, `Processor` 3 部分组成, 其中只有 `Processor` 是接口类型.
+`Logger` 主要负责全局的日志配置, `Logger` 可以通过内嵌的 `Entry` 值对象实现日志处理.
+`Entry` 负责保存局部的的日志配置, 比如覆盖 `Logger` 的 `Caller` 开关或设置日志的时间属性; `Entry` 生成单条日志(`ReadonlyEntry`), 并调用 `Processor` 输出日志.
+
+## 使用方式
+
+### 获取全局 `Logger` 对象
+
+一般只用来配置全局 `Logger` 对象(通过 `Set*` 或 `AddProcessor` 方法)
+
+```go
+log.Logger()
+```
+
+### 修改 `Logger` 配置
+
+`Logger` 提供以下方法用来修改全局配置
+
+- `AddProcessor` 新增处理器;
+- `SetLevel` 设置全局日志等级, 只有小于 `Logger` 上设置的日志等级的日志才会被生成;
+- `SetCallerSkip` 设置从 `runtime` 包获取调用信息时的 `skip` 参数, 为了方便使用, 0 表示调用 `Logger` / `Entry` 的日志方法处;
+- `SetReportCaller` 设置生成调用信息;
+- `SetReportStack` 设置生成调用栈;
+- `SetReportStackLevel` 当日志等级小于设定值时强制生成调用栈;
+- `Reset` 把 Logger 恢复到初始状态;
+- `SetExit` 设置 `Logger` 的退出函数(`Logger.Exit`), 当日志等级为 `LevelFatal` 时调用这个函数;
+
+### 日志生成
+
+`Entry` 负责生成日志, `Logger` 通过内嵌 `Entry` 值对象的方式获得 `Entry` 的方法.
+`Entry` 提供以下方法来修改局部配置, `log` 包提供了对应的函数调用
+
+- `AddCallerSkip` 增加通过 `runtime` 获取调用信息时的 `skip` 值, `skip` 可以是负值;
+- `WithField` 添加1组键值对;
+- `WithFields` 添加键值对;
+- `WithTime` 设置生成的日志的时间;
+- `WithReportCaller` 覆盖 `Logger` 上的生成调用信息的设置;
+- `WithReportStack` 覆盖 `Logger` 上的生成调用栈的设置;
+
+`Entry` 提供以下方法来生成日志, 所有方法的第 1 个参数都是 `context.Context`, `Log` 方法的参数包含日志等级和日志消息,
+其他方法的参数是日志消息.
+所有方法除了 `Log` 外日志等级从高到底(严重程度从低到高), 这些方法有对应的格式化方法(如 `Info` 和 `Infof`).
+`log` 包提供了对应的函数调用
+
+- `Log`
+- `Trace`
+- `Debug`
+- `Info`
+- `Warn`
+- `Error`
+- `Fatal`
+- `Panic`
+
+### 其他用法
+
+关闭日志生成 `log.Logger().SetLevel(logsdk.LevelDisabled)`
+
+关闭强制生成调用栈 `log.Logger().SetReportStackLevel(logsdk.LevelDisabled)`
+
+mock 实现 mock 日志处理器对生成的日志进行处理
+
+---
+
+## 日志处理器
+
+- [logsdk/logjson](logsdk/logjson) 控制台 JSON 日志
+- [go get git.blauwelle.com/go/crate/logotel](../logotel) OpenTelemetry 日志

log/go.mod

@@ -0,0 +1,3 @@
+module git.blauwelle.com/go/crate/log
+
+go 1.20

log/log.go

@@ -0,0 +1,157 @@
+// log 实现了全局的日志处理
+//
+// 这个包里定义的函数都是对全局的 [logsdk.Logger] 对象的封装.
+// 全局的 Logger 不能重新赋值,
+// Logger 的配置方法和日志方法可以并发调用.
+
+package log
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"git.blauwelle.com/go/crate/log/logsdk"
+)
+
+type (
+	Level = logsdk.Level
+)
+
+const (
+	LevelPanic = logsdk.LevelPanic
+	LevelFatal = logsdk.LevelFatal
+	LevelError = logsdk.LevelError
+	LevelWarn  = logsdk.LevelWarn
+	LevelInfo  = logsdk.LevelInfo
+	LevelDebug = logsdk.LevelDebug
+	LevelTrace = logsdk.LevelTrace
+)
+
+// Field 返回键值对
+func Field(key string, value any) logsdk.KV {
+	return logsdk.KV{
+		Value: value,
+		Key:   key,
+	}
+}
+
+// AddCallerSkip 增加调用 [runtime.Callers] 时的 skip 参数,
+// 当通过装饰器等方式封装 Entry 导致增加调用 Entry 方法的深度时使用 AddCallerSkip 调整 skip,
+// 直接在需要日志的地方调用 Entry 的方法时不需要 AddCallerSkip.
+func AddCallerSkip(n int) logsdk.Entry {
+	return globalLogger.AddCallerSkip(n)
+}
+
+// WithField 增加1组键值对
+func WithField(key string, value any) logsdk.Entry {
+	return globalLogger.WithField(key, value)
+}
+
+// WithFields 增加键值对
+func WithFields(fields ...logsdk.KV) logsdk.Entry {
+	return globalLogger.WithFields(fields...)
+}
+
+// WithTime 设置日志的时间,
+// Entry 默认使用调用 Log 等最终方法的时间作为日志的时间.
+func WithTime(t time.Time) logsdk.Entry {
+	return globalLogger.WithTime(t)
+}
+
+// WithReportCaller 设置 [logsdk.Entry] 是否收集调用记录
+func WithReportCaller(reportCaller bool) logsdk.Entry {
+	return globalLogger.WithReportCaller(reportCaller)
+}
+
+// WithReportStack 设置 [logsdk.Entry] 是否收集调用栈
+func WithReportStack(reportStack bool) logsdk.Entry {
+	return globalLogger.WithReportStack(reportStack)
+}
+
+// Log 输出日志
+func Log(ctx context.Context, level Level, args ...any) {
+	globalLogger.AddCallerSkip(1).Log(ctx, level, fmt.Sprint(args...))
+}
+
+// Trace 输出 LevelTrace 等级的日志
+func Trace(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Trace(ctx, args...)
+}
+
+// Debug 输出 LevelDebug 等级的日志
+func Debug(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Debug(ctx, args...)
+}
+
+// Info 输出 LevelInfo 等级的日志
+func Info(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Info(ctx, args...)
+}
+
+// Warn 输出 LevelWarn 等级的日志
+func Warn(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Warn(ctx, args...)
+}
+
+// Error 输出 LevelError 等级的日志
+func Error(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Error(ctx, args...)
+}
+
+// Fatal 输出 LevelFatal 等级的日志并调用 Logger.Exit
+func Fatal(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Fatal(ctx, args...)
+}
+
+// Panic 输出 LevelPanic 等级的日志后执行 panic,
+// 即使 Logger 日志等级高于 LevelPanic 也会 panic.
+func Panic(ctx context.Context, args ...any) {
+	globalLogger.AddCallerSkip(1).Panic(ctx, args...)
+}
+
+// Logf 格式化输出日志
+func Logf(ctx context.Context, level Level, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Logf(ctx, level, format, args...)
+}
+
+// Tracef 格式化输出 LevelTrace 等级的日志
+func Tracef(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Tracef(ctx, format, args...)
+}
+
+// Debugf 格式化输出 LevelDebug 等级的日志
+func Debugf(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Debugf(ctx, format, args...)
+}
+
+// Infof 格式化输出 LevelInfo 等级的日志
+func Infof(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Infof(ctx, format, args...)
+}
+
+// Warnf 格式化输出 LevelWarn 等级的日志
+func Warnf(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Warnf(ctx, format, args...)
+}
+
+// Errorf 格式化输出 LevelError 等级的日志
+func Errorf(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Errorf(ctx, format, args...)
+}
+
+// Fatalf 格式化输出 LevelFatal 等级的日志并调用 Logger.Exit
+func Fatalf(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Fatalf(ctx, format, args...)
+}
+
+// Panicf 格式化输出 LevelPanic 等级的日志
+func Panicf(ctx context.Context, format string, args ...any) {
+	globalLogger.AddCallerSkip(1).Panicf(ctx, format, args...)
+}
+
+// Logger 返回全局 logger, 通常用来在程序启动时对全局 logger 进行配置,
+// 业务代码处理日志时直接使用这个包里定义的日志函数.
+func Logger() *logsdk.Logger {
+	return globalLogger
+}

log/logsdk/entry.go

@@ -0,0 +1,216 @@
+package logsdk
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+// Entry 包含日志所需的全部中间信息并负责输出日志
+type Entry struct {
+	logger            *Logger
+	time              time.Time
+	fields            []KV
+	callerSkip        int
+	reportCaller      bool
+	isReportCallerSet bool
+	reportStack       bool
+	isReportStackSet  bool
+	initialized       bool
+}
+
+func (entry Entry) copy() Entry {
+	if entry.initialized {
+		return entry
+	}
+	return entry.logger.newEntry()
+}
+
+// AddCallerSkip 增加调用 [runtime.Callers] 时的 skip 参数,
+// 当通过装饰器等方式封装 Entry 导致增加调用 Entry 方法的深度时使用 AddCallerSkip 调整 skip,
+// 直接在需要日志的地方调用 Entry 的方法时不需要 AddCallerSkip.
+func (entry Entry) AddCallerSkip(n int) Entry {
+	newEntry := entry.copy()
+	newEntry.callerSkip += n
+	return newEntry
+}
+
+// WithField 增加1组键值对
+func (entry Entry) WithField(key string, value any) Entry {
+	return entry.WithFields(Field(key, value))
+}
+
+// WithFields 增加键值对
+func (entry Entry) WithFields(fields ...KV) Entry {
+	newEntry := entry.copy()
+	newEntry.fields = make([]KV, len(entry.fields)+len(fields))
+	copy(newEntry.fields, entry.fields)
+	copy(newEntry.fields, fields)
+	return newEntry
+}
+
+// WithTime 设置日志的时间,
+// Entry 默认使用调用 Log 等最终方法的时间作为日志的时间.
+func (entry Entry) WithTime(t time.Time) Entry {
+	newEntry := entry.copy()
+	newEntry.time = t
+	return newEntry
+}
+
+// GetReportCaller 获取是否收集调用记录,
+// 默认使用 Logger 上的对应配置.
+func (entry Entry) GetReportCaller() bool {
+	if entry.isReportCallerSet {
+		return entry.reportCaller
+	}
+	return entry.logger.GetReportCaller()
+}
+
+// WithReportCaller 设置是否收集调用记录
+func (entry Entry) WithReportCaller(reportCaller bool) Entry {
+	newEntry := entry.copy()
+	newEntry.reportCaller = reportCaller
+	newEntry.isReportCallerSet = true
+	return newEntry
+}
+
+// GetReportStack 获取是否收集调用栈,
+// 默认使用 Logger 上的对应配置.
+func (entry Entry) GetReportStack() bool {
+	if entry.isReportStackSet {
+		return entry.reportStack
+	}
+	return entry.logger.GetReportStack()
+}
+
+// WithReportStack 设置是否收集调用栈
+func (entry Entry) WithReportStack(reportStack bool) Entry {
+	newEntry := entry.copy()
+	newEntry.reportStack = reportStack
+	newEntry.isReportStackSet = true
+	return newEntry
+}
+
+// Log 输出日志
+func (entry Entry) Log(ctx context.Context, level Level, args ...any) {
+	entry.log(ctx, level, fmt.Sprint(args...))
+}
+
+// Trace 输出 LevelTrace 等级的日志
+func (entry Entry) Trace(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelTrace, fmt.Sprint(args...))
+}
+
+// Debug 输出 LevelDebug 等级的日志
+func (entry Entry) Debug(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelDebug, fmt.Sprint(args...))
+}
+
+// Info 输出 LevelInfo 等级的日志
+func (entry Entry) Info(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelInfo, fmt.Sprint(args...))
+}
+
+// Warn 输出 LevelWarn 等级的日志
+func (entry Entry) Warn(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelWarn, fmt.Sprint(args...))
+}
+
+// Error 输出 LevelError 等级的日志
+func (entry Entry) Error(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelError, fmt.Sprint(args...))
+}
+
+// Fatal 输出 LevelFatal 等级的日志并调用 Logger.Exit
+func (entry Entry) Fatal(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelFatal, fmt.Sprint(args...))
+	entry.logger.Exit(1)
+}
+
+// Panic 输出 LevelPanic 等级的日志后执行 panic,
+// 即使 Logger 日志等级高于 LevelPanic 也会 panic.
+func (entry Entry) Panic(ctx context.Context, args ...any) {
+	entry.log(ctx, LevelPanic, fmt.Sprint(args...))
+}
+
+// Logf 格式化输出日志
+func (entry Entry) Logf(ctx context.Context, level Level, format string, args ...any) {
+	entry.log(ctx, level, fmt.Sprintf(format, args...))
+}
+
+// Tracef 格式化输出 LevelTrace 等级的日志
+func (entry Entry) Tracef(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelTrace, fmt.Sprintf(format, args...))
+}
+
+// Debugf 格式化输出 LevelDebug 等级的日志
+func (entry Entry) Debugf(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelDebug, fmt.Sprintf(format, args...))
+}
+
+// Infof 格式化输出 LevelInfo 等级的日志
+func (entry Entry) Infof(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelInfo, fmt.Sprintf(format, args...))
+}
+
+// Warnf 格式化输出 LevelWarn 等级的日志
+func (entry Entry) Warnf(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelWarn, fmt.Sprintf(format, args...))
+}
+
+// Errorf 格式化输出 LevelError 等级的日志
+func (entry Entry) Errorf(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelError, fmt.Sprintf(format, args...))
+}
+
+// Fatalf 格式化输出 LevelFatal 等级的日志并调用 Logger.Exit
+func (entry Entry) Fatalf(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelFatal, fmt.Sprintf(format, args...))
+	entry.logger.Exit(1)
+}
+
+// Panicf 格式化输出 LevelPanic 等级的日志
+// 即使 Logger 日志等级高于 LevelPanic 也会 panic.
+func (entry Entry) Panicf(ctx context.Context, format string, args ...any) {
+	entry.log(ctx, LevelPanic, fmt.Sprintf(format, args...))
+}
+
+func (entry Entry) log(ctx context.Context, level Level, message string) {
+	newEntry := entry.copy()
+	defer func() {
+		if level == LevelPanic {
+			panic(message)
+		}
+	}()
+	if newEntry.logger.GetLevel() < level {
+		return
+	}
+	readonlyEntry := ReadonlyEntry{
+		Fields:  newEntry.fields,
+		Message: message,
+		Time:    newEntry.time,
+		Level:   level,
+	}
+	if readonlyEntry.Time.IsZero() {
+		readonlyEntry.Time = time.Now()
+	}
+	if newEntry.GetReportCaller() {
+		readonlyEntry.Caller = getCaller(newEntry.callerSkip)
+	}
+	if newEntry.GetReportStack() || level <= newEntry.logger.GetReportStackLevel() {
+		readonlyEntry.Stack = getStack(newEntry.callerSkip, maximumFrames)
+	}
+	for _, processor := range newEntry.logger.getLevelProcessors(level) {
+		processor.Process(ctx, readonlyEntry)
+	}
+}
+
+// ReadonlyEntry 是日志系统收集到1条日志记录
+type ReadonlyEntry struct {
+	Caller  Frame
+	Stack   []Frame
+	Time    time.Time
+	Message string
+	Fields  []KV
+	Level   Level
+}

log/logsdk/field.go

@@ -0,0 +1,17 @@
+package logsdk
+
+// Field 返回键值对
+func Field(key string, value any) KV {
+	return KV{
+		Key:   key,
+		Value: value,
+	}
+}
+
+// KV 是日志记录中的键值对
+//
+//nolint:govet
+type KV struct {
+	Key   string `json:"k"`
+	Value any    `json:"v"`
+}

log/logsdk/level.go

@@ -0,0 +1,78 @@
+package logsdk
+
+import "fmt"
+
+// Level 日志等级
+type Level int
+
+func (level Level) String() string {
+	if b, err := level.MarshalText(); err == nil {
+		return string(b)
+	}
+	return "unknown"
+}
+
+func (level Level) MarshalText() ([]byte, error) {
+	switch level {
+	case LevelPanic:
+		return []byte(LevelPanicValue), nil
+	case LevelFatal:
+		return []byte(LevelFatalValue), nil
+	case LevelError:
+		return []byte(LevelErrorValue), nil
+	case LevelWarn:
+		return []byte(LevelWarnValue), nil
+	case LevelInfo:
+		return []byte(LevelInfoValue), nil
+	case LevelDebug:
+		return []byte(LevelDebugValue), nil
+	case LevelTrace:
+		return []byte(LevelTraceValue), nil
+	case LevelDisabled:
+		return []byte(levelDisabledValue), nil
+	}
+	return nil, fmt.Errorf("not a valid log level %d", level)
+}
+
+const (
+	// LevelCount 日志等级的个数
+	LevelCount = 7
+
+	// LevelOffset 是把 LevelInfo 等级的日志值偏移到零值的偏移量
+	LevelOffset = 4
+)
+
+const (
+	// LevelDisabled 表示不处理任何等级的日志,
+	// 其他日志等级的值越小表示日志严重程度越高.
+	LevelDisabled Level = iota - LevelOffset - 1
+	LevelPanic
+	LevelFatal
+	LevelError
+	LevelWarn
+	LevelInfo
+	LevelDebug
+	LevelTrace
+)
+
+const (
+	LevelPanicValue = "panic"
+	LevelFatalValue = "fatal"
+	LevelErrorValue = "error"
+	LevelWarnValue  = "warn"
+	LevelInfoValue  = "info"
+	LevelDebugValue = "debug"
+	LevelTraceValue = "trace"
+
+	levelDisabledValue = "disabled"
+)
+
+var AllLevels = []Level{
+	LevelPanic,
+	LevelFatal,
+	LevelError,
+	LevelWarn,
+	LevelInfo,
+	LevelDebug,
+	LevelTrace,
+}

log/logsdk/logger.go

@@ -0,0 +1,143 @@
+package logsdk
+
+import (
+	"os"
+	"sync"
+	"sync/atomic"
+)
+
+// New 返回初始未经过参数调整的 Logger
+func New() *Logger {
+	logger := &Logger{}
+	logger.entry.logger = logger
+	logger.Reset()
+	return logger
+}
+
+// entry 仅被用来嵌入 Logger
+type entry = Entry
+
+// Logger 中保存了日志所需的全局配置,
+// 使用 Logger 处理日志.
+type Logger struct {
+	exit            func(code int)  // protected by lock
+	levelProcessors levelProcessors // protected by lock
+	entry
+	lock             sync.RWMutex
+	level            atomic.Int32
+	reportStackLevel atomic.Int32
+	callerSkip       atomic.Int32
+	reportCaller     atomic.Bool
+	reportStack      atomic.Bool
+}
+
+// AddProcessor 把日志处理器增加到 Logger
+func (logger *Logger) AddProcessor(levels []Level, processor EntryProcessor) {
+	logger.lock.Lock()
+	for _, level := range levels {
+		logger.levelProcessors[level+LevelOffset] = append(logger.levelProcessors[level+LevelOffset], processor)
+	}
+	logger.lock.Unlock()
+}
+
+// GetLevel 返回日志系统的等级, 严重程度低于返回等级的日志不会被处理.
+func (logger *Logger) GetLevel() Level {
+	return Level(logger.level.Load())
+}
+
+// SetLevel 设置日志系统的等级
+func (logger *Logger) SetLevel(level Level) {
+	logger.level.Store(int32(level))
+}
+
+// GetCallerSkip 获取调用 [runtime.Callers] 时的 skip 参数,
+// skip 已经被偏移到从调用 Logger 相关方法处获取调用信息.
+// 0 表示从调用 Logger 相关方法处获取调用信息.
+func (logger *Logger) GetCallerSkip() int {
+	return int(logger.callerSkip.Load())
+}
+
+// SetCallerSkip 设置调用 [runtime.Callers] 时的 skip 参数,
+// skip 已经被偏移到从调用 Logger 相关方法处获取调用信息.
+// 0 表示从调用 Logger 相关方法处获取调用信息.
+func (logger *Logger) SetCallerSkip(callerSkip int) {
+	logger.callerSkip.Store(int32(callerSkip))
+}
+
+// GetReportCaller 返回是否收集调用信息
+func (logger *Logger) GetReportCaller() bool {
+	return logger.reportCaller.Load()
+}
+
+// SetReportCaller 设置是否收集调用信息
+func (logger *Logger) SetReportCaller(reportCaller bool) {
+	logger.reportCaller.Store(reportCaller)
+}
+
+// GetReportStack 返回是否收集调用栈信息
+func (logger *Logger) GetReportStack() bool {
+	return logger.reportStack.Load()
+}
+
+// SetReportStack 设置是否收集调用栈信息
+func (logger *Logger) SetReportStack(reportStack bool) {
+	logger.reportStack.Store(reportStack)
+}
+
+// GetReportStackLevel 获取自动添加调用栈对应的日志等级
+func (logger *Logger) GetReportStackLevel() Level {
+	return Level(logger.reportStackLevel.Load())
+}
+
+// SetReportStackLevel 设置日志等级小于等于 level 时自动添加调用栈
+func (logger *Logger) SetReportStackLevel(level Level) {
+	logger.reportStackLevel.Store(int32(level))
+}
+
+// Reset 把 Logger 重置到初始状态
+func (logger *Logger) Reset() {
+	logger.lock.Lock()
+	logger.exit = nil
+	logger.levelProcessors = levelProcessors{}
+	logger.lock.Unlock()
+
+	logger.SetLevel(LevelInfo)
+	logger.SetReportStackLevel(LevelWarn)
+	logger.SetCallerSkip(0)
+	logger.SetReportCaller(false)
+	logger.SetReportStack(false)
+}
+
+// Exit 退出程序, 执行的具体过程可以通过 SetExit 指定
+func (logger *Logger) Exit(code int) {
+	logger.lock.RLock()
+	exit := logger.exit
+	logger.lock.RUnlock()
+	if exit == nil {
+		os.Exit(code)
+	}
+	exit(code)
+}
+
+// SetExit 指定退出程序时执行的函数
+func (logger *Logger) SetExit(fn func(code int)) {
+	logger.lock.Lock()
+	logger.exit = fn
+	logger.lock.Unlock()
+}
+
+func (logger *Logger) getLevelProcessors(level Level) []EntryProcessor {
+	logger.lock.RLock()
+	defer logger.lock.RUnlock()
+	return logger.levelProcessors[level+LevelOffset]
+}
+
+func (logger *Logger) newEntry() Entry {
+	return Entry{
+		logger:       logger,
+		callerSkip:   logger.GetCallerSkip() + entrySkipOffset,
+		reportCaller: logger.GetReportCaller(),
+		reportStack:  logger.GetReportStack(),
+		initialized:  true,
+	}
+}

log/logsdk/logjson/option.go

@@ -0,0 +1,97 @@
+package logjson
+
+import (
+	"io"
+	"os"
+	"time"
+)
+
+// Option 配置日志处理对象
+type Option interface {
+	apply(cfg *config)
+}
+
+// WithBufferPool 配置缓冲池
+func WithBufferPool(pool BytesBufferPool) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.bytesBufferPool = pool
+		cfg.hasPool = true
+	})
+}
+
+// WithOutput 配置输出
+func WithOutput(w io.Writer) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.output = w
+	})
+}
+
+// WithTimeFormat 配置时间格式
+func WithTimeFormat(format string) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.timestampFormat = format
+	})
+}
+
+// WithDisableTime 配置仅用时间输出
+func WithDisableTime(disable bool) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.disableTime = disable
+	})
+}
+
+// WithDisableHTMLEscape 配置禁止 HTML 转义
+func WithDisableHTMLEscape(disable bool) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.disableHTMLEscape = disable
+	})
+}
+
+// WithPrettyPrint 配置 JSON 多行缩进输出
+func WithPrettyPrint(pretty bool) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.prettyPrint = pretty
+	})
+}
+
+func newConfig(opts ...Option) *config {
+	cfg := defaultConfig()
+	for _, opt := range opts {
+		opt.apply(cfg)
+	}
+	if !cfg.hasPool {
+		cfg.bytesBufferPool = NewBytesBufferPool(bytesBufferInitialSize, bytesBufferMaximumSize)
+	}
+	if cfg.output == nil {
+		cfg.output = NewSyncWriter(os.Stderr)
+	}
+	if cfg.timestampFormat == "" {
+		cfg.timestampFormat = time.RFC3339Nano
+	}
+	return cfg
+}
+
+func defaultConfig() *config {
+	return &config{
+		hasPool:           false,
+		disableTime:       false,
+		disableHTMLEscape: false,
+		prettyPrint:       false,
+	}
+}
+
+type config struct {
+	bytesBufferPool   BytesBufferPool
+	output            io.Writer
+	timestampFormat   string
+	hasPool           bool
+	disableTime       bool
+	disableHTMLEscape bool
+	prettyPrint       bool
+}
+
+type optionFunc func(cfg *config)
+
+func (fn optionFunc) apply(cfg *config) {
+	fn(cfg)
+}

log/logsdk/logjson/pool.go

@@ -0,0 +1,44 @@
+package logjson
+
+import (
+	"bytes"
+	"sync"
+)
+
+const (
+	bytesBufferInitialSize = 512
+	bytesBufferMaximumSize = 4096
+)
+
+type BytesBufferPool interface {
+	Get() *bytes.Buffer
+	Put(buffer *bytes.Buffer)
+}
+
+// NewBytesBufferPool 创建并返回 BytesBufferPool
+func NewBytesBufferPool(initialSize, maximumSize int) BytesBufferPool {
+	return &bytesBufferPool{
+		pool: sync.Pool{
+			New: func() any {
+				return bytes.NewBuffer(make([]byte, 0, initialSize))
+			},
+		},
+		maximumSize: maximumSize,
+	}
+}
+
+type bytesBufferPool struct {
+	pool        sync.Pool
+	maximumSize int
+}
+
+func (pool *bytesBufferPool) Get() *bytes.Buffer {
+	return pool.pool.Get().(*bytes.Buffer)
+}
+
+func (pool *bytesBufferPool) Put(buf *bytes.Buffer) {
+	if buf.Cap() > pool.maximumSize {
+		return
+	}
+	pool.pool.Put(buf)
+}

log/logsdk/logjson/processor.go

@@ -0,0 +1,88 @@
+package logjson
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+
+	"git.blauwelle.com/go/crate/log/logsdk"
+)
+
+var _ logsdk.EntryProcessor = &Processor{}
+
+// New 返回日志处理对象,
+// 返回的对象是 [logsdk.EntryProcessor].
+func New(opts ...Option) *Processor {
+	cfg := newConfig(opts...)
+	return &Processor{
+		bytesBufferPool:   cfg.bytesBufferPool,
+		output:            cfg.output,
+		timeFormat:        cfg.timestampFormat,
+		disableTime:       cfg.disableTime,
+		disableHTMLEscape: cfg.disableHTMLEscape,
+		prettyPrint:       cfg.prettyPrint,
+	}
+}
+
+// Processor 日志处理对象, 把日志处理成 JSON.
+type Processor struct {
+	bytesBufferPool   BytesBufferPool
+	output            io.Writer
+	timeFormat        string
+	disableTime       bool
+	disableHTMLEscape bool
+	prettyPrint       bool
+}
+
+// Process 处理日志
+func (processor *Processor) Process(_ context.Context, entry logsdk.ReadonlyEntry) {
+	m := Entry{
+		Stack:   entry.Stack,
+		Fields:  entry.Fields,
+		Level:   entry.Level,
+		Message: entry.Message,
+	}
+	if !processor.disableTime {
+		m.Time = entry.Time.Format(processor.timeFormat) // 1次分配
+	}
+	if entry.Caller.IsValid() {
+		// 1次分配
+		// 直接取 &entry.Caller 会增加堆内存分配
+		m.Caller = &logsdk.Frame{
+			Function: entry.Caller.Function,
+			File:     entry.Caller.File,
+			Line:     entry.Caller.Line,
+		}
+	}
+
+	buf := processor.bytesBufferPool.Get()
+	buf.Reset()
+	defer processor.bytesBufferPool.Put(buf)
+
+	encoder := json.NewEncoder(buf)
+	if processor.prettyPrint {
+		encoder.SetIndent("", "  ")
+	}
+	encoder.SetEscapeHTML(!processor.disableHTMLEscape)
+
+	// Encode 2次分配
+	if err := encoder.Encode(m); err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "JSON processor cannot encode log %#v: %s\n", m, err.Error())
+	}
+
+	if _, err := buf.WriteTo(processor.output); err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "JSON processor cannot write log: %s\n", err.Error())
+	}
+}
+
+// Entry 被用来 JSON 序列化
+type Entry struct {
+	Message string         `json:"msg"`
+	Time    string         `json:"time,omitempty"`
+	Caller  *logsdk.Frame  `json:"caller,omitempty"`
+	Stack   []logsdk.Frame `json:"stack,omitempty"`
+	Fields  []logsdk.KV    `json:"fields,omitempty"`
+	Level   logsdk.Level   `json:"level"`
+}

log/logsdk/logjson/writer.go

@@ -0,0 +1,25 @@
+package logjson
+
+import (
+	"io"
+	"sync"
+)
+
+// NewSyncWriter 返回写互斥的 io.Writer
+func NewSyncWriter(writer io.Writer) io.Writer {
+	return &syncWriter{
+		writer: writer,
+		lock:   sync.Mutex{},
+	}
+}
+
+type syncWriter struct {
+	writer io.Writer
+	lock   sync.Mutex
+}
+
+func (w *syncWriter) Write(p []byte) (int, error) {
+	w.lock.Lock()
+	defer w.lock.Unlock()
+	return w.writer.Write(p)
+}

log/logsdk/processor.go

@@ -0,0 +1,10 @@
+package logsdk
+
+import "context"
+
+// EntryProcessor 处理日志记录
+type EntryProcessor interface {
+	Process(ctx context.Context, entry ReadonlyEntry)
+}
+
+type levelProcessors [LevelCount][]EntryProcessor

log/logsdk/runtime.go

@@ -0,0 +1,58 @@
+package logsdk
+
+import (
+	"runtime"
+)
+
+const (
+	maximumFrames       = 32
+	getCallerSkipOffset = 2
+	entrySkipOffset     = 2
+)
+
+// Frame 调用相关信息
+type Frame struct {
+	Function string `json:"func"`
+	File     string `json:"file"`
+	Line     int    `json:"line"`
+}
+
+// IsValid 表示是否有效
+func (frame Frame) IsValid() bool {
+	return frame.Line > 0
+}
+
+func getCaller(skip int) Frame {
+	pc := make([]uintptr, 1)
+	n := runtime.Callers(skip+getCallerSkipOffset, pc)
+	frame, _ := runtime.CallersFrames(pc[:n]).Next()
+	if frame.PC == 0 {
+		return Frame{}
+	}
+	return Frame{
+		Function: frame.Function,
+		File:     frame.File,
+		Line:     frame.Line,
+	}
+}
+
+func getStack(skip, maximumFrames int) []Frame {
+	pc := make([]uintptr, maximumFrames)
+	n := runtime.Callers(skip+getCallerSkipOffset, pc)
+	stack := make([]Frame, 0, n)
+	frames := runtime.CallersFrames(pc[:n])
+	for {
+		frame, more := frames.Next()
+		if frame.PC != 0 {
+			stack = append(stack, Frame{
+				Function: frame.Function,
+				File:     frame.File,
+				Line:     frame.Line,
+			})
+		}
+		if !more {
+			break
+		}
+	}
+	return stack
+}

log/state.go

@@ -0,0 +1,8 @@
+package log
+
+import (
+	"git.blauwelle.com/go/crate/log/logsdk"
+)
+
+// globalLogger 不能重新赋值
+var globalLogger = logsdk.New()

logotel/go.mod

@@ -0,0 +1,9 @@
+module git.blauwelle.com/go/crate/logotel
+
+go 1.20
+
+require (
+	git.blauwelle.com/go/crate/log v0.8.0
+	go.opentelemetry.io/otel v1.13.0
+	go.opentelemetry.io/otel/trace v1.13.0
+)

logotel/go.sum

@@ -0,0 +1,11 @@
+git.blauwelle.com/go/crate/log v0.8.0 h1:TINzuFo330MZIagzdULouwBoLCcLIB4yjI/G1IH0I+0=
+git.blauwelle.com/go/crate/log v0.8.0/go.mod h1:jfVfpRODZTA70A8IkApVeGsS1zfLk1D77sLWZM/w+L0=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+go.opentelemetry.io/otel v1.13.0 h1:1ZAKnNQKwBBxFtww/GwxNUyTf0AxkZzrukO8MeXqe4Y=
+go.opentelemetry.io/otel v1.13.0/go.mod h1:FH3RtdZCzRkJYFTCsAKDy9l/XYjMdNv6QrkFFB8DvVg=
+go.opentelemetry.io/otel/trace v1.13.0 h1:CBgRZ6ntv+Amuj1jDsMhZtlAPT6gbyIRdaIzFhfBSdY=
+go.opentelemetry.io/otel/trace v1.13.0/go.mod h1:muCvmmO9KKpvuXSf3KKAXXB2ygNYHQ+ZfI5X08d3tds=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

logotel/option.go

@@ -0,0 +1,45 @@
+package logotel
+
+import (
+	"git.blauwelle.com/go/crate/log/logsdk/logjson"
+)
+
+func newConfig(opts ...Option) *config {
+	cfg := defaultConfig()
+	for _, opt := range opts {
+		opt.apply(cfg)
+	}
+	if !cfg.hasPool {
+		cfg.bytesBufferPool = logjson.NewBytesBufferPool(512, 4096)
+	}
+	return cfg
+}
+
+func defaultConfig() *config {
+	return &config{
+		hasPool: false,
+	}
+}
+
+// WithBufferPool 指定缓冲池
+func WithBufferPool(pool logjson.BytesBufferPool) Option {
+	return optionFunc(func(cfg *config) {
+		cfg.bytesBufferPool = pool
+		cfg.hasPool = true
+	})
+}
+
+// Option 配置 Processor
+type Option interface {
+	apply(cfg *config)
+}
+
+type config struct {
+	bytesBufferPool logjson.BytesBufferPool
+	hasPool         bool
+}
+type optionFunc func(cfg *config)
+
+func (fn optionFunc) apply(cfg *config) {
+	fn(cfg)
+}

logotel/processor.go

@@ -0,0 +1,91 @@
+// otellog 提供 git.blauwelle.com/go/crate/log 的 opentelemetry 处理功能
+
+package logotel
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+
+	"git.blauwelle.com/go/crate/log/logsdk"
+	"git.blauwelle.com/go/crate/log/logsdk/logjson"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// New 创建 log/opentelemetry 处理器
+func New(opts ...Option) *Processor {
+	cfg := newConfig(opts...)
+	return &Processor{
+		bufferPool: cfg.bytesBufferPool,
+	}
+}
+
+var _ logsdk.EntryProcessor = &Processor{}
+
+// Processor 用于把日志和 opentelemetry 对接
+type Processor struct {
+	bufferPool logjson.BytesBufferPool
+}
+
+func (processor *Processor) Process(ctx context.Context, entry logsdk.ReadonlyEntry) {
+	span := trace.SpanFromContext(ctx)
+	if !span.IsRecording() {
+		return
+	}
+
+	attrs := make([]attribute.KeyValue, 0, len(entry.Fields)+6)
+	attrs = append(attrs, attribute.String("log.severity", entry.Level.String()))
+	attrs = append(attrs, attribute.String("log.message", entry.Message))
+	if entry.Caller.IsValid() {
+		attrs = append(attrs, semconv.CodeFunctionKey.String(entry.Caller.Function))
+		attrs = append(attrs, semconv.CodeFilepathKey.String(entry.Caller.File))
+		attrs = append(attrs, semconv.CodeLineNumberKey.Int(entry.Caller.Line))
+	}
+	if len(entry.Stack) > 0 {
+		buf := processor.bufferPool.Get()
+		for _, frame := range entry.Stack {
+			buf.WriteString(frame.Function)
+			buf.WriteByte('\n')
+			buf.WriteByte('\t')
+			buf.WriteString(frame.File)
+			buf.WriteByte(':')
+			buf.WriteString(strconv.Itoa(frame.Line))
+			buf.WriteByte('\n')
+		}
+		processor.bufferPool.Put(buf)
+		attrs = append(attrs, attribute.String("zz.stack", buf.String()))
+	}
+	for _, field := range entry.Fields {
+		attrs = append(attrs, fieldToKV(field))
+	}
+	span.AddEvent("log", trace.WithTimestamp(entry.Time), trace.WithAttributes(attrs...))
+	if entry.Level <= logsdk.LevelError {
+		span.SetStatus(codes.Error, entry.Message)
+	}
+}
+
+func fieldToKV(field logsdk.KV) attribute.KeyValue {
+	switch value := field.Value.(type) {
+	case nil:
+		return attribute.String(field.Key, "<nil>")
+	case string:
+		return attribute.String(field.Key, value)
+	case int:
+		return attribute.Int(field.Key, value)
+	case int64:
+		return attribute.Int64(field.Key, value)
+	case float64:
+		return attribute.Float64(field.Key, value)
+	case bool:
+		return attribute.Bool(field.Key, value)
+	case error:
+		return attribute.String(field.Key, value.Error())
+	case fmt.Stringer:
+		return attribute.String(field.Key, value.String())
+	}
+
+	return attribute.String(field.Key, fmt.Sprint(field.Value))
+}

mapset/.golangci.yaml

@@ -0,0 +1,138 @@
+## 更新到 golangci-lint@v1.52.2
+run:
+  timeout: 1m
+  build-tags: [ ]
+  skip-dirs: [ ]
+  skip-files: [ ]
+linters:
+  disable-all: true
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - typecheck
+    - unused
+    - asasalint
+    - asciicheck
+    - bidichk
+    - bodyclose
+    - containedctx
+    - cyclop
+    - dupl
+    - durationcheck
+    - errname
+    - errorlint
+    - exhaustive
+    - exportloopref
+    - funlen
+    - gocheckcompilerdirectives
+    - gochecknoinits
+    - goconst
+    - gocritic
+    - gocyclo
+    - goimports
+    - gomnd
+    - goprintffuncname
+    - gosec
+    - lll
+    - loggercheck
+    - makezero
+    - nakedret
+    - nestif
+    - nilnil
+    - noctx
+    - nolintlint
+    - nosprintfhostport
+    - prealloc
+    - predeclared
+    - promlinter
+    - reassign
+    - revive
+    - stylecheck
+    - tenv
+    - testableexamples
+    - testpackage
+    - tparallel
+    - unconvert
+    - unparam
+    - usestdlibvars
+    - wastedassign
+    - whitespace
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+    exclude-functions: [ ]
+  govet:
+    enable-all: true
+    disable: [ ]
+  cyclop:
+    max-complexity: 10
+    package-average: 0.0
+  dupl:
+    threshold: 150
+  exhaustive:
+    check:
+      - switch
+      - map
+  funlen:
+    lines: 100
+    statements: 60
+  gocritic:
+    disabled-checks:
+      - commentFormatting
+    settings:
+      captLocal:
+        paramsOnly: false
+      underef:
+        skipRecvDeref: false
+  gocyclo:
+    min-complexity: 20
+  gomnd:
+    ignored-functions:
+      - os.Chmod
+      - os.Mkdir
+      - os.MkdirAll
+      - os.OpenFile
+      - os.WriteFile
+      - prometheus.ExponentialBuckets
+      - prometheus.ExponentialBucketsRange
+      - prometheus.LinearBuckets
+  lll:
+    line-length: 240
+  nakedret:
+    max-func-lines: 10
+  nestif:
+    min-complexity: 5
+  predeclared:
+    ignore: ""
+    q: false
+  reassign:
+    patterns:
+      - ".*"
+  tenv:
+    all: true
+  usestdlibvars:
+    time-month: true
+    time-layout: true
+    crypto-hash: true
+    default-rpc-path: true
+    os-dev-null: true
+    sql-isolation-level: true
+    tls-signature-scheme: true
+    constant-kind: true
+    syslog-priority: true
+issues:
+  max-same-issues: 10
+  exclude-rules:
+    - source: "//noinspection"
+      linters: [ gocritic ]
+    - path: "_test\\.go"
+      linters:
+        - bodyclose
+        - dupl
+        - funlen
+        - goconst
+        - gosec
+        - noctx

mapset/mapset.go

@@ -7,6 +7,10 @@ import (
 	"strings"
 )
 
+const (
+	maximumItemToPrint = 64
+)
+
 // New 返回 [MapSet]
 func New[T comparable](keys ...T) MapSet[T] {
 	s := make(MapSet[T], len(keys))
@@ -14,7 +18,7 @@ func New[T comparable](keys ...T) MapSet[T] {
 	return s
 }
 
-// MapSet 是集合的范型实现
+// MapSet 是集合的 generics 实现
 type MapSet[T comparable] map[T]struct{}
 
 // Cardinality 返回集合的元素个数
@@ -267,8 +271,8 @@ func (s *MapSet[T]) UnmarshalJSON(b []byte) error {
 
 func (s MapSet[T]) String() string {
 	size := s.Cardinality()
-	if size > 64 {
+	if size > maximumItemToPrint {
-		size = 64
+		size = maximumItemToPrint
 	}
 	keys := make([]string, 0, size)
 	for key := range s {

synchelper/bytes_buffer_pool.go

@@ -0,0 +1,18 @@
+package synchelper
+
+import "bytes"
+
+// NewBytesBufferPool 返回新的 BytesBufferPool
+func NewBytesBufferPool(initialSize, maximumSize int) BytesBufferPool {
+	return NewPool(
+		func() any {
+			return bytes.NewBuffer(make([]byte, 0, initialSize))
+		},
+		func(v *bytes.Buffer) bool {
+			return v.Cap() <= maximumSize
+		},
+	)
+}
+
+// BytesBufferPool 是 [*bytes.Buffer] 的资源池
+type BytesBufferPool = Pool[*bytes.Buffer]

synchelper/go.mod

@@ -0,0 +1,3 @@
+module git.blauwelle.com/go/crate/synchelper
+
+go 1.20

synchelper/io_writer.go

@@ -0,0 +1,25 @@
+package synchelper
+
+import (
+	"io"
+	"sync"
+)
+
+// NewSyncWriter 返回写互斥的 writer
+func NewSyncWriter(writer io.Writer) io.Writer {
+	return &syncWriter{
+		writer: writer,
+		lock:   sync.Mutex{},
+	}
+}
+
+type syncWriter struct {
+	writer io.Writer
+	lock   sync.Mutex
+}
+
+func (w *syncWriter) Write(p []byte) (n int, err error) {
+	w.lock.Lock()
+	defer w.lock.Unlock()
+	return w.writer.Write(p)
+}

synchelper/pool.go

@@ -0,0 +1,34 @@
+package synchelper
+
+import (
+	"sync"
+)
+
+// NewPool 初始化 Pool,
+// newFn 是资源的构造函数,
+// putCond 返回 true 时表示资源可以被放回 Pool 中.
+func NewPool[T any](newFn func() any, putCond func(v T) bool) Pool[T] {
+	return Pool[T]{
+		pool:    &sync.Pool{New: newFn},
+		putCond: putCond,
+	}
+}
+
+// Pool 是通用的资源池
+type Pool[T any] struct {
+	pool    *sync.Pool
+	putCond func(v T) bool
+}
+
+// Get 获取资源
+func (pool Pool[T]) Get() T {
+	return pool.pool.Get().(T)
+}
+
+// Put 放回资源
+func (pool Pool[T]) Put(v T) {
+	if !pool.putCond(v) {
+		return
+	}
+	pool.pool.Put(v)
+}

uptracehelper/helper.go

@@ -2,6 +2,7 @@ package uptracehelper
 
 import (
 	"context"
+
 	"github.com/uptrace/uptrace-go/uptrace"
 )
 
@@ -11,12 +12,7 @@ type Config struct {
 	DeploymentEnvironment string
 }
 
-// InitTracer 初始化并等待 uptrace
+func Setup(cfg Config) {
-// 配合 [git.blauwelle.com/go/crate/exegroup] 使用
-// env
-//   - UPTRACE_DISABLED 存在就不再初始化
-//   - UPTRACE_DSN 服务端地址
-func InitTracer(cfg Config) (func(ctx context.Context) error, func(ctx context.Context)) {
 	opts := []uptrace.Option{
 		uptrace.WithServiceName(cfg.ServiceName),
 		uptrace.WithServiceVersion(cfg.ServiceVersion),
@@ -25,7 +21,16 @@ func InitTracer(cfg Config) (func(ctx context.Context) error, func(ctx context.C
 		opts = append(opts, uptrace.WithDeploymentEnvironment(cfg.DeploymentEnvironment))
 	}
 	uptrace.ConfigureOpentelemetry(opts...)
-	shutdownErr := make(chan error)
+}
+
+// GoStop 初始化并等待 uptrace
+// 配合 [git.blauwelle.com/go/crate/exegroup] 使用
+// env
+//   - UPTRACE_DISABLED 存在就不再初始化
+//   - UPTRACE_DSN 服务端地址
+func GoStop(cfg Config) (func(ctx context.Context) error, func(ctx context.Context)) {
+	Setup(cfg)
+	shutdownErr := make(chan error, 1)
 	goFunc := func(context.Context) error {
 		return <-shutdownErr
 	}