grpc
/
grpc-go
mirror of https://github.com/grpc/grpc-go.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

README: adjust links, and slight rework of page (#3736)

This commit is contained in:
Patrice Chalin 2020-07-15 13:41:05 -04:00 committed by GitHub
parent a6c3c6968e
commit 46d42f139d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 64 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
README.md
View File

@ -1,65 +1,53 @@
# gRPC-Go # gRPC-Go
[![Build Status](https://travis-ci.org/grpc/grpc-go.svg)](https://travis-ci.org/grpc/grpc-go) [![Build Status](https://travis-ci.org/grpc/grpc-go.svg)](https://travis-ci.org/grpc/grpc-go)
[![GoDoc](https://godoc.org/google.golang.org/grpc?status.svg)](https://godoc.org/google.golang.org/grpc) [![GoDoc](https://godoc.org/google.golang.org/grpc?status.svg)][API]
[![GoReportCard](https://goreportcard.com/badge/grpc/grpc-go)](https://goreportcard.com/report/github.com/grpc/grpc-go) [![GoReportCard](https://goreportcard.com/badge/grpc/grpc-go)](https://goreportcard.com/report/github.com/grpc/grpc-go)
The Go implementation of [gRPC](https://grpc.io/): A high performance, open The [Go][] implementation of [gRPC][]: A high performance, open source, general
source, general RPC framework that puts mobile and HTTP/2 first. For more RPC framework that puts mobile and HTTP/2 first. For more information see the
information see the [gRPC Quick Start: [Go gRPC docs][], or jump directly into the [quick start][].
Go](https://grpc.io/docs/languages/go/quickstart/) guide.
Installation ## Prerequisites
------------
To install this package, you need to install Go and setup your Go workspace on - **[Go][]**: any one of the **three latest major** [releases][go-releases].
your computer. The simplest way to install the library is to run:
## Installation
With [Go module][] support (Go 1.11+), simply add the following import
```go
import "google.golang.org/grpc"
``` ```
to your code, and then `go [build|run|test]` will automatically fetch the
necessary dependencies.
Otherwise, to install the `grpc-go` package, run the following command:
```console
$ go get -u google.golang.org/grpc $ go get -u google.golang.org/grpc
``` ```
With Go module support (Go 1.11+), simply `import "google.golang.org/grpc"` in > **Note:** If you are trying to access `grpc-go` from **China**, see the
your source code and `go [build|run|test]` will automatically download the > [FAQ](#FAQ) below.
necessary dependencies ([Go modules
ref](https://github.com/golang/go/wiki/Modules)).
If you are trying to access grpc-go from within China, please see the ## Learn more
[FAQ](#FAQ) below.
Prerequisites - [Go gRPC docs][], which include a [quick start][] and [API
------------- reference][API] among other resources
gRPC-Go officially supports the - [Low-level technical docs](Documentation) from this repository
[three latest major releases of Go](https://golang.org/doc/devel/release.html). - [Performance benchmark][]
- [Examples](examples)
Documentation ## FAQ
-------------
- See [godoc](https://godoc.org/google.golang.org/grpc) for package and API
descriptions.
- Documentation on specific topics can be found in the [Documentation
directory](Documentation/).
- Examples can be found in the [examples directory](examples/).
Performance ### I/O Timeout Errors
-----------
Performance benchmark data for grpc-go and other languages is maintained in
[this
dashboard](https://performance-dot-grpc-testing.appspot.com/explore?dashboard=5652536396611584&widget=490377658&container=1286539696).
Status
------
General Availability [Google Cloud Platform Launch
Stages](https://cloud.google.com/terms/launch-stages).
FAQ
---
#### I/O Timeout Errors
The `golang.org` domain may be blocked from some countries. `go get` usually The `golang.org` domain may be blocked from some countries. `go get` usually
produces an error like the following when this happens: produces an error like the following when this happens:
``` ```console
$ go get -u google.golang.org/grpc $ go get -u google.golang.org/grpc
package google.golang.org/grpc: unrecognized import path "google.golang.org/grpc" (https fetch: Get https://google.golang.org/grpc?go-get=1: dial tcp 216.239.37.1:443: i/o timeout) package google.golang.org/grpc: unrecognized import path "google.golang.org/grpc" (https fetch: Get https://google.golang.org/grpc?go-get=1: dial tcp 216.239.37.1:443: i/o timeout)
``` ```
@ -70,7 +58,7 @@ To build Go code, there are several options:
- Without Go module support: `git clone` the repo manually: - Without Go module support: `git clone` the repo manually:
``` ```sh
git clone https://github.com/grpc/grpc-go.git $GOPATH/src/google.golang.org/grpc git clone https://github.com/grpc/grpc-go.git $GOPATH/src/google.golang.org/grpc
``` ```
@ -80,7 +68,7 @@ To build Go code, there are several options:
- With Go module support: it is possible to use the `replace` feature of `go - With Go module support: it is possible to use the `replace` feature of `go
mod` to create aliases for golang.org packages. In your project's directory: mod` to create aliases for golang.org packages. In your project's directory:
``` ```sh
go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest
go mod tidy go mod tidy
go mod vendor go mod vendor
@ -88,19 +76,17 @@ To build Go code, there are several options:
``` ```
Again, this will need to be done for all transitive dependencies hosted on Again, this will need to be done for all transitive dependencies hosted on
golang.org as well. Please refer to [this golang.org as well. For details, refer to [golang/go issue #28652](https://github.com/golang/go/issues/28652).
issue](https://github.com/golang/go/issues/28652) in the golang repo regarding
this concern.
#### Compiling error, undefined: grpc.SupportPackageIsVersion ### Compiling error, undefined: grpc.SupportPackageIsVersion
##### If you are using Go modules: #### If you are using Go modules:
Please ensure your gRPC-Go version is `require`d at the appropriate version in Ensure your gRPC-Go version is `require`d at the appropriate version in
the same module containing the generated `.pb.go` files. For example, the same module containing the generated `.pb.go` files. For example,
`SupportPackageIsVersion6` needs `v1.27.0`, so in your `go.mod` file: `SupportPackageIsVersion6` needs `v1.27.0`, so in your `go.mod` file:
``` ```go
module <your module name> module <your module name>
require ( require (
@ -108,23 +94,27 @@ require (
) )
``` ```
##### If you are *not* using Go modules: #### If you are *not* using Go modules:
Please update proto package, gRPC package and rebuild the proto files: Update the `proto` package, gRPC package, and rebuild the `.proto` files:
- `go get -u github.com/golang/protobuf/{proto,protoc-gen-go}`
- `go get -u google.golang.org/grpc`
- `protoc --go_out=plugins=grpc:. *.proto`
#### How to turn on logging ```sh
go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
The default logger is controlled by the environment variables. Turn everything go get -u google.golang.org/grpc
on by setting: protoc --go_out=plugins=grpc:. *.proto
```
GRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info
``` ```
#### The RPC failed with error `"code = Unavailable desc = transport is closing"` ### How to turn on logging
The default logger is controlled by environment variables. Turn everything on
like this:
```console
$ export GRPC_GO_LOG_VERBOSITY_LEVEL=99
$ export GRPC_GO_LOG_SEVERITY_LEVEL=info
```
### The RPC failed with error `"code = Unavailable desc = transport is closing"`
This error means the connection the RPC is using was closed, and there are many This error means the connection the RPC is using was closed, and there are many
possible reasons, including: possible reasons, including:
@ -140,3 +130,12 @@ It can be tricky to debug this because the error happens on the client side but
the root cause of the connection being closed is on the server side. Turn on the root cause of the connection being closed is on the server side. Turn on
logging on __both client and server__, and see if there are any transport logging on __both client and server__, and see if there are any transport
errors. errors.
[API]: https://grpc.io/docs/languages/go/api
[Go]: https://golang.org
[Go module]: https://github.com/golang/go/wiki/Modules
[gRPC]: https://grpc.io
[Go gRPC docs]: https://grpc.io/docs/languages/go
[Performance benchmark]: https://performance-dot-grpc-testing.appspot.com/explore?dashboard=5652536396611584&widget=490377658&container=1286539696
[quick start]: https://grpc.io/docs/languages/go/quickstart
[go-releases]: https://golang.org/doc/devel/release.html