github.com/ManabuSeki/goa-v1@v1.4.3/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 context.Context interface as first parameter so that deadlines and cancelation 20 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