goa

Goa implements a Go-based Domain Specific Language (DSL) that developers use to declaratively define API structures using Service(), Method(), Payload(), Result(), and transport-specific functions. The DSL is compiled and executed by the generator, which evaluates all constructs into an internal expression system (RootExpr, ServiceExpr, MethodExpr, AttributeExpr, ValidationExpr, HTTPEndpointExpr, GRPCEndpointExpr) that represents the complete API design. This expression tree becomes the single source of truth for all downstream code generation, documentation, and client generation.

The code generation engine orchestrates protocol-specific generators that consume the expression tree and produce transport-layer implementations. HTTP transport generation creates route handlers, request/response marshaling, and middleware hooks; gRPC generation produces service definitions and interceptor support; JSON-RPC generation creates JSON-RPC 2.0 compliant endpoints. Each protocol generator is independent but shares type definitions and validation rules from the unified expression model, ensuring consistency across transports without code duplication.

Goa supports design evolution by allowing developers to modify the DSL and regenerate code. The generator produces code in separate files (service.go, endpoints.go, http.go, grpc.go) such that business logic files (service implementation) are not overwritten during regeneration. Developers can add new methods, modify types, or change transport configurations, and the generator updates only the affected generated files. The design model tracks version information and can detect breaking changes, though the framework does not enforce backward compatibility automatically.

Goa generates JSON-RPC 2.0 compliant endpoints from service definitions, creating HTTP endpoints that accept JSON-RPC 2.0 requests and return JSON-RPC 2.0 responses. The generator creates request/response marshaling code that maps JSON-RPC parameters to service method arguments and service method results to JSON-RPC responses. Error handling is integrated through JSON-RPC error codes and messages. The generated code handles both positional and named parameters as defined in the JSON-RPC 2.0 specification.

Goa generates type-safe client libraries for all transport protocols (HTTP, gRPC, JSON-RPC) from the service definition. The generator creates client structs with methods that correspond to service methods, handling request marshaling, response unmarshaling, and error handling. HTTP clients use the standard Go http.Client; gRPC clients use the generated gRPC stubs; JSON-RPC clients use HTTP with JSON-RPC 2.0 formatting. Generated clients are fully type-safe and include proper error handling and timeout support.

Goa generates code that maps HTTP request/response headers, path parameters, query parameters, and request bodies to service method arguments and results. The HTTPEndpointExpr configuration specifies where each parameter comes from (path, query, header, body), and the generator creates code that extracts, validates, and transforms these parameters. Response headers and status codes are also configured in the design and automatically generated. The generator handles type conversion (e.g., string to int) and validation for all parameter types.

Goa generates validation code for all request payloads and response results based on ValidationExpr rules defined in the DSL (Required, Enum, Format, Pattern, Minimum, Maximum, etc.). The generated validation functions are type-safe Go code that enforces constraints at runtime before business logic executes. Validation rules are embedded in AttributeExpr definitions and automatically propagated to all transport layers (HTTP, gRPC, JSON-RPC), ensuring consistent validation across protocols without duplicating constraint definitions.

Goa generates OpenAPI 3.0 specifications directly from the expression tree, mapping service definitions, methods, payloads, results, and HTTP endpoint configurations into OpenAPI components (paths, schemas, parameters, responses). The generator traverses the expression model and produces valid OpenAPI YAML/JSON that accurately reflects the API design, including request/response schemas, validation constraints, and HTTP metadata. This ensures the OpenAPI spec is always synchronized with the implementation and never becomes stale.

Goa generates type transformation functions that convert between transport-layer types (HTTP request bodies, gRPC messages, JSON-RPC parameters) and internal service types. The generator analyzes the expression tree to determine which fields must be transformed, in what order, and with what validation. Marshaling code is generated for serialization (Go structs to JSON/Protobuf) and unmarshaling code for deserialization (JSON/Protobuf to Go structs), with automatic handling of nested types, arrays, and custom types.

Goa generates HTTP endpoint routing code that maps HTTP requests to service methods based on HTTPEndpointExpr configurations (routes, HTTP methods, path parameters, query parameters, headers). The generated code creates a net/http compatible router that handles request parsing, parameter extraction, validation, and response serialization. Middleware hooks are generated at multiple points (before routing, before business logic, after business logic) allowing developers to inject cross-cutting concerns (logging, authentication, rate limiting) without modifying generated code.

Goa generates gRPC service definitions (.proto files) and Go service stubs from GRPCEndpointExpr configurations. The generator creates gRPC service interfaces, request/response message types, and server/client implementations. Interceptor hooks are generated at multiple points (unary, streaming) allowing developers to inject cross-cutting concerns (authentication, logging, metrics) without modifying generated code. The generator handles both unary and streaming RPC patterns defined in the design.

Goa generates example server implementations that demonstrate how to implement the service interface, and example CLI clients that show how to invoke the API. The generator creates boilerplate code that developers can use as a starting point for their implementation. Example code includes proper error handling, logging, and usage patterns. CLI clients are generated with command-line argument parsing and output formatting, allowing developers to test the API from the command line.

Goa generates Go service interfaces from ServiceExpr and MethodExpr definitions, creating type-safe interfaces that developers implement with business logic. Each method in the interface corresponds to a method in the design, with parameters matching the Payload type and return values matching the Result type. The generated interface enforces a contract between the design and implementation, ensuring that business logic matches the API specification. Error handling is integrated through the Errors field in MethodExpr, generating error types that can be returned from service methods.

Goa generates HTTP WebSocket and Server-Sent Events (SSE) endpoint code from MethodExpr streaming configurations. The generator creates WebSocket upgrade handlers and SSE response writers that integrate with the service interface. Streaming endpoints are defined in the design using Stream configuration, which specifies the streaming direction (client-to-server, server-to-client, bidirectional) and message types. The generated code handles connection lifecycle, message marshaling/unmarshaling, and error propagation.