github.com/brycereitano/goa@v0.0.0-20170315073847-8ffa6c85e265/doc.go (about)

     1  /*
     2  Package goa provides the runtime support for goa microservices.
     3  
     4  Code Generation
     5  
     6  goa service development begins with writing the *design* of a service. The design is described using
     7  the goa language implemented by the github.com/goadesign/goa/design/apidsl package. The `goagen` tool
     8  consumes the metadata produced from executing the design language to generate service specific code
     9  that glues the underlying HTTP server with action specific code and data structures.
    10  
    11  The goa package contains supporting functionality for the generated code including basic request
    12  and response state management through the RequestData and ResponseData structs, error handling via
    13  error classes, middleware support via the Middleware data structure as well as decoding and
    14  encoding algorithms.
    15  
    16  Request Context
    17  
    18  The RequestData and ResponseData structs provides access to the request and response state. goa request
    19  handlers also accept a golang.org/x/net/Context interface as first parameter so that deadlines and
    20  cancelation signals may easily be implemented.
    21  
    22  The request state exposes the underlying http.Request object as well as the deserialized payload (request
    23  body) and parameters (both path and querystring parameters). Generated action specific contexts wrap
    24  the context.Context, ResponseData and RequestData data structures. They expose properly typed fields
    25  that correspond to the request parameters and body data structure descriptions appearing in the design.
    26  
    27  The response state exposes  the response status and body length as well as the underlying ResponseWriter.
    28  Action contexts provide action specific helper methods that write the responses as described in the
    29  design optionally taking an instance of the media type for responses that contain a body.
    30  
    31  Here is an example showing an "update" action corresponding to following design (extract):
    32  
    33      Resource("bottle", func() {
    34          DefaultMedia(Bottle)
    35          Action("update", func() {
    36              Params(func() {
    37                  Param("bottleID", Integer)
    38              })
    39              Payload(UpdateBottlePayload)
    40              Response(OK)
    41              Response(NotFound)
    42          })
    43      })
    44  
    45  The action signature generated by goagen is:
    46  
    47      type BottleController interface {
    48          goa.Controller
    49          Update(*UpdateBottleContext) error
    50      }
    51  
    52  where UpdateBottleContext is:
    53  
    54      type UpdateBottleContext struct {
    55          context.Context      // Timeout and deadline support
    56          *goa.ResponseData    // Response state access
    57          *goa.RequestData     // Request state access
    58          Service *goa.Service // Service handling request
    59          BottleID  int        // Properly typed parameter fields
    60          Payload   *UpdateBottlePayload // Properly typed payload
    61      }
    62  
    63  and implements:
    64  
    65      func (ctx *UpdateBottleContext) OK(resp *Bottle) error
    66      func (ctx *UpdateBottleContext) NotFound() error
    67  
    68  The definitions of the Bottle and UpdateBottlePayload data structures are ommitted for brievity.
    69  
    70  Controllers
    71  
    72  There is one controller interface generated per resource defined via the design language. The
    73  interface exposes the controller actions. User code must provide data structures that implement these
    74  interfaces when mounting a controller onto a service. The controller data structure should include
    75  an anonymous field of type *goa.Controller which takes care of implementing the middleware handling.
    76  
    77  Middleware
    78  
    79  A goa middleware is a function that takes and returns a Handler. A Handler is a the low level
    80  function which handles incoming HTTP requests. goagen generates the handlers code so each handler
    81  creates the action specific context and calls the controller action with it.
    82  
    83  Middleware can be added to a goa service or a specific controller using the corresponding Use
    84  methods. goa comes with a few stock middleware that handle common needs such as logging, panic
    85  recovery or using the RequestID header to trace requests across multiple services.
    86  
    87  Error Handling
    88  
    89  The controller action methods generated by goagen such as the Update method of the BottleController
    90  interface shown above all return an error value. goa defines an Error struct that action
    91  implementations can use to describe the content of the corresponding HTTP response. Errors can be
    92  created using error classes which are functions created via NewErrorClass.
    93  
    94  The ErrorHandler middleware maps errors to HTTP responses. Errors that are instances of the Error
    95  struct are mapped using the struct fields while other types of errors return responses with status
    96  code 500 and the error message in the body.
    97  
    98  Validation
    99  
   100  The goa design language documented in the dsl package makes it possible to attach validations to
   101  data structure definitions. One specific type of validation consists of defining the format that a
   102  data structure string field must follow. Example of formats include email, data time, hostnames etc.
   103  The ValidateFormat function provides the implementation for the format validation invoked from the
   104  code generated by goagen.
   105  
   106  Encoding
   107  
   108  The goa design language makes it possible to specify the encodings supported by the API both as
   109  input (Consumes) and output (Produces). goagen uses that information to registed the corresponding
   110  packages with the service encoders and decoders via their Register methods. The service exposes the
   111  DecodeRequest and EncodeResponse that implement a simple content type negotiation algorithm for
   112  picking the right encoder for the "Content-Type" (decoder) or "Accept" (encoder) request header.
   113  */
   114  package goa