github.com/hxx258456/ccgo@v0.0.5-0.20230213014102-48b35f46f66f/grpc/README.md (about)

     1  # gRPC-Go
     2  
     3  [![Build Status](https://travis-ci.org/grpc/grpc-go.svg)](https://travis-ci.org/grpc/grpc-go)
     4  [![GoDoc](https://pkg.go.dev/badge/google.golang.org/grpc)][API]
     5  [![GoReportCard](https://goreportcard.com/badge/grpc/grpc-go)](https://goreportcard.com/report/github.com/grpc/grpc-go)
     6  
     7  The [Go][] implementation of [gRPC][]: A high performance, open source, general
     8  RPC framework that puts mobile and HTTP/2 first. For more information see the
     9  [Go gRPC docs][], or jump directly into the [quick start][].
    10  
    11  ## Prerequisites
    12  
    13  - **[Go][]**: any one of the **three latest major** [releases][go-releases].
    14  
    15  ## Installation
    16  
    17  With [Go module][] support (Go 1.11+), simply add the following import
    18  
    19  ```go
    20  import "github.com/hxx258456/ccgo/grpc"
    21  ```
    22  
    23  to your code, and then `go [build|run|test]` will automatically fetch the
    24  necessary dependencies.
    25  
    26  Otherwise, to install the `grpc-go` package, run the following command:
    27  
    28  ```console
    29  $ go get -u google.golang.org/grpc
    30  ```
    31  
    32  > **Note:** If you are trying to access `grpc-go` from **China**, see the
    33  > [FAQ](#FAQ) below.
    34  
    35  ## Learn more
    36  
    37  - [Go gRPC docs][], which include a [quick start][] and [API
    38    reference][API] among other resources
    39  - [Low-level technical docs](Documentation) from this repository
    40  - [Performance benchmark][]
    41  - [Examples](examples)
    42  
    43  ## FAQ
    44  
    45  ### I/O Timeout Errors
    46  
    47  The `golang.org` domain may be blocked from some countries. `go get` usually
    48  produces an error like the following when this happens:
    49  
    50  ```console
    51  $ go get -u google.golang.org/grpc
    52  package google.golang.org/grpc: unrecognized import path "github.com/hxx258456/ccgo/grpc" (https fetch: Get https://google.golang.org/grpc?go-get=1: dial tcp 216.239.37.1:443: i/o timeout)
    53  ```
    54  
    55  To build Go code, there are several options:
    56  
    57  - Set up a VPN and access google.golang.org through that.
    58  
    59  - Without Go module support: `git clone` the repo manually:
    60  
    61    ```sh
    62    git clone https://github.com/grpc/grpc-go.git $GOPATH/src/google.golang.org/grpc
    63    ```
    64  
    65    You will need to do the same for all of grpc's dependencies in `golang.org`,
    66    e.g. `golang.org/x/net`.
    67  
    68  - With Go module support: it is possible to use the `replace` feature of `go
    69    mod` to create aliases for golang.org packages.  In your project's directory:
    70  
    71    ```sh
    72    go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest
    73    go mod tidy
    74    go mod vendor
    75    go build -mod=vendor
    76    ```
    77  
    78    Again, this will need to be done for all transitive dependencies hosted on
    79    golang.org as well. For details, refer to [golang/go issue #28652](https://github.com/golang/go/issues/28652).
    80  
    81  ### Compiling error, undefined: grpc.SupportPackageIsVersion
    82  
    83  #### If you are using Go modules:
    84  
    85  Ensure your gRPC-Go version is `require`d at the appropriate version in
    86  the same module containing the generated `.pb.go` files.  For example,
    87  `SupportPackageIsVersion6` needs `v1.27.0`, so in your `go.mod` file:
    88  
    89  ```go
    90  module <your module name>
    91  
    92  require (
    93      google.golang.org/grpc v1.27.0
    94  )
    95  ```
    96  
    97  #### If you are *not* using Go modules:
    98  
    99  Update the `proto` package, gRPC package, and rebuild the `.proto` files:
   100  
   101  ```sh
   102  go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
   103  go get -u google.golang.org/grpc
   104  protoc --go_out=plugins=grpc:. *.proto
   105  ```
   106  
   107  ### How to turn on logging
   108  
   109  The default logger is controlled by environment variables. Turn everything on
   110  like this:
   111  
   112  ```console
   113  $ export GRPC_GO_LOG_VERBOSITY_LEVEL=99
   114  $ export GRPC_GO_LOG_SEVERITY_LEVEL=info
   115  ```
   116  
   117  ### The RPC failed with error `"code = Unavailable desc = transport is closing"`
   118  
   119  This error means the connection the RPC is using was closed, and there are many
   120  possible reasons, including:
   121   1. mis-configured transport credentials, connection failed on handshaking
   122   1. bytes disrupted, possibly by a proxy in between
   123   1. server shutdown
   124   1. Keepalive parameters caused connection shutdown, for example if you have configured
   125      your server to terminate connections regularly to [trigger DNS lookups](https://github.com/grpc/grpc-go/issues/3170#issuecomment-552517779).
   126      If this is the case, you may want to increase your [MaxConnectionAgeGrace](https://pkg.go.dev/google.golang.org/grpc/keepalive?tab=doc#ServerParameters),
   127      to allow longer RPC calls to finish.
   128  
   129  It can be tricky to debug this because the error happens on the client side but
   130  the root cause of the connection being closed is on the server side. Turn on
   131  logging on __both client and server__, and see if there are any transport
   132  errors.
   133  
   134  [API]: https://pkg.go.dev/google.golang.org/grpc
   135  [Go]: https://golang.org
   136  [Go module]: https://github.com/golang/go/wiki/Modules
   137  [gRPC]: https://grpc.io
   138  [Go gRPC docs]: https://grpc.io/docs/languages/go
   139  [Performance benchmark]: https://performance-dot-grpc-testing.appspot.com/explore?dashboard=5180705743044608
   140  [quick start]: https://grpc.io/docs/languages/go/quickstart
   141  [go-releases]: https://golang.org/doc/devel/release.html