增加 status 相关特性

Author: FishGoddess

HISTORY.md

@@ -1,5 +1,12 @@
 ## ✒ 历史版本的特性介绍 (Features in old versions)
 
+### v0.5.0
+
+> 此版本发布于 2023-06-19
+
+* 优化代码，调整内置错误
+* 增加 status 相关特性
+
 ### v0.4.0
 
 > 此版本发布于 2023-06-18

README.en.md

@@ -53,10 +53,10 @@ func main() {
 	err = errors.BadRequest(nil)          // Classic enough! Ah :)
 	err = errors.Forbidden(nil)           // Classic enough! Ah :)
 	err = errors.NotFound(nil)            // Classic enough! Ah :)
+	err = errors.RequestTimeout(nil)      // Classic enough! Ah :)
 	err = errors.InternalServerError(nil) // Classic enough! Ah :)
-	err = errors.Timeout(nil)
-	err = errors.NetworkError(nil)
 	err = errors.DBError(nil)
+	err = errors.PageTokenInvalid(nil)
 
 	// Use WithMsg to carry a message.
 	err = errors.Wrap(io.EOF, codeTestError, errors.WithMsg("test"))
@@ -67,6 +67,9 @@ func main() {
 
 ```
 
+* [basic](_examples/basic.go)
+* [status](_examples/status.go)
+
 ### 👥 Contributing
 
 If you find that something is not working as expected, just fork and fix by yourself or open an _**issue**_ :).

README.md

@@ -53,10 +53,10 @@ func main() {
 	err = errors.BadRequest(nil)          // Classic enough! Ah :)
 	err = errors.Forbidden(nil)           // Classic enough! Ah :)
 	err = errors.NotFound(nil)            // Classic enough! Ah :)
+	err = errors.RequestTimeout(nil)      // Classic enough! Ah :)
 	err = errors.InternalServerError(nil) // Classic enough! Ah :)
-	err = errors.Timeout(nil)
-	err = errors.NetworkError(nil)
 	err = errors.DBError(nil)
+	err = errors.PageTokenInvalid(nil)
 
 	// Use WithMsg to carry a message.
 	err = errors.Wrap(io.EOF, codeTestError, errors.WithMsg("test"))
@@ -67,6 +67,9 @@ func main() {
 
 ```
 
+* [basic](_examples/basic.go)
+* [status](_examples/status.go)
+
 ### 👥 贡献者
 
 如果您觉得 **Errors** 缺少您需要的功能，那就 fork 到自己仓库随便玩。当然，也可以提 _**issue**_ :)。

_examples/basic.go

@@ -39,10 +39,10 @@ func main() {
 	err = errors.BadRequest(nil)          // Classic enough! Ah :)
 	err = errors.Forbidden(nil)           // Classic enough! Ah :)
 	err = errors.NotFound(nil)            // Classic enough! Ah :)
+	err = errors.RequestTimeout(nil)      // Classic enough! Ah :)
 	err = errors.InternalServerError(nil) // Classic enough! Ah :)
-	err = errors.Timeout(nil)
-	err = errors.NetworkError(nil)
 	err = errors.DBError(nil)
+	err = errors.PageTokenInvalid(nil)
 
 	// Use WithMsg to carry a message.
 	err = errors.Wrap(io.EOF, codeTestError, errors.WithMsg("test"))

_examples/status.go

@@ -0,0 +1,56 @@
+// Copyright 2023 FishGoddess. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/FishGoddess/errors"
+	"github.com/FishGoddess/errors/status"
+)
+
+var (
+	errAuthFailed = errors.New("auth failed")
+)
+
+func isAuthFailed(err error) bool {
+	return err == errAuthFailed
+}
+
+func main() {
+	// We provide a way to transfer errors to status.
+	// A status can be used by a server like grpc server with google.status.
+	// For example, we have an auth failed error which will be returned by service.
+	// However, we usually return a status code represents it in server,
+	// and we usually return a human-being readable msg instead of the error msg.
+	// So it has a gap between service error and server status.
+	// You can register a status with server code and msg, then use Parse to restore them.
+	authFailedStatus := status.New(1000, "you should check auth", isAuthFailed)
+	status.RegisterStatus(authFailedStatus)
+
+	// Get code and msg from error.
+	code, msg := status.Parse(errAuthFailed)
+	fmt.Println(code, msg)
+
+	// Of course, you can use errors.Wrap to get an error with msg.
+	// Then register a status about it.
+	errCode := int32(123456)
+	err := errors.Wrap(io.EOF, errCode, errors.WithMsg("hello"))
+
+	isError := func(err error) bool {
+		return errors.Is(err, errCode)
+	}
+
+	// As you can see, the error code and status code don't need to be the same.
+	statusCode := int32(654321)
+	status.RegisterStatus(status.New(statusCode, "i am status", isError))
+
+	// The msg will be the one set to error using WithMsg.
+	// The registered msg would be used only if the error doesn't have a set msg.
+	// Try to remove errors.WithMsg("hello") above and run again.
+	code, msg = status.Parse(err)
+	fmt.Println(code, msg)
+}

_icons/coverage.svg

@@ -14,7 +14,7 @@ func New(text string) error {
 	return errors.New(text)
 }
 
-// NewF returns a string error.
-func NewF(text string, params ...interface{}) error {
+// Newf returns a string error formatted with params.
+func Newf(text string, params ...interface{}) error {
 	return fmt.Errorf(text, params...)
 }

errors.go

@@ -16,9 +16,9 @@ func TestNew(t *testing.T) {
 	}
 }
 
-// go test -v -cover -run=^TestNewF$
-func TestNewF(t *testing.T) {
-	err := NewF("test %d %.2f", 123, 3.14)
+// go test -v -cover -run=^TestNewf$
+func TestNewf(t *testing.T) {
+	err := Newf("test %d %.2f", 123, 3.14)
 	if err.Error() != "test 123 3.14" {
 		t.Errorf("err.Error() %s != 'test 123 3.14'", err.Error())
 	}

errors_test.go

@@ -5,41 +5,10 @@
 package errors
 
 const (
-	codeTimeout      = 1000
-	codeNetworkError = 1100
-	codeDBError      = 1200
+	codeDBError          = 1100
+	codePageTokenInvalid = 1200
 )
 
-// Timeout returns a timeout error.
-func Timeout(err error, opts ...Option) error {
-	return Wrap(err, codeTimeout, opts...)
-}
-
-// IsTimeout if err is timeout.
-func IsTimeout(err error) bool {
-	return Is(err, codeTimeout)
-}
-
-// UnwrapTimeout if err is timeout.
-func UnwrapTimeout(err error) (error, bool) {
-	return Unwrap(err, codeTimeout)
-}
-
-// NetworkError returns a network error.
-func NetworkError(err error, opts ...Option) error {
-	return Wrap(err, codeNetworkError, opts...)
-}
-
-// IsNetworkError if err is network error.
-func IsNetworkError(err error) bool {
-	return Is(err, codeNetworkError)
-}
-
-// UnwrapNetworkError if err is network error.
-func UnwrapNetworkError(err error) (error, bool) {
-	return Unwrap(err, codeNetworkError)
-}
-
 // DBError returns a db error.
 func DBError(err error, opts ...Option) error {
 	return Wrap(err, codeDBError, opts...)
@@ -54,3 +23,18 @@ func IsDBError(err error) bool {
 func UnwrapDBError(err error) (error, bool) {
 	return Unwrap(err, codeDBError)
 }
+
+// PageTokenInvalid returns a page token invalid error.
+func PageTokenInvalid(err error, opts ...Option) error {
+	return Wrap(err, codePageTokenInvalid, opts...)
+}
+
+// IsPageTokenInvalid if err is page token invalid.
+func IsPageTokenInvalid(err error) bool {
+	return Is(err, codePageTokenInvalid)
+}
+
+// UnwrapPageTokenInvalid if err is page token invalid.
+func UnwrapPageTokenInvalid(err error) (error, bool) {
+	return Unwrap(err, codePageTokenInvalid)
+}

extension.go

@@ -9,40 +9,6 @@ import (
 	"testing"
 )
 
-// go test -v -cover -run=^TestTimeout$
-func TestTimeout(t *testing.T) {
-	err := Timeout(nil)
-	if err != nil {
-		t.Error("Timeout is wrong", err)
-	}
-
-	err = Timeout(errors.New("timeout"))
-	if !IsTimeout(err) {
-		t.Error("IsTimeout is wrong", err)
-	}
-
-	if e, ok := UnwrapTimeout(err); !ok || e.Error() != "timeout" {
-		t.Error("Timeout or UnwrapTimeout is wrong", err)
-	}
-}
-
-// go test -v -cover -run=^TestNetworkError$
-func TestNetworkError(t *testing.T) {
-	err := NetworkError(nil)
-	if err != nil {
-		t.Error("NetworkError is wrong", err)
-	}
-
-	err = NetworkError(errors.New("network error"))
-	if !IsNetworkError(err) {
-		t.Error("IsNetworkError is wrong", err)
-	}
-
-	if e, ok := UnwrapNetworkError(err); !ok || e.Error() != "network error" {
-		t.Error("NetworkError or UnwrapNetworkError is wrong", err)
-	}
-}
-
 // go test -v -cover -run=^TestDBError$
 func TestDBError(t *testing.T) {
 	err := DBError(nil)
@@ -59,3 +25,20 @@ func TestDBError(t *testing.T) {
 		t.Error("DBError or UnwrapDBError is wrong", err)
 	}
 }
+
+// go test -v -cover -run=^TestPageTokenInvalid$
+func TestPageTokenInvalid(t *testing.T) {
+	err := PageTokenInvalid(nil)
+	if err != nil {
+		t.Error("PageTokenInvalid is wrong", err)
+	}
+
+	err = PageTokenInvalid(errors.New("page token invalid"))
+	if !IsPageTokenInvalid(err) {
+		t.Error("IsPageTokenInvalid is wrong", err)
+	}
+
+	if e, ok := UnwrapPageTokenInvalid(err); !ok || e.Error() != "page token invalid" {
+		t.Error("PageTokenInvalid or UnwrapPageTokenInvalid is wrong", err)
+	}
+}