OSDN Git Service

Merge pull request #41 from Bytom/dev
[bytom/vapor.git] / errors / doc.go
1 /*
2 Package errors implements a basic error wrapping pattern, so that errors can be
3 annotated with additional information without losing the original error.
4
5 Example:
6
7         import "chain/errors"
8
9         func query() error {
10                 err := pq.Exec("SELECT...")
11                 if err != nil {
12                         return errors.Wrap(err, "select query failed")
13                 }
14
15                 err = pq.Exec("INSERT...")
16                 if err != nil {
17                         return errors.Wrap(err, "insert query failed")
18                 }
19
20                 return nil
21         }
22
23         func main() {
24                 err := query()
25                 if _, ok := errors.Root(err).(sql.ErrNoRows); ok {
26                         log.Println("There were no results")
27                         return
28                 } else if err != nil {
29                         log.Println(err)
30                         return
31                 }
32
33                 log.Println("success")
34         }
35
36 When to wrap errors
37
38 Errors should be wrapped with additional messages when the context is ambiguous.
39 This includes when the error could arise in multiple locations in the same
40 function, when the error is very common and likely to appear at different points
41 in the call tree (e.g., JSON serialization errors), or when you need specific
42 parameters alongside the original error message.
43
44 Error handling best practices
45
46 Errors are part of a function's interface. If you expect the caller to perform
47 conditional error handling, you should document the errors returned by your
48 function in a function comment, and include it as part of your unit tests.
49
50 Be disciplined about validating user input. Programs should draw a very clear
51 distinction between user errors and internal errors.
52
53 Avoid redundant error logging. If you return an error, assume it will be logged
54 higher up the call stack. For a given project, choose an appropriate layer to
55 handle error logging.
56 */
57 package errors