Skip to content

Goa4 usage note

Jump to bottom Edit New page
KerwinKoo edited this page Jan 25, 2016 · 12 revisions

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实现。

Add a custom footer

[[TOC]]

Clone this wiki locally