Tarkov.dev スキーマ更新スキル

tarkov.dev GraphQL スキーマを更新するか、Go クライアントを再生成する際にこのスキルを使用します。

使用する場合

Tarkov.dev API が新しいフィールドまたはタイプを追加した
GraphQL クエリが「unknown field」エラーで失敗している
API で利用可能な新しいデータを使用したい
tarkov.dev API の大規模な更新後
プロジェクトを初めてセットアップする場合（スキーマが不足している場合）

クイック更新

# 最新スキーマを取得してクライアントを再生成
task tarkovdev

以下の 2 つのステップが実行されます：

tarkovdev:get-schema - tarkov.dev から最新スキーマをダウンロード
tarkovdev:regenerate - クエリから Go コードを再生成

ステップバイステッププロセス

ステップ 1: 最新スキーマを取得

task tarkovdev:get-schema

実行内容:

https://api.tarkov.dev/graphql の tarkov.dev GraphQL API をイントロスペクト
スキーマを internal/tarkovdev/schemas/schema.graphql に書き込み

必要なもの:

graphql-inspector CLI ツール（task deps:install:node でインストール）
api.tarkov.dev に到達するためのインターネット接続

ステップ 2: クエリを更新（必要に応じて）

新しいフィールドを使用する場合は、以下のクエリを更新します：

internal/tarkovdev/schemas/queries.graphql

例: 既存のクエリに新しいフィールドを追加

query GetWeapons {
  items(type: weapon) {
    id
    name
    # ここに新しいフィールドを追加
    weight
    basePrice
  }
}

ステップ 3: Go クライアントを再生成

task tarkovdev:regenerate

実行内容:

genqlient コードジェネレータを実行
genqlient.yaml 設定を読み込み
internal/tarkovdev/generated-queries.go に Go 型と関数を生成

設定ファイル: genqlient.yaml

schema: internal/tarkovdev/schemas/schema.graphql
operations:
  - internal/tarkovdev/schemas/queries.graphql
generated: internal/tarkovdev/generated-queries.go

ステップ 4: 変更を検証

# 変更内容を確認
git diff internal/tarkovdev/

# コンパイルできることを確認
go build ./...

# 関連するテストを実行
go test ./internal/tarkovdev/...
go test ./internal/importers/...

生成されるもの

再生成後、internal/tarkovdev/generated-queries.go には以下が含まれます：

Go 構造体 - クエリで使用するすべての GraphQL 型
クエリ関数 - GetWeapons(ctx, client)、GetMods(ctx, client) など
レスポンス型 - 適切な JSON アンマーシャリング付き

生成されたコードの例:

type GetWeaponsResponse struct {
    Items []GetWeaponsItem `json:"items"`
}

type GetWeaponsItem struct {
    Id   string `json:"id"`
    Name string `json:"name"`
    // 新しいフィールドはここに自動的に表示されます
}

func GetWeapons(ctx context.Context, client graphql.Client) (*GetWeaponsResponse, error) {
    // 生成されたクエリ実行
}

クエリの変更

新しいクエリを追加

internal/tarkovdev/schemas/queries.graphql を開く
クエリを追加：

query GetTraderOffers {
  traders {
    id
    name
    cashOffers {
      item {
        id
        name
      }
      price
    }
  }
}

再生成：

task tarkovdev:regenerate

生成された関数を使用：

import "tarkov-build-optimiser/internal/tarkovdev"

resp, err := tarkovdev.GetTraderOffers(ctx, graphqlClient)

既存のクエリを変更

queries.graphql のクエリを編集
再生成: task tarkovdev:regenerate
古い構造を使用しているコードを更新（コンパイラが見つけるのを支援します）

クエリを削除

queries.graphql のクエリを削除またはコメントアウト
再生成: task tarkovdev:regenerate
削除された関数を呼び出しているコードを削除

スキーマを理解する

スキーマを表示

# エディタで開く
code internal/tarkovdev/schemas/schema.graphql

スキーマには以下が表示されます：

利用可能な型（Item、Weapon、Mod、Trader など）
各型のフィールド
使用可能なクエリ操作
Enum とその値

利用可能なフィールドを確認

# 関心のある型を探す
type Item {
  id: ID!
  name: String
  weight: Float
  types: [ItemType!]!
  # ... その他多くのフィールド
}

クエリ操作を確認

type Query {
  items(type: ItemType): [Item]
  item(id: ID!): Item
  traders: [Trader]
  # ... など
}

トラブルシューティング

スキーマの取得に失敗

エラー: api.tarkov.dev に接続できない

解決方法:

インターネット接続を確認
API がオンラインであることを確認: curl https://api.tarkov.dev/graphql
API エンドポイントが変更されていないか確認（Taskfile で更新）
後でもう一度試す（API がダウンしている可能性があります）

コード生成に失敗

エラー: 再生成中に genqlient エラーが発生

確認事項:

クエリの構文が有効な GraphQL であるか
フィールド名がスキーマと完全に一致しているか（大文字小文字を区別）
クエリで使用されている型がスキーマに存在するか
必須フィールドがクエリに含まれているか

デバッグ:

# クエリを手動で検証
cat internal/tarkovdev/schemas/queries.graphql

# genqlient バージョンを確認
go list -m github.com/Khan/genqlient

生成されたコードにコンパイルエラーがある

再生成後、Go ビルドが失敗

解決方法:

変更された型を使用しているコードを更新
API でフィールド名または型が変更されていないか確認
クエリが新しいスキーマと一致しているか検証
tarkov.dev API の重大な変更を確認

新しいフィールドが表示されない

スキーマを取得しましたが、新しいフィールドが利用できない