doc: update doc for website

2026-02-08 06:32:28 +08:00 · 2023-08-30 11:46:16 +08:00
parent ef79e1305e
commit 03d331dfb6
13 changed files with 6385 additions and 3 deletions
--- a/docs/api/packages/system.md
+++ b/docs/api/packages/system.md
@@ -0,0 +1,307 @@
+# System
+
+system 包含 os, runtime, shell command 相关函数。
+
+<div STYLE="page-break-after: always;"></div>
+
+## 源码:
+
+-   [https://github.com/duke-git/lancet/blob/main/system/os.go](https://github.com/duke-git/lancet/blob/main/system/os.go)
+
+<div STYLE="page-break-after: always;"></div>
+
+## 用法:
+
+```go
+import (
+    "github.com/duke-git/lancet/v2/system"
+)
+```
+
+<div STYLE="page-break-after: always;"></div>
+
+## 目录
+
+-   [IsWindows](#IsWindows)
+-   [IsLinux](#IsLinux)
+-   [IsMac](#IsMac)
+-   [GetOsEnv](#GetOsEnv)
+-   [SetOsEnv](#SetOsEnv)
+-   [RemoveOsEnv](#RemoveOsEnv)
+-   [CompareOsEnv](#CompareOsEnv)
+-   [ExecCommand](#ExecCommand)
+-   [GetOsBits](#GetOsBits)
+
+<div STYLE="page-break-after: always;"></div>
+
+## 文档
+
+### <span id="IsWindows">IsWindows</span>
+
+<p>检查当前操作系统是否是windows</p>
+
+<b>函数签名:</b>
+
+```go
+func IsWindows() bool
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/zIflQgZNuxD)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    isOsWindows := system.IsWindows()
+    fmt.Println(isOsWindows)
+}
+```
+
+### <span id="IsLinux">IsLinux</span>
+
+<p>检查当前操作系统是否是linux</p>
+
+<b>函数签名:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/zIflQgZNuxD)</span></b>
+
+```go
+func IsLinux() bool
+```
+
+<b>示例:</b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    isOsLinux := system.IsLinux()
+    fmt.Println(isOsLinux)
+}
+```
+
+### <span id="IsMac">IsMac</span>
+
+<p>检查当前操作系统是否是macos</p>
+
+<b>函数签名:</b>
+
+```go
+func IsMac() bool
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/Mg4Hjtyq7Zc)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    isOsMac := system.IsMac()
+    fmt.Println(isOsMac)
+}
+```
+
+### <span id="GetOsEnv">GetOsEnv</span>
+
+<p>获取key命名的环境变量的值</p>
+
+<b>函数签名:</b>
+
+```go
+func GetOsEnv(key string) string
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/D88OYVCyjO-)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    err := system.SetOsEnv("foo", "abc")
+    result := system.GetOsEnv("foo")
+
+    fmt.Println(err)
+    fmt.Println(result)
+    // Output:
+    // <nil>
+    // abc
+}
+```
+
+### <span id="SetOsEnv">SetOsEnv</span>
+
+<p>设置由key命名的环境变量的值</p>
+
+<b>函数签名:</b>
+
+```go
+func SetOsEnv(key, value string) error
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/D88OYVCyjO-)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    err := system.SetOsEnv("foo", "abc")
+    result := system.GetOsEnv("foo")
+
+    fmt.Println(err)
+    fmt.Println(result)
+    // Output:
+    // <nil>
+    // abc
+}
+```
+
+### <span id="RemoveOsEnv">RemoveOsEnv</span>
+
+<p>删除单个环境变量</p>
+
+<b>函数签名:</b>
+
+```go
+func RemoveOsEnv(key string) error
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/fqyq4b3xUFQ)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    err1 := system.SetOsEnv("foo", "abc")
+    result1 := GetOsEnv("foo")
+
+    err2 := system.RemoveOsEnv("foo")
+    result2 := GetOsEnv("foo")
+
+    fmt.Println(err1)
+    fmt.Println(err2)
+    fmt.Println(result1)
+    fmt.Println(result2)
+
+    // Output:
+    // <nil>
+    // <nil>
+    // abc
+    //
+}
+```
+
+### <span id="CompareOsEnv">CompareOsEnv</span>
+
+<p>获取key命名的环境变量值并与compareEnv进行比较</p>
+
+<b>函数签名:</b>
+
+```go
+func CompareOsEnv(key, comparedEnv string) bool
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/BciHrKYOHbp)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    err := system.SetOsEnv("foo", "abc")
+    if err != nil {
+        return
+    }
+
+    result := system.CompareOsEnv("foo", "abc")
+
+    fmt.Println(result)
+
+    // Output:
+    // true
+}
+```
+
+### <span id="ExecCommand">ExecCommand</span>
+
+<p>执行shell命令，返回命令的stdout和stderr字符串，如果出现错误，则返回错误。参数`command`是一个完整的命令字符串，如ls-a（linux），dir（windows），ping 127.0.0.1。在linux中，使用/bin/bash-c执行命令，在windows中，使用powershell.exe执行命令。</p>
+
+<b>函数签名:</b>
+
+```go
+type (
+	Option func(*exec.Cmd)
+)
+func ExecCommand(command string, opts ...Option) (stdout, stderr string, err error)
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/n-2fLyZef-4)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    // linux or mac
+    stdout, stderr, err := system.ExecCommand("ls")
+    fmt.Println("std out: ", stdout)
+    fmt.Println("std err: ", stderr)
+    assert.Equal("", stderr)
+
+    // windows
+    stdout, stderr, err = system.ExecCommand("dir")
+    fmt.Println("std out: ", stdout)
+    fmt.Println("std err: ", stderr)
+
+    // error command
+    stdout, stderr, err = system.ExecCommand("abc")
+    fmt.Println("std out: ", stdout)
+    fmt.Println("std err: ", stderr)
+    if err != nil {
+        fmt.Println(err.Error())
+    }
+}
+```
+
+### <span id="GetOsBits">GetOsBits</span>
+
+<p>获取当前操作系统位数，返回32或64</p>
+
+<b>函数签名:</b>
+
+```go
+func GetOsBits() int
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/ml-_XH3gJbW)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/system"
+)
+
+func main() {
+    osBit := system.GetOsBits()
+    fmt.Println(osBit) // 32 or 64
+}
+```
--- a/docs/api/packages/tuple.md
+++ b/docs/api/packages/tuple.md
--- a/docs/api/packages/validator.md
+++ b/docs/api/packages/validator.md
--- a/docs/api/packages/xerror.md
+++ b/docs/api/packages/xerror.md
@@ -0,0 +1,491 @@
+# Xerror
+
+xerror 错误处理逻辑封装
+
+<div STYLE="page-break-after: always;"></div>
+
+## 源码:
+
+-   [https://github.com/duke-git/lancet/blob/main/xerror/xerror.go](https://github.com/duke-git/lancet/blob/main/xerror/xerror.go)
+
+<div STYLE="page-break-after: always;"></div>
+
+## 用法:
+
+```go
+import (
+    "github.com/duke-git/lancet/v2/xerror"
+)
+```
+
+<div STYLE="page-break-after: always;"></div>
+
+## 目录
+
+-   [New](#New)
+-   [Wrap](#Wrap)
+-   [Unwrap](#Unwrap)
+-   [XError_Wrap](#XError_Wrap)
+-   [XError_Unwrap](#XError_Unwrap)
+-   [XError_With](#XError_With)
+-   [XError_Is](#XError_Is)
+-   [XError_Id](#XError_Id)
+-   [XError_Values](#XError_Values)
+-   [XError_StackTrace](#XError_StackTrace)
+-   [XError_Info](#XError_Info)
+-   [XError_Error](#XError_Error)
+-   [TryUnwrap](#TryUnwrap)
+
+<div STYLE="page-break-after: always;"></div>
+
+
+## 文档
+
+### <span id="New">New</span>
+
+<p>创建XError对象实例。</p>
+
+<b>函数签名:</b>
+
+```go
+type XError struct {
+    id      string
+    message string
+    stack   *stack
+    cause   error
+    values  map[string]any
+}
+
+func New(format string, args ...any) *XError
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/w4oWZts7q7f)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err := xerror.New("error")
+    fmt.Println(err.Error())
+
+    // Output:
+    // error
+}
+```
+
+### <span id="Wrap">Wrap</span>
+
+<p>根据error对象创建XError对象实例，可添加message。</p>
+
+<b>函数签名:</b>
+
+```go
+func Wrap(cause error, message ...any) *XError
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/5385qT2dCi4)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err := xerror.New("wrong password")
+    wrapErr := xerror.Wrap(err, "error")
+
+    fmt.Println(wrapErr.Error())
+
+    // Output:
+    // error: wrong password
+}
+```
+
+### <span id="Unwrap">Unwrap</span>
+
+<p>从error对象中解构出XError。</p>
+
+<b>函数签名:</b>
+
+```go
+func Unwrap(err error) *XError
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/LKMLep723tu)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/pkg/errors"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err1 := xerror.New("error").With("level", "high")
+    wrapErr := errors.Wrap(err1, "oops")
+
+    err := xerror.Unwrap(wrapErr)
+
+    values := err.Values()
+    fmt.Println(values["level"])
+
+    // Output:
+    // high
+}
+```
+
+### <span id="XError_Wrap">XError_Wrap</span>
+
+<p>创建新的XError对象并将消息和id复制到新的对象中。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Wrap(cause error) *XError
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/RpjJ5u5sc97)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "errors"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err1 := xerror.New("error").With("level", "high")
+	err2 := err1.Wrap(errors.New("invalid username"))
+
+	fmt.Println(err2.Error())
+
+	// Output:
+	// error: invalid username
+}
+```
+
+### <span id="XError_Unwrap">XError_Unwrap</span>
+
+<p>解构XEerror为error对象。适配github.com/pkg/errors。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Unwrap() error
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/VUXJ8BST4c6)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err1 := xerror.New("error").With("level", "high")
+    err2 := err1.Wrap(errors.New("invalid username"))
+
+    err := err2.Unwrap()
+
+    fmt.Println(err.Error())
+
+    // Output:
+    // invalid username
+}
+```
+
+### <span id="XError_With">XError_With</span>
+
+<p>添加与XError对象的键和值。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) With(key string, value any) *XError
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/ow8UISXX_Dp)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err := xerror.New("error").With("level", "high")
+
+    errLevel := err.Values()["level"]
+
+    fmt.Println(errLevel)
+
+    // Output:
+    // high
+}
+```
+
+### <span id="XError_Id">XError_Id</span>
+
+<p>设置XError对象的id。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Id(id string) *XError
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/X6HBlsy58U9)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err1 := xerror.New("error").Id("e001")
+    err2 := xerror.New("error").Id("e001")
+    err3 := xerror.New("error").Id("e003")
+
+    equal := err1.Is(err2)
+    notEqual := err1.Is(err3)
+
+    fmt.Println(equal)
+    fmt.Println(notEqual)
+
+    // Output:
+    // true
+    // false
+}
+```
+
+### <span id="XError_Is">XError_Is</span>
+
+<p>检查目标error是否为XError，两个错误中的error.id是否匹配。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Is(target error) bool
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/X6HBlsy58U9)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err1 := xerror.New("error").Id("e001")
+    err2 := xerror.New("error").Id("e001")
+    err3 := xerror.New("error").Id("e003")
+
+    equal := err1.Is(err2)
+    notEqual := err1.Is(err3)
+
+    fmt.Println(equal)
+    fmt.Println(notEqual)
+
+    // Output:
+    // true
+    // false
+}
+```
+
+### <span id="XError_Values">XError_Values</span>
+
+<p>返回由With设置的键和值的映射。将合并所有XError键和值。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Values() map[string]any
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/ow8UISXX_Dp)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err := xerror.New("error").With("level", "high")
+
+    errLevel := err.Values()["level"]
+
+    fmt.Println(errLevel)
+
+    // Output:
+    // high
+}
+```
+
+
+### <span id="XError_StackTrace">XError_StackTrace</span>
+
+<p>返回与pkg/error兼容的堆栈信息。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) StackTrace() StackTrace
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/6FAvSQpa7pc)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err := xerror.New("error")
+
+    stacks := err.Stacks()
+
+    fmt.Println(stacks[0].Func)
+    fmt.Println(stacks[0].Line)
+
+    containFile := strings.Contains(stacks[0].File, "xxx.go")
+    fmt.Println(containFile)
+}
+```
+
+
+### <span id="XError_Info">XError_Info</span>
+
+<p>返回可打印的XError对象信息。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Info() *errInfo
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/1ZX0ME1F-Jb)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    cause := errors.New("error")
+    err := xerror.Wrap(cause, "invalid username").Id("e001").With("level", "high")
+
+    errInfo := err.Info()
+
+    fmt.Println(errInfo.Id)
+    fmt.Println(errInfo.Cause)
+    fmt.Println(errInfo.Values["level"])
+    fmt.Println(errInfo.Message)
+
+    // Output:
+    // e001
+    // error
+    // high
+    // invalid username
+}
+```
+
+
+### <span id="XError_Error">XError_Error</span>
+
+<p>实现标准库的error接口。</p>
+
+<b>函数签名:</b>
+
+```go
+func (e *XError) Error() string
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/w4oWZts7q7f)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    err := xerror.New("error")
+    fmt.Println(err.Error())
+
+    // Output:
+    // error
+}
+```
+
+### <span id="TryUnwrap">TryUnwrap</span>
+
+<p>检查error, 如果err为nil则展开，则它返回一个有效值，如果err不是nil则TryUnwrap使用err发生panic。</p>
+
+<b>函数签名:</b>
+
+```go
+func TryUnwrap[T any](val T, err error) T
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/acyZVkNZEeW)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/xerror"
+)
+
+func main() {
+    result1 := xerror.TryUnwrap(strconv.Atoi("42"))
+    fmt.Println(result1)
+
+    _, err := strconv.Atoi("4o2")
+    defer func() {
+        v := recover()
+        result2 := reflect.DeepEqual(err.Error(), v.(*strconv.NumError).Error())
+        fmt.Println(result2)
+    }()
+
+    xerror.TryUnwrap(strconv.Atoi("4o2"))
+
+    // Output:
+    // 42
+    // true
+}
+```