ぺい

渋谷系アドテクエンジニアの落書き

GolangのgoaでAPIをデザインしよう（Model編）

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

Golangのgoaの勉強に役立つ情報まとめ - ぺい
goaの情報をもっと見たい方は、上のリンクから確認してください

Model層をいい感じにしてくれるgorma

goaはAPIの入り口と出口の部分をいい感じにしてくれますが、Modelとのやり取りなどのロジックは手で書く必要があります。正直だるくないっすか？だるいですよね。簡単なRDBMSとのやり取り程度なら実は自動でいい感じにしてくれるプラグインがgormaです。

goaには、goagenというものがあり、これに独自で書いたコード生成ロジックを作成して食わせるといい感じにしてくれます。gormaはそのコード生成ロジックのModel部分のものです。

gormaがやってくれること

では、実際にgormaがやってくれる素晴らしい仕事をざっくりではありますけど、紹介します。

CRUDは秒で終わる

以下によくあるエンドポイントの例があります。これくらいなら、gormaに任せたら実装は終了します。

GET /api/v1/bottles
bottlesを複数取得する

GET /api/v1/bottles/{id}
bottlesから1件取得する

POST /api/v1/bottles
bottlesを1件作成する

DELETE /api/v1/bottles/{id}
bottlesを1件削除する

PUT/api/v1/bottles/{id}
bottlesを1件更新する

ちょっとした入れ子構造はいい感じにしてくれる

bottlesというリソースがあったとします。bottlesのひとつひとつには、所有者であるaccountsのリソースに紐付いています。jsonでいい感じに返してくださいという案件があったとします。以下のようなjsonがほしくなります。

gormaでやると秒で終わります。

[
  {
    "account": {
      "email": "example@gmail.com",
      "id": 1,
      "name": "山田　太郎"
    },
    "id": 1,
    "name": "シャルドネ",
    "quantity": 4
  },
  {
    "account": {
      "email": "example@gmail.com",
      "id": 1,
      "name": "山田　太郎"
    },
    "id": 1,
    "name": "シャルドネ",
    "quantity": 4
  }
]

カスタマイズ出来る

gormaってよくわかんないやつ嫌だなーと最初は思ってたんですけど、実はこいつはgormというORMのコードを自動生成してくれてるだけなので、gormの使い方を理解していればカスタマイズはいくらでも出来ます。

github.com

さっそくgorma開発

gormaの開発には当然ですけど、RDBMSで使うDDLやMySQLなどの環境構築が必要になります。なので、用意しました。最低限必要なのはDockerが動く環境なので、適宜用意してください。

今回使うサンプル
github.com

$ go get github.com/tikasan/goa-simple-sample
または
$ ghq get github.com/tikasan/goa-simple-sample

上記のいずれかのコマンドで、ローカルに落としてきてください。

環境構築と実行

Docker立ち上げて、DDL読み込ませて、起動してSwaggerで実行してみます。

$ make docker/build
$ make docker/start
$ make migrate/up
$ make rundb
$ make swaggerUI

Bottlesリソースに対してのアクションをしてみましょう。 f:id:tikasan0804:20170512152749p:plain f:id:tikasan0804:20170512152559p:plain f:id:tikasan0804:20170512152600p:plain

とりあえず、レスポンスが返ってきました。では、どういう動きだったかについて詳しく説明します。

やったこと

ER図
f:id:tikasan0804:20170512153959p:plain

発行したSQL

SELECT * FROM `bottles`  WHERE `bottles`.`deleted_at` IS NULL
SELECT * FROM `accounts`  WHERE `accounts`.`deleted_at` IS NULL AND ((`id` IN ('1','2','2','3')))

goaコード

MediaType

var Account = MediaType("application/vnd.account+json", func() {
    Description("celler account")
    Attributes(func() {
        Attribute("id", Integer, "id", func() {
            Example(1)
        })
        Attribute("name", String, "名前", func() {
            Example("山田　太郎")
        })
        Attribute("email", String, "メールアドレス", func() {
            Example("example@gmail.com")
        })
        Required("id", "name", "email")
    })
    View("default", func() {
        Attribute("id")
        Attribute("name")
        Attribute("email")
    })
})

var Bottle = MediaType("application/vnd.bottle+json", func() {
    Description("celler bottles")
    Attributes(func() {
        Attribute("id", Integer, "id", func() {
            Example(1)
        })
        Attribute("name", String, "ボトル名", func() {
            Example("シャルドネ")
        })
        Attribute("quantity", Integer, "数量", func() {
            Example(4)
        })
        // accountのMediaTypeを入れ子構造にする
        Attribute("account", Account)
        Required("id", "name", "quantity", "account")
    })

    View("default", func() {
        Attribute("id")
        Attribute("name")
        Attribute("quantity")
        Attribute("account")
    })
})

var Category = MediaType("application/vnd.category+json", func() {
    Description("celler account")
    Attributes(func() {
        Attribute("id", Integer, "id", func() {
            Example(1)
        })
        Attribute("name", String, "名前", func() {
            Example("ワイン")
        })
        Required("id", "name")
    })
    View("default", func() {
        Attribute("id")
        Attribute("name")
    })
})

エンドポイント

var _ = Resource("bottles", func() {
    BasePath("/bottles")

    // --------- さっき実行したのはこれ ---------
    Action("list", func() {
        Description("複数")
        Routing(
            GET("/"),
        )
        Response(OK, CollectionOf(Bottle))
        Response(BadRequest, ErrorMedia)
    })
    // --------- さっき実行したのはこれ ---------

    Action("show", func() {
        Description("単数")
        Routing(
            GET("/:id"),
        )
        Params(func() {
            Param("id", Integer, "id", func() {
                Example(1)
            })
        })
        Response(OK, Bottle)
        Response(NotFound)
        Response(BadRequest, ErrorMedia)
    })
    Action("add", func() {
        Description("追加")
        Routing(
            POST("/"),
        )
        Params(func() {
            Param("account_id", Integer, "アカウントID", func() {
                Example(1)
            })
            Param("name", String, "ボトル名", func() {
                Default("")
                Example("赤ワインなにか")
            })
            Param("quantity", Integer, "数量", func() {
                Example(0)
            })
            Required("account_id", "name", "quantity")
        })
        Response(Created)
        Response(BadRequest, ErrorMedia)
    })
    Action("delete", func() {
        Description("削除")
        Routing(
            DELETE("/:id"),
        )
        Params(func() {
            Param("id", Integer, "id", func() {
                Example(1)
            })
        })
        Response(OK)
        Response(NotFound)
        Response(BadRequest, ErrorMedia)
    })
    Action("update", func() {
        Description("更新")
        Routing(
            PUT("/:id"),
        )
        Params(func() {
            Param("id", Integer, "id", func() {
                Example(1)
            })
            Param("name", String, "ボトル名", func() {
                Default("")
                Example("赤ワインなにか")
            })
            Param("quantity", Integer, "数量", func() {
                Default(0)
                Minimum(0)
                Example(0)
            })
        })
        Response(OK)
        Response(NotFound)
        Response(BadRequest, ErrorMedia)
    })
})

gormaコード

Model

gormaには、命名規則があります。

種類 説明 gormaでの書き方
テーブル名 テーブル名は複数形 bottles,categories
カラム名 カラム名はスネークケース user_id
Model名 テーブル名が複数形でみModelは単数形 Bottle,Category
PrimaryKey 必ずid統一する （IntegerかUUID） id
timestamp created_at,updated_at,deleted_atで統一 ---

特にModel名とテーブル名が同じにならないのは、結構ハマりポイントだったりする。この他にもあるかもしれませんが、基本的にgormの規則に従っています。
実際に組んだコードを以下に示します。

package design

import (
    "github.com/goadesign/gorma"
    . "github.com/goadesign/gorma/dsl"
)

var _ = StorageGroup("celler", func() {
    Description("celler Model")
    // Mysqlを使う
    Store("MySQL", gorma.MySQL, func() {
        Description("MySQLのリレーションナルデータベース")
        // accountsテーブルのModelなら、Account
        Model("Account", func() {
            // MediaTypeで作成したAccountにマッピングする
            RendersTo(Account)
            Description("celler account")
            // PrimaryKeyの設定
            Field("id", gorma.Integer, func() {
                PrimaryKey()
            })
            Field("name", gorma.String)
            Field("email", gorma.String)
            // timestamp系の定義
            Field("created_at", gorma.Timestamp)
            Field("updated_at", gorma.Timestamp)
            Field("deleted_at", gorma.NullableTimestamp)
            // HasMany(複数形名, 単数形名)
            HasMany("Bottles", "Bottle")
        })
        Model("Bottle", func() {
            RendersTo(Bottle)
            Description("celler bottle")
            Field("id", gorma.Integer, func() {
                PrimaryKey()
            })
            Field("name", gorma.String)
            Field("quantity", gorma.Integer)
            Field("created_at", gorma.Timestamp)
            Field("updated_at", gorma.Timestamp)
            Field("deleted_at", gorma.NullableTimestamp)
            // BelongTo(単数形)
            BelongsTo("Account")
            HasMany("BottleCategories", "BottleCategory")
        })
        Model("Category", func() {
            RendersTo(Category)
            Description("celler category")
            Field("id", gorma.Integer, func() {
                PrimaryKey()
            })
            Field("name", gorma.String)
            Field("created_at", gorma.Timestamp)
            Field("updated_at", gorma.Timestamp)
            Field("deleted_at", gorma.NullableTimestamp)
            HasMany("BottleCategories", "BottleCategory")
        })
        Model("BottleCategory", func() {
            Description("celler bottle category")
            Field("id", gorma.Integer, func() {
                PrimaryKey()
            })
            Field("created_at", gorma.Timestamp)
            Field("updated_at", gorma.Timestamp)
            Field("deleted_at", gorma.NullableTimestamp)
            BelongsTo("Category")
            BelongsTo("Bottle")
        })
    })
})

gormaのコード生成は以下のコマンドです。

$ go get github.com/goadesign/gorma <--- gorma入れてない人はこれする
$ goagen --design=$(REPO)/design gen --pkg-path=github.com/goadesign/gorma
models/
├── account.go
├── account_helper.go
├── bottle.go
├── bottle_helper.go
├── bottlecategory.go
├── bottlecategory_helper.go
├── category.go
└── category_helper.go

上記のようなファイル群が出てきたかと思います。それぞれのファイルが持っているコードは以下のようになっています。

ファイル名 説明
model名.go gormに必要な構造体とCRUDの最低限のメソッド
model名_helper.go MediaTypeに合わせたRead系メソッド集

では、実際にクエリを投げるために、下準備をします。
gormaでは、外部テーブルからの参照系のクエリをデフォルトでは実装されていません。恐らくなんでもかんでも結合すると、クエリの処理速度が遅くなるからだと思われす。models/bottle_helper.go

// ListBottle returns an array of view: default.
func (m *BottleDB) ListBottle(ctx context.Context, accountID int) []*app.Bottle {
    defer goa.MeasureSince([]string{"goa", "db", "bottle", "listbottle"}, time.Now())

    var native []*Bottle
    var objs []*app.Bottle
    //err := m.Db.Scopes(BottleFilterByAccount(accountID, m.Db)).Table(m.TableName()).Find(&native).Error
    // Accountテーブルから、情報を取得したいので、Preloadメソッドを追加する
    err := m.Db.Scopes(BottleFilterByAccount(accountID, m.Db)).Table(m.TableName()).Preload("Account").Find(&native).Error

    if err != nil {
        goa.LogError(ctx, "error listing Bottle", "error", err.Error())
        return objs
    }

    for _, t := range native {
        objs = append(objs, t.BottleToBottle())
    }

    return objs
}

上記のように、メソッドを直接書き換えるのも良いですが、自動生成されたメソッドをあまり書き換えたくないというのもあるので、私はユーザー定義用のファイルを作成して対応したりしてます。

bottle_defined.go
model名_defined.go

そして、modelのデザインに変更が発生して、再生成する時は、以下のMakeコマンドを走らせることで、安全にコードを再生するようにしています。

model:
    @ls models | grep -v '_defined.go' | xargs rm -f
    @goagen --design=$(REPO)/design gen --pkg-path=github.com/goadesign/gorma

次にコントローラーを定義します。controller/bottles.go

package controller

import (
    "github.com/goadesign/goa"
    "github.com/jinzhu/gorm"
    "github.com/tikasan/goa-simple-sample/app"
    "github.com/tikasan/goa-simple-sample/models"
)

// BottlesController implements the bottles resource.
type BottlesController struct {
    *goa.Controller
    db *gorm.DB
}

// NewBottlesController creates a bottles controller.
func NewBottlesController(service *goa.Service, db *gorm.DB) *BottlesController {
    return &BottlesController{
        Controller: service.NewController("BottlesController"),
        db:         db,
    }
}

// Add runs the add action.
func (c *BottlesController) Add(ctx *app.AddBottlesContext) error {
    // BottlesController_Add: start_implement

    // Put your logic here
    b := &models.Bottle{}
    b.AccountID = ctx.AccountID
    b.Name = ctx.Name
    b.Quantity = ctx.Quantity
    bdb := models.NewBottleDB(c.db)
    err := bdb.Add(ctx.Context, b)
    if err != nil {
        return ctx.BadRequest(goa.ErrBadRequest(err))
    }
    // BottlesController_Add: end_implement
    return ctx.Created()
}

// Delete runs the delete action.
func (c *BottlesController) Delete(ctx *app.DeleteBottlesContext) error {
    // BottlesController_Delete: start_implement

    // Put your logic here
    bdb := models.NewBottleDB(c.db)
    err := bdb.Delete(ctx.Context, ctx.ID)
    if err != nil {
        return ctx.BadRequest(goa.ErrBadRequest(err))
    }

    // BottlesController_Delete: end_implement
    return nil
}


//---------------------------------
// 例で使った部分
//---------------------------------
// List runs the list action.
func (c *BottlesController) List(ctx *app.ListBottlesContext) error {
    // BottlesController_List: start_implement

    // Put your logic here
    bdb := models.NewBottleDB(c.db)
    b := bdb.ListBottle(ctx.Context, 0)

    // BottlesController_List: end_implement
    res := app.BottleCollection{}
    res = b
    return ctx.OK(res)
}

// Show runs the show action.
func (c *BottlesController) Show(ctx *app.ShowBottlesContext) error {
    // BottlesController_Show: start_implement

    // Put your logic here
    bdb := models.NewBottleDB(c.db)
    b, err := bdb.OneBottle(ctx.Context, ctx.ID, 0)
    if err != nil {
        return ctx.NotFound()
    }

    // BottlesController_Show: end_implement
    res := &app.Bottle{}
    res = b
    return ctx.OK(res)
}

// Update runs the update action.
func (c *BottlesController) Update(ctx *app.UpdateBottlesContext) error {
    // BottlesController_Update: start_implement

    // Put your logic here
    b := &models.Bottle{}
    b.ID = ctx.ID
    b.Name = ctx.Name
    b.Quantity = ctx.Quantity
    bdb := models.NewBottleDB(c.db)
    err := bdb.Update(ctx.Context, b)
    if err == gorm.ErrRecordNotFound {
        return ctx.NotFound()
    } else if err != nil {
        return ctx.BadRequest(goa.ErrBadRequest(err))
    }

    // BottlesController_Update: end_implement
    return nil
}

これで、完成しました。自動的にマッピングも完了し、欲しい情報を簡単に取得することが出来ます。
gormaは多少取っ付きにくさはありますが、理解すると、goaでの開発がさらにスピードアップするので、結構おすすめです。

gormaですんなり出来ない多対多問題

gormaの作成してくれたコードだけでは、当然出来ないことがあります。それは多対多のリレーションの場合です。これは元々のgormの癖が強いというこもあり、かなり苦労しました。

f:id:tikasan0804:20170515171457p:plain

この解決方法が全然日本語情報がない上に、しかも、よく見かけるケースなので、また記事にする予定です。 今回はgormaをさくっと使うところまでということで、ここまでにしておきます。

GolangのgoaでAPIをデザインしよう（ハマりポイント編）

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

Golangのgoaの勉強に役立つ情報まとめ - ぺい
goaの情報をもっと見たい方は、上のリンクから確認してください

designが読み込めない

症状

goagenでコード生成出来ない。

goagen bootstrap -d ./design
main.go:15:2: local import "./design" in non-local package

対策

$GOPATHからの相対で指定する必要があります。

goagen bootstrap -d github.com/tikasan/goa-stater/design

デザインを書き直したけど、動きが変わらない

症状

  • デザイン書き直したんだけど、どうもエンドポイントの動きが変わっていない気がする。
  • goagen流したのだけど、動き変わらない。

対策

デザインはあくまでデザインなので、goagenでコードを再生成する必要があります。また、goagenコマンドを流したとしても既にあるファイルには上書きしない仕様になっています。なので、一度消すかまたはforceオプションで強制上書きが必要です。

私は以下のようなMakefileでコード生成のし直しをしています。これで間違いなく生成のし直しが行われます。

REPO:=github.com/tikasan/goa-simple-sample <--- ここを自分の環境に合わせる

gen: clean generate

clean:
    @rm -rf app
    @rm -rf client
    @rm -rf tool
    @rm -rf swagger
    @rm -rf schema
    @rm -rf js
    @rm -f build

generate:
    @goagen app     -d $(REPO)/design
    @goagen swagger -d $(REPO)/design
    @goagen client -d $(REPO)/design
    @goagen js -d $(REPO)/design
    @goagen schema -d $(REPO)/design
    @go build -o build
$ make gen

GAE/Goで使えないんだけど！！（contextの問題で）

症状

GAE/Go環境下で実行するとcontextパッケージが使えません！的なエラーが出る。

$ goapp serve ./server
2017/05/07 22:59:44 Can't find package "context" in $GOPATH: cannot find package "context" in any of:
        /Users/jumpei/go/src/github.com/tikasan/hoge/vendor/context (vendor tree)
        /Users/jumpei/go_appengine/goroot/src/context (from $GOROOT)
        /Users/jumpei/go/src/github.com/tikasan/hoge/src/context (from $GOPATH)
        /Users/jumpei/go/src/context

対策

一部のソース書き換えを行います。
examples/appengine at master · goadesign/examples · GitHub

Golangのgoaの勉強に役立つ情報まとめ

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

当ブログgoaまとめ

シリーズ

  1. GolangのgoaでAPIをデザインしよう（基本編） - ぺい
  2. GolangのgoaでAPIをデザインしよう（バリデーション編） - ぺい
  3. GolangのgoaでAPIをデザインしよう（レスポンス編） - ぺい
  4. GolangのgoaでAPIをデザインしよう（クライアント編） - ぺい
  5. GolangのgoaでAPIをデザインしよう（エンドポイント編） - ぺい
  6. GolangのgoaでAPIをデザインしよう（ハマりポイント編） - ぺい
  7. GolangのgoaでAPIをデザインしよう（Model編） - ぺい
  8. GolangのgoaでAPIをデザインしよう（Model編②） - ぺい
  9. GolangのgoaでAPIをデザインしよう（ベース作成編） - ぺい

単発

日本語記事

公式

ソース

スライド

勉強会

GolangのgoaでAPIをデザインしよう（エンドポイント編）

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

Golangのgoaの勉強に役立つ情報まとめ - ぺい
goaの情報をもっと見たい方は、上のリンクから確認してください

エンドポイントにも色々ある

同じエンドポイントの指定でも、DSLの書き方で変わります。若干癖があったりするので、今回はそれについてまとめたいと思います。

例：ユーザーのフォロー操作。
同じ名前だけど、HTTPメソッドが違うので、操作の中身が違う。

PUT /users/follow // フォローする
DELETE /users/follow // フォローを外す

例：なんかのリスト
/listというリソースに対してエンドポイントで操作を表現している。（途中まで操作同じだけど、若干違う）

GET /list/new  // 新しいリスト
GET /list/topic // 注目されてるリスト
GET /list // リスト（全件）

例：ちょっと特殊ケース

GET /api/v1/method/users/:id/follow/:type

以上のエンドポイントをDSLでどうやって表現するかを紹介します。

goaはコード生成する時に少し長めのコマンドが必要になるので、Makefileを作っておくと良いと思います。 ちなみに、コマンドやフォルダ構成は毎回同じものを使うので、テンプレートを作成しました。よろしければ利用してください。
もし、もっと便利なフォーマットがあればPRをください。

$ go get github.com/tikasan/goa-stater
または
$ ghq get github.com/tikasan/goa-stater

APIをデザインする

順を追って記事を読んでいればすんなりソースも読めると思います。（つまりコメントがなし）

package design

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

var _ = Resource("method", func() {
    BasePath("/method")
    Action("method", func() {
        Description("HTTPメソッド")
        Routing(
            GET("/get"),
            POST("/post"),
            DELETE("/delete"),
            PUT("/put"),
        )
        Response(OK, MessageMedia)
        Response(BadRequest, ErrorMedia)
    })
    Action("list", func() {
        Description("リストを返す")
        Routing(
            GET("/list"),
            GET("/list/new"),
            GET("/list/topic"),
        )
        Response(OK, CollectionOf(UserMedia))
        Response(BadRequest, ErrorMedia)
    })
    Action("follow", func() {
        Description("フォロー操作")
        Routing(
            PUT("/users/follow"),
            DELETE("/users/follow"),
        )
        Response(OK, MessageMedia)
        Response(BadRequest, ErrorMedia)
    })
    Action("etc", func() {
        Routing(GET("/users/:id/follow/:type"))
        Description("ちょっと特殊ケース")
        Params(func() {
            Param("id", Integer, "id")
            Param("type", Integer, "タイプ", func() {
                Enum(1, 2, 3)
            })
        })
        Response(OK, "plain/text")
        Response(BadRequest, ErrorMedia)
    })
})

MediaTypeを定義する

以前記事で書いたコードです。

var UserMedia = MediaType("application/vnd.user+json", func() {
    Description("example")
    Attributes(func() {
        Attribute("id", Integer, "id", func() {
            Example(1)
        })
        Attribute("name", String, "名前", func() {
            Example("hoge")
        })
        Attribute("email", String, "メールアドレス", func() {
            Example("satak47cpc@gmail.com")
        })
        Required("id", "name", "email")
    })
    // 特別な指定がない場合はdefaultのMediaType
    View("default", func() {
        Attribute("id")
        Attribute("name")
        Attribute("email")
    })
    // tinyという名前の場合は、簡潔なレスポンスフォーマットにすることが出来る
    View("tiny", func() {
        Attribute("id")
        Attribute("name")
    })
})

コントローラー定義

デザインを元にコードを生成しましょう。コントローラーは、値を返すだけの単純なものを作成します。

$ goagen bootstrap -d github.com/tikasan/goa-stater/design
package controller

import (
    "fmt"

    "github.com/goadesign/goa"
    "github.com/tikasan/goa-stater/app"
)

// MethodController implements the method resource.
type MethodController struct {
    *goa.Controller
}

// NewMethodController creates a method controller.
func NewMethodController(service *goa.Service) *MethodController {
    return &MethodController{Controller: service.NewController("MethodController")}
}

// Etc runs the etc action.
func (c *MethodController) Etc(ctx *app.EtcMethodContext) error {
    // MethodController_Etc: start_implement

    // Put your logic here

    // MethodController_Etc: end_implement
    return ctx.OK([]byte(fmt.Sprintf("ID: %d, Type %d", ctx.ID, ctx.Type)))
}

// Follow runs the follow action.
func (c *MethodController) Follow(ctx *app.FollowMethodContext) error {
    // MethodController_Follow: start_implement

    // Put your logic here
    var message string
    //　何かのフォロー操作
    if "PUT" == ctx.Request.Method {
        message = "フォローした"
    } else if "DELETE" == ctx.Request.Method {
        message = "フォロー外した"
    }
    // MethodController_Follow: end_implement
    res := &app.Message{}
    res.Message = message
    return ctx.OK(res)
}

// List runs the list action.
func (c *MethodController) List(ctx *app.ListMethodContext) error {
    // MethodController_List: start_implement

    // Put your logic here
    var listType string
    switch ctx.RequestURI {
    //case client.ListMethodPath(): <---これでもいけるけど・・・って感じ　何かいい方法。
    case "/api/v1/method/list":
        listType = "ただの"
    case "/api/v1/method/list/new":
        listType = "新しい"
    case "/api/v1/method/list/topic":
        listType = "注目されている"
    }
    // MethodController_List: end_implement
    res := make(app.UserTinyCollection, 2)
    u1 := &app.UserTiny{
        ID:   1,
        Name: listType + "ユーザー1",
    }
    u2 := &app.UserTiny{
        ID:   2,
        Name: listType + "ユーザー2",
    }
    res[0] = u1
    res[1] = u2
    return ctx.OKTiny(res)
}

// Method runs the method action.
func (c *MethodController) Method(ctx *app.MethodMethodContext) error {
    // MethodController_Method: start_implement

    // Put your logic here
    message := ctx.RequestURI

    // MethodController_Method: end_implement
    res := &app.Message{}
    res.Message = message
    return ctx.OK(res)
}

実際に動かしてみよう

$ go run main.go
$ curl -v -X PUT 'http://localhost:8080/api/v1/method/users/follow'
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> PUT /api/v1/method/users/follow HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/vnd.message+json
< Date: Sat, 06 May 2017 06:34:09 GMT
< Content-Length: 33
< 
{"message":"フォローした"}
* Connection #0 to host localhost left intact
$ curl -v -X DELETE 'http://localhost:8080/api/v1/method/users/follow'
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> DELETE /api/v1/method/users/follow HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/vnd.message+json
< Date: Sat, 06 May 2017 06:35:05 GMT
< Content-Length: 36
< 
{"message":"フォロー外した"}
* Connection #0 to host localhost left intact
$ curl -v 'http://localhost:8080/api/v1/method/users/1/follow/3'
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> GET /api/v1/method/users/1/follow/3 HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: plain/text
< Date: Sat, 06 May 2017 06:35:35 GMT
< Content-Length: 13
< 
* Connection #0 to host localhost left intact
ID: 1, Type 3%

これで出来上がりです。エンドポイントのURIによって処理を変えるところが少し不細工なんで、誰か良い案あれば教えて欲しいです。

goa紹介で使うソース達は、以下のリポジトリに随時更新していきます。
github.com

GolangのgoaでAPIをデザインしよう（クライアント編）

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

Golangのgoaの勉強に役立つ情報まとめ - ぺい
goaの情報をもっと見たい方は、上のリンクから確認してください

クライアント編

バックエンドをいい感じに出来るgoaですけど、欲を言えばクライアント側もいい感じにしてほしい。実はいい感じにしてくれます。とは言ってもちょっとした手助けをしてくれる感じです。
対応しているのは、JavascriptでのAPIへのリクエストです。

$ go get github.com/tikasan/goa-simple-sample
または
$ ghq get github.com/tikasan/goa-simple-sample

今回はgoaのサンプルを作成しているリポジトリを使って説明したいと思います。 本来は以下のコマンドで実行して、クライアント側のコードを生成しますが、出来上がっているので、生成されたものを見てみましょう。

goagen js -d github.com/tikasan/goa-simple-sample/design
// This module exports functions that give access to the goa simple sample API hosted at localhost:8080.
// It uses the axios javascript library for making the actual HTTP requests.
define(['axios'] , function (axios) {
  function merge(obj1, obj2) {
    var obj3 = {};
    for (var attrname in obj1) { obj3[attrname] = obj1[attrname]; }
    for (var attrname in obj2) { obj3[attrname] = obj2[attrname]; }
    return obj3;
  }

  return function (scheme, host, timeout) {
    scheme = scheme || 'http';
    host = host || 'localhost:8080';
    timeout = timeout || 20000;

    // Client is the object returned by this module.
    var client = axios;

    // URL prefix for all API requests.
    var urlPrefix = scheme + '://' + host;

  // 複数アクション（:ID）
  // path is the request path, the format is "/api/v1/actions/:ID"
  // config is an optional object to be merged into the config built by the function prior to making the request.
  // The content of the config object is described here: https://github.com/mzabriskie/axios#request-api
  // This function returns a promise which raises an error if the HTTP response is a 4xx or 5xx.
  client.IDActions = function (path, config) {
    cfg = {
      timeout: timeout,
      url: urlPrefix + path,
      method: 'get',
      responseType: 'json'
    };
    if (config) {
      cfg = merge(cfg, config);
    }
    return client(cfg);
  }


----------------------------------------------------------------


  // Validation
  // path is the request path, the format is "/api/v1/validation"
  // ID, defaultType, email, enumType, integerType, reg, stringType are used to build the request query string.
  // config is an optional object to be merged into the config built by the function prior to making the request.
  // The content of the config object is described here: https://github.com/mzabriskie/axios#request-api
  // This function returns a promise which raises an error if the HTTP response is a 4xx or 5xx.
  client.validationValidation = function (path, ID, defaultType, email, enumType, integerType, reg, stringType, config) {
    cfg = {
      timeout: timeout,
      url: urlPrefix + path,
      method: 'get',
      params: {
        id: id,
        defaultType: defaultType,
        email: email,
        enumType: enumType,
        integerType: integerType,
        reg: reg,
        stringType: stringType
      },
      responseType: 'json'
    };
    if (config) {
      cfg = merge(cfg, config);
    }
    return client(cfg);
  }
  return client;
  };
});

jsでそのまま使えるリクエスト集が出来上がりました。
この機能を知った時は感動しましたが、あまりに楽すぎてダメ人間になりそうと思ったので、今後も使っていこうと思います。(?)

GolangのgoaでAPIをデザインしよう（レスポンス編）

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

Golangのgoaの勉強に役立つ情報まとめ - ぺい
goaの情報をもっと見たい方は、上のリンクから確認してください

レスポンス

いきなりですが、以下のエンドポイントを見てください。RESTを知ってる人は、レスポンスが違うことが分かると思います。

GET /users/1
GET /users

開発するチームにもよって変わる可能生はあると思いますが、GET /users/1は恐らくひとりのユーザー情報だけを返す。そして、GET /usersはひとり以上のユーザー情報を返す。
また、GET /usersはIDや名前だけで良かったり、GET /users/1は詳細な情報が欲しかったり、同じリソースに対しての操作でも、レスポンスは変える必要があります。（と思っています）

具体的にレスポンスの例を示すと以下のような感じになります。

GET /users

[
  {
    "id": 1,
    "name": "ユーザー1"
  },
  {
    "ID": 2,
    "name": "ユーザー2"
  }
]

GET /users/1

{
  "id": 1,
  "email": "satak47cpc@gmail.com",
  "name": "ユーザー1"
}

また、場合によってはIDの一覧だけ欲しい時もあったり

{"america":3,"japan":2,"korea":4}

キーに意味を持たせた連想配列が欲しかったり

[1,2,3]

上記のような需要全てに対応することが出来ます。実際に動かしてみましょう。

goaはコード生成する時に少し長めのコマンドが必要になるので、Makefileを作っておくと良いと思います。 ちなみに、コマンドやフォルダ構成は毎回同じものを使うので、テンプレートを作成しました。よろしければ利用してください。
もし、もっと便利なフォーマットがあればPRをください。

$ go get github.com/tikasan/goa-stater
または
$ ghq get github.com/tikasan/goa-stater

APIデザインをする

package design

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

var _ = Resource("response", func() {
    BasePath("/response")
    Action("list", func() {
        Description("ユーザー（複数）")
        Routing(
            GET("/users"),
        )
        // 複数返す
        Response(OK, CollectionOf(UserMedia))
        Response(BadRequest, ErrorMedia)
    })
    Action("show", func() {
        Description("ユーザー（単数）")
        Routing(
            GET("/users/:id"),
        )
        // 単一
        Response(OK, UserMedia)
        Response(BadRequest, ErrorMedia)
    })
    Action("hash", func() {
        Description("ユーザー（ハッシュ）")
        Routing(
            GET("/users/hash"),
        )
        // 連想配列
        Response(OK, HashOf(String, Integer))
        Response(BadRequest, ErrorMedia)
    })
    Action("array", func() {
        Description("ユーザー（配列）")
        Routing(
            GET("/users/array"),
        )
        // 配列
        Response(OK, ArrayOf(Integer))
        Response(BadRequest, ErrorMedia)
    })
})

MediaTypeを定義する

package design

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

var UserMedia = MediaType("application/vnd.user+json", func() {
    Description("example")
    Attributes(func() {
        Attribute("id", Integer, "id", func() {
            Example(1)
        })
        Attribute("name", String, "名前", func() {
            Example("hoge")
        })
        Attribute("email", String, "メールアドレス", func() {
            Example("satak47cpc@gmail.com")
        })
        Required("id", "name", "email")
    })
    // 特別な指定がない場合はdefaultのMediaType
    View("default", func() {
        Attribute("id")
        Attribute("name")
        Attribute("email")
    })
    // tinyという名前の場合は、簡潔なレスポンスフォーマットにすることが出来る
    View("tiny", func() {
        Attribute("id")
        Attribute("name")
    })
})

Controllerを定義する

goagen bootstrap -d github.com/tikasan/goa-stater/design

特にビジネスロジックなどはなしで、値を返すだけのコードを実装します。

package controller

import (
    "github.com/goadesign/goa"
    "github.com/tikasan/goa-stater/app"
)

// ResponseController implements the response resource.
type ResponseController struct {
    *goa.Controller
}

// NewResponseController creates a response controller.
func NewResponseController(service *goa.Service) *ResponseController {
    return &ResponseController{Controller: service.NewController("ResponseController")}
}

// Array runs the array action.
func (c *ResponseController) Array(ctx *app.ArrayResponseContext) error {
    // ResponseController_Array: start_implement

    // Put your logic here

    // ResponseController_Array: end_implement
    res := make([]int, 3)
    res[0] = 1
    res[1] = 2
    res[2] = 3
    return ctx.OK(res)
}

// Hash runs the hash action.
func (c *ResponseController) Hash(ctx *app.HashResponseContext) error {
    // ResponseController_Hash: start_implement

    // Put your logic here

    // ResponseController_Hash: end_implement
    res := make(map[string]int, 3)
    res["japan"] = 2
    res["america"] = 3
    res["korea"] = 4
    return ctx.OK(res)
}

// List runs the list action.
func (c *ResponseController) List(ctx *app.ListResponseContext) error {
    // ResponseController_List: start_implement

    // Put your logic here

    // ResponseController_List: end_implement
    res := make(app.UserTinyCollection, 2)
    u1 := &app.UserTiny{
        ID:   1,
        Name: "ユーザー1",
    }
    u2 := &app.UserTiny{
        ID:   2,
        Name: "ユーザー2",
    }
    res[0] = u1
    res[1] = u2
    return ctx.OKTiny(res)
}

// Show runs the show action.
func (c *ResponseController) Show(ctx *app.ShowResponseContext) error {
    // ResponseController_Show: start_implement

    // Put your logic here

    // ResponseController_Show: end_implement
    res := &app.User{}
    res.ID = 1
    res.Name = "ユーザー1"
    res.Email = "satak47cpc@gmail.com"
    return ctx.OK(res)
}

準備が整ったので、実行してリクエストを投げてみましょう！

$ go run main.go
$ curl -v 'http://localhost:8080/api/v1/response/users/1'
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> GET /api/v1/response/users/1 HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/vnd.user+json
< Date: Sat, 06 May 2017 04:33:08 GMT
< Content-Length: 63
< 
{"ID":1,"email":"satak47cpc@gmail.com","name":"ユーザー1"}
* Connection #0 to host localhost left intact
$ curl -v 'http://localhost:8080/api/v1/response/users'
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> GET /api/v1/response/users HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/vnd.user+json; type=collection
< Date: Sat, 06 May 2017 04:35:02 GMT
< Content-Length: 66
< 
[{"ID":1,"name":"ユーザー1"},{"ID":2,"name":"ユーザー2"}]
* Connection #0 to host localhost left intact

いい感じのデータが返ってきました。goaはいいぞ！

GolangのgoaでAPIをデザインしよう（バリデーション編）

Golang goa

goaはいいぞ！

f:id:tikasan0804:20170505212036p:plain

Golangのgoaの勉強に役立つ情報まとめ - ぺい
goaの情報をもっと見たい方は、上のリンクから確認してください

わかっちゃいるけど、さぼりたいバリデーション

APIは単純なJSONやText返したり、用途は色々あると思います。ですけど、実際返す処理の前にクライアントから飛んでくるリクエストが間違っていないかバリデーションが必要になりますよね。これがだるい！
しかも、プログラム側で実装するだけでも大変なのに、それをドキュメントにどういう条件でOKとするかとか書き出すと、結構細かく記述する必要があり、正直面倒でしかないと思います。そして、仕様変更があれば楽しい修正が始まります。無駄無駄無駄無駄無駄無駄無駄！！！！！！

goaでやったら秒で終わるよ

そこで、今回はgoaでバリデーションすると、幸せになれる一例を示したいと思います。サンプルコードと説明を貼っていくので、この楽さを実感してほしいです。

goaはコード生成する時に少し長めのコマンドが必要になるので、Makefileを作っておくと良いと思います。 ちなみに、コマンドやフォルダ構成は毎回同じものを使うので、テンプレートを作成しました。よろしければ利用してください。
もし、もっと便利なフォーマットがあればPRをください。

$ go get github.com/tikasan/goa-stater
または
$ ghq get github.com/tikasan/goa-stater

デザイン定義

以下のような感じで、用意されているメソッドを使えば大体なんとかなります。
ちなみにFormay関数には、email以外にもいくつかあります。

  • “date-time”: RFC3339 date time
  • “email”: RFC5322 email address
  • “hostname”: RFC1035 internet host name
  • “ipv4”, “ipv6”, “ip”: RFC2373 IPv4, IPv6 address or either
  • “uri”: RFC3986 URI
  • “mac”: IEEE 802 MAC-48, EUI-48 or EUI-64 MAC address
  • “cidr”: RFC4632 or RFC4291 CIDR notation IP address
  • “regexp”: RE2 regular expression
var _ = Resource("validation", func() {
    BasePath("/validation")
    Action("validation", func() {
        Description("Validation")
        Routing(
            GET("/"),
        )
        Params(func() {
            // Integer型
            Param("id", Integer, "id", func() {
                Example(1)
            })
            // Integer型かつ1〜10以下
            Param("integerType", Integer, "数字（1〜10）", func() {
                Minimum(0)
                Maximum(10)
                Example(2)
            })
            // String型かつ1〜10文字以下
            Param("stringType", String, "文字（1~10文字）", func() {
                MinLength(1)
                MaxLength(10)
                Example("あいうえお")
            })
            // String型かつemailフォーマット
            Param("email", String, "メールアドレス", func() {
                Format("email")
                Example("example@gmail.com")
            })
            // String型でEnumで指定されたいずれかの文字列
            Param("enumType", String, "列挙型", func() {
                Enum("A", "B", "C")
                Example("A")
            })
            // String型で何も指定が無ければ”でふぉ”という文字列が自動でセットされる
            Param("defaultType", String, "デフォルト値", func() {
                Default("でふぉ")
                Example("でふぉ")
            })
            // String型で正規表現で指定したパターンの文字列
            Param("reg", String, "正規表現", func() {
                Pattern("^[a-z0-9]{5}$")
                Example("12abc")
            })

            // 全て必須パラメーター
            Required("id", "integerType", "stringType", "email", "enumType", "defaultType", "reg")
        })
        Response(OK, ValidationMedia)
        Response(BadRequest, ErrorMedia)
    })
})

MediaTypeの定義

とりあえず、返すだけ。

var ValidationMedia = MediaType("application/vnd.validation+json", func() {
    Description("example")
    Attributes(func() {
        Attribute("id", Integer, "id", func() {
            Example(1)
        })
        Attribute("integerType", Integer, "数字（1〜10）", func() {
            Example(5)
        })
        Attribute("stringType", String, "文字（1~10文字）", func() {
            Example("あいうえお")
        })
        Attribute("email", String, "メールアドレス", func() {
            Example("example@gmail.com")
        })
        Attribute("enumType", String, "列挙型", func() {
            Example("A")
        })
        Attribute("defaultType", String, "デフォルト値", func() {
            Example("でふぉ")
        })
        Attribute("reg", String, "デフォルト値", func() {
            Example("12abc")
        })
    })
    Required("id", "integerType", "stringType", "email", "enumType", "defaultType", "reg")
    View("default", func() {
        Attribute("id")
        Attribute("integerType")
        Attribute("stringType")
        Attribute("email")
        Attribute("enumType")
        Attribute("defaultType")
        Attribute("reg")
    })
})

コントローラー定義

コントローラーは、バリデーションが完了した値が来た時だけを想定した処理をすればおｋです。デザイン定義が完了したら、デザインを元にコードを生成しましょう。

$ goagen bootstrap -d github.com/tikasan/goa-stater/design
package main

import (
    "github.com/goadesign/goa"
    "github.com/tikasan/goa-stater/app"
)

// ValidationController implements the validation resource.
type ValidationController struct {
    *goa.Controller
}

// NewValidationController creates a validation controller.
func NewValidationController(service *goa.Service) *ValidationController {
    return &ValidationController{Controller: service.NewController("ValidationController")}
}

// Validation runs the validation action.
func (c *ValidationController) Validation(ctx *app.ValidationValidationContext) error {
    // ValidationController_Validation: start_implement

    // Put your logic here

    // ValidationController_Validation: end_implement
    res := &app.Validation{}
    res.ID = ctx.ID
    res.IntegerType = ctx.IntegerType
    res.StringType = ctx.StringType
    res.Email = ctx.Email
    res.EnumType = ctx.EnumType
    res.DefaultType = ctx.DefaultType
    res.Reg = ctx.Reg
    return ctx.OK(res)
}

実際に動かしてみよう

$ go run main.go
$ curl -v 'http://localhost:8080/api/v1/validation?id=1&defaultType=&email=satak%40gmail.com&enumType=A&integerType=10&stringType=foo&reg=12abc'
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> GET /api/v1/validation?id=1&defaultType=&email=satak%40gmail.com&enumType=A&integerType=10&stringType=foo&reg=12abc HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/vnd.validation+json
< Date: Sat, 06 May 2017 01:47:26 GMT
< Content-Length: 117
< 
{"id":1,"defaultType":"","email":"satak@gmail.com","enumType":"A","integerType":10,"reg":"12abc","stringType":"foo"}
* Connection #0 to host localhost left intact

goa紹介で使うソース達は、以下のリポジトリに随時更新していきます。
github.com