このテンプレートは、@ras0q さんのテンプレートを改変し、 何もしなくてもNeoShowcase上でデプロイできるようにしたテンプレートをさらに改変し、 oapi-codegenを用いてより安全/簡単/高速に開発できるようにした、OpenAPI.yamlの存在が前提のテンプレートです。

openapi/openapi.yamlを書き換え、tools/tools.goからコードを生成し、openapi/server.gen.goのServerInterfaceをinternal/handler/*.goで実装する事で、より安全/簡単/高速にAPIを実装できます。

また、OpenAPIで定義されたSchemasや、Request Body & Response Bodyが、openapi/models/models.gen.goにGoの構造体として生成されており、DBからGoの構造体に落とし込む際にも使えて便利です。

以下の様に、何もしなくても正常に動きます(MariaDBも自動で環境変数を見て繋がります)。

ハッカソンなど短期間でWebアプリを開発する際のバックエンドのGo実装例です。 学習コストと開発コストを抑えることを目的としています。

GitHubの Use this template ボタンからレポジトリを作成するか、以下のgonewコマンドで作成できます。

go run golang.org/x/tools/cmd/gonew@latest github.com/pikachu0310/go-backend-template {{ project_name }}

※ GitHub Templateから作成した場合は別途モジュール名を変更することを推奨します。

• 最低限DockerとDocker Composeが必要です。

  • Compose Watchを使うため、Docker Composeのバージョンは2.22以上にしてください。

• linter, formatterにはgolangci-lintを使っています。

  • VSCodeを使用する場合は.vscode/settings.jsonでlinterの設定を行ってください

  {
    "go.lintTool": "golangci-lint"
  }

• makeコマンドのターゲット一覧とその説明はmake helpで確認できます

docker compose watch

API、DB、DB管理画面が起動します。 各コンテナが起動したら、以下のURLにアクセスすることができます。 Compose Watchにより、ソースコードの変更を検知して自動で再起動します。

• http:https://localhost:8080/ (API)
• http:https://localhost:8081/ (DBの管理画面)

全てのテスト

make test

単体テストのみ

make test-unit

結合テストのみ

make test-integration

• main.go: エントリーポイント
  • 依存ライブラリの初期化など最低限の処理のみを書く
  • ルーティングの設定は./internal/handler/handler.goに書く
  • 肥大化しそうなら./internal/infrastructure/{pkgname}を作って外部ライブラリの初期化処理を書くのもアリ
• internal/: アプリ本体の主実装
  • Tips: Goの仕様でinternalパッケージは他プロジェクトから参照できない (https://go.dev/doc/go1.4#internalpackages)
  • handler/: ルーティング
    • 飛んできたリクエストを裁いてレスポンスを生成する
    • DBアクセスはrepository/で実装したメソッドを呼び出す
    • Tips: リクエストのバリデーションがしたい場合は↓のどちらかを使うと良い
      • go-playground/validatorでタグベースのバリデーションをする
      • go-ozzo/ozzo-validationでコードベースのバリデーションをする
  • migration/: DBマイグレーション
    • DBのスキーマを定義する
    • Tips: マイグレーションツールはpressly/gooseを使っている
    • 初期化スキーマは1_schema.sqlに記述し、運用開始後のスキーマ定義変更等は2_add_user_age.sqlのように連番を振って記述する
      • Tips: Goでは1.16からembedパッケージを使ってバイナリにファイルを文字列として埋め込むことができる
  • repository/: DBアクセス
    • DBへのアクセス処理
      • 引数のバリデーションはhandler/に任せる
  • pkg/: 汎用パッケージ
    • 複数パッケージから使いまわせるようにする
    • 例: pkg/config/: アプリ・DBの設定
    • Tips: 外部にパッケージを公開したい場合はinternal/の外に出しても良い
• integration/: 結合テスト
  • internal/の実装から実際にデータが取得できるかテストする
  • DBの立ち上げにはory/dockertestを使っている
  • 短期開発段階では時間があれば書く程度で良い
  • Tips: 外部サービス(traQ, Twitterなど)へのアクセスが発生する場合はgolang/mockなどを使ってモック(テスト用処理)を作ると良い

• ドメインを書く (internal/domain/など)
  • 現在は簡単のためにAPIスキーマとDBスキーマのみを書きこれらを直接やり取りしている
  • 本来はアプリの仕様や概念をドメインとして書き、スキーマの変換にはドメインを経由させるべき
• 単体テスト・結合テストのカバレッジを上げる
  • カバレッジの可視化にはCodecov(traPだと主流)やCoverallsが便利
• ログの出力を整備する
  • ロギングライブラリは好みに合ったものを使うと良い