YAML & プロジェクト構造

プロジェクトレイアウト、YAML定義ファイル、命名規則について説明します。

ディレクトリレイアウト

myapp/
├── .wippy.yaml          # ランタイム設定
├── wippy.lock           # ソースディレクトリとロックされたモジュール
├── .wippy/              # インストール済みモジュール
└── src/                 # アプリケーションソース
    ├── _index.yaml      # エントリ定義
    ├── api/
    │   ├── _index.yaml
    │   └── *.lua
    └── workers/
        ├── _index.yaml
        └── *.lua

YAML定義ファイル

ファイル構造

namespaceに加えて、entries配列またはトップレベルのname+kindのいずれかを持つYAMLファイルは有効な定義ファイルです。versionは省略可能です：

version: "1.0"
namespace: app.api

entries:
  - name: get_user
    kind: function.lua
    meta:
      comment: IDでユーザーを取得
    source: file://get_user.lua
    method: handler
    modules:
      - sql
      - json

  - name: get_user.endpoint
    kind: http.endpoint
    meta:
      comment: ユーザーAPIエンドポイント
    method: GET
    path: /users/{id}
    func: get_user

命名規則

意味的な区切りにはドット（.）を、単語の区切りにはアンダースコア（_）を使用します：

# 関数とそのエンドポイント
- name: get_user              # 関数
- name: get_user.endpoint     # そのHTTPエンドポイント

# 同じ関数に対する複数のエンドポイント
- name: list_orders
- name: list_orders.endpoint.get
- name: list_orders.endpoint.post

# ルーター
- name: api.public            # パブリックAPIルーター
- name: api.admin             # 管理者用APIルーター

名前空間

名前空間はドット区切りの識別子です：

app
app.api
app.api.v2
app.workers

エントリのフルIDは名前空間と名前を組み合わせます：app.api:get_user

ロックファイル

wippy.lockは、Wippyが定義をロードする場所と、選択されたモジュールのバージョンを記録します：

directories:
  modules: .wippy
  src: ./src
options:
  unpack_modules: false
modules:
  - name: acme/http
    version: v1.2.0
    hash: 4ea816fe84ca58a1f0869e5ca6afa93d6ddd72fa09e1162d9e600a7fbf39f0a2

ベンダリングされたパックは.wappファイルとして保持されます。unpack_modules: trueの場合、各モジュールはディレクトリへも展開され、検証済みの.wappはその隣に残ります。インストール処理はパックを探すため、パックが失われたディレクトリは再度ダウンロードされます。

wippy.lock内のreplacements:セクションは非推奨です。警告付きで引き続きロードされますが、ローカルモジュールのオーバーライドはランタイム設定ファイルのworkspace.replacements配下で宣言してください。依存関係管理を参照してください。

エントリ定義

各エントリはentries配列内に定義します。プロパティはルートレベルにあります（data:ラッパーなし）：

entries:
  - name: hello
    kind: function.lua
    meta:
      comment: Hello Worldを返す
    source: file://hello.lua
    method: handler
    modules:
      - http
      - json

  - name: hello.endpoint
    kind: http.endpoint
    meta:
      comment: Helloエンドポイント
    method: GET
    path: /hello
    func: hello

メタデータ

UI向けの情報にはmetaを使用します：

- name: payment_handler
  kind: function.lua
  meta:
    title: 決済プロセッサ
    comment: Stripe決済を処理
  source: file://payment.lua

規則：meta.titleとmeta.commentは管理UIで適切にレンダリングされます。

アプリケーションエントリ

アプリケーションレベルの設定にはregistry.entry種別を使用します：

- name: config
  kind: registry.entry
  meta:
    title: アプリケーション設定
    type: application
  environment: production
  features:
    dark_mode: true
    beta_access: false

一般的なエントリ種別

完全なリファレンスはエントリ種別ガイドを参照してください。

設定ファイル

.wippy.yaml

プロジェクトルートのランタイム設定：

version: "1.0"

logger:
  encoding: json

logmanager:
  min_level: 0

supervisor:
  host:
    worker_count: 16

すべてのオプションについては設定ガイドを参照してください。

wippy.lock

ソースディレクトリと選択されたモジュールグラフ — 上記のロックファイルを参照してください。

エントリの参照

エントリはフルIDまたは相対名で参照できます。子は親側のリストではなく、metaを通じて親に紐付きます：

# ルーターは自身をサーバーに対して宣言する
- name: api
  kind: http.router
  meta:
    server: app:gateway
  prefix: /api

# エンドポイントはレジストリIDでルーターを参照する（名前空間をまたぐ場合も同じ）
- name: get_user.endpoint
  kind: http.endpoint
  meta:
    router: app.api:api
  method: GET
  path: /users/{id}
  func: app.api:get_user

プロジェクト例

myapp/
├── .wippy.yaml
├── wippy.lock
└── src/
    ├── _index.yaml           # namespace: app
    ├── api/
    │   ├── _index.yaml       # namespace: app.api
    │   ├── users.lua
    │   └── orders.lua
    ├── lib/
    │   ├── _index.yaml       # namespace: app.lib
    │   └── database.lua
    └── workers/
        ├── _index.yaml       # namespace: app.workers
        └── email_sender.lua

関連項目

• アプリケーションアーキテクチャ - アプリをスライスとレイヤーに分割する方法
• エントリ種別ガイド - 利用可能なエントリ種別
• 設定ガイド - ランタイムオプション
• カスタムエントリ種別 - ハンドラの実装（上級）