github.com/kaituanwang/hyperledger@v2.0.1+incompatible/docs/source/error-handling.rst (about)

     1  Error handling
     2  ==============
     3  
     4  General Overview
     5  ----------------
     6  Hyperledger Fabric code should use the vendored package
     7  **github.com/pkg/errors** in place of the standard error type provided by Go.
     8  This package allows easy generation and display of stack traces with error
     9  messages.
    10  
    11  Usage Instructions
    12  ------------------
    13  
    14  **github.com/pkg/errors** should be used in place of all calls to
    15  ``fmt.Errorf()`` or ``errors.New()``. Using this package will generate a
    16  call stack that will be appended to the error message.
    17  
    18  Using this package is simple and will only require easy tweaks to your code.
    19  
    20  First, you'll need to import **github.com/pkg/errors**.
    21  
    22  Next, update all errors that are generated by your code to use one of the error
    23  creation functions (errors.New(), errors.Errorf(), errors.WithMessage(),
    24  errors.Wrap(), errors.Wrapf().
    25  
    26  .. note:: See https://godoc.org/github.com/pkg/errors for complete documentation
    27            of the available error creation function. Also, refer to the General guidelines
    28            section below for more specific guidelines for using the package for Fabric
    29            code.
    30  
    31  Finally, change the formatting directive for any logger or fmt.Printf() calls
    32  from ``%s`` to ``%+v`` to print the call stack along with the error message.
    33  
    34  General guidelines for error handling in Hyperledger Fabric
    35  -----------------------------------------------------------
    36  
    37  - If you are servicing a user request, you should log the error and return it.
    38  - If the error comes from an external source, such as a Go library or vendored
    39    package, wrap the error using errors.Wrap() to generate a call stack for the
    40    error.
    41  - If the error comes from another Fabric function, add further context, if
    42    desired, to the error message using errors.WithMessage() while leaving the
    43    call stack unaffected.
    44  - A panic should not be allowed to propagate to other packages.
    45  
    46  Example program
    47  ---------------
    48  
    49  The following example program provides a clear demonstration of using the
    50  package:
    51  
    52  .. code:: go
    53  
    54    package main
    55  
    56    import (
    57      "fmt"
    58  
    59      "github.com/pkg/errors"
    60    )
    61  
    62    func wrapWithStack() error {
    63      err := createError()
    64      // do this when error comes from external source (go lib or vendor)
    65      return errors.Wrap(err, "wrapping an error with stack")
    66    }
    67    func wrapWithoutStack() error {
    68      err := createError()
    69      // do this when error comes from internal Fabric since it already has stack trace
    70      return errors.WithMessage(err, "wrapping an error without stack")
    71    }
    72    func createError() error {
    73      return errors.New("original error")
    74    }
    75  
    76    func main() {
    77      err := createError()
    78      fmt.Printf("print error without stack: %s\n\n", err)
    79      fmt.Printf("print error with stack: %+v\n\n", err)
    80      err = wrapWithoutStack()
    81      fmt.Printf("%+v\n\n", err)
    82      err = wrapWithStack()
    83      fmt.Printf("%+v\n\n", err)
    84    }
    85  
    86  .. Licensed under Creative Commons Attribution 4.0 International License
    87     https://creativecommons.org/licenses/by/4.0/