This example provides a basic overview of Goa. It consists of a single service that implements an endpoints that multiplies two integers and returns the result (exciting I know).
The example shows how to generate server and client code that supports both the HTTP and gRPC transports.
The calc service provides a single method multiply which takes the integer
operands as the payload and returns the integer sum as the result.
// design/design.go
var _ = Service("calc", func() {
Method("multiply", func() {
Payload(func() {
Attribute("a", Int, "Left operand", func() {
Meta("rpc:tag", "1")
})
Field(2, "b", Int, "Right operand")
Required("a", "b")
})
Result(Int)
...
})
The design then describes how the multiply method must be served via HTTP and gRPC
transports.
// HTTP describes the HTTP tranport mapping.
HTTP(func() {
GET("/multiply/{a}/{b}")
Response(StatusOK)
})
// GRPC describes the gRPC transport mapping.
GRPC(func() {
Response(CodeOK)
})
The design also describes an endpoint that serves the auto-generated open API specification using the HTTP file server.
Files("/swagger.json", "../../gen/http/openapi.json")
goa gen command generates the boilerplate code needed to serve the multiply
method via HTTP and gRPC transports.
$ goa gen goa.design/examples/basic/design -o $GOPATH/src/goa.design/examples/basic
The above command creates a gen folder inside the directory $GOPATH/src/goa.design/examples/basic with the following layout
├── design
│ └── design.go
└── gen
├── calc
│ ├── client.go
│ ├── endpoints.go
│ └── service.go
├── grpc
│ ├── calc
│ │ ├── client
│ │ │ ├── client.go
│ │ │ ├── cli.go
│ │ │ ├── encode_decode.go
│ │ │ └── types.go
│ │ ├── pb
│ │ │ ├── calc.pb.go
│ │ │ └── calc.proto
│ │ └── server
│ │ ├── encode_decode.go
│ │ ├── server.go
│ │ └── types.go
│ └── cli
│ └── calc
│ └── cli.go
└── http
├── calc
│ ├── client
│ │ ├── client.go
│ │ ├── cli.go
│ │ ├── encode_decode.go
│ │ ├── paths.go
│ │ └── types.go
│ └── server
│ ├── encode_decode.go
│ ├── paths.go
│ ├── server.go
│ └── types.go
├── cli
│ └── calc
│ └── cli.go
├── openapi.json
└── openapi.yaml
gen/calccontains the transport-independent logic that exposes the business logic to the HTTP and gRPC transports via goa endpoints.gen/httpandgen/grpccontain the HTTP and gRPC transport server and client code respectively.
Users SHOULD NOT edit the code generated by goa gen command. Instead user
code should consume the generated code using the usual Go constructs: function
calls, structs that implement generated interfaces etc.
The goa example command creates an example service implementation along with
the example server code to spin up both HTTP and gRPC servers and their client
counterparts. Users SHOULD edit the code generated by goa example, this
command is intended to be run once to get started.
$ goa example goa.design/examples/basic/design -o $GOPATH/src/goa.design/examples/basic
├── calc.go
├── cmd
│ ├── calc
│ │ ├── grpc.go
│ │ ├── http.go
│ │ └── main.go
│ └── calc-cli
│ ├── grpc.go
│ ├── http.go
│ └── main.go
├── design
└── gen
calc.gocontains the service implementation where users add the business logic.
func (s *calcSvc) Multiply(ctx context.Context, p *calcsvc.MultiplyPayload) (int, error) {
return p.A + p.B, nil
}
- The directories in the
cmdcorrespond to the optionalServerDSL described in the design. A directory is created for eachServerDSL.
The generated example server and client can be built and run as follows
$ go build ./cmd/calc && go build ./cmd/calc-cli
# Run the server
$ ./calc
[calc] 12:27:57 HTTP "Multiply" mounted on GET /multiply/{a}/{b}
[calc] 12:27:57 HTTP "../../gen/http/openapi.json" mounted on GET /swagger.json
[calc] 12:27:57 serving gRPC method calc.Calc/Multiply
[calc] 12:27:57 HTTP server listening on "localhost:8000"
[calc] 12:27:57 gRPC server listening on "localhost:8080"
# Run the client
# Contact HTTP server
$ ./calc-cli --url="http://localhost:8000" calc multiply --a 1 --b 2
3
# Contact gRPC server
$ ./calc-cli --url="grpc://localhost:8080" calc multiply --message '{"a": 1, "b": 2}'
3
-h/--helpprovides more information on using the server and client executables.
Goa generates Open API v2.0 specifications for every service that defines an HTTP transport. Users can view the generated docs using their choice of swagger documentation viewer.
- Online Viewer - https://editor.swagger.io/
- Local server - https://swagger.io/tools/swagger-editor/
Goa also generates a proto file for each service that defines a gRPC transport.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent