構成

以下の構成でデータを同期することにしました。

• 要件1: データの断面は合わせたい
  • 元々はEmblukを使って直接同期しようと考えていたが、Embulkだとテーブル毎にデータを同期することになり、テーブルによってデータの断面が微妙にずれるため断念
  • CSV 形式でダンプして、Embulk で同期することもできそうだが、元々自動でスナップショットが取られているのでそれを利用することにした
  • => スナップショットを parquet 形式で S3 にエクスポートすれば、BigQuery Data Transfer Service を使って BigQuery に取り込むことができるので、採用
• 要件2: コストを抑えたい
  • 定額利用料がかかるサービスは使うことはできない
  • => ほぼ無料で使える Lambda を採用
  • => データ転送料くらいしかコストのかからない BigQuery Data Transfer Service　を採用

Amazon RDS => Snapshot

RDSのデータベースを作成する際に 自動バックアップを有効 にしておくと、1日1回自動で Snapshot を作成してくれるので、それをそのまま利用します。

Snapshot => S3

Lambda で　aws-sdk を利用して、スナップショットを S3 にエクスポートします。

まず、Lambda の実行ロールに以下の Policy をアタッチする必要があります。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole",
                "rds:DescribeDBSnapshots",
                "rds:StartExportTask"
            ],
            "Resource": "*"
        }
    ]
}

また、スナップショットを S3 にエクスポートする際に指定する以下の二つのリソースが必要です。

• IAM Role
  • 以下の policy をアタッチ

    {
        "Statement": [
            {
                "Action": [
                    "s3:PutObject*",
                    "s3:ListBucket",
                    "s3:GetObject*",
                    "s3:GetBucketLocation",
                    "s3:DeleteObject*"
                ],
                "Effect": "Allow",
                "Resource": [
                    "arn:aws:s3:::xxxx-bucket/*",
                    "arn:aws:s3:::xxxx-bucket"
                ],
                "Sid": ""
            }
        ],
        "Version": "2012-10-17"
    }

  • 信頼関係に以下を指定

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "",
                "Effect": "Allow",
                "Principal": {
                    "Service": "export.rds.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            }
        ]
    }

• KMS の key
  • 対称、暗号化＆複合化の設定で作成

最後に、エクスポートを開始する Lambda を実装します。
コアな部分を抜き出して載せておきます。typescriptで実装してあります。

const rds = new AWS.RDS({ region: 'ap-northeast-1' });
const response = await rds.describeDBSnapshots({ DBInstanceIdentifier: 'xxxxxx' }).promise();
const snapshots = response['DBSnapshots'];
const latestSnapshot = snapshots?.sort((s1, s2) => (isBefore(s1.SnapshotCreateTime as Date, s2.SnapshotCreateTime as Date) ? -1 : 1))[0]; // isBefore は date-fns

const response = await rds
  .startExportTask({
    ExportTaskIdentifier: 'xxxxxx',
    SourceArn: snapshot.DBSnapshotArn,
    S3BucketName: 'xxxx-bucket',
    IamRoleArn: 'xxxxxx',
    KmsKeyId: 'xxxxxx',
    S3Prefix: 'xxxxxx',
  })
  .promise();

console.log(`response: ${JSON.stringify(response)}`);

こちらを実行すると、 S3 へのエクスポートが開始されます。
この Lambda の実行自体は数秒で終わりますが、エクスポートには20〜30分ぐらいかかるので注意が必要です。

S3 => BigQuery

次は、S3 にエクスポートしたスナップショットデータを BigQuery に同期するための Lambda を実装していきます。
BigQuery Data Transfer Service を使って同期するのですが、処理の流れは以下のようにしました。

• BigQuery にテーブルが存在していない場合作成する
• 既存の転送定義が存在する場合は、転送定義を削除する
• 転送定義を作成する
• 転送を開始する

転送定義を毎回削除=>作成しているのは、転送定義中のS3のスナップショットのパスが、毎日異なっており、そこを更新する必要があるためです。作成or更新を判断して利用するAPIを使い分けるのでもいいと思います。

事前準備

• GCP でサービスアカウントを作成する
  • BigQuery にアクセスして、テーブルを作成したり、転送定義を作成／開始したり権限が必要です
  • 必要なロールは以下の二つでした
  • BigQuery 管理者
  • BigQuery Data Transfer Service エージェント
• AWS で IAM User を作成する
  • BigQuery Data Transfer が AWS S3 にアクセスしたり、暗号化されたファイルを複合するための権限が必要です
  • 以下のようなポリシーを設定する必要があります

    {
        "Statement": [
            {
                "Action": [
                    "s3:List*",
                    "s3:Get*"
                ],
                "Effect": "Allow",
                "Resource": [
                    "arn:aws:s3:::xxxx-bucket/*",
                    "arn:aws:s3:::xxxx-bucket"
                ],
                "Sid": ""
            },
            {
                "Action": "kms:Decrypt",
                "Effect": "Allow",
                "Resource": "arn:aws:kms:xx-xxxxxxxxx-x:xxxxxxxxxx:key/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
                "Sid": ""
            }
        ],
        "Version": "2012-10-17"
    }

• GCP で Big Query と BigQuery Data Transfer Service の API を有効にする
• BigQuery で同期先のデータセットを作成する

ここまでで、事前準備は終わりです。次は Lambda を作成していきます。

BigQuery にテーブルが存在していない場合作成する

まずは、BigQuery にテーブルが存在しなかったら、作成する処理になります。
該当部分を抜粋すると以下のような感じになります。

// MySQLからテーブル名の一覧を取得
const [rows] = await con.execute('show tables from xxxxxx;'); // con は、MySQLのDBベースへのコネクションです。これを取得する部分は端折ってます
const tableNames = rows.map((row) => row['Tables_in_xxxxxx']);

// BigQueryのクライアントを初期化
const auth = googleAuth('bigqeury-projectname-xxx', 'service-account-email-xxx', 'service-account-private-key-xxxxxx', [
   'https://www.googleapis.com/auth/bigquery',
  'https://www.googleapis.com/auth/cloud-platform',
]);
const client = (await auth.getClient()) as JSONClient;
const bq = tnew BigQuery({ projectId: 'bigqeury-projectname-xxx', authClient: client });

// テーブルがなかったら作成
const dataset = bq.dataset('dataset-xxxx');
for (const tableName of tableNames) {
  const [tableExists] = await dataset.table(tableName).exists();
  if (tableExists) continue;
  await dataset.createTable(tableName, {});
}

既存の転送定義が存在する場合は、転送定義を削除する

次の既存の転送定義の有無を確認して、存在したら削除する処理を実装します。

// BigQuery Data Transfer Service のクライアントを初期化
const bqTransfer = new DataTransferServiceClient({ projectId: 'bigqeury-projectname-xxx',, authClient: client }); // clientは上で生成したもの

// 転送定義一覧を取得
const [configs] = await bqTransfer.listTransferConfigs({ parent: `projects/bigqeury-projectname-xxx/locations/asia-east2` });

// 転送定義が存在したら削除
for (const tableName of tableNames) { // この tableNames は上で取得したもの
  const existingConfigs = configs.filter((c) => c.displayName === tableName);
  for (const existingConfig of existingConfigs) {
    await bqTransfer.deleteTransferConfig({ name: existingConfig.name }); // 転送定義name＝テーブル名としてある
  }
}

転送定義を作成する

転送定義を作成します。
スケジュール実行にするとややこしいので、スケジューリングせず、オンデマンドで実行する設定で作成します。
設定値は、こちら で確認できます。

• data_pathの部分は、パスのフォルダ構成をちゃんと指定しないと上手く認識してくれませんでした
  • ちなみに、このパスの部分は毎日異なるフォルダに出力されるため、最新のスナップショットが格納されているフォルダパスを取得する必要があります。この例では端折ってますが、実際にはS3から最新のスナップショットのパスを取得してそれを指定する必要があります
• この転送設定のオーナーはサービスアカウントになるため、転送実行時にエラーが発生した場合には、サービスアカウントのメールアドレスにメールが送信され、気づくことができません。他のメールアドレスをパラメータで設定してみたのですが、ダメでした。エラーを検知するためには、pub/sub で通知する必要あるようですが、今回はそこまでやってません。

const parent = bqTransfer.projectPath('bigqeury-projectname-xxx');

const configs = [];
for (const tableName of tableNames) {
  const [config] = await bqTransfer.createTransferConfig({
    parent,
    transferConfig: {
      name: tableName,
      displayName: tableName,
      destinationDatasetId: 'dataset-xxxx',
      dataSourceId: 'amazon_s3',
      scheduleOptions: { disableAutoScheduling: true }, // スケジュール実行はしない
      params: {
        fields: {
          destination_table_name_template: { stringValue: tableName },
          data_path: {
            stringValue: 's3://xxxx-bucket/snapshot/xxxxxx/xxxxxx.${tableName}/*/*.parquet',
          },
          access_key_id: { stringValue: 'xxxxxx' },
          secret_access_key: { stringValue: 'xxxxxx' },
          file_format: { stringValue: 'PARQUET' },
          write_disposition: { stringValue: 'WRITE_TRUNCATE' },
        },
      },
      emailPreferences: { enableFailureEmail: true }, 
    },
  });
  configs.push(config);
}

転送を開始する

最後は、転送を開始する部分を実装します。

for (const config of configs) { // configs は上で取得
  await bqTransfer.startManualTransferRuns({ parent: config.name, requestedRunTime: { seconds: new Date().getTime() / 1000 } });
}

実行

上記で作成した Lambda を実行すると、 BigQuery の「データ転送」タブに新しい転送定義が作成されて、転送が開始されます。

実行時に以下のようなトラブルが発生したので、並列実行で対応しました。

• シーケンシャルに100以上のテーブルについて、テーブル作成=>転送定義削除=>転送定義作成=>転送開始をやったところ、Lambdaの実行時間の制限（15分）を超える可能性がありそうだった。実際、12分ぐらいかかっていた
• 単純に promise.all で一気に並列実行したら、GCP側の API コール回数の Quota　に引っかかって途中でエラーになった
• => 3 並列ぐらいで処理するようにしたら、処理時間も5分ぐらいでおさまり、Quota エラーも出なくなった

トラブルは上記ぐらいで、問題なく動いてくれました。

最後に

今回、「RDSの自動スナップショット => S3にエクスポート => BigQuery Data Transerで BigQueryに転送」という構成でRDSをBigQueryに同期する仕組みを作りました。
一週間くらいは運用してますが、一度もエラーなく毎朝動いてくれています。
特に、スナップショットをインプットにしているので、

• 実運用中のDBに負荷がかからないこと
• データの断面が揃っていること
  が気に入っています。
  1日に一度程度の同期頻度で良い場合は、この構成結構いいんじゃないかなと思いました。

利用している技術

• 言語: golang
• web framework: chi
• ORM: bun

トランザクションの開始／終了

通常の　Web APIでは1リクエスト1トランザクションが一番シンプルで分かりやすいので、リクエストとトランザクションのライフサイクルは同じにしたいです。
一つのAPIコールの途中で何かエラーが発生したら、全部ロールバックする形です。

この場合、controllers 層でトランザクションを開始／終了するのが良さそうです。

controllers 層の各ハンドラーにて、以下のような感じで実装するのが一番シンプルですが、同じ実装が何度も出てくるのがとても煩雑です。

func (s *Server) DoSomething(w http.ResponseWriter, r *http.Request) {
    s.db.RunInTx(r.Context(), nil, func(ctx context.Context, tx bun.Tx) error {
        err := doSomething()
        if err != nil {
            return err // rollbackされる
        }
        return nil // commit される
    })
}

重複コードを減らすには、middleware を使うのが良さそうです。
chi と bun を使ってるケースですが、以下のような middleware を作成しました。

func (s *Server) SetTxMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        s.db.RunInTx(r.Context(), nil, func(ctx context.Context, tx bun.Tx) error { // start transaction
            new_ctx := context.WithValue(r.Context(), repositories.TX_KEY, &tx)
            ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
            next.ServeHTTP(ww, r.WithContext(new_ctx))

            if ww.Status() != http.StatusOK {
                return errors.New("rollbacked needed") // rollback
            }
            return nil // commit
        })
    })
}

ここでは以下のようなことを実装しています。

• ハンドラーが呼び出されるたびに、トランザクションをスタートして context　に設定する
  • repositories 層では、context からトランザクションを取得して利用する
• status を取得して、OK(200)以外の場合は、ロールバックする
  • status を取得できるようにするために、NewWrapResponseWriterを利用している
• s.dbはwireでDIして渡してる
  • 詳細はgithubのソースコードを参照ください

後は、作成した middleware を設定するだけです。

func main() {
    server := InitializeServer()
    router := chi.NewRouter()
    router.Use(server.SetTxMiddleware)
    controllers.HandlerFromMux(server, router)
    http.ListenAndServe(port, router)
}

これで、ハンドラーが呼び出されるたびに、トランザクションが開始して、status がOK(200)ならコミット、OK(200)以外ならロールバックされるようになりました。

トランザクションの利用

contorllers層で開始したトランザクションは、以下のような感じでrepositories層で利用できます。

func (c CommentRepositoryImpl) Add(ctx context.Context, commentEntity entities.CommentEntity) (entities.CommentEntity, error) {
    dbComment := repositories.FromCommentEntity(commentEntity)
    tx := ctx.Value(TX_KEY).(*bun.Tx)
    _, err := tx.NewInsert().Model(&dbComment).Exec(ctx)
    if err != nil {
        return entities.CommentEntity{}, err
    }
    //  return entities.CommentEntity{}, errors.New("dummy error")
    return dbComment.ToCommentEntity(), nil
}

試しに、上記のコメントアウトしている部分をコメントインして実行してみると、ちゃんとロールバックされていることをログおよびDBから確認することができました。

最後に

今回のケースでは、chi+bunの組み合わせですが、他のルータやORMを使うケースでも同じ考え方でいけると思います。
初めてmiddlewareを使ってみたのですが、定型のコードを一箇所にまとめて、transactionに関する処理を一元化できたのがよかったです。
また、リクエストとトランザクションのライフサイクルを合わせたのですが、ライフサイクルを意識して実装するのも大事だなぁと改めて思いました。

既存のRepositoryモデルを元に、RepositoryモデルをDomainモデルに変換するマッパーを生成するようなケースを紹介します。

フォルダ構成

├── domains
│   └── model.go                      # Domainモデル
└── repositories
    ├── gen
    │   ├── gen.go                    # generator本体
    │   └── mapper.tmpl               # 参照するテンプレート
    ├── model.go                      # 参照するRepositoryモデル
    └── mapper.gen.go                 # 自動生成されたマッパー

genフォルダ配下にgenerator本体を置くのは、go generate のベストプラクティス を参考にさせていただきました。

参照元のコード

Repositoryモデル

今回はbunを使ってます。

import (
    "github.com/uptrace/bun"
    "time"
)

type DbComment struct {
    bun.BaseModel `bun:"table:comment,alias:c"`

    Id        *int64     `bun:"id,pk"`
    Text      string     `bun:"text"`
    CreatedAt *time.Time `bun:"created_at"`
    UpdatedAt *time.Time `bun:"updated_at"`
}

自動生成

動かしてみる

実際にファイルを生成したいフォルダ配下にgenというフォルダを生成して、そこにgen.goを作成します。

repositories/gen/gen.go
まずは、以下のような内容を記載してみます。

//go:generate go run .
//go:generate gofmt -w ../

import (
    "fmt"
)

func main() {
    fmt.Println("generate!!!")
}

go generateは、実行フォルダ配下で、//go:generate xxxのようなコメントが存在する場合、xxxの部分をコマンドとして実行してくれます。上記の例では

• 1行目は、go run .が実行され、具体的にはmain()が実行されます
• 2行目は、gofmt -w ../が実行され、親フォルダ配下（自動生成したソースコードを含む）をフォーマットします。

この時点で、以下のコマンドを実行すると、main()が実行されたことが分かると思います。

cd repositories/gen
go generate
> generate!!!

つまり、あとはmain()の中で、

• RepositoryモデルのASTを読み込んで必要な情報を取得する
• Domainモデルとのマッパーファイルを作成する
  • テンプレートを準備しておいてそこに流し込む

という作業をやってあげれば良さそうです。

gen.goを実装する

細々説明するほど難しい実装でもないので、全体をそのまま載っけておきます。
main()から辿っていけば何をやっているかわかると思います。

repositories/gen/gen.go

//go:generate go run .
//go:generate gofmt -w ../

package main

import (
    "bytes"
    "fmt"
    "go/ast"
    "go/parser"
    "go/printer"
    "go/token"
    "log"
    "os"
    "strings"
    "text/template"
)

// 構造体定義
type StructDef struct {
    Name   string
    Fields []FieldDef
}

func (sd StructDef) Alias() string {
    return strings.ToLower(sd.Name[0:1]) + sd.Name[1:]
}

// 構造体フィールド定義
type FieldDef struct {
    Name string
    Type string
}

func (fd FieldDef) Alias() string {
    return strings.ToLower(fd.Name[0:1]) + fd.Name[1:]
}

// ファイルをパースしてASTから必要な構造体情報を返却
func ParseFirstStruct(fpath string) ([]StructDef, error) {
    fset := token.NewFileSet()
    f, err := parser.ParseFile(fset, fpath, nil, 0)
    if err != nil {
        return nil, err
    }

    list := []StructDef{}
    ast.Inspect(f, func(n ast.Node) bool {
        x, ok := n.(*ast.TypeSpec)
        if !ok {
            return true
        }
        if y, ok := x.Type.(*ast.StructType); ok {
            sdef := StructDef{}
            sdef.Name = x.Name.Name
            for _, fld := range y.Fields.List {
                if fld.Names == nil {
                    continue
                }
                var typeNameBuf bytes.Buffer
                err := printer.Fprint(&typeNameBuf, fset, fld.Type)
                if err != nil {
                    log.Fatalf("failed printing %s", err)
                }
                sdef.Fields = append(sdef.Fields, FieldDef{Name: fld.Names[0].Name, Type: typeNameBuf.String()})
            }
            list = append(list, sdef)
        }
        return true
    })
    return list, nil
}

// マッパーファイルを生成
func createMapperFile(outputFilePath string, def StructDef) error {
    file, err := os.Create(outputFilePath)
    if err != nil {
        return err
    }
    defer file.Close()

    t := template.Must(template.ParseFiles("./mapper.tmpl"))
    data := map[string]interface{}{
        "ModelName":  def.Name[2:], // "Comment"
        "ModelArias": strings.ToLower(def.Name[2:][0:1]) + def.Name[2:][1:], // "comment"
        "Fields":     def.Fields,
    }
    if err := t.Execute(file, data); err != nil {
        return err
    }
    fmt.Println(outputFilePath + " is generated.")
    return nil
}

// エントリーポイント
func main() {
    inputFilePath := "../model.go"

    list, err := ParseFirstStruct(inputFilePath)
    if err != nil || len(list) == 0 {
        fmt.Fprintf(os.Stderr, "model parse faild.\n: %s", err)
        os.Exit(1)
    }

    outputFilePath := "../" + strings.Split(strings.Split(inputFilePath, "/")[1], ".")[0] + "_mapper.gen.go"
    err = createMapperFile(outputFilePath, list[0])
    if err != nil {
        fmt.Fprintf(os.Stderr, "code generate failed.\n: %s", err)
        os.Exit(1)
    }
}

/repositories/gen/mapper.tmpl

// Code generated by go generate DO NOT EDIT.

package repositories

import domains "github.com/rinoguchi/microblog/test/domains"

func (db{{ .ModelName }} Db{{ .ModelName }}) ToDomain{{ .ModelName }}() domains.{{ .ModelName }} {
    return domains.{{ .ModelName }}{
    {{range .Fields -}}
    {{ .Name }}:  db{{ $.ModelName }}.{{ .Name }},
    {{end -}}
    }
}

func FromDomain{{ .ModelName }}({{ .ModelArias }} domains.{{ .ModelName }}) Db{{ .ModelName }} {
    return Db{{ .ModelName }}{
    {{range .Fields -}}
    {{ .Name }}:  {{ $.ModelArias }}.{{ .Name }},
    {{end -}}
    }
}

上記を実装した上で、改めてgo generateを実行すると、model_mapper.gen.goが生成されました。

go generate
../model_mapper.gen.go is generated.

/repositories/model_mapper.gen.go

// Code generated by go generate DO NOT EDIT.

package repositories

import domains "github.com/rinoguchi/microblog/test/domains"

func (dbComment DbComment) ToDomainComment() domains.Comment {
    return domains.Comment{
        Id:        dbComment.Id,
        Text:      dbComment.Text,
        CreatedAt: dbComment.CreatedAt,
        UpdatedAt: dbComment.UpdatedAt,
    }
}

func FromDomainComment(comment domains.Comment) DbComment {
    return DbComment{
        Id:        comment.Id,
        Text:      comment.Text,
        CreatedAt: comment.CreatedAt,
        UpdatedAt: comment.UpdatedAt,
    }
}

これにて終了です。

この記事では、バックエンド（APIサーバ）部分について記載していきます。ソースコードも公開してますので、細かいところは直接参照ください。
https://github.com/rinoguchi/microblog

使う技術

• バックエンドAPIサーバ
  • 言語: Go
    • 経験少なめなので慣れておきたい
  • Webフレームワーク: chi
  • DIツール: wire
• 実行環境: GAE(Google App Engine)
  • Goが使える
  • 1日あたり 28 インスタンス時間の無料枠がある
  • Dockerイメージすら作らずに、アプリをデプロイ＋公開できる
• データベース: supabase
  • 500MBまで無料！個人利用なら十分 ※料金体系
  • 中身は慣れ親しんだPostgreSQL

作るもの

twitterの劣化版という感じで、コメントを投稿して公開するだけの超絶シンプルなマイクロブログのバックエンドAPIを作ります。

初期段階のAPIのエンドポイントは以下の二つです。

• post /comments
  • コメントを投稿する
• get /comments
  • コメントを全件取得する

既存のHello WorldアプリをGAEにデプロイ

まずは、公開されている既存の「Hello Worldアプリ」をGAEにデプロイして実行してみることで、開発の流れを把握します。
こちらを読みながら順番にやってみました。

• GCPのプロジェクト作成する
• 課金を有効にする（元々やってあった）
• 「Cloud Build API」を有効にする
• Google Cloud CLI をインストール & 初期化する

  # バイナリダウンロード
  # https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-370.0.0-darwin-x86_64.tar.gz?hl=ja
  ./google-cloud-sdk/install.sh
  ./google-cloud-sdk/bin/gcloud init

• app-engine-goコンポートネントをインストール

  gcloud components install app-engine-go

• App Engine アプリを初期化

  gcloud app create --project=xxx
  # `asia-northeast1`(東京)を選択

• Hello WorldアプリをGitからダウンロード

  git clone https://github.com/GoogleCloudPlatform/golang-samples.git
  cd golang-samples/appengine/go11x/helloworld

• App Engine に Hello World をデプロイ

  gcloud app deploy

• 動作確認

  # コマンドでブラウザ起動
  gcloud app browse
  
  # curlで確認
  curl https://xxx.an.r.appspot.com/
  > Hello, World!

サクサクできてとりあえず動くところまで確認できるのはありがたいです。

自前でHello Worldアプリを実装

次は、chi を使って、Hello Worldアプリを作ってみたいと思います。
chi は、軽量で高速でGo標準ライブラリのみに依存するとても薄いWebフレームワークとのことで、クリーンアーキテクチャとは相性が良さそうです。

以下の手順で簡単にアプリ構築＋GAEデプロイができました。

• go.mod

  go mod init helloworld

• main.go

  package main
  
  import (
      "net/http"
  
      "github.com/go-chi/chi/v5"
      "github.com/go-chi/chi/v5/middleware"
  )
  
  func main() {
      r := chi.NewRouter()
      r.Use(middleware.RequestID)
      r.Use(middleware.Logger)
      r.Use(middleware.Recoverer)
  
      r.Get("/", func(w http.ResponseWriter, r *http.Request) {
          w.Write([]byte("はろー　わーるど！"))
      })
  
      http.ListenAndServe(":8080", r)
  }

• app.yamlを作成

  runtime: go116

• 依存関係を解決

  go mod tidy

• デプロイ

   gcloud app deploy

• 動作確認

  gcloud app browse
  > はろー　わーるど！

ここまでは結構分かりやすかったです。

クリーンアーキテクチャでAPIを作る

やっと本体を作っていきます。クリーンアーキテクチャでAPIを実装していこうと思います。

フォルダ構成

フォルダ構成（=パッケージ名）は以下ように、クリーンアーキテクチャの図に出てくる名称を使ってみることにしました。（entitiesあたりは違和感がすごいですが、きっと慣れるでしょう。。。）

.
├── _docs
│   ├── api-schema.yaml
│   ├── chi-server.config.yaml
│   ├── models.config.yaml
│   ├── xorm_reverse.config.gen.yaml
│   └── xorm_reverse.config.yaml
│
├── adapters              # 外界とのインターフェース
│   ├── controllers       # APIリクエストのコントローラー
│   │   ├── models
│   │   │   ├── gen
│   │   │   │   ├── gen.go
│   │   │   │   └── mapper.tmpl
│   │   │   ├── comment_mapper.gen.edt.go
│   │   │   └── models.gen.go
│   │   ├── server.gen.go
│   │   └── server.go
│   │
│   └── repositories      # データをやり取りするリポジトリ。現状裏側はpostgresqlのみ
│       ├── models
│       │   ├── gen
│       │   │   ├── gen.go
│       │   │   ├── goxorm.tmpl
│       │   │   └── mapper.tmpl
│       │   ├── models.go
│       │   └── models_mapper.gen.edt.go
│       ├── comment_repository.go
│       └── db.go
│
├── usecases              # アプリケーションのユースケースを表現
│   ├── models
│   │   ├── gen
│   │   │   ├── gen.go
│   │   │   └── model.tmpl
│   │   └── comment.gen.edt.go
│   ├── comment_usecase.go
│   └── models.gen.go
│
├── entities              # コアなデータ構造およびデータ変更を行う
│   └── comment.go
│
├── utils                 # 全レイヤーからアクセス可能なutility
│   ├── gen_utils.go
│   └── string_utils.go
│
├── Makefile
├── README.md
├── app.yaml
├── env.yaml
├── go.mod
├── go.sum
├── main.go
├── wire.go
└── wire_gen.go

コード自動生成について

非常にシンプルなアプリなのにクリーンアーキテクチャを採用しているので、各レイヤーでのモデル定義、詰め替え処理など、とても無駄が多くなります。なので、自動で生成できるものはできるだけ自動生成するようにします。

• ファイル名に.genとついているものは、自動生成したもの
• .gen.edtとついているものは、自動生成したけど後で編集できるもの
  • 1行目に// DO NOT OVERWRITEと記載することで、次回以降上書きされない

`go generateに関しては、以下の記事を書いたのでそちらで使い方を参照ください。
https://rinoguchi.net/2022/09/go-generate.html

Entitiesを実装

この層では、アプリケーションに寄らないドメインモデルとリポジトリのインターフェースを定義します。
現時点ではドメインモデルは振る舞いを持ってませんが、いずれ持たせることになるかもしれません。
ドメインモデルが持つ振る舞いは、ドメインモデルのデータの中身を変更する様な処理と考えています。

entities/comment.go

package entities

import (
    "context"
    "time"
)

type CommentEntity struct {
    Id        *int64
    Text      string
    CreatedAt *time.Time
    UpdatedAt *time.Time
}

type CommentRepository interface {
    FindAll(ctx context.Context) ([]CommentEntity, error)
    Add(ctx context.Context, comment CommentEntity) (CommentEntity, error)
}

現時点では、CommentEntityは振る舞いは持ってないですが、今後追加する可能性もあります。
CommentRepositoryは別ファイルに分けても良かったですが、ドメインモデルのデータを扱うリポジトリは同じファイルに存在する方がわかりやすい気がするので、同じファイルにしてあります。

UseCasesを実装

この層では、アプリケーション固有のユースケースを実装します。
今回は、「コメント一覧を取得する」「コメントを登録する」というユースケースを記載しています
この層はUseCases層とEntities層のみに依存し、外側の層には依存しません。

Usecasesのモデルは自動生成しました。UsecasesのモデルとEntities（ドメイン）のモデルのマッパーも合わせて自動生成しています。

usecases/models/comment.gen.edt.go
usecases/models/gen/gen.goで自動生成しています。

// Code generated by go generate DO NOT EDIT.
// If you edit this file, write "// DO NOT OVERWRITE" on the first line.

package usecases

import (
    "github.com/rinoguchi/microblog/entities"
    "time"
)

type UComment struct {
    CreatedAt *time.Time
    Id        *int64
    Text      string
    UpdatedAt *time.Time
}

func (uComment UComment) ToCommentEntity() entities.CommentEntity {
    return entities.CommentEntity{
        CreatedAt: uComment.CreatedAt,
        Id:        uComment.Id,
        Text:      uComment.Text,
        UpdatedAt: uComment.UpdatedAt,
    }
}

func FromCommentEntity(comment entities.CommentEntity) UComment {
    return UComment{
        CreatedAt: comment.CreatedAt,
        Id:        comment.Id,
        Text:      comment.Text,
        UpdatedAt: comment.UpdatedAt,
    }
}

アプリケーションのユースケースを実装しています。
Entities(ドメイン)層に定義したRepositoryのインターフェースを通じてデータを取得して返却しているだけです。

usecases/comment_usecase.go

package usecases

import (
    "context"

    "github.com/rinoguchi/microblog/entities"
    usecases "github.com/rinoguchi/microblog/usecases/models"
)

type CommentUsecase struct {
    commentRepository entities.CommentRepository
}

func NewCommentUsecase(
    commentRepository entities.CommentRepository,
) CommentUsecase {
    return CommentUsecase{
        commentRepository: commentRepository,
    }
}

func (c CommentUsecase) FindAllComment(ctx context.Context) ([]usecases.UComment, error) {
    commentEntities, err := c.commentRepository.FindAll(ctx)
    if err != nil {
        return nil, err
    }
    uComments := []usecases.UComment{}
    for _, commentEntity := range commentEntities {
        uComments = append(uComments, usecases.FromCommentEntity(commentEntity))
    }
    return uComments, nil
}

func (c CommentUsecase) AddComment(ctx context.Context, uComment usecases.UComment) (usecases.UComment, error) {
    commentEntity, err := c.commentRepository.Add(ctx, entities.CommentEntity{
        Text: uComment.Text,
    })
    if err != nil {
        return usecases.UComment{}, err
    }
    return usecases.FromCommentEntity(commentEntity), nil
}

ちなみに、正直このレイヤーは今回のようなシンプルなアプリの場合は、無駄なモデルの変換を行なっているだけでコード量が増えただけで、controllersとusecasesを分ける意味はほとんど無いように感じましたw

Controllersを実装

ここは、HTTPリクエストをハンドリングするだけの層です。

まずは、HTTPリクエスト用のモデルをAPIスキーマから oapi-codegen を使って自動生成しました。

/adapters/controllers/models/models.gen.go

// Package controllers provides primitives to interact with the openapi HTTP API.
//
// Code generated by github.com/deepmap/oapi-codegen version v1.11.0 DO NOT EDIT.
package controllers

import (
    "time"
)

// Comment defines model for Comment.
type Comment struct {
    CreatedAt *time.Time `json:"created_at,omitempty"`
    Id        *int64     `json:"id,omitempty"`
    Text      string     `json:"text"`
    UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

// CommonProps defines model for CommonProps.
type CommonProps struct {
    CreatedAt *time.Time `json:"created_at,omitempty"`
    Id        *int64     `json:"id,omitempty"`
    UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

// Error defines model for Error.
type Error struct {
    Message string `json:"message"`
}

// NewComment defines model for NewComment.
type NewComment struct {
    Text string `json:"text"`
}

// AddCommentJSONBody defines parameters for AddComment.
type AddCommentJSONBody = NewComment

// AddCommentJSONRequestBody defines body for AddComment for application/json ContentType.
type AddCommentJSONRequestBody = AddCommentJSONBody

次に、自前で go generator を使って、controller モデルと cusecase モデルのマッパーも自動生成しました。

/adapters/controllers/models/comment_mapper.gen.edt.go
/adapters/controllers/models/gen/gen.goで自動生成しています。

// Code generated by go generate DO NOT EDIT.
// If you edit this file, write "// DO NOT OVERWRITE" on the first line.

package controllers

import usecases "github.com/rinoguchi/microblog/usecases/models"

func (comment Comment) ToUComment() usecases.UComment {
    return usecases.UComment{
        CreatedAt: comment.CreatedAt,
        Id:        comment.Id,
        Text:      comment.Text,
        UpdatedAt: comment.UpdatedAt,
    }
}

func FromUComment(uComment usecases.UComment) Comment {
    return Comment{
        CreatedAt: uComment.CreatedAt,
        Id:        uComment.Id,
        Text:      uComment.Text,
        UpdatedAt: uComment.UpdatedAt,
    }
}

今回は、Webフレームワークとして chi を利用していますので、APIスキーマから oapi-codegen を使って、chi用のハンドラのインターフェースを自動生成しました。
※ 詳細は 別記事 参照

/adapters/controllers/server.gen.go（自動生成、一部抜粋）
ServerInterfaceインターフェースでGetComment()とAddCommentというハンドラが定義されています。

package controllers

// ServerInterface represents all server handlers.
type ServerInterface interface {

    // (GET /comments)
    GetComments(w http.ResponseWriter, r *http.Request)

    // (POST /comments)
    AddComment(w http.ResponseWriter, r *http.Request)
}

// ServerInterfaceWrapper converts contexts to parameters.
type ServerInterfaceWrapper struct {
    Handler            ServerInterface
    HandlerMiddlewares []MiddlewareFunc
    ErrorHandlerFunc   func(w http.ResponseWriter, r *http.Request, err error)
}

// GetComments operation middleware
func (siw *ServerInterfaceWrapper) GetComments(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    var handler = func(w http.ResponseWriter, r *http.Request) {
        siw.Handler.GetComments(w, r)
    }

    for _, middleware := range siw.HandlerMiddlewares {
        handler = middleware(handler)
    }

    handler(w, r.WithContext(ctx))
}

// AddComment operation middleware
func (siw *ServerInterfaceWrapper) AddComment(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    var handler = func(w http.ResponseWriter, r *http.Request) {
        siw.Handler.AddComment(w, r)
    }

    for _, middleware := range siw.HandlerMiddlewares {
        handler = middleware(handler)
    }

    handler(w, r.WithContext(ctx))
}

最後に、上記で作成されたインターフェースを実装しました。

/adapters/controllers/server.go

Serverという構造体が、自動生成されたServerInterfaceを実装したものです。この構造体にGetComments()とAddComment()を実装してあります。

package controllers

import (
    "context"
    "encoding/json"
    "net/http"

    controllers "github.com/rinoguchi/microblog/adapters/controllers/models"
    "github.com/rinoguchi/microblog/adapters/repositories"
    "github.com/rinoguchi/microblog/usecases"
)

type Server struct {
    commentUsecase usecases.CommentUsecase
}

func NewServer(commentUsecase usecases.CommentUsecase) *Server {
    return &Server{
        commentUsecase: commentUsecase,
    }
}

func (s *Server) GetComments(w http.ResponseWriter, r *http.Request) {
    ctx := context.WithValue(r.Context(), repositories.DbKey, repositories.GetDb())
    uComments, err := s.commentUsecase.FindAllComment(ctx)
    if err != nil {
        handleError(w, err)
        return
    }

    var comments []controllers.Comment
    for _, uComment := range uComments {
        comments = append(comments, controllers.FromUComment(uComment))
    }

    w.Header().Set("Content-Type", "application/json; charset=UTF-8")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(comments)
}

func (s *Server) AddComment(w http.ResponseWriter, r *http.Request) {
    ctx := context.WithValue(r.Context(), repositories.DbKey, repositories.GetDb())

    var comment controllers.Comment
    if err := json.NewDecoder(r.Body).Decode(&comment); err != nil {
        handleError(w, err)
        return
    }

    uComment, err := s.commentUsecase.AddComment(ctx, comment.ToUComment())
    if err != nil {
        handleError(w, err)
        return
    }

    w.Header().Set("Content-Type", "application/json; charset=UTF-8")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(controllers.FromUComment(uComment))
}

func handleError(w http.ResponseWriter, err error) {
    w.WriteHeader(http.StatusInternalServerError)
    w.Write([]byte(http.StatusText(http.StatusInternalServerError)))
}

データベース準備

Repositoriesを実装する前に、データベースを準備してなかったので、supabaseを利用してPostgreSQLのDBを立てます。
supabaseは500MBまでは無料みたいなので、今回の用途であれば十分です^^

データベース作成

以下を実行するだけでデータベースを作成できました。

• https://supabase.com/ を開く
• Start your project から開始
• SignIn with GitHubからサインイン
• New Project からプロジェクトを作成
• Database名、パスワード、Region(asia-east-1) などを入力

クレジットカードなどを登録する必要がない**ので、気軽にDBを作成できるのが嬉しいです(^^)

timezone変更

デフォルトのtimezoneはUTCなので、Asia/Tokyoに変更しました。
SQLはSQL Editorで実行できます。

-- 確認
show timezone;
-- 変更
alter database postgres
set timezone to 'Asia/Tokyo';

アプリ接続用ユーザ作成

アプリからDBに接続する時に利用するユーザを作成しました。

-- ユーザ作成
create user microblog_app
password '**********';

-- スキーマ自体へのアクセス権限付与
grant all on schema public to microblog_app;

-- publicスキーマの各種オブジェクトへのデフォルト権限の付与
alter default privileges in schema public grant all on tables to microblog_app;
alter default privileges in schema public grant all on sequences to microblog_app;
alter default privileges in schema public grant all on functions to microblog_app;

テーブル作成

コメントを保存するテーブルを作成しました。

create table comment (
  id bigint generated by default as identity primary key,
  text text,
  created_at timestamp with time zone default (now() at time zone 'jst') not null,
  updated_at timestamp with time zone default (now() at time zone 'jst') not null
);

psqlで接続

裏側はただのPostgreSQLなので、普通にpsqlで接続できます。
接続情報は、Settings > Database > Connection Infoに記載されています。
接続ユーザは先ほど作ったmicroblog_app を利用しました。

$ psql -h db.xxxxxxxxxxxx.supabase.co -p 5432 -d postgres -U microblog_app
Password for user microblog_app: 
psql (14.2, server 14.1)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

postgres=> \dt
             List of relations
 Schema |   Name   | Type  |     Owner
--------+----------+-------+----------------
 public | comment | table | supabase_admin
(1 row)

postgres=> select * from comment;
 id | text | created_at | updated_at
----+------+------------+------------
(0 rows)

postgres=> insert into comment(text) values('dummy text');
INSERT 0 1
postgres=> select * from comment;
 id |    text    |          created_at           |          updated_at
----+------------+-------------------------------+-------------------------------
  2 | dummy text | 2022-07-31 11:53:16.830773+09 | 2022-07-31 11:53:16.830773+09
(1 row)

postgres=> drop table comment;
ERROR:  must be owner of table comment
postgres=> \q

無事に接続できました。
DMLは実行できて、DDLは実行できないようになってるので、想定通りです。

Repositoriesの実装

モデルの自動生成

RepositoryモデルをDBスキーマから自動生成したいと思います。
ここは xorm/reserve を使って実現しました。

まずはインストールします。

go get xorm.io/reverse

/adapters/repositories/models/gen/goxorm.tmpl
Model出力用のテンプレートファイルです。出力したい内容になるようにテンプレートを作成します。

// Code generated by xorm/reverse generate DO NOT EDIT.
package repositories

{{$ilen := len .Imports}}
{{if gt $ilen 0}}
import (
    {{range .Imports}}"{{.}}"{{end}}
  "github.com/uptrace/bun"
)
{{end}}

{{range .Tables}}
type Db{{ (TableMapper .Name) }} struct {
bun.BaseModel `bun:"table:{{ .Name }},alias:{{ slice .Name 0 1 }}"`

{{$table := .}}
{{range .ColumnsSeq}}{{$col := $table.GetColumn .}} {{ColumnMapper $col.Name}}  {{if (eq (ColumnMapper $col.Name) "Id")}}*{{end}}{{if (eq (ColumnMapper $col.Name) "CreatedAt")}}*{{end}}{{if (eq (ColumnMapper $col.Name) "UpdatedAt")}}*{{end}}{{Type $col}} `bun:"{{$col.Name}}{{if (eq (ColumnMapper $col.Name) "Id")}},pk{{end}}"`
{{end}}
}

{{end}}

さらに、実行用の設定ファイルを作成します。
_docs/xorm_reverse.config.gen.yaml

kind: reverse
name: microblog
source:
  database: postgres
  conn_str: "postgresql://microblog_app:******@db.******.supabase.co:5432/postgres"
targets:
  - type: codes
    language: golang
    output_dir: adapters/repositories/models
    template_path: adapters/repositories/models/gen/goxorm.tmpl

テンプレートを実装したら、自動生成を実行します。

reverse -f _docs/xorm_reverse.config.gen.yaml

/adapters/repositories/models/models.go
想定通りの内容が自動生成されていました。

// Code generated by xorm/reverse generate DO NOT EDIT.
package repositories

import (
    "github.com/uptrace/bun"
    "time"
)

type DbComment struct {
    bun.BaseModel `bun:"table:comment,alias:c"`

    Id        *int64     `bun:"id,pk"`
    Text      string     `bun:"text"`
    CreatedAt *time.Time `bun:"created_at"`
    UpdatedAt *time.Time `bun:"updated_at"`
}

モデルマッパーの実装

Repository モデルを　Entity（ドメイン） モデルに変換するマッパーが必要なのですが、こちらも go generate で自動生成しました。

/adapters/repositories/models/models_mapper.gen.edt.go
/adapters/repositories/models/gen/gen.goで自動生成しています。

// Code generated by go generate DO NOT EDIT.
// If you edit this file, write "// DO NOT OVERWRITE" on the first line.

package repositories

import "github.com/rinoguchi/microblog/entities"

func (dbComment DbComment) ToCommentEntity() entities.CommentEntity {
    return entities.CommentEntity{
        Id:        dbComment.Id,
        Text:      dbComment.Text,
        CreatedAt: dbComment.CreatedAt,
        UpdatedAt: dbComment.UpdatedAt,
    }
}

func FromCommentEntity(comment entities.CommentEntity) DbComment {
    return DbComment{
        Id:        comment.Id,
        Text:      comment.Text,
        CreatedAt: comment.CreatedAt,
        UpdatedAt: comment.UpdatedAt,
    }
}

DB接続部分を実装

今回は、PostgreSQL用にアクセスするためのclientは、bunを利用してみようと思います。

ライブラリインストール

go get github.com/uptrace/bun
go get github.com/uptrace/bun/dialect/pgdialect
go get github.com/uptrace/bun/driver/pgdriver@v1.1.5

※ GAEはgo1.16までしか対応しておらず、最新バージョンのpgdriverだと、以下のエラーが発生するため少し前のバージョンを利用しています。

go get github.com/uptrace/bun/driver/pgdriver
> # github.com/uptrace/bun/driver/pgdriver
> ../../go/1.16.13/pkg/mod/github.com/uptrace/bun/driver/pgdriver@v1.1.7/proto.go:125:17: tlsCN.HandshakeContext undefined (type *tls.Conn has no field or method HandshakeContext)
> note: module requires Go 1.17

DBパラメータを環境変数に設定

ローカル実行環境向けは、.envrcに設定してdirenvで読み込むことにしました。

.envrc

export DB_ADDRESS=db.****.supabase.co:****
export DB_USER=****
export DB_PASSWORD=****
export DB_NAME=****
export DB_APPLICATION_NAME=****

GAEデプロイ時にapp.yamlで環境変数を指定することにしました。
直接記載するとGit管理下に含まれるので、env.yamlに外出しし、Git管理対象外としました。

app.yaml

runtime: go116
includes:
  - env.yaml

env.yaml

env_variables:
  "DB_ADDRESS": "db.****.supabase.co:****"
  "DB_USER": "****"
  "DB_PASSWORD": '****"'
  "DB_NAME": "****"
  "DB_APPLICATION_NAME": "****"

DB接続アダプター

db.goでPostgreSQLに接続するためのアダプター（ミドルウェア）を作成します。
必要な情報は環境変数から取得する形にしてあります。

/adapters/repositories/db.go

package repositories

import (
    "crypto/tls"
    "database/sql"
    "os"
    "time"

    "github.com/uptrace/bun"
    "github.com/uptrace/bun/dialect/pgdialect"
    "github.com/uptrace/bun/driver/pgdriver"
    "github.com/uptrace/bun/extra/bundebug"
)

// コンテキスト追加用のキー
type dbKey int

const DbKey dbKey = iota

func GetDb() *bun.DB {

    pgconn := pgdriver.NewConnector(
        pgdriver.WithNetwork("tcp"),
        pgdriver.WithAddr(os.Getenv("DB_ADDRESS")),
        pgdriver.WithTLSConfig(&tls.Config{InsecureSkipVerify: true}),
        pgdriver.WithUser(os.Getenv("DB_USER")),
        pgdriver.WithPassword(os.Getenv("DB_PASSWORD")),
        pgdriver.WithDatabase(os.Getenv("DB_NAME")),
        pgdriver.WithApplicationName(os.Getenv("DB_APPLICATION_NAME")),
        pgdriver.WithTimeout(5*time.Second),
        pgdriver.WithDialTimeout(5*time.Second),
        pgdriver.WithReadTimeout(5*time.Second),
        pgdriver.WithWriteTimeout(5*time.Second),
    )

    pgdb := sql.OpenDB(pgconn)

    // Create a Bun db on top of it.
    db := bun.NewDB(pgdb, pgdialect.New())

    // Print all queries to stdout.
    db.AddQueryHook(bundebug.NewQueryHook(bundebug.WithVerbose(true)))

    return db
}

Controllerでcontextにdb追加

同じリクエストは同一のDB接続を使い回すために、controller側でDBに接続し、contextに突っ込んで使い回すことにしました。（本当はミドルウェアを使う方が良さそうなので、後日修正すると思います...）
実装は、Context|GORM という記事を参考にしてます。

server.go（一部抜粋）

func (s *Server) GetComments(w http.ResponseWriter, r *http.Request) {
    ctx := context.WithValue(r.Context(), repositories.DbKey, repositories.GetDb())
    uComments, err := s.commentUsecase.FindAllComment(ctx)
    if err != nil {
        handleError(w, err)
        return
    }

    var comments []controllers.Comment
    for _, uComment := range uComments {
        comments = append(comments, controllers.FromUComment(uComment))
    }

    w.Header().Set("Content-Type", "application/json; charset=UTF-8")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(comments)
}

Repositoriesの実装

やとRepository本体を実装できます。。
contextからDB接続を取り出して、SelectやInsertを実行しています。

comment_repository.go

package repositories

import (
    "context"

    repositories "github.com/rinoguchi/microblog/adapters/repositories/models"
    "github.com/rinoguchi/microblog/entities"
    "github.com/uptrace/bun"
)

type CommentRepositoryImpl struct {
}

func NewCommentRepositoryImpl() entities.CommentRepository {
    return CommentRepositoryImpl{}
}

func (c CommentRepositoryImpl) Add(ctx context.Context, commentEntity entities.CommentEntity) (entities.CommentEntity, error) {
    dbComment := repositories.FromCommentEntity(commentEntity)
    db := ctx.Value(DbKey).(*bun.DB)
    _, err := db.NewInsert().Model(&dbComment).Exec(ctx)
    if err != nil {
        return entities.CommentEntity{}, err
    }
    return dbComment.ToCommentEntity(), nil
}

func (c CommentRepositoryImpl) FindAll(ctx context.Context) ([]entities.CommentEntity, error) {
    var dbComments []repositories.DbComment
    db := ctx.Value(DbKey).(*bun.DB)
    err := db.NewSelect().Model(&dbComments).Scan(ctx)
    if err != nil {
        return nil, err
    }

    commentEntities := make([]entities.CommentEntity, len(dbComments))
    for i, commentRecord := range dbComments {
        commentEntities[i] = commentRecord.ToCommentEntity()
    }
    return commentEntities, nil
}

動作確認

ここまででやっと一通り実装完了しましたので、動作確認したいと思います。

ローカル環境での動作確認

まずはアプリケーションを起動して

go run .
> main started
> starting server port:8080

curlでAPIを呼び出してみます。

# コメント追加
curl -X POST -H "Content-Type: application/json" -d '{"text" : "あいうえお"}' http://localhost:8080/comments
> {"created_at":"2022-08-13T17:44:44.616795+09:00","id":19,"text":"あいうえお","updated_at":"2022-08-13T17:44:44.616795+09:00"}

curl -X POST -H "Content-Type: application/json" -d '{"text" : "かきくけこ"}' http://localhost:8080/comments
> {"created_at":"2022-08-13T17:45:19.954428+09:00","id":20,"text":"かきくけこ","updated_at":"2022-08-13T17:45:19.954428+09:00"}

# コメント全件取得
curl http://localhost:8080/comments
> [{"created_at":"2022-08-13T17:44:44.616795+09:00","id":19,"text":"あいうえお","updated_at":"2022-08-13T17:44:44.616795+09:00"},{"created_at":"2022-08-13T17:45:19.954428+09:00","id":20,"text":"かきくけこ","updated_at":"2022-08-13T17:45:19.954428+09:00"}]

無事動いてくれました。

GAEでの動作確認

GAEにデプロイします。

gcloud app deploy
> Services to deploy:
> 
> descriptor:                  [/Users/xxx/workplace/microblog/app.yaml]
> source:                      [/Users/xxx/workplace/microblog]
> target project:              [microblog-999]
> target service:              [default]
> target version:              [20220813t999]
> target url:                  [https://xxx-xxx.xx.x.appspot.com]/
> target service account:      [App Engine default service account]
> 
> Do you want to continue (Y/n)?  Y
> 
> Beginning deployment of service [default]...
> 
> File upload done.
> Updating service [default]...done.
> Setting traffic split for service [default]...done.
> Deployed service [default] to [https://xxx-xxx.xx.x.appspot.com]/

次に、curlで同じようにAPIを呼び出してみました。

# コメント追加
curl -X POST -H "Content-Type: application/json" -d '{"text" : "さしすせそ"}' https://xxx-xxx.xx.x.appspot.com/comments
> {"created_at":"2022-08-13T17:54:26.284776+09:00","id":21,"text":"さしすせそ","updated_at":"2022-08-13T17:54:26.284776+09:00"}

# コメント全件取得
curl https://xxx-xxx.xx.x.appspot.com/comments
> [{"created_at":"2022-08-13T17:44:44.616795+09:00","id":19,"text":"あいうえお","updated_at":"2022-08-13T17:44:44.616795+09:00"},{"created_at":"2022-08-13T17:45:19.954428+09:00","id":20,"text":"かきくけこ","updated_at":"2022-08-13T17:45:19.954428+09:00"},{"created_at":"2022-08-13T17:54:26.284776+09:00","id":21,"text":"さしすせそ","updated_at":"2022-08-13T17:54:26.284776+09:00"}]

こちらも問題なく動いてくれました！
これにて今回の記事は終了にしようと思います。

最後に

今回マイクロブログのバックエンドAPIサーバを以下の技術を使ってクリーンアーキテクチャで作ってみました。

• Golang
• chi
• OpenAPI
• GAE
• PostgreSQL（supbase）

エラーハンドリング、validation、transaction管理、、などまだまだ課題がありそうですが、とりあえずはなんとかやっていけそうな感触を得られてよかったです。

なお、ソースコードは以下で公開しています。
https://github.com/rinoguchi/microblog

フロントエンド

React.jsやVue.jsなどで作っているWebアプリケーションの日時を変更したいです。

new Date() した際の日時を変更する mockdate というライブラリを使います。

まずは、ライプラリをインストールします。

npm install -D mockdate
# or
yarn add -D mockdate

あとは、main.tsなど、アプリを起動する処理の直前に以下を指定します。

import MockDate from "mockdate";
MockDate.set("2022-06-29 19:30:00"); // JSTで設定

これだけで、フロントエンドアプリ内の現在日時を変更することができます。

バックエンド

Dockerコンテナ上で実行しているバックエンドAPIサーバの現在日時を変更したいです。
libfaketime というライブラリを利用します。

まずはDockerfileにて、以下のような感じでインストール処理を記載します。

WORKDIR /tmp
RUN git clone https://github.com/wolfcw/libfaketime.git
WORKDIR /tmp/libfaketime/src
RUN sudo make install

あとは、Dockerコンテナ内の環境変数に以下を設定します。

LD_PRELOAD=/usr/local/lib/faketime/libfaketime.so.1
FAKETIME=2022-06-29 09:30:00 # UTCで指定

docker-composeを使うのであれば、docker-compose.ymlに以下のように設定すればOKです。

services:
  app:
    environment:
      - LD_PRELOAD=/usr/local/lib/faketime/libfaketime.so.1
      - FAKETIME=2022-06-29 09:30:00 # UTCで指定

今回は、バックエンドAPIサーバはPython+Djangoアプリでしたが、 datetimeを使って現在日時を取得する際に、上記の日時に置き換わってくれていました。

チュートリアルを自分が今作っているマイクロブログに当てはめただけです。

DI導入前

導入前は以下のように、自前でインスタンスを生成して引数として渡していました。

func InitializeServer() *controllers.Server {
    commentRepository := repositories.NewCommentRepositoryImpl()
    commentUsecase := usecases.NewCommentUsecase(commentRepository)
    server := controllers.NewServer(commentUsecase)
    return server
}

これはこれでシンプルなのですが、repositoryやusecaseが増えてくると大変そうです。
wireは上記のようなソースコードを自動生成してくれるツールです。

wireのインストール

go install github.com/google/wire/cmd/wire@latest

wire.goを記述

wireは、wire.goとそこで指定されているコンストラクタ関数から自動でDI用のコードを自動生成してくれます。
今回のケースでは、以下のようにwire.goを記述しました。
wire.Build()で各構造体のコンストラクタ関数を列挙しておくと、勝手にソースコードから関連性を把握してくれるようです。

//go:build wireinject
// +build wireinject

package main

import (
    "github.com/google/wire"
    "github.com/rinoguchi/microblog/adapters/controllers"
    "github.com/rinoguchi/microblog/adapters/repositories"
    "github.com/rinoguchi/microblog/usecases"
)

func InitializeServer() *controllers.Server {
    wire.Build(
        controllers.NewServer,
        usecases.NewCommentUsecase,
        repositories.NewCommentRepositoryImpl,
    )
    return &controllers.Server{}
}

DI用のコードを自動生成

以下のコマンドでDI用のコード（wire_gen.go）を自動生成します。

wire
> wire: github.com/rinoguchi/microblog: wrote /Users/xxx/xxx/microblog/wire_gen.go

トラブルシューティング

wireの設定や実装がおかしいとwire実行時にエラーが発生します。

• wire.Buildでコンストラクタ関数の指定が足らない場合

  wire
  > wire: /Users/xxx/xxx/microblog/wire.go:13:1: inject InitializeServer: no provider found for github.com/rinoguchi/microblog/entities.CommentRepository
  >  needed by *github.com/rinoguchi/microblog/usecases.CommentUsecase in provider "NewCommentUsecase" (/Users/ryoichiinoguchi/workplace/microblog/usecases/comment_usecase.go:13:6)
  >  needed by *github.com/rinoguchi/microblog/adapters/controllers.Server in provider "NewServer" (/Users/xxx/xxx/microblog/adapters/controllers/server.go:14:6)
  > wire: github.com/rinoguchi/microblog: generate failed
  > wire: at least one generate failure

wire_gen.goの内容

DI導入前に自前で実装していたコードと全く同じ内容が自動再生されていました。

// Code generated by Wire. DO NOT EDIT.

//go:generate go run github.com/google/wire/cmd/wire
//go:build !wireinject
// +build !wireinject

package main

import (
    "github.com/rinoguchi/microblog/adapters/controllers"
    "github.com/rinoguchi/microblog/adapters/repositories"
    "github.com/rinoguchi/microblog/usecases"
)

// Injectors from wire.go:

func InitializeServer() *controllers.Server {
    commentRepository := repositories.NewCommentRepositoryImpl()
    commentUsecase := usecases.NewCommentUsecase(commentRepository)
    server := controllers.NewServer(commentUsecase)
    return server
}

main.goから呼び出し

最後に、mian.goから対象のコードを呼び出せば完了です。

package main

import (
    "fmt"
    "net/http"
    "os"

    middleware "github.com/deepmap/oapi-codegen/pkg/chi-middleware"
    "github.com/go-chi/chi/v5"
    "github.com/rinoguchi/microblog/adapters/controllers"
)

func main() {
    swagger, err := controllers.GetSwagger()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error loading swagger spec\n: %s", err)
        os.Exit(1)
    }
    swagger.Servers = nil
    server := InitializeServer() // <==== この部分
    router := chi.NewRouter()
    router.Use(middleware.OapiRequestValidator(swagger))
    controllers.HandlerFromMux(server, router)
    http.ListenAndServe(":8080", router)
}

アプリケーションの実行

以下のようにしてアプリケーションを実行します。

go run .

main.goを指定すると、以下のようにwire.goの内容が読み込まれずにエラーが発生します。

go run main.go
# command-line-arguments
./main.go:20:12: undefined: InitializeServer

ビルドしてから実行するのもありです。

# ビルド（microblogという実行ファイルが作成される）
go build
# 実行
microblog

さいごに

今回、実装したソースコードは以下のリポジトリで公開してます。
https://github.com/rinoguchi/microblog

• oapi-codegen v1.11.0
• chi v5.0.7

APIスキーマ定義

まずはAPIスキーマをyaml定義します。

VS CodeでOpen API(Swagger) Editorという拡張を入れて編集すると便利です。

以下の二つのAPIの定義を書いてます。

• post /comments
  • コメントを新規作成する
• get /comments
  • コメントを全件取得する

api-schema.yamlというyamlファイルを作成しました。
難しい内容ではないので、説明は割愛します。

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Microblog
  description: API for mycroblog
  contact:
    name: rinoguchi
    email: xxx@xxx.com
    url: https://rinoguchi.net/
  license:
    name: MIT
    url: https://opensource.org/licenses/mit-license.php
servers:
  - url: http://localhost:8080/
paths:
  /comments:
    post:
      description: create a new comment
      operationId: addComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewComment"
      responses:
        "200":
          description: comment response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      description: get comments
      operationId: getComments
      responses:
        "200":
          description: comment response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    CommonProperties:
      type: object
      properties:
        id:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    NewComment:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          maxLength: 100

    Comment:
      allOf:
        - $ref: "#/components/schemas/NewComment"
        - $ref: "#/components/schemas/CommonProperties"

    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string

モジュールのインストール

必要なモジュールをインストールします。

go get github.com/go-chi/chi/v5
go get github.com/deepmap/oapi-codegen/cmd/oapi-codegen

コード自動生成

次に、作成したスキーマ定義からコードを自動生成したいと思います。

• models
  • request / response の入れ物
• embedded-spec
  • yamlをgzipしてblob化したもの。validationなどに使われる
• chi-server
  • chi 用のハンドラーのインターフェース

model

まずは、モデルを自動生成します。
oapi-codegen v1.11からコード生成のオプションの指定方法がconfigファイルで設定するように変わったようなので、models.config.yamlというファイルを作成しました。

package: usecases
generate:
  models: true
output: usecases/models.gen.go
output-options:
  skip-prune: true

usecasesというパッケージ配下に、models.gen.goが生成される設定にしてます。
（今回クリーンアーキテクチャを採用しています。APIの request/response に対応するモデルは本来adapters層に出力した方が綺麗だと思うのですが、シンプルなAPIサーバでusecasesの input/output がAPIの request/response と完全一致するため、usecasesに直接出力することにしています。）

以下のコマンドで自動生成を実行できます。

oapi-codegen -config models.config.yaml schema.yaml

シンプルなモデルとスペック情報を扱うコードが生成されました。
api-schema.yamlのコンポーネント一つ一つがそれぞれモデルとして出力されていることが分かります。
また、maxLength: 100のようなvalidation定義は出力されません。その部分は、embedded-schemaとして別途出力する必要があります。

// Package usecases provides primitives to interact with the openapi HTTP API.
//
// Code generated by github.com/deepmap/oapi-codegen version v1.11.0 DO NOT EDIT.
package usecases

import (
    "time"
)

// Comment defines model for Comment.
type Comment struct {
    CreatedAt *time.Time `json:"created_at,omitempty"`
    Id        *int64     `json:"id,omitempty"`
    Text      string     `json:"text"`
    UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

// CommonProperties defines model for CommonProperties.
type CommonProperties struct {
    CreatedAt *time.Time `json:"created_at,omitempty"`
    Id        *int64     `json:"id,omitempty"`
    UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

// Error defines model for Error.
type Error struct {
    Message string `json:"message"`
}

// NewComment defines model for NewComment.
type NewComment struct {
    Text string `json:"text"`
}

// AddCommentJSONBody defines parameters for AddComment.
type AddCommentJSONBody = NewComment

// AddCommentJSONRequestBody defines body for AddComment for application/json ContentType.
type AddCommentJSONRequestBody = AddCommentJSONBody

chi-server & embedded-spec

同じように chi 用の各APIのハンドラーのインターフェースを出力します。configファイルとしてchi-server.config.yamlを作成しました。
　このタイミングで、embedded-specも合わせて出力する設定にしてあります。

package: adapters
generate:
  chi-server: true
  embedded-spec: true
output: adapters/server.gen.go
output-options:
  skip-prune: true

以下のコマンドで自動生成できます。

oapi-codegen -config chi-server.config.yaml schema.yaml

以下のようなコードが出力されました。
全部で278行もあったので、一部省略してあります。

package adapters

// ServerInterface represents all server handlers.
type ServerInterface interface {

    // (GET /comments)
    GetComments(w http.ResponseWriter, r *http.Request)

    // (POST /comments)
    AddComment(w http.ResponseWriter, r *http.Request)
}

// ServerInterfaceWrapper converts contexts to parameters.
type ServerInterfaceWrapper struct {
    Handler            ServerInterface
    HandlerMiddlewares []MiddlewareFunc
    ErrorHandlerFunc   func(w http.ResponseWriter, r *http.Request, err error)
}

type MiddlewareFunc func(http.HandlerFunc) http.HandlerFunc

// GetComments operation middleware
func (siw *ServerInterfaceWrapper) GetComments(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    var handler = func(w http.ResponseWriter, r *http.Request) {
        siw.Handler.GetComments(w, r)
    }

    for _, middleware := range siw.HandlerMiddlewares {
        handler = middleware(handler)
    }

    handler(w, r.WithContext(ctx))
}

// Handler creates http.Handler with routing matching OpenAPI spec.
func Handler(si ServerInterface) http.Handler {
    return HandlerWithOptions(si, ChiServerOptions{})
}

type ChiServerOptions struct {
    BaseURL          string
    BaseRouter       chi.Router
    Middlewares      []MiddlewareFunc
    ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
}

// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.
func HandlerFromMux(si ServerInterface, r chi.Router) http.Handler {
    return HandlerWithOptions(si, ChiServerOptions{
        BaseRouter: r,
    })
}

// HandlerWithOptions creates http.Handler with additional options
func HandlerWithOptions(si ServerInterface, options ChiServerOptions) http.Handler {
    r := options.BaseRouter

    if r == nil {
        r = chi.NewRouter()
    }
    if options.ErrorHandlerFunc == nil {
        options.ErrorHandlerFunc = func(w http.ResponseWriter, r *http.Request, err error) {
            http.Error(w, err.Error(), http.StatusBadRequest)
        }
    }
    wrapper := ServerInterfaceWrapper{
        Handler:            si,
        HandlerMiddlewares: options.Middlewares,
        ErrorHandlerFunc:   options.ErrorHandlerFunc,
    }

    r.Group(func(r chi.Router) {
        r.Get(options.BaseURL+"/comments", wrapper.GetComments)
    })
    r.Group(func(r chi.Router) {
        r.Post(options.BaseURL+"/comments", wrapper.AddComment)
    })

    return r
}

// Base64 encoded, gzipped, json marshaled Swagger object
var swaggerSpec = []string{

    "H4sIAAAAAAAC/+RVTW/UMBD9K9HAMd2kgKD1iVIhVImPHuBUVch1ZhNXsceMJ7TVKv8d2bvZ7SorKqTe",
    "uE1m3rwZP+clKzDkAnn0xEkGxxxxxxxHXlKo+/7bEtTVCl4yLkHBi2rXVm16qq94xxN/WM5d+hCUf+",
    "kikgi8UI4/VYwiyrVxhD2ngyjFmx+6rzWktilCBoteCTWIZQxxxxxxxxxxxxNvsYa2xXt292OOsFW+QE",
    "HELzj+TjNkM3t2jSueEjM/F8c4cx6hZTOCdh/Dxxxxxxxxxxxxv0/Wf0rXSgjuu6xxxxxxxxxxxxfGJa",
    "7pqPSjDrl5Q1Jy/xaZG502vZZNGqH49N3p+/blxxxxxxxxxxxxxxxyd4JxKiqqpxxxtZeExn6fBaNgG",
    "seRBwssssxxxSemvQxyzbhv7LxfcZMQXx0kQxxxyVo83xxxxDInQhjRQrfaaxxxxxxxxxuyG/",
    "keN6heNFxvagTLDHqYExxxHB65wqIWjpstDpfXaTxxxfpExUptqDMxTqVLhpQ8AnlfFdjjIHSronlVV1P",
    "gk/GC6xG3JjdXtzGRTxZNxxzpvVium2eubWOqhl2cbv3bBgeGDx/uARrApcIcJFA/ouHZ7oQuP",
    "d5OgMz3PmuZ8xW0qvNkb5QM3Dsx3l8Wdt3z7CA47/4R3+OHCHCRWRk5Xyj2JnxxxxxxQndfrY",
    "/wkAAP//Hzjw+XgGxxxAAA=",
}

// GetSwagger returns the content of the embedded swagger specification file
// or error if failed to decode
func decodeSpec() ([]byte, error) {
    zipped, err := base64.StdEncoding.DecodeString(strings.Join(swaggerSpec, ""))
    if err != nil {
        return nil, fmt.Errorf("error base64 decoding spec: %s", err)
    }
    zr, err := gzip.NewReader(bytes.NewReader(zipped))
    if err != nil {
        return nil, fmt.Errorf("error decompressing spec: %s", err)
    }
    var buf bytes.Buffer
    _, err = buf.ReadFrom(zr)
    if err != nil {
        return nil, fmt.Errorf("error decompressing spec: %s", err)
    }

    return buf.Bytes(), nil
}

var rawSpec = decodeSpecCached()

// a naive cached of a decoded swagger spec
func decodeSpecCached() func() ([]byte, error) {
    data, err := decodeSpec()
    return func() ([]byte, error) {
        return data, err
    }
}

// Constructs a synthetic filesystem for resolving external references when loading openapi specifications.
func PathToRawSpec(pathToFile string) map[string]func() ([]byte, error) {
    var res = make(map[string]func() ([]byte, error))
    if len(pathToFile) > 0 {
        res[pathToFile] = rawSpec
    }

    return res
}

// GetSwagger returns the Swagger specification corresponding to the generated code
// in this file. The external references of Swagger specification are resolved.
// The logic of resolving external references is tightly connected to "import-mapping" feature.
// Externally referenced files must be embedded in the corresponding golang packages.
// Urls can be supported but this task was out of the scope.
func GetSwagger() (swagger *openapi3.T, err error) {
    var resolvePath = PathToRawSpec("")

    loader := openapi3.NewLoader()
    loader.IsExternalRefsAllowed = true
    loader.ReadFromURIFunc = func(loader *openapi3.Loader, url *url.URL) ([]byte, error) {
        var pathToFile = url.String()
        pathToFile = path.Clean(pathToFile)
        getSpec, ok := resolvePath[pathToFile]
        if !ok {
            err1 := fmt.Errorf("path not found: %s", pathToFile)
            return nil, err1
        }
        return getSpec()
    }
    var specData []byte
    specData, err = rawSpec()
    if err != nil {
        return
    }
    swagger, err = loader.LoadFromData(specData)
    if err != nil {
        return
    }
    return
}

少しだけ解説しておきます。

• ServerInterfaceが各APIのハンドラーに対応するインターフェースです。このインターフェースを実装して、実際の処理を行う必要があります
• swaggerSpecがAPIスキーマ定義のyamlをencodeしたもので、これをdecodeしてvalidationなどの処理が行われます

ServerInterfaceを実装

次に、自動生成されたServerInterfaceインターフェースを実装していきます。
こちら を参考にしながら、以下のserver.goを実装しました。
対象のハンドラーが呼ばれたら、ダミーレスポンスを返すだけのシンプルな作りです。

package adapters

import (
    "encoding/json"
    "net/http"
    "time"

    "github.com/rinoguchi/microblog/usecases"
)

type Server struct{}

func (s *Server) GetComments(w http.ResponseWriter, r *http.Request) {
    // TODO: get comments from DB via repository
    comments := []*usecases.Comment{newDummyComment()}
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(comments)
}

func (s *Server) AddComment(w http.ResponseWriter, r *http.Request) {
    // TODO: add comment to DB via repository
    comment := newDummyComment()
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(comment)
}

func NewServer() *Server {
    return &Server{}
}

func newDummyComment() *usecases.Comment {
    id := int64(123)
    now := time.Now()
    return &usecases.Comment{
        Id:        &id,
        Text:      "Dummy Text",
        CreatedAt: &now,
        UpdatedAt: &now,
    }
}

main.goを実装

最後に、こちら を参考にmain.goを実装しました。
詳細はコメントを参照ください。

package main

import (
    "fmt"
    "net/http"
    "os"

    middleware "github.com/deepmap/oapi-codegen/pkg/chi-middleware"
    "github.com/go-chi/chi/v5"
    "github.com/rinoguchi/microblog/adapters"
)

func main() {
    swagger, err := adapters.GetSwagger() // APIスキーマ定義を取得
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error loading swagger spec\n: %s", err)
        os.Exit(1)
    }
    swagger.Servers = nil
    server := adapters.NewServer()
    router := chi.NewRouter()
    router.Use(middleware.OapiRequestValidator(swagger)) // validationを設定
    adapters.HandlerFromMux(server, router)              // chiのrouterと実装したserverを紐付け
    http.ListenAndServe(":8080", router)                 // 8080ポートをリッスン
}

動作確認

以下でAPIサーバを起動して、

go run main.go

curlで動作確認したところ、無事想定通り動きました。

# コメント一覧取得
curl http://localhost:8080/comments
> [{"created_at":"2022-06-12T22:25:53.946313+09:00","id":123,"text":"Dummy Text","updated_at":"2022-06-12T22:25:53.946313+09:00"}]

# コメント追加（正常系）
curl -X POST -H "Content-Type: application/json" -d '{"text": "dummy"}' http://localhost:8080/comments
> {"created_at":"2022-06-12T22:27:01.471484+09:00","id":123,"text":"Dummy Text","updated_at":"2022-06-12T22:27:01.471484+09:00"}

# コメント追加（異常系：必須項目なし）
curl -X POST -H "Content-Type: application/json" -d '{}' http://localhost:8080/comments
> request body has an error: doesn't match the schema: Error at "/text": property "text" is missing

# コメント追加（異常系：101文字以上）
curl -X POST -H "Content-Type: application/json" -d '{"text": "xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1xxxxxxxxx1x"}' http://localhost:8080/comments
> request body has an error: doesn't match the schema: Error at "/text": maximum string length is 100

最後に

oapi-codegenでchi用APIインターフェースを自動生成しましたが、比較的少ない実装でやりたいことが実現できることを確認しました。
この後、フロントエンド側の実装の時には同じapi-schema.yamlからTypeScriptのモデルを自動生成することもできると思いますので、その点も良さそうです。

今回検証しなかったのですが、実運用ではエラー発生時にjson形式でカスタマイズしたエラーメッセージを返す必要があると思うので、その点も別途調査したいと思います。

外部キーが貼れなかったエラー

今回、新しくテーブルを作って、既存テーブルに対して外部キーを貼ろうとしたところ、エラーが発生してダメでした。

エラーログ

エラーログは以下の通りでした。情報が全く足りません。。。

ERROR 1215 (HY000): Cannot add foreign key constraint

そのような場合は、以下のSQLを実行することでエラーの詳細を見ることができます。

show engine innodb status;

今回は、以下のログが出力されていました。

2022-05-18 10:27:06 xxx Error in foreign key constraint of table caisuke/#sql-1_2d8:
FOREIGN KEY
    xxx (hoge_id)
    REFERENCES hoge (id):
Cannot find an index in the referenced table where the
referenced columns appear as the first columns, or column types
in the table and the referenced table do not match for constraint.
Note that the internal storage type of ENUM and SET changed in
tables created with >= InnoDB-4.1.12, and such columns in old tables
cannot be referenced by such columns in new tables.
Please refer to http://dev.mysql.com/doc/refman/5.7/en/innodb-foreign-key-constraints.html for correct foreign key definition.

英語が難しくてよくわからないのですが、

• 参照先のカラムのインデックスが見つからない
• 参照先のカラムの型が制約に使えない型である

みたいな感じのことが書いてあります。
しかし、今回は参照先のカラムは PK で、UUIDなので型もchar(32)なので問題なさそうです。

原因

ログからはわからなかったのですが、参照元と参照先のテーブルのテーブル定義を調べてみると、charsetが異なっており、これが原因でした。

> -- 参照先テーブル
> show create table hoge;

CREATE TABLE `hoge` (
  `id` char(32) NOT NULL,
  ...
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC

>  -- 参照元テーブル
> show create table fuga;

CREATE TABLE `fuga` (
  `id` char(32) NOT NULL,
  `hoge_id` char(32) NOT NULL,
  ...
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 ROW_FORMAT=DYNAMIC

このようなことは通常発生しないと思いますが、今回のケースでは、create table時にcharsetは特に設定していません。

ということは、データベースのcharacter_set_databaseの設定に従ってテーブルのcharsetが決定されるはずです。（参照）

よくよく考えてみると、

• 参照先テーブル（hoge）は、stagingのDBをダンプしてlocalのDBにインポートしたもの
• 参照元テーブル(fuga)は、localのDBで今回新しく作成したもの

のように、由来が違うものでした。

なので、各環境のDBの'character_set_database'の設定を確認すると、ビンゴ、やはりutf8とutf8mb4で設定が異なっていました。

-- staging
show variables like 'character_set_database';

Variable_name   Value
character_set_database  utf8mb4

-- local
show variables like 'character_set_database';

Variable_name   Value
character_set_database  utf8

対応

MySQLでは、utf8は4バイト文字には対応しておらず、4バイト文字を格納するには、MySQL 5.5で導入されたutf8mb4を利用する必要があります。なので、今回はutf8mb4に統一することにしました。

具体的には、my.cnfを以下のように修正することにしました。

[mysqld]
- character-set-server = utf8
+ character-set-server = utf8mb4

その上で、テーブルを再作成して、外部キーを貼ってみると問題なく外部キーを貼ることができました。

MySQLのcharset設定

エラー対応のために、ドキュメントを読んでると、なんとなくcharsetの設定内容がわかってきました。

どうやら、大きく2種類のcharsetの設定があるようです。

• サーバサイドのcharset
• クライアントから接続時のcharset

現在の設定は、以下のSQLで確認できます。

show variables like '%character%';

サーバサイドのcharset

サーバサイドの設定は以下の通りになっています。

設定はmy.cnfにて以下のように行います。

[mysqld]
character-set-server = utf8 # server, database, systemの設定に反映される
character-set-filesystem = utf8

クライアントから接続時のcharset

接続時のcharsetに関しては こちら に記載があります。
クライアントの設定は以下の通りになっています。

設定はmy.cnfにて以下のように行います。

[client]
default-character-set = utf8 # client, connection, resultsの設定に反映される

ちなみに、接続時の設定はclient側のアプリケーションやソフトにて設定されます。

MySQLのgeneral_logをみていると、自分が使っているDBクライアントで接続した場合に、以下のSQLが実行されていました。

set names = 'utf8mb4';

これによって、上記の3つの接続時のcharsetが変更されていました。

こんな感じで動作します。

ソースコードはこちらで公開しています。
https://github.com/rinoguchi/asana_highlighter

動機

現在所属している会社ではチケット管理にAsanaを利用しているのですが、Asanaにはコードブロックをハイライトする機能がありません。

機能開発やテックサポートなどをしていると、ソースコードをAsana上に保存しておきたいケースはそれなりにあり、ソースコードが良い感じにハイライトされてないと頭に入ってきません。とても嫌な感じです。

Asana上でもリクエストがあがってるのですが、年単位で放置されており、すぐに対応されることはなさそうです。。

• https://forum.asana.com/t/code-snippets-in-asana/2182/167
• https://forum.asana.com/t/highlight-text-and-code-section-in-task-description/10040

幸い私は過去にChrome拡張を作って公開したこともありますし、完璧を求めなければそんなに難しい内容でもないので、作ってみることにしました。

コードブロックのハイライト処理

ハイライト処理自体は、highlight.jsで行なっています。
ページ内のコメント欄をquerySelectorAllで取得して、コードブロック（```で囲んだ部分）を置き換えるだけです。

実装上の注意点は、コメントでコード中に記載したので、そちらを確認ください。

import hljs from "highlight.js";
import "highlight.js/styles/hybrid.css"; // 必要なcssを読み込み。css-loader+style-loaderで最終的に<style>タグとしてDOMに追加される

function render() {
  // コメントリストを取得
  const comments: NodeListOf<Element> = document.querySelectorAll(".RichText");
  comments.forEach((c) => {
    // 装飾のために挿入されているHTMLタグやHTML特殊文字がそのまま表示されないように置換
    const newInnerHTML = c.innerHTML.replace(
      /```(.*?)<br>(.*?)```/g,
      (_all: string, lang: string | undefined, src: string) => {
        const fixedSrc = src
          .replace(/<br>/g, "\n")
          .replace(/<code>|<\/code>/g, "")
          .replace(/<strong>|<\/strong>/g, "")
          .replace(/</g, "<")
          .replace(/>/g, ">")
          .replace(/"/g, '"')
          .replace(/&/g, "&")
          .replace(/ /g, " ");

        let highlightedSrc;
        if (!lang) {
          // 言語が指定されてない場合は自動ハイライト
          highlightedSrc = hljs.highlightAuto(fixedSrc).value;
        } else {
          // サポートされている言語の場合は言語指定でハイライト
          const fixedLang = lang.toLowerCase().trim();
          if (hljs.listLanguages().includes(fixedLang)) {
            highlightedSrc = hljs.highlight(fixedSrc, {
              language: lang.toLowerCase().trim(),
            }).value;
          } else {
            // サポートされてない言語の場合は自動ハイライト
            highlightedSrc = hljs.highlightAuto(fixedSrc).value;
          }
        }
        // highlight.jsのスタイルに合わせてタグを追加
        return `<pre><code class="hljs">${highlightedSrc}</code></pre>`;
      }
    );
    // 変更がある場合は上記の内容でHTMLを置き換え
    if (newInnerHTML !== c.innerHTML) {
      c.innerHTML = newInnerHTML;
    }
  });
}

setInterval(render, 1000);　// 1秒に1回上記の描画処理を実行

• HTMLタグやHTML特殊文字に関しては、他にもいろんなパターンがありそうなので、変なタグが表示されるケースもありそうです
• Description欄は入力途中の制御が難しかったので対応はやめておきました

Chrome拡張としての設定

manifest.json

Chrome拡張として利用するためには、manifest.jsonが必要になります。
今回は、特定のURLの場合に上で作ったスクリプトを実行するだけなので、以下のようにとてもシンプルです。

{
  "name": "asana highlighter",
  "description": "highlight the source code block on Asana pages",
  "version": "1.0.0",
  "manifest_version": 3,
  "icons": {
    "48": "icons/icon_48.png",
    "128": "icons/icon_128.png"
  },
  "content_scripts": [
    {
      "matches": ["https://app.asana.com/*"],
      "js": ["highlighter.js"]
    }
  ]
}

• 公式ページにも以下のように書いてあるように、manifest_versionは、3を設定する必要があります
  

  As of January 17, 2022 Chrome Web Store has stopped accepting new Manifest V2 extensions. We strongly recommend that new extensions target Manifest V3.

• ストアで公開するために、iconsも設定してあります
• content_scriptsは、対象のWebページのコンテキストでスクリプトを実行する際に利用する機能です。AsanaのURLの場合に、highlight.jsを実行する設定にしてあります。

webpack設定

Chrome拡張としてブラウザに登録するためには、manifest.jsonとそこで参照しているファイル群を一つのフォルダにまとめる必要がありますので、webpackでバンドルしました。
今回のケースでは、以下のようなフォルダ構成を出力します。

dist
├── highlighter.js
├── icons
│   ├── icon_128.png
│   └── icon_48.png
└── manifest.json

• highlight.jsは、highlight.tsを元にwebpackでトランスパイル＋バンドルしたものです
• iconsとmanifest.jsonはsrcフォルダ配下のものを単純にコピーするだけです

webpack.config.jsは以下のようになりました。ポイントはコメントで記載してます。

const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  mode: "development",
  context: __dirname + "/src",
  devtool: "source-map", // NOTE: バンドル後のJSでevalを使わない。manifest V3ではevalは許可されていない。「Uncaught EvalError: Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'".」回避
  entry: {
    highlighter: "./highlighter.ts",
  },
  output: {
    path: __dirname + "/dist",
    filename: "[name].js",
  },
  resolve: {
    extensions: [".ts", ".js", ".css"],
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader", // 読み込んだスタイルを<style>タグとしてhtmlに出力
          "css-loader", // .cssファイルをJSで文字列として読み込む。末尾から実行される
        ],
      },
      {
        test: /\.ts$/,
        loader: "ts-loader",
      },
      {
        test: /\.js$/,
        loader: "babel-loader",
        exclude: /node_modules/,
      },
    ],
  },
  plugins: [
    // iconsとmanifest.jsonを単純にコピー
    new CopyPlugin({
      patterns: [
        { from: "icons", to: "icons" },
        {
          from: "manifest.json",
          to: "manifest.json",
        },
      ],
    }),
  ],
  externals: {},
};

webpackを実行すると、無事distフォルダに必要なファイルが出力されました。

$ webpack

assets by path icons/*.png 6.81 KiB
  asset icons/icon_128.png 5 KiB [compared for emit] [from: icons/icon_128.png] [copied]
  asset icons/icon_48.png 1.81 KiB [compared for emit] [from: icons/icon_48.png] [copied]
asset highlighter.js 1.53 MiB [compared for emit] (name: highlighter) 1 related asset
asset manifest.json 346 bytes [emitted] [from: manifest.json] [copied]
runtime modules 937 bytes 4 modules
modules by path ../node_modules/highlight.js/lib/languages/*.js 1.35 MiB 192 modules
modules by path ../node_modules/style-loader/dist/runtime/*.js 5.75 KiB 6 modules
modules by path ../node_modules/highlight.js/styles/*.css 3.6 KiB
  ../node_modules/highlight.js/styles/hybrid.css 1.04 KiB [built] [code generated]
  ../node_modules/css-loader/dist/cjs.js!../node_modules/highlight.js/styles/hybrid.css 2.56 KiB [built] [code generated]
modules by path ../node_modules/highlight.js/lib/*.js 85.4 KiB
  ../node_modules/highlight.js/lib/index.js 12 KiB [built] [code generated]
  ../node_modules/highlight.js/lib/core.js 73.4 KiB [built] [code generated]
modules by path ../node_modules/css-loader/dist/runtime/*.js 2.94 KiB
  ../node_modules/css-loader/dist/runtime/sourceMaps.js 688 bytes [built] [code generated]
  ../node_modules/css-loader/dist/runtime/api.js 2.26 KiB [built] [code generated]
./highlighter.ts 1.29 KiB [built] [code generated]
../node_modules/highlight.js/es/index.js 203 bytes [built] [code generated]
webpack 5.72.0 compiled successfully in 2994 ms

$ tree dist

dist
├── highlighter.js
├── highlighter.js.map
├── icons
│   ├── icon_128.png
│   └── icon_48.png
└── manifest.json

試しに実行

必要なファイル群ができたので、Chrome拡張として登録してみます。

• Chrome拡張機能画面を開く
  • chrome://extensions/
• デベロッパーモードを ON
• パッケージ化されてない拡張機能を読み込むをクリック
• 先ほど作成したdistフォルダを指定

これで、URLがhttps://app.asana.com/*にマッチするページを開くと今回作ったhighlight.jsが実行されて、コードブロックがハイライトされるはずです。

実際に、Asanaのチケットを表示してみたところ、以下のようにうまくコードブロックがはハイライトされました^^

Storeに申請

昔ブログを書いてたので、それを見ながら申請しました。
iconとか画像が必要なぐらいで、特に難しいことはないと思います。

https://rinoguchi.net/2020/10/publish-chrome-extension.html

申請したら、翌日には公開されていました。

最後に

AsanaのコードブロックをハイライトするChrome拡張を作って公開しました。
本家で対応してくれるまでの間に合せとしては十分かな、と思ってます。
不具合を見つけたらプルリクをいただくか、ISSUEを登録いただけると助かります。

ソースコードを一見して正直どこで何が行われているのか全くわからなかったので、チュートリアルを見ながら簡単なAPIを作成し、その後、DRFを使ってAPIを作り直してみて、勉強しようと思います。

Python: 3.10.2
Django: 4.0.3
DRF: 3.13.1

作成したソースコードは以下で公開しています。
https://github.com/rinoguchi/django_rest_framework

Djangoで投票アプリ構築

まずは、DRFは利用せず素のDjangoのみで、チュートリアルに従って投票（polls）アプリを作ってみたいと思います。

環境構築

poetryを使って環境構築しました。
pythonの仮想環境を作って、djangoをインストールするところまで、やってみました。

#  pythonのバージョンを最新に
pyenv install pyenv
pyenv local 3.10.2

# poetryをインストール
pip install poetry
echo "export PATH=~/.poetry/bin:$PATH" > ~/.bash_profile

# poetry初期化 -> pyproject.tomlが作成される
poetry init

# djangoの依存関係を追加
poetry add django

# pythonのREPLをpoetry経由で起動
poetry run python
> Python 3.10.2 (main, Mar  1 2022, 11:29:47) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin
> Type "help", "copyright", "credits" or "license" for more information.

# djangoのバージョン確認
>>> import django
>>> print(django.get_version())
> 4.0.3

Djangoプロジェクト作成

django-adminコマンドを使って、プロジェクトを作成します。

poetry run django-admin startproject apps # poetryを利用しない場合は、`poetry run`は不要

自動生成されたフォルダおよびファイルは以下の通りです。

.
└── apps
    ├── manage.py
    └── apps
        ├── asgi.py
        ├── settings.py
        ├── urls.py
        └── wsgi.py

• manage.py
  • とても重要なファイル。アプリケーションを操作する様々なコマンドを提供している
• settings.py
  • アプリケーションの設定ファイル
  • 設定内容はこちらを参照
• urls.py
  • ルーティング定義
• wsgi.py
  • WSGIとはWeb Server Gateway Interfaceの略で、PythonでWebサーバとアプリケーション間の標準化インタフェースのことらしい
  • このファイルは、プロジェクトを提供するWSGI互換Webサーバのエントリポイント
• asgi.py
  • ASGIは、Asynchronous Server Gateway Interfaceの略で、WSGIの後継者で、非同期対応のWebサーバとアプリケーション間の標準インターフェイスのことらしい
  • このファイルは、プロジェクトを提供するASGI互換Web サーバのエントリポイント

サーバの起動

poetry run python manage.py runserver # poetryを利用しない場合は、`poetry run`は不要

https://rinoguchi.net/ にアクセスして、「The install worked successfully! Congratulations!」と表示されたので、ここまでは問題なくできたようです。

投票アプリの雛形作成

Djangoではプロジェクトの下に複数のアプリケーションを追加することができます。こちらもmanager.pyを使ってアプリの雛形を作成します。

poetry run python manage.py startapp polls # poetryを利用しない場合は、`poetry run`は不要

先程のappsフォルダの隣にpollsフォルダが作成されました。

├── apps
│   ├── apps
│   └── polls
│       ├── admin.py
│       ├── apps.py
│       ├── migrations
│       ├── models.py
│       ├── tests.py
│       └── views.py
├── poetry.lock
└── pyproject.toml

ビュー作成

views.pyを書き換えます。
「polls index」というレスポンスを返すだけの関数を定義しています。

from django.http import HttpResponse

def index(request):
    return HttpResponse("polls index")

ルーティング定義

まず、polls/urls.pyを作成します。
直下のURLに対してindexという関数をマッピングしているのがわかります。

from django.urls import path

from . import views

urlpatterns = [
    path('', views.index, name='index'),
]

次に、apps/urls.pyにpolls/urls.pyへの参照を定義します。
polls/というURLに対して、polls/urlsをマッピングしているのがわかります。

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('polls/', include('polls.urls')), # <--追加
    path('admin/', admin.site.urls),
]

curlコマンドで、今回作成したURLにアクセスしてみると、無事、実装した文字列が返ってきました。

curl https://rinoguchi.net/polls/
> polls index

データベースの準備

MySQL立ち上げ

docker-composeでMySQLを立ち上げます。

まず、docker-compose.yml記載します。

version: '3'

services:
  db:
    image: mysql:latest
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: polls
      MYSQL_USER: polls_user
      MYSQL_PASSWORD: polls_password
      TZ: 'Asia/Tokyo'
    command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    volumes:
    - ./docker/db/data:/var/lib/mysql
    - ./docker/db/my.cnf:/etc/mysql/conf.d/my.cnf
    - ./docker/db/sql:/docker-entrypoint-initdb.d
    ports:
    - 3306:3306

次に、以下のコマンドで立ち上げます。

docker-compose up　-d

試しに、msqlコマンドでアクセスしてみると、無事にログインできました。

mysql -h 127.0.0.1 -u polls_user -p polls

> Enter password: 
> Welcome to the MariaDB monitor.  Commands end with ; or \g.
> Your MySQL connection id is 10
> Server version: 8.0.28 MySQL Community Server - GPL
> 
> Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
> 
> Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
> 
> MySQL [polls]>

設定

Webアプリが立ち上げたデータベースにアクセスするには、データベースを伝えてあげる必要があります。
apps/apps/settings.pyにMySQLのpollsデータベースにアクセスするための情報を記載します。

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'polls',
        'USER': 'polls_user',
        'PASSWORD': 'polls_password',
        'HOST': '127.0.0.1',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
        }
    }
}

本来、環境変数から取得すると思いますが、今回はお試しなのでベタ書きです。

また、MySQLを利用するので、MySQLのクライアントライブラリをインストールします。

poetry add mysqlclient

Djangoのプロジェクトは、以下のようにデフォルトで色々と機能が提供されており、データベースを利用するようになっています。

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

マイグレーション実行

今回、データベースをSQLiteからMySQLに変更したので、DBマイグレーションを行う必要があります。

poetry run python manage.py migrate # poetryを利用しない場合は、`poetry run`は不要

> Operations to perform:
>   Apply all migrations: admin, auth, contenttypes, sessions
> Running migrations:
>   Applying contenttypes.0001_initial... OK
>   Applying auth.0001_initial... OK
>   Applying admin.0001_initial... OK
>   Applying admin.0002_logentry_remove_auto_add... OK
>   Applying admin.0003_logentry_add_action_flag_choices... OK
>   Applying contenttypes.0002_remove_content_type_name... OK
>   Applying auth.0002_alter_permission_name_max_length... OK
>   Applying auth.0003_alter_user_email_max_length... OK
>   Applying auth.0004_alter_user_username_opts... OK
>   Applying auth.0005_alter_user_last_login_null... OK
>   Applying auth.0006_require_contenttypes_0002... OK
>   Applying auth.0007_alter_validators_add_error_messages... OK
>   Applying auth.0008_alter_user_username_max_length... OK
>   Applying auth.0009_alter_user_last_name_max_length... OK
>   Applying auth.0010_alter_group_name_max_length... OK
>   Applying auth.0011_update_proxy_permissions... OK
>   Applying auth.0012_alter_user_first_name_max_length... OK
>   Applying sessions.0001_initial... OK

mysqlコマンドで確認するといくつかテーブルが作成されることが確認できました。

MySQL [polls]> show tables;

> +----------------------------+
> | Tables_in_polls            |
> +----------------------------+
> | auth_group                 |
> | auth_group_permissions     |
> | auth_permission            |
> | auth_user                  |
> | auth_user_groups           |
> | auth_user_user_permissions |
> | django_admin_log           |
> | django_content_type        |
> | django_migrations          |
> | django_session             |
> +----------------------------+
> 10 rows in set (0.005 sec)

テーブル（モデル）作成

モデル作成

モデルとは、データベースのレイアウトとそれに付随するメタデータを表現するものです。
クラスがテーブル、フィールドがカラムを表しています。

from django.db import models

class Question(models.Model):
    question_text = models.CharField(max_length=200)
    publish_date = models.DateTimeField("date published")

class Choice(models.Model):
    question = models.ForeignKey(Question, on_delete=models.CASCADE, related_name="choices")
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)

• 今回は、Question（質問）とChoice（選択肢）の二つのモデル（テーブル）を定義しています
• Choiceのquestionが、外部キー制約でQuestion（のid）を参照しています
• 合わせて、related_nameでQuestionモデル側にchoicesプロパティが擬似的に存在するようにしてあります
  • これにより、Question.choicesのようなイメージで、親側からone-to-manyのプロパティにアクセスできるようになります

設定

モデルを定義してマイグレーションを行うことでDDLが実行されますが、そのためにはpollsアプリケーションをプロジェクトに追加する必要があります。
具体的には、apps/apps/settings.pyのINSTALLED_APPSにpollsの定義を追加します。

INSTALLED_APPS = [
    'polls.apps.PollsConfig',
    # ...省略...
]

マイグレーション実行

以下のコマンドでマイグレーションファイルを作成します。

poetry run python manage.py makemigrations polls # poetryを利用しない場合は、`poetry run`は不要
> Migrations for 'polls':
>  polls/migrations/0001_initial.py
>    - Create model Question
>    - Create model Choice

ログの通り、apps/polls/migrations/0001_initial.pyというファイルが作成されています。
中身は以下の通りです。
Djangoではマイグレーション内容は、SQLではなくpythonのプログラムとして表現するようです。

# Generated by Django 4.0.3 on 2022-03-20 06:19

from django.db import migrations, models
import django.db.models.deletion

class Migration(migrations.Migration):

    initial = True

    dependencies = [
    ]

    operations = [
        migrations.CreateModel(
            name='Question',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('question_text', models.CharField(max_length=200)),
                ('pub_date', models.DateTimeField(verbose_name='date published')),
            ],
        ),
        migrations.CreateModel(
            name='Choice',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('choice_text', models.CharField(max_length=200)),
                ('votes', models.IntegerField(default=0)),
                ('question', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='polls.question')),
            ],
        ),
    ]

正直、pythonをSQLに脳内変換する必要があるのでちょっと微妙ですが、書いてあることはわかります。
具体的なSQLを知りたい場合は、以下のコマンドを実行すれば良いらしいです。

poetry run python manage.py sqlmigrate polls 0001 # poetryを利用しない場合は、`poetry run`は不要
> -- Create model Question
> CREATE TABLE `polls_question` (`id` bigint AUTO_INCREMENT NOT NULL PRIMARY KEY, `question_text` varchar(200) NOT NULL, `pub_date` datetime(6) NOT NULL);
> -- Create model Choice
> CREATE TABLE `polls_choice` (`id` bigint AUTO_INCREMENT NOT NULL PRIMARY KEY, `choice_text` varchar(200) NOT NULL, `votes` integer NOT NULL, `question_id` bigint NOT NULL);
> ALTER TABLE `polls_choice` ADD CONSTRAINT `polls_choice_question_id_c5b4b260_fk_polls_question_id` FOREIGN KEY (`question_id`) REFERENCES `polls_question` (`id`);

では、実際にマイグレーションを実行してみます。

poetry run python manage.py migrate # poetryを利用しない場合は、`poetry run`は不要
> Operations to perform:
>   Apply all migrations: admin, auth, contenttypes, polls, sessions
> Running migrations:
>   Applying polls.0001_initial... OK

問題なく実行されました。

mysqlコマンドで確認すると以下のようにテーブルが作成されていることを確認できました。

MySQL [polls]> desc polls_choice;
+-------------+--------------+------+-----+---------+----------------+
| Field       | Type         | Null | Key | Default | Extra          |
+-------------+--------------+------+-----+---------+----------------+
| id          | bigint       | NO   | PRI | NULL    | auto_increment |
| choice_text | varchar(200) | NO   |     | NULL    |                |
| votes       | int          | NO   |     | NULL    |                |
| question_id | bigint       | NO   | MUL | NULL    |                |
+-------------+--------------+------+-----+---------+----------------+
4 rows in set (0.005 sec)

MySQL [polls]> desc polls_question;
+---------------+--------------+------+-----+---------+----------------+
| Field         | Type         | Null | Key | Default | Extra          |
+---------------+--------------+------+-----+---------+----------------+
| id            | bigint       | NO   | PRI | NULL    | auto_increment |
| question_text | varchar(200) | NO   |     | NULL    |                |
| pub_date      | datetime(6)  | NO   |     | NULL    |                |
+---------------+--------------+------+-----+---------+----------------+
3 rows in set (0.005 sec)

ちなみに、もう一回マイグレーションを実行すると、同じマイグレーションファイルがもう一度実行されることはありません。

poetry run python manage.py migrate 
> Operations to perform:
>   Apply all migrations: admin, auth, contenttypes, polls, sessions
> Running migrations:
>   No migrations to apply.

つまり、実行済みのマイグレーションファイルが管理されているということなのですが、これはdjango_migrationsというテーブルで管理されているようです。
データを確認すると、一番最後のid=19のレコードとして、pollsの0001_initial（マイグレーションファイル名）が2022-03-20 06:29:06に適用されたことが記録されています。

MySQL [polls]> select * from django_migrations;
+----+--------------+------------------------------------------+----------------------------+
| id | app          | name                                     | applied                    |
+----+--------------+------------------------------------------+----------------------------+
|  1 | contenttypes | 0001_initial                             | 2022-03-13 10:52:22.904357 |
|  2 | auth         | 0001_initial                             | 2022-03-13 10:52:24.068071 |
|  3 | admin        | 0001_initial                             | 2022-03-13 10:52:24.348645 |
|  4 | admin        | 0002_logentry_remove_auto_add            | 2022-03-13 10:52:24.367090 |
|  5 | admin        | 0003_logentry_add_action_flag_choices    | 2022-03-13 10:52:24.384456 |
|  6 | contenttypes | 0002_remove_content_type_name            | 2022-03-13 10:52:24.625532 |
|  7 | auth         | 0002_alter_permission_name_max_length    | 2022-03-13 10:52:24.742140 |
|  8 | auth         | 0003_alter_user_email_max_length         | 2022-03-13 10:52:24.800678 |
|  9 | auth         | 0004_alter_user_username_opts            | 2022-03-13 10:52:24.814271 |
| 10 | auth         | 0005_alter_user_last_login_null          | 2022-03-13 10:52:24.926167 |
| 11 | auth         | 0006_require_contenttypes_0002           | 2022-03-13 10:52:24.936311 |
| 12 | auth         | 0007_alter_validators_add_error_messages | 2022-03-13 10:52:24.953623 |
| 13 | auth         | 0008_alter_user_username_max_length      | 2022-03-13 10:52:25.074838 |
| 14 | auth         | 0009_alter_user_last_name_max_length     | 2022-03-13 10:52:25.195808 |
| 15 | auth         | 0010_alter_group_name_max_length         | 2022-03-13 10:52:25.234605 |
| 16 | auth         | 0011_update_proxy_permissions            | 2022-03-13 10:52:25.253413 |
| 17 | auth         | 0012_alter_user_first_name_max_length    | 2022-03-13 10:52:25.367748 |
| 18 | sessions     | 0001_initial                             | 2022-03-13 10:52:25.452248 |
| 19 | polls        | 0001_initial                             | 2022-03-20 06:29:06.803184 |
+----+--------------+------------------------------------------+----------------------------+
19 rows in set (0.005 sec)

Admin画面でデータ登録

Djangoでは、モデルで管理されているテーブルに対するCRUD操作を行うためのAdmin画面が提供されています。
これを追加って、Question（質問）とChoice（選択肢）のデータを登録してみたいと思います。

まずは、apps/polls/admin.pyを以下のように編集し、Admin画面で二つのモデルを編集できるようにします。

from django.contrib import admin

from .models import Question, Choice

admin.site.register(Question)
admin.site.register(Choice)

次に、以下のコマンドで、adminユーザを作成します。

poetry run python manage.py createsuperuser
> Username (leave blank to use 'xxx'): admin
> Email address: xxx@gmail.com
> Password: **********
> Password (again): **********
> Superuser created successfully.

あとは、Djangoアプリケーションを起動して、

poetry run python manage.py runserver

以下のAdmin画面のURLにアクセスして、nameとpasswordを入力します。
https://rinoguchi.net/admin/

無事に、QuestionとChoiceのCRUD画面へのリンクが表示されました。

この画面から、以下のように、二つの質問とそれぞれ4つの選択肢のデータを登録してみました。

MySQL [polls]> select * from polls_question q join polls_choice c on c.question_id = q.id order by q.id, c.id;
+----+--------------------------------+----------------------------+----+--------------+-------+-------------+
| id | question_text                  | pub_date                   | id | choice_text  | votes | question_id |
+----+--------------------------------+----------------------------+----+--------------+-------+-------------+
|  1 | 旅行に行きたい国は？           | 2022-03-20 07:02:46.000000 |  1 | 中国         |     0 |           1 |
|  1 | 旅行に行きたい国は？           | 2022-03-20 07:02:46.000000 |  2 | 韓国         |     0 |           1 |
|  1 | 旅行に行きたい国は？           | 2022-03-20 07:02:46.000000 |  3 | アメリカ     |     0 |           1 |
|  1 | 旅行に行きたい国は？           | 2022-03-20 07:02:46.000000 |  4 | その他       |     0 |           1 |
|  2 | 好きなスポーツは？             | 2022-03-20 07:11:06.000000 |  5 | 野球         |     0 |           2 |
|  2 | 好きなスポーツは？             | 2022-03-20 07:11:06.000000 |  6 | サッカー     |     0 |           2 |
|  2 | 好きなスポーツは？             | 2022-03-20 07:11:06.000000 |  7 | バスケ       |     0 |           2 |
|  2 | 好きなスポーツは？             | 2022-03-20 07:11:06.000000 |  8 | その他       |     0 |           2 |
+----+--------------------------------+----------------------------+----+--------------+-------+-------------+

API作成

必要なデータも揃ったところで、チュートリアルに従ってアプリの画面作成をやっていこうと思ったのですが、実際のところサーバサイドレンダリングはやらなそうなので、API作成だけやってみようと思います。

以下の三つのAPIを作成してみました。

• 質問一覧API
  • GET /polls/questions/
• 質問API
  • GET /polls/questions/<question_id>/
• 投票API
  • POST /polls/questions/<question_id>/vote/

ルーティング定義を追加

apps/polls/urls.pyに以下の定義を追加しました。

設定方法は、URLと対応する関数を指定するだけでとても簡単です。

from django.urls import path

from . import views

urlpatterns = [
    path("questions/", views.get_questions, name="questions"),
    path("questions/<int:id>/", views.get_question, name="question"),
    path("questions/<int:id>/vote/", views.vote, name="vote"),
]

一つポイントなのですが、こちらに記載されているように、リクエストメソッドは関係なくGETでもPOSTでもおなじ関数に紐づけられるという点に注意が必要です。

The URLconf doesn’t look at the request method. In other words, all request methods – POST, GET, HEAD, etc. – will be routed to the same function for the same URL.

質問一覧API

GET /polls/questions/に対応する関数をapps/polls/views.pyに記載します。

from django.http import HttpRequest, JsonResponse
from polls.models import Question

def get_questions(request: HttpRequest):
    questions = list(Question.objects.all().order_by("id").values())
    return JsonResponse(
        questions, safe=False, json_dumps_params={"ensure_ascii": False}
    )

• values()は辞書型のリストを返すので、プロパティ名と値のセットがJSONに出力されます
• safe=Falseを指定しないと以下のエラーが発生します
  • TypeError: In order to allow non-dict objects to be serialized set the safe parameter to False.
• json_dumps_params={"ensure_ascii": False}を指定することで、日本語がunicodeエンコーディングされず、期待通りUTF-8でそのまま返却されます

動作確認すると、ちゃんとレスポンスが返ってきました。

curl https://rinoguchi.net/polls/questions/
[{"id": 1, "question_text": "旅行に行きたい国は？", "pub_date": "2022-03-20T07:02:46Z"}, {"id": 2, "question_text": "好きなスポーツは？", "pub_date": "2022-03-20T07:11:06Z"}]

質問API

GET /polls/questions/<question_id>/に対応する関数をapps/polls/views.pyに記載します。

def get_question(request: HttpRequest, id: int):
    question = Question.objects.get(id=id)
    response = dict()
    response["id"] = question.id
    response["question_text"] = question.question_text
    response["pub_date"] = question.pub_date
    response["choices"] = list(question.choices.all().values())
    return JsonResponse(response, safe=False, json_dumps_params={"ensure_ascii": False})

• Djangoでは、one-to-manyのフィールド（Question.choices）を含んだ形でQuestionオブジェクトを取得して、それを一発でJSONにシリアライズするような手段がなさそうです
  • 数時間ググったり、色々試したりしましたが発見できませんでした
  • 仕方ないので、questionとchoicesを個別に取得して、一つのJSONとして返すようにしました
• Question.objects.prefetch_related('choices')は使っていません
  • これは、one-to-manyのフィールドを事前に取得してキャッシュしておく機構なのですが、今回はchoicesを一度しか使ってないので、逆に実行されるSQLが増えてしまって、やめておきました
• Question.objects.fields('choices')も使っていません
  • 良さそうなのですが、Choiceオブジェクトではなく、Choide.idだけが含まれる形だったので使えませんでした
• filterではなくgetを使っています
  • get()はfilter()[0]のシノニムっぽい。複数件返ってきた場合はエラーになります

動作確認すると、期待通りレスポンスが返ってきました。

curl https://rinoguchi.net/polls/questions/1/
{"id": 1, "question_text": "旅行に行きたい国は？", "pub_date": "2022-03-20T07:02:46Z", "choices": [{"id": 1, "question_id": 1, "choice_text": "中国", "votes": 0}, {"id": 2, "question_id": 1, "choice_text": "韓国", "votes": 0}, {"id": 3, "question_id": 1, "choice_text": "アメリカ", "votes": 0}, {"id": 4, "question_id": 1, "choice_text": "その他", "votes": 0}]}

投票API

POST /polls/questions/<question_id>/voteに対応する関数をapps/polls/views.pyに記載します。

@csrf_exempt
def vote(request: HttpRequest, id: int):
    choice = Choice.objects.get(
        question__id=id, id=json.loads(request.body).get("choice_id")
    )
    choice.votes += 1
    choice.save()
    return HttpResponse(status=200)

• @csrf_exemptでcsrf-tokenのチェックを除外する指定です
• json.loads()で受け取ったjsonをパースしています
• choice.save()でUPDATE文が実行されます
• 本来、Questionオブジェクトを返却したいですが、サクッとできないので、status=200を返す形にしてますw

動作確認すると、期待通りレスポンスが返ってきました。

curl --request POST --url http://127.0.0.1:8000/polls/questions/1/vote/ --header 'Content-Type: application/json' --data '{"choice_id": 1}' -v
# 省略
< HTTP/1.1 200 OK

DBの投票カウントもちゃんとカウントアップされていました。

MySQL [polls]> select * from polls_choice where question_id = 1 and id = 1;
+----+-------------+-------+-------------+
| id | choice_text | votes | question_id |
+----+-------------+-------+-------------+
|  1 | 中国        |     1 |           1 |
+----+-------------+-------+-------------+

長かったですが、素のDjangoを使って投票アプリのAPIサーバを作るのは一旦これで終わりにします。
なかなかに、クセが強くて時間がかかりましたが、なんとなく基本的なところは把握できた気はしますね。

DRFでAPIを作り直す

ここまでは素のDjangoで実装してきましたが、REST APIを作成する場合はDRF(Django Rest Framework)を使うと実装量をかなり減らせるようで、そちらを試してみたいと思います。

インストール

まずは、ライブラリをインストールして、

poetry add djangorestframework

次に、apps/apps/settings.py のINSTALLED_APPSに設定を追加し、DjangoにDRFを利用することを伝えます。

INSTALLED_APPS = [
    "rest_framework",
]

投票アプリの雛形作成

新しく、drfpollsというアプリを作ります。

poetry run python manage.py startapp drfpolls

apps/apps/settings.py のINSTALLED_APPSに設定を追加します。

INSTALLED_APPS = [
    "drfpolls.apps.DrfpollsConfig",
]

モデルは、pollsと同じものを使い回す予定です。

ルーティング定義を追加

apps/apps/urls.pyにdrfpolls/へのルーティング定義を追加します。

urlpatterns = [
    path("drfpolls/", include("drfpolls.urls")),
]

drfpolls/配下のルーティング定義は、apps/drfpolls/urls.pyに記載します。

from django.urls import include, path
from rest_framework import routers
from drfpolls import views

router = routers.DefaultRouter()
router.register(r"questions", views.QuestionViewSet)

urlpatterns = [
    path("", include(router.urls)),
]

• /drfpolls/questions/というURLに対して、QuestionViewSetを割り当てています
  • ViewSetというだけあって、いくつかのURLをこのQuestionViewSetが提供してくれます

ビューの作成

apps/drfpolls/views.pyを作成します。

from rest_framework import viewsets

from polls.models import Question
from drfpolls.serializers import QuestionSerializer

class QuestionViewSet(viewsets.ModelViewSet):
    queryset = Question.objects.all()
    serializer_class = QuestionSerializer

• ModelViewSetは、内部的にCreateModelMixinやListModelMixinなどをミクスインしています。結果的に、いくつかのAPIが自動的に作成されます
  • ListModelMixin => 一覧取得（GET /drfpolls/questions/）
  • RetrieveMixin => 取得（GET /drfpolls/questions/1/）
  • CreateModelMixin => 作成（POST /drfpolls/questions/）
  • UpdateModelMixin => 更新（PATCH /drfpolls/questions/1/）
  • DestroyModelMixin => 削除（DELETE /drfpolls/questions/1/）
  • 上記の一部だけを提供したい場合は、ModelViewSetではなく、CreateModelMixinなどを個別にミクスインすればOKです
• querysetにより、一覧取得や取得で利用する元データを指定しています
  • Questionモデルの全データを指定しています
  • all()ではなく、filterを使って、何かの条件で絞り込んだデータを指定することもできます

シリアライザーの作成

シリアライザーの役割は以下の二つのようです。

• リクエスト（JSON）をvalidateして、チェックOKならモデルに変換する（さらにDBにも保存する）
• DBからデータをモデルとして取得し、レスポンス（JSON）に変換して返却する

apps/drfpolls/serializers.pyを作成します。

from rest_framework import serializers

from polls.models import Question

class QuestionSerializer(serializers.ModelSerializer):
    class Meta:
        model = Question
        fields = ["id", "question_text", "pub_date", "choices"]
        read_only_fields = ["choices"]
        depth = 1

• チュートリアルだと、HyperlinkedModelSerializerを利用しているが、シンプルにしたかったので、ModelSerializerに変更しました
  • HyperlinkedModelSerializerは関連するモデルの情報をそのリソースのURLの形式で返却するが、ModelSerializerは単純にIDを返却します
• fieldsで出力対象のフィールドを指定しています。choicesはone-to-manyの関連モデルです
• read_only_fieldsで、choicesが更新対象外であることを指定しています
• depth = 1とすることで、関連モデルのプロパティもレスポンスに含まれるようにしています
  • これを指定しないと、choicesは[1,2,3,4]のようなIDの配列になります

ここまでの実装で、だいたい動くようになりました。

• 一覧取得

  curl http://127.0.0.1:8000/drfpolls/questions/
  
  curl http://127.0.0.1:8000/drfpolls/questions/
  [{"id":1,"question_text":"旅行に行きたい国は？","pub_date":"2022-03-20T07:02:46Z","choices":[{"id":1,"choice_text":"中国","votes":4,"question":1},{"id":2,"choice_text":"韓国","votes":0,"question":1},{"id":3,"choice_text":"アメリカ","votes":0,"question":1},{"id":4,"choice_text":"その他","votes":0,"question":1}]},{"id":2,"question_text":"好きなスポーツは？","pub_date":"2022-03-20T07:11:06Z","choices":[{"id":5,"choice_text":"野球","votes":0,"question":2},{"id":6,"choice_text":"サッカー","votes":0,"question":2},{"id":7,"choice_text":"バスケ","votes":0,"question":2},{"id":8,"choice_text":"その他","votes":0,"question":2}]}]

• 取得

  curl http://127.0.0.1:8000/drfpolls/questions/1/
  
  {"id":1,"question_text":"旅行に行きたい国は？","pub_date":"2022-03-20T07:02:46Z","choices":[{"id":1,"choice_text":"中国","votes":4,"question":1},{"id":2,"choice_text":"韓国","votes":0,"question":1},{"id":3,"choice_text":"アメリカ","votes":0,"question":1},{"id":4,"choice_text":"その他","votes":0,"question":1}]}

• 作成

  curl -X POST -H "Content-Type: application/json" -d '{"question_text":"好きな本は？","pub_date":"2022-04-17T07:02:46Z"}' http://127.0.0.1:8000/drfpolls/questions/
  
  {"id":3,"question_text":"好きな本は？","pub_date":"2022-04-17T07:02:46Z","choices":[]}

• 更新

  curl -X PATCH -H "Content-Type: application/json" -d '{"question_text":"好きなゲームは？","pub_date":"2022-04-17T07:02:46Z"}' http://127.0.0.1:8000/drfpolls/questions/3/
  
  {"id":3,"question_text":"好きなゲームは？","pub_date":"2022-04-17T07:02:46Z","choices":[]}

• 削除

  curl -X DELETE http://127.0.0.1:8000/drfpolls/questions/3/

この実装量で、これだけのAPIがいい感じで動いてくれるのは、慣れれば相当生産性が上がりそうですね（初見殺しだけど）。

投票APIの実装

最後に、投票API（POST /drfpolls/questions/<question_id>/vote）を作ってみました。
具体的には、apps/drfpolls/views.pyにvoteという関数を追加しました。

from urllib.request import Request
from django.http import HttpResponse
from rest_framework import viewsets
from polls.models import Question
from drfpolls.serializers import QuestionSerializer
from rest_framework.decorators import action

class QuestionViewSet(viewsets.ModelViewSet):
    queryset = Question.objects.all()
    serializer_class = QuestionSerializer

    @action(detail=True, methods=["post"])
    def vote(self, request: Request, *args, **kwargs):
        question = self.get_object()
        choice_id = request.data.get("choice_id")  # type: ignore
        choice = question.choices.get(id=choice_id)
        choice.votes = choice.votes
        choice.save()

        return HttpResponse(status=200)

• @actionで装飾することで、関数名のURLにマッピングされたアクションになります
  • detail=Trueとしているので、詳細を取得するURL扱いになります。つまり今回だとdrfpolls/questions/99/vote/というURLにマッピングされます
• ModelViewSetの内部でGenericViewSetがミクスインされているので、self.get_object()で対象のオブジェクトを取得できます。今回だとQuestionオブジェクトを取得できます
• リクエストJSONからchoice_idを取得して、Questionオブジェクトから対象のChoiceを選択し、投票数（votes）を+1して保存しています
  • 本来、DBへの保存はシリアライザーでやるべきな気がするものの、面倒なのでここで実装しちゃってます

動作確認すると、無事動いてくれました。データも問題なく登録されていました。

curl -X POST -H "Content-Type: application/json" -d '{"choice_id": 3}' http://127.0.0.1:8000/drfpolls/questions/1/vote/ -v
#省略
< HTTP/1.1 200 OK

Tips

SQLをログ出力

Djangoでは、モデルを経由してSQLを実行するため、どんなSQLが実行されているのか全くわかりません。
実際のSQLを意識せずに実装すると間違ったデータを取得したり、ひどい性能になったりするので、SQLを常に見れるようにしたいです。
SQLをログに出力するのは、settings.pyに設定するだけでOKでした。以下の記事の通りでうまくいきました。（ありがとうございます）

https://qiita.com/fumihiko-hidaka/items/0f619749580da5ad9ce5

REPL起動

pythonで実装するときREPLを起動して動作確認することが多いと思います。
以下のコマンドでREPLを起動すると、Djangoを起動した時と同じ状態でREPLを起動できます。

poetry run python manage.py shell # poetryを利用しない場合は、`poetry run`は不要

さいごに

今回、Djangoのチュートリアルを大体一通りやってみて、かつ、作ったAPIをDRFを使って再作成しました。
少ないソースコードで多くの機能が実装されるので、Djangoに染まればかなりの生産性で実装可能だと思います。
一方で、初見殺し感はハンパないので、新規メンバーがキャッチアップするのはだいぶ大変そうです。

好みはあると思いますが、チームの特性次第では（例えば、Djangoのプロフェッショナルで構成され、人の入れ替わりが少ない）、有力なフレームワークだと思いました。