nginx-c-module-design

nginx.org C モジュールのディレクティブ設計に関するベストプラクティス

nginx C モジュールの作成者向けの包括的なディレクティブ設計ガイドです。明確で一貫性があり、管理者にとって使いやすい設定インターフェースの作成に重点を置いています。8 つのカテゴリにわたる 46 のルールを収録し、何を公開するか、どのように命名するか、安全に進化させるにはどうすればよいかについて、影響度に応じて優先順位を付けています。

適用するタイミング

以下を判断するときに、これらのガイドラインを参照してください。

• 設定可能なディレクティブとして公開する値と、ハードコードする値を決めるとき
• 新しいディレクティブに名前を付け、引数の型を選ぶとき
• スコープ（http、server、location）を決めるとき
• デフォルト値と検証動作を設定するとき
• 実行時データ用の nginx 変数を設計するとき
• 既存のディレクティブを非推奨にしたり、名前を変更したりするとき

関連スキル

このスキルでは設計上の判断（「何を」と「なぜ」）に焦点を当てます。実装の詳細については、以下を参照してください。

• nginx-c-modules — C の実装：メモリプール、リクエストのライフサイクル、設定の解析、ハンドラー、フィルター
• nginx-c-perf — パフォーマンス：バッファー、接続、ロック、キャッシュ、タイムアウト
• nginx-c-debug — デバッグ：クラッシュの診断、GDB、トレース、サニタイザー

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	公開するかどうかの判断	重大	expose-
2	命名規則	重大	naming-
3	ディレクティブの型	高	type-
4	スコープ設計	高	scope-
5	デフォルト値	中〜高	default-
6	検証とエラーメッセージ	中	valid-
7	変数設計	中	var-
8	進化と互換性	低〜中	compat-

クイックリファレンス

1. 公開するかどうかの判断（重大）

• expose-configurable-vs-hardcode - 設定可能な値とハードコードする値を判断するためのフレームワーク
• expose-escape-hatch - ハードコードされたデフォルト値を回避できる手段を用意する
• expose-feature-gate - オプションの動作には機能ゲートを使用する
• expose-too-many-directives - 過剰な設定を避ける
• expose-path-resource - 外部リソースのパスは常に公開する
• expose-security-surface - 公開するすべてのディレクティブについてセキュリティ上の影響を監査する
• expose-environment-dependent - デプロイ環境によって異なる値を公開する

2. 命名規則（重大）

• naming-module-prefix - すべてのディレクティブで一貫したモジュールプレフィックスを使用する
• naming-sub-prefix-groups - サブプレフィックスを使って関連するディレクティブをグループ化する
• naming-noun-over-verb - ディレクティブ名には動詞句より名詞句を優先する
• naming-no-abbreviations - ディレクティブ名に独自の略語を使わない
• naming-cross-module-consistency - 類似するディレクティブでは Nginx コアのサフィックスパターンに合わせる
• naming-lowercase-underscore - 小文字とアンダースコアのみを使用する

3. ディレクティブの型（高）

• type-flag-for-toggles - 二値の切り替えには NGX_CONF_FLAG を使用する
• type-enum-over-string - 既知の値の集合には列挙型スロットを使用する
• type-time-size-units - 時間やサイズの値には時間・サイズ用スロット関数を使用する
• type-take-n-fixed-args - 固定の引数数には TAKE1／TAKE2／TAKE12 を使用する
• type-one-more-lists - 可変長の値リストには 1MORE を使用する
• type-avoid-block - 機能にブロックディレクティブを使用しない
• type-custom-handler-complex - 複雑なディレクティブの解析にはカスタムハンドラーを使用する

4. スコープ設計（高）

• scope-default-three-levels - デフォルトで http + server + location スコープを使用する
• scope-http-only-shared-resources - 共有リソースのディレクティブを http レベルのみに制限する
• scope-server-connection-level - 接続レベルの設定には http + server スコープを使用する
• scope-avoid-if-context - 十分にテストされていない限り、if コンテキストをサポートしない
• scope-location-path-operations - パスルーティングのディレクティブを location コンテキストに制限する

5. デフォルト値（中〜高）

• default-zero-config-safe - ゼロ設定でも安全な動作になるようにする
• default-performance-optin - パフォーマンス機能はオプトイン方式にする
• default-safety-on - セキュリティ設定は制限的な値をデフォルトにする
• default-generous-timeouts - タイムアウトには余裕のある値をデフォルトにする
• default-zero-unlimited - 数値制限では、ゼロを無制限または無効の意味で使用する
• default-platform-aware-buffers - プラットフォームを考慮したバッファサイズのデフォルト値を使用する

6. 検証とエラーメッセージ（中）

• valid-parse-time-check - 設定の解析時にすべてのディレクティブ値を検証する
• valid-show-invalid-value - エラーメッセージに無効な値を含める
• valid-suggest-range - エラーメッセージに有効な範囲または形式を含める
• valid-conflict-detection - マージ時に競合するディレクティブを検出する
• valid-actionable-guidance - エラーメッセージに実行可能なガイダンスを示す

7. 変数設計（中）

• var-runtime-data-only - リクエストごとの実行時データのみを変数として公開する
• var-naming-convention - モジュールのプレフィックスと説明的なサフィックスを使って変数に名前を付ける
• var-dynamic-prefix - キーと値のデータには動的なプレフィックス変数を使用する
• var-lazy-evaluation - コストの高い変数には遅延評価を活用する
• var-in-directive-values - リクエストごとに値を変える必要がある場合にのみ、ディレクティブ値での変数の使用をサポートする
• var-read-only-diagnostics - 可観測性のため、読み取り専用の診断変数を公開する

8. 進化と互換性（低〜中）

• compat-deprecation-warning - 削除前に非推奨のディレクティブに関する警告をログに記録する
• compat-alias-old-directive - 古いディレクティブ名をエイリアスとして維持する
• compat-multi-version-window - 複数バージョンにわたる非推奨期間を設ける
• compat-document-migration - 古いディレクティブと新しいディレクティブの両方のドキュメントに移行方法を記載する

使用方法

詳しい説明やコード例については、個別のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報