Goa4 usage note

Goa日志

Goa的日志格式固定，如测试代码的mount日志：

INFO[01-25|09:56:34] mount      app=API ctrl=Operands action=Add route="GET /add/:left/:right"

依次为：

• 日志类型
• 日志时间
• 行为名称
• 日志内容

其中日志内容是以key=value的形式存在。

Logger接口的实现写在包gopkg.in/inconshreveable/log15.v2，Goa将其重命名为log：

// A Logger writes key/value pairs to a Handler
type Logger interface {
	// New returns a new Logger that has this logger's context plus the given context
	New(ctx ...interface{}) Logger

	// SetHandler updates the logger to write records to the specified handler.
	SetHandler(h Handler)

	// Log a message at the given level with context key/value pairs
	Debug(msg string, ctx ...interface{})
	Info(msg string, ctx ...interface{})
	Warn(msg string, ctx ...interface{})
	Error(msg string, ctx ...interface{})
	Crit(msg string, ctx ...interface{})
}

具体调用方法为：

service.Info("mount", "ctrl", "Operands", "action", "Add", "route", "GET /add/:left/:right")

第一个是日志的名字，其他必须是成对出现，每对为对应的key=value。

注意

• Goa不支持日志存储，因为对日志存储的需求因人而异。为不影响访问速度，建议自省实现异步的日志存储，可以使用MQ。

Goa Media

使用Goa的Media之前，首先得明白其存在的意义。

当终端访问我们的HTTP API时，应有一个双方约定好的信息格式载体，我们以常用的JSON为例。Response body信息为JSON，同时server端反馈的信息也应该是JSON。在Go代码里，JSON的本质是一个type为string的key-value的map，代码表述为：

map[string]interface{}

其中interface接受各种类型。

当我们需要实现这么一个map时，最规范也是最常用的办法，就是将此段JSON的模板结构体直接赋值转换为map。

因此，go生成API-JSON返回信息的基本流程为：

• 1.定义结构体&定义该结构体对应的JSON模板
• 2.为结构体变量赋值
• 3.将结构体变量映射到JSON模板中，生成JSON型map
• 4.将此map（已成为JSON）返回给终端

除了第2步需要人为的写代码赋值外，Goa的MediaType均可以在Design过程中指定关键字来实现。

基于官方的Test code举个栗子：

design.go中关于API resource：bottle的testcode解读：

var _ = Resource("bottle", func() { //定义资源，资源名为bottle
	BasePath("/bottles")
	DefaultMedia(BottleMedia) //指定generated code中默认使用的Media
	Action("show", func() {
		Description("Retrieve bottle with given id")
		Routing(GET("/:bottleID"))
		Params(func() {
			Param("bottleID", Integer, "Bottle ID")
		})
		Response(OK)
		Response(NotFound)
	})
})

var BottleMedia = MediaType("application/vnd.goa.example.bottle+json", func() {
	Description("A bottle of wine")
	TypeName("BottleMedia") //给Media重命名
	Attributes(func() {
		Attribute("id", Integer, "Unique bottle ID") //参数分别为JSON-key，type，描述
		Attribute("href", String, "API href for making requests on the bottle")
		Attribute("name", String, "Name of wine")
	})

	View("default", func() { //定义好Media后，必须要指定一个default的View
		Attribute("id") //在这个View中暴露出的属性
		Attribute("href")
		Attribute("name")
	})
})

代码说明：

• DefaultMedia(BottleMedia)中的变量不一定非得是在View中指定为“default”的Media，而是说要使用哪个Media（Test code里只定义了一个名为default的media）。如果没有这句代码，默认生成的Show method里没有media的框架（可以手动添加）。

• TypeName("BottleMedia")该行代码的作用是将Media重命名。如果没有这一行，Goa会根据MediaType函数的第一个参数生成Media名（即结构体名字），上面的例子中，如果去掉该行，生成的Media名为GoaExampleBottle。

• View可以定义多个，在生成的代码中，决定使用哪个JSON模板做Media的载体。但View中必须要有一个名为default的定义，当没有指定view时，系统默认暴露default。只要有media，就要有个default的view。

• 关于Media和View的关系。View是Media的子集，REST API中一个资源可以有很多属性，但并不是每个该资源的HTTP请求都应反馈整个属性list，而是根据不同的请求地址，返回不同需求的资源信息，这种方式可以在Design过程中通过View实现。

上面的design代码生成的次代代码(media_types.go)如下：

// A bottle of wine
// Identifier: application/vnd.goa.example.bottle+json
type BottleMedia struct {
	// API href for making requests on the bottle
	Href *string `json:"href,omitempty"`
	// Unique bottle ID
	ID *int `json:"id,omitempty"`
	// Name of wine
	Name *string `json:"name,omitempty"`
}

// Dump produces raw data from an instance of BottleMedia running all the
// validations. See LoadBottleMedia for the definition of raw data.
func (mt *BottleMedia) Dump() (res map[string]interface{}, err error) {
	res, err = MarshalBottleMedia(mt, err)
	return
}

// MarshalBottleMedia validates and renders an instance of BottleMedia into a interface{}
// using view "default".
func MarshalBottleMedia(source *BottleMedia, inErr error) (target map[string]interface{}, err error) {
	err = inErr
	tmp23 := map[string]interface{}{
		"href": source.Href,
		"id":   source.ID,
		"name": source.Name,
	}
	target = tmp23
	return
}

从代码中可以看出，当我们需要给该Media赋值时，需要将资源（BottleMedia型的结构体指针）传值给MarshalBottleMedia。该资源在对应的contexts.go中进行定义。

生成的Action Func代码（bottle.go）如下：

// Show runs the show action.
func (c *BottleController) Show(ctx *app.ShowBottleContext) error {
	res := &app.BottleMedia{}
	return ctx.OK(res)
}

可以看到定义的res变量即为我们要的BottleMedia型的结构体指针，而函数MarshalBottleMedia进行多重封装后在return ctx.OK(res)这一句中被调用，因此上面讲的第二步，即是我们需要做的修改，根据业务，将信息写入变量res，然后发出。