goa

module
v3.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2025 License: MIT

README

Goa

Release Go Doc Go Report Card Software License Gurubase

Wizard Logo

Goa Design Wizard

Use the Goa Design Wizard to:

  • Create Goa designs in seconds
  • Review existing designs
  • Explore the Goa DSL

(requires a ChatGPT Plus subscription)

Goa - Design First, Code With Confidence

Overview

Goa transforms how you build APIs and microservices in Go with its powerful design-first approach. Instead of writing boilerplate code, you express your API's intent through a clear, expressive DSL. Goa then automatically generates production-ready code, comprehensive documentation, and client libraries—all perfectly aligned with your design.

The result? Dramatically reduced development time, consistent APIs, and the elimination of the documentation-code drift that plagues traditional development.

Sponsors

incident.io

incident.io: Bounce back stronger after every incident

Use our platform to empower your team to run incidents end-to-end. Rapidly fix and learn from incidents, so you can build more resilient products.

Learn more
Speakeasy

Speakeasy: Enterprise DevEx for your API

Our platform makes it easy to create feature-rich production ready SDKs. Speed up integrations and reduce errors by giving your API the DevEx it deserves.

Integrate with Goa

Why Goa?

Traditional API development suffers from:

  • Inconsistency: Manually maintained docs that quickly fall out of sync with code
  • Wasted effort: Writing repetitive boilerplate and transport-layer code
  • Painful integrations: Client packages that need constant updates
  • Design afterthoughts: Documentation added after implementation, missing key details

Goa solves these problems by:

  • Generating 30-50% of your codebase directly from your design
  • Ensuring perfect alignment between design, code, and documentation
  • Supporting multiple transports (HTTP and gRPC) from a single design
  • Maintaining a clean separation between business logic and transport details

🌟 Key Features

  • Expressive Design Language: Define your API with a clear, type-safe DSL that captures your intent
  • Comprehensive Code Generation:
    • Type-safe server interfaces that enforce your design
    • Client packages with full error handling
    • Transport layer adapters (HTTP/gRPC) with routing and encoding
    • OpenAPI/Swagger documentation that's always in sync
    • CLI tools for testing your services
  • Multi-Protocol Support: Generate HTTP REST and gRPC endpoints from a single design
  • Clean Architecture: Business logic remains separate from transport concerns
  • Enterprise Ready: Supports authentication, authorization, CORS, logging, and more

🔄 How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────────────┐
│ Design API  │────>│ Generate Code│────>│ Implement Business  │
│ using DSL   │     │ & Docs       │     │ Logic               │
└─────────────┘     └──────────────┘     └─────────────────────┘
  1. Design: Express your API's intent in Goa's DSL
  2. Generate: Run goa gen to create server interfaces, client code, and documentation
  3. Implement: Focus solely on writing your business logic in the generated interfaces
  4. Evolve: Update your design and regenerate code as your API evolves

🚀 Quick Start

# Install Goa
go install goa.design/goa/v3/cmd/goa@latest

# Create a new module
mkdir hello && cd hello
go mod init hello

# Define a service in design/design.go
mkdir design
cat > design/design.go << EOF
package design

import . "goa.design/goa/v3/dsl"

var _ = Service("hello", func() {
    Method("say_hello", func() {
        Payload(func() {
            Field(1, "name", String)
            Required("name")
        })
        Result(String)

        HTTP(func() {
            GET("/hello/{name}")
        })
    })
})
EOF

# Generate the code
goa gen hello/design
goa example hello/design

# Build and run
go mod tidy
go run cmd/hello/*.go --http-port 8000

# In another terminal
curl http://localhost:8000/hello/world

The example above:

  1. Defines a simple "hello" service with one method
  2. Generates server and client code
  3. Starts a server that logs requests server-side (without displaying any client output)

📚 Documentation

Our completely redesigned documentation site at goa.design provides comprehensive guides and references:

🛠️ Real-World Examples

The examples repository contains complete, working examples demonstrating:

  • Basic: Simple service showcasing core Goa concepts
  • Cellar: A more complete REST API example
  • Cookies: HTTP cookie management
  • Encodings: Working with different content types
  • Error: Comprehensive error handling strategies
  • Files & Upload/Download: File handling capabilities
  • HTTP Status: Custom status code handling
  • Interceptors: Request/response processing middleware
  • Multipart: Handling multipart form submissions
  • Security: Authentication and authorization examples
  • Streaming: Implementing streaming endpoints
  • Tracing: Integrating with observability tools
  • TUS: Resumable file uploads implementation

🏢 Success Stories

"Goa reduced our API development time by 40% while ensuring perfect consistency between our documentation and implementation. It's been a game-changer for our microservices architecture." - Lead Engineer at FinTech Company

"We migrated 30+ services to Goa and eliminated documentation drift entirely. Our teams can now focus on business logic instead of maintaining OpenAPI specs by hand." - CTO at SaaS Platform

🤝 Community & Support

📣 What's New

Jan 2024: Goa's powerful design DSL is now accessible through the Goa Design Wizard, a specialized AI trained on Goa. Generate service designs through natural language conversations!

February 2025: The Goa website has been completely redesigned with extensive new documentation, tutorials, and guides to help you build better services.

📄 License

MIT License - see LICENSE for details.

Directories

Path Synopsis
cmd
goa
Package codegen contains data structures and algorithms used by the Goa code generation tool.
 Package codegen contains data structures and algorithms used by the Goa code generation tool.
cli
Package cli contains helpers used by transport-specific command-line client generators for parsing the command-line flags to identify the service and the method to make a request along with the request payload to be sent.
 Package cli contains helpers used by transport-specific command-line client generators for parsing the command-line flags to identify the service and the method to make a request along with the request payload to be sent.
codegentest
Package codegentest provides utilities to assist writing unit test for codegen packages.
 Package codegentest provides utilities to assist writing unit test for codegen packages.
example
Package example contains code generation algorithms to produce an example server and client implementation for the transports defined in the design.
 Package example contains code generation algorithms to produce an example server and client implementation for the transports defined in the design.
generator
Package generator contains the code generation algorithms for a service server, client, and OpenAPI specification.
 Package generator contains the code generation algorithms for a service server, client, and OpenAPI specification.
service
Package service contains the code generation algorithms to produce code for the service and views packages and dummy implementation for the services defined in the design.
 Package service contains the code generation algorithms to produce code for the service and views packages and dummy implementation for the services defined in the design.
Package dsl implements the Goa DSL.
 Package dsl implements the Goa DSL.
Package eval implements a DSL engine for executing arbitrary Go DSLs.
 Package eval implements a DSL engine for executing arbitrary Go DSLs.
Package expr defines expressions and data types used by the DSL and the code generators.
 Package expr defines expressions and data types used by the DSL and the code generators.
Package grpc contains code generation logic to produce a server that serves gRPC requests and a client that encode requests to and decode responses from a gRPC server.
 Package grpc contains code generation logic to produce a server that serves gRPC requests and a client that encode requests to and decode responses from a gRPC server.
codegen
Package codegen contains the code generation logic to generate gRPC service definitions (.proto files) from the design DSLs and the corresponding server and client code that wraps the goa-generated endpoints with the protocol buffer compiler (protoc) generated clients and servers.
 Package codegen contains the code generation logic to generate gRPC service definitions (.proto files) from the design DSLs and the corresponding server and client code that wraps the goa-generated endpoints with the protocol buffer compiler (protoc) generated clients and servers.
middleware
Package middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality.
 Package middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality.
middleware/xray
Package xray contains unary and streaming server and client interceptors that create AWS X-Ray segments from the gRPC requests and responses and send the segments to an AWS X-ray daemon.
 Package xray contains unary and streaming server and client interceptors that create AWS X-Ray segments from the gRPC requests and responses and send the segments to an AWS X-ray daemon.
pb
Package goapb contains protocol buffer message types used by the code generation logic.
 Package goapb contains protocol buffer message types used by the code generation logic.
Package http contains HTTP specific constructs that complement the code generated by Goa.
 Package http contains HTTP specific constructs that complement the code generated by Goa.
codegen
Package codegen contains code generation algorithms that produce HTTP servers and clients meant to call - or wrap - the Goa endpoints generated by the service package.
 Package codegen contains code generation algorithms that produce HTTP servers and clients meant to call - or wrap - the Goa endpoints generated by the service package.
codegen/openapi
Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs.
 Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs.
codegen/openapi/v2
Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs.
 Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs.
codegen/openapi/v3
Package openapiv3 contains the algorithms and data structures used to generate OpenAPI v3 specifications from Goa designs.
 Package openapiv3 contains the algorithms and data structures used to generate OpenAPI v3 specifications from Goa designs.
middleware
Package middleware contains HTTP middlewares that wrap a HTTP handler to provide ancilliary functionality such as capturing HTTP details into the request context or printing debug information on incoming requests.
 Package middleware contains HTTP middlewares that wrap a HTTP handler to provide ancilliary functionality such as capturing HTTP details into the request context or printing debug information on incoming requests.
middleware/xray
Package xray contains middleware that creates AWS X-Ray segments from the HTTP requests and responses and send the segments to an AWS X-ray daemon.
 Package xray contains middleware that creates AWS X-Ray segments from the HTTP requests and responses and send the segments to an AWS X-ray daemon.
Package middleware contains transport independent middlewares.
 Package middleware contains transport independent middlewares.
xray
Package xray contains the AWS X-Ray segment document type populated by the transport-specific X-Ray middleware.
 Package xray contains the AWS X-Ray segment document type populated by the transport-specific X-Ray middleware.
xray/xraytest
Package xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.
 Package xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.
Package goa implements a Go framework for writing microservices that promotes best practice by providing a single source of truth from which server code, client code, and documentation is derived.
 Package goa implements a Go framework for writing microservices that promotes best practice by providing a single source of truth from which server code, client code, and documentation is derived.
Package security contains the types used by the code generators to secure goa endpoint.
 Package security contains the types used by the code generators to secure goa endpoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.