Goa is a framework for building micro-services and APIs in Go using a unique design-first approach.
Goa takes a different approach to building services by making it possible to describe the design of the service API using a simple Go DSL. Goa uses the description to generate specialized service helper code, client code and documentation. Goa is extensible via plugins, for example the goakit plugin generates code that leverage the Go kit library.
The service design describes the transport independent layer of the services in the form of simple methods that accept a context and a payload and return a result and an error. The design also describes how the payloads, results and errors are serialized in the transport (HTTP or gRPC). For example a service method payload may be built from an HTTP request by extracting values from the request path, headers and body. This clean separation of layers makes it possible to expose the same service using multiple transports. It also promotes good design where the service business logic concerns are expressed and implemented separately from the transport logic.
The Goa DSL consists of Go functions so that it may be extended easily to avoid repetition and promote standards. The design code itself can easily be shared across multiple services by simply importing the corresponding Go package again promoting reuse and standardization across services.
The Goa tool accepts the Go design package import path as input and produces the interface as well as the glue that binds the service and client code with the underlying transport. The code is specific to the API so that for example there is no need to cast or "bind" any data structure prior to using the request payload or response result. The design may define validations in which case the generated code takes care of validating the incoming request payload prior to invoking the service method on the server, and validating the response prior to invoking the client code.
A couple of Getting Started guides produced by the community.
Joseph Ocol from Pelmorex Corp. goes through a complete example writing a server and client service using both HTTP and gRPC transports.
Gleidson Nascimento goes through how to create a complete service that using both CORS and JWT based authentication to secure access.
Assuming you have a working Go setup, and are using Go modules:
env GO111MODULE=on go get -u goa.design/goa/v3/...@v3Alternatively, when NOT using Go modules (this installs Goa v2, see below):
env GO111MODULE=off go get -u goa.design/goa/...Goa v2 and Goa v3 are functionally identical. The only addition in Goa v3 is support for Go modules. Goa v3 requires Go v1.11 or above, it also requires projects that use Goa to be within modules.
Projects that use Goa v3 use goa.design/goa/v3 as root package import path
while projects that use v2 use goa.design/goa (projects that use v1 use
github.com/goadesign/goa).
Note that the Goa v3 tool is backwards compatible and can generate code for v2 designs. This means that you don't need to swap the tool to generate code for designs using v2 or v3 (designs using v1 use a different tool altogether).
Since Goa generates and compiles code vendoring tools are not able to
automatically identify all the dependencies. In particular the generator
package is only used by the generated code. To alleviate this issue simply add
goa.design/goa/codegen/generator as a required package to the vendor manifest.
For example if you are using dep add the following line to Gopkg.toml:
required = ["goa.design/goa/codegen/generator"]This only applies to Goa v2 as vendoring is not used together with Go modules.
Goa follows Semantic Versioning which is a fancy way of
saying it publishes releases with version numbers of the form vX.Y.Z and makes
sure that your code can upgrade to new versions with the same X component
without having to make changes.
Releases are tagged with the corresponding version number. There is also a
branch for each major version (v1, v2 and v3).
Current Release: v3.2.6
Note: the instructions below assume Goa v3.
Create a new Goa project:
mkdir -p calcsvc/design
cd calcsvc
go mod init calcsvcCreate the file design.go in the design directory with the following
content:
package design
import . "goa.design/goa/v3/dsl"
// API describes the global properties of the API server.
var _ = API("calc", func() {
Title("Calculator Service")
Description("HTTP service for adding numbers, a goa teaser")
Server("calc", func() {
Host("localhost", func() { URI("http://localhost:8088") })
})
})
// Service describes a service
var _ = Service("calc", func() {
Description("The calc service performs operations on numbers")
// Method describes a service method (endpoint)
Method("add", func() {
// Payload describes the method payload
// Here the payload is an object that consists of two fields
Payload(func() {
// Attribute describes an object field
Attribute("a", Int, "Left operand")
Attribute("b", Int, "Right operand")
// Both attributes must be provided when invoking "add"
Required("a", "b")
})
// Result describes the method result
// Here the result is a simple integer value
Result(Int)
// HTTP describes the HTTP transport mapping
HTTP(func() {
// Requests to the service consist of HTTP GET requests
// The payload fields are encoded as path parameters
GET("/add/{a}/{b}")
// Responses use a "200 OK" HTTP status
// The result is encoded in the response body
Response(StatusOK)
})
})
})This file contains the design for a calc service which accepts HTTP GET
requests to /add/{a}/{b} where {a} and {b} are placeholders for integer
values. The API returns the sum of a and b in the HTTP response body.