1. YAML 設定ファイルの基本構造例
以下は、管理者API用のルート設定を定義した正しいYAMLの例です。
routes:
- id: sl-express-ms-web-manager
uri: lb://sl-express-ms-web-manager
predicates:
- Path=/manager/**
filters:
- ManagerToken
- StripPrefix=1この構成は、/manager/** へのリクエストを sl-express-ms-web-manager サービスへ負荷分散し、ManagerToken フィルタによる認証チェックを実施、さらにパスの先頭1セグメントを削除するという動作を実現しています。
2. YAML の構文ルールと注意点
(1) インデントは空格のみ、統一性が必須
YAMLでは、階層構造をインデントで表現します。このインデントには絶対にタブ文字を使わず、必ず半角スペースで統一する必要があります。たとえば2つの異なるインデント幅が混在すると、構文解析に失敗します。
| 正しい記述 | 誤った記述（NG） |
|---|---|
| |
(2) リスト要素には「-」が必要
配列（YAMLではリスト）を記述する際には、各行の先頭で記号「-」を用い、その後に必ず半角スペースを1つ入れる必要があります。これは入れ子のあるルート、述語、フィルタ定義で繰り返し登場します。
| 正しい例 | NG例 |
|---|---|
| |
(3) キーと値の記述形式
ペア形式（マップ）を記述する際には、コロン（:）の直後に半角スペース1つを必須とし、前にはスペースを置かないでください。これはJSONやプロパティファイルとの混在時に特に注意が必要です。
| 正しい形式 | 誤った形式 |
|---|---|
| |
(4) 複数行文字列の記述
特定のフィルタ設定や説明文など、改行を保持したい場合は「|」記号を用います。一方、改行を空白に折りたたみたい場合は「>」を用います。ただし実際のルート設定にはそこまで複雑な文字列は多くありません。
# 式展開する必要がない文字列を保持
description: |
manager パス以下の呼び出しには、
ManagerToken フィルタによる
認証が必須です。(5) 特殊文字のエスケープ処理
コロン（:）、ハッシュ記号（#）といったYAML構文で意味を持つ記号をリテラルとして使う場合は、その値を二重引用符で囲む必要があります。
example:
pattern: "observe the colon\: here"
# pattern: observe the colon: here # ← この場合、行末までがコメント文として扱われる3. YAML 構文が厳格な理由
YAMLは「Yet Another Markup Language」ではなく、「YAML Ain’t Markup Language」の略であり、人間が読みやすく、簡潔に構造を表現することを目的として設計されています。このため、JSONやXMLと比べて柔軟で直感的である一方で、記号やインデントの誤りに対して極めて非情に反応します。
| 比較対象 | YAML | JSON |
|---|---|---|
| インデント | 構文の核 （誤りで解析失敗） | 無関係 （自由に空白可） |
| コメント記法 | サポート （ #） | 非サポート |
| 拡張型 | 日時・数値・バイナリなど | 文字列・数値・真偽値・配列・オブジェクトのみ |
| 可読性 | 高い（自然言語に近い） | 低め（機械眼球視点） |
4. 実際によくあるバグの事例
事例①：インデントの不整合
gateway:
routes:
- id: user-service
uri: lb://user-service
predicates:
- Path=/user/** # ← 1文字だけずれたインデント！
事例②：リスト記号の欠如
predicates:
Path=/api/**
Method=GET
事例③：誤ったスペースの位置
filters:
-StripPrefix=1 # コンパイル時に「stray '-'」エラー発生
URI : lb://xxx # 結果としてキー名が「URI 「:」」になる
上記のいずれも、構文エラーとしてアプリケーションの起動直後に失敗します。実際の開発では vSCodium や IntelliJ IDEA などのIDEでYAML Linterを有効化しておくことで、未然に防げるミスが多数あります。