微服务框架goa安装使用指南

什么是goa

goa RESTful go web 快速开发框架，goa与其他go web开发框架有本质的不同，它是以框架设计为主，是 Design-based HTTP微服务框架。 推荐一篇文章goa: Untangling Microservices

安装

首先安装goa代码生成工具goagen，goagen是工具，是goa项目的主要产物之一；如果不是修改goagen，基本不需要goa的源码。

go get github.com/goadesign/goa/goagen
go install github.com/goadesign/goa/goagen

期间会有某些依赖包被墙，无法下载，到这里下载吧。

使用

1.建立接口文件（设计）

必须要在GOPATH的src的目录下，新建一个目录(例如：goa_demo)，然后在它下面新建一个design的子目录。 子design目录下，新建文件design.go

package design

import (
	. "github.com/goadesign/goa/design"
	. "github.com/goadesign/goa/design/apidsl"
)

var _ = API("adder", func() {
	Title("The adder API")
	Description("A teaser for goa")
	Host("localhost:9090")
	Scheme("http")
})

var _ = Resource("operands", func() {
	Action("add", func() {
		Routing(GET("add/:left/:right"))
		Description("add returns the sum of the left and right parameters in the response body")
		Params(func() {
			Param("left", Integer, "Left operand")
			Param("right", Integer, "Right operand")
		})
		Response(OK, "text/plain")
	})

})

此文件定义了一个API名为adder，皆有HTTP GET请求，地址为： /add/:x/:y，接收两个整数作为参数。

2.生成框架代码（实现）

使用命令，生成框架代码（注意执行的目录，如果不加-o选项指定输出目录 , 这些代码是会生成到当前目录下，参数路径从GOPATH开始）

goagen bootstrap -d goa_demo/design

此操作会生成下列输出，观察目录结构及文件

• 根目录下main.go为程序的主入口，operands.go为业务逻辑代码，可以在此基础上修改，重新执行goagen时不会改变这两个文件
• app目录中的代码是API的胶水代码（脚手架代码），用于实现HTTP底层功能，包括信息接收管理，信息反馈模板，底层路由分发，以及goa定义的媒介结构体。如果没有特殊要求，这个目录下的代码文件系自动生成，不需要我们修改
• client目录包含一个客户端的简单实现，支持命令行参数，可以进行简单的server request测试
• tool目录包含一个CLI（command-line interface，命令行界面）工具代码
• swagger目录中存放swagger规范的API说明文件（GET/swagger.json），通过访问swagger可以查看API说明

最后需要编写业务逻辑代码，修改operands.go文件内容，实现Add function

// Add runs the add action.
func (c *OperandsController) Add(ctx *app.AddOperandsContext) error {
	sum := ctx.Left + ctx.Right
	return ctx.OK([]byte(strconv.Itoa(sum)))
}

3.编译运行

编译主文件，运行，访问http://localhost:8080/add/1/2 可看到访问结果 观察运行期间控制台的输出，框架提供了很多特性。 可以试试编译运行生成的CLI工具，很便于测试。

4.文档

swagger 目录下是API的Swagger说明，包括YAML and JSON两种格式。 The swagger directory contains the API Swagger specification in both YAML and JSON format.

For open source projects hosted on github swagger.goa.design provides a free service that renders the Swagger representation dynamically from goa design packages. Simply set the url query string with the import path to the design package. For example displaying the docs for github.com/goadesign/goa-cellar/design is done by browsing to:

http://swagger.goa.design/?url=goadesign%2Fgoa-cellar%2Fdesign

Note that the above generates the swagger spec dynamically and does not require it to be present in the Github repo.

The Swagger JSON can also easily be served from the documented service itself using a simple Files definition in the design. Edit the file design/design.go and add:

var _ = Resource("swagger", func() {
        Origin("*", func() {
               Methods("GET") // Allow all origins to retrieve the Swagger JSON (CORS)
        })
        Files("/swagger.json", "swagger/swagger.json")
})

Re-run goagen bootstrap -d goa-adder/design and note the new file swagger.go containing the implementation for a controller that serves the swagger.json file.

Mount the newly generated controller by adding the following two lines to the main function in main.go:

cs := NewSwaggerController(service)
app.MountSwaggerController(service, cs)

Recompile and restart the service:

^C
go build
./goa-adder
2016/06/06 10:31:14 [INFO] mount ctrl=Operands action=Add route=GET /add/:left/:right
2016/06/06 10:31:14 [INFO] mount ctrl=Swagger files=swagger/swagger.json route=GET /swagger.json
2016/06/06 10:31:14 [INFO] listen transport=http addr=:8080

Note the new route /swagger.json. Requests made to it return the Swagger specification. The generated controller also takes care of adding the proper CORS headers so that the JSON may be retrieved from browsers using JavaScript served from a different origin (e.g. via Swagger UI). The client also has a new download action:

cd tool/adder-cli
go build
./adder-cli download --help
Download file with given path

Usage:
  adder-cli download [PATH] [flags]

Flags:
      --out string   Output file

Global Flags:
      --dump               Dump HTTP request and response.
  -H, --host string        API hostname (default "localhost:8080")
  -s, --scheme string      Set the requests scheme
  -t, --timeout duration   Set the request timeout (default 20s)

Which can be used like this to download the file swagger.json in the current directory:

./adder-cli download swagger.json
2016/06/06 10:36:24 [INFO] started file=swagger.json id=ciHL2VLt GET=http://localhost:8080/swagger.json
2016/06/06 10:36:24 [INFO] completed file=swagger.json id=ciHL2VLt status=200 time=1.013307ms

We now have a self-documenting API and best of all the documentation is automatically updated as the API design changes.