メインコンテンツまでスキップ

よくある質問

新規参加者がよく抱く疑問とその回答です。

開発環境​

Q: ポートが既に使用されています​

A: 別のプロセスがポートを使用している可能性があります。

# 使用中のポートを確認
sudo lsof -i :5432  # PostgreSQL
sudo lsof -i :8080  # API Server

# ポートを変更する場合は
# infra/env/dev/ports.env を編集

Q: Docker Composeが起動しません​

A: 以下の確認をしてください：

  1. Docker Desktopが起動しているか確認
  2. ポートが競合していないか確認
  3. make compose/down で一度停止してから make compose/up を実行

Q: マイグレーションが失敗します​

A: データベースをリセットして再実行：

make compose/db.reset
make db/reset

コードベース​

Q: 新しい機能はどこに実装すればいいですか？​

A: 機能の種類によって異なります：

  • ビジネスロジック: server-core/ 配下に新しいパッケージを作成
  • DB操作: server-platform/datastore/postgres/ にRepository実装
  • APIハンドラー: server-apps/gateway/handlers/ または server-apps/api/handlers/

詳細はレイヤー構成と境界と責務を参照してください。

Q: Protocol Buffersを変更したら何をすべきですか？​

A: 以下の順序で実行：

  1. .protoファイル編集
  2. make proto/lint - リントチェック
  3. make proto/gen - コード生成
  4. 生成コード（packages/proto-gen-go/, packages/proto-gen-ts/）をコミット

詳しくはProtocol Buffersを参照してください。

Q: データベーススキーマを変更するには？​

A: マイグレーションファイルを作成：

  1. infra/db/migrations/ に新しいマイグレーションファイル作成
  2. make db/mig-up でマイグレーション実行
  3. 問題があれば make db/mig-down でロールバック

詳しくはデータベース設計を参照してください。

アーキテクチャ​

Q: server-coreとserver-platformの違いは？​

A:

  • server-core: ビジネスロジックとドメインモデル。外部依存なし。
  • server-platform: server-coreで定義されたインターフェースの実装（DB、ログなど）。

詳しくはレイヤー構成を参照してください。

Q: GatewayとAPI Serverの役割の違いは？​

A:

  • Gateway: HTTP/JSON ↔ gRPC変換、認証、レート制限など境界の責務
  • API Server: ビジネスロジック実行、データ永続化

詳しくは境界と責務を参照してください。

トラブルシューティング​

Q: テストが失敗します​

A: 以下を確認：

# 依存関係を整理
make go/tidy

# テストを再実行
make go/test

# 特定のパッケージのテストのみ実行
cd server-core/post
go test ./...

Q: ビルドエラーが出ます​

A: 以下を試してください：

# Go依存関係整理
make go/tidy

# キャッシュクリア
make go/clean

# 再ビルド
make compose/build

Q: Protocol Buffersの生成コードが古い​

A: 再生成してください：

make proto/gen

生成コードの差分を確認してコミットしてください。

関連ドキュメント​