YAML 및 프로젝트 구조

디렉토리 레이아웃

myapp/
├── .wippy.yaml          # 런타임 설정
├── wippy.lock           # 소스 디렉토리 및 잠긴 모듈
├── .wippy/              # 설치된 모듈
└── src/                 # 애플리케이션 소스
    ├── _index.yaml      # 엔트리 정의
    ├── api/
    │   ├── _index.yaml
    │   └── *.lua
    └── workers/
        ├── _index.yaml
        └── *.lua

YAML 정의 파일

YAML 정의는 시작 시 레지스트리에 로드됩니다. 레지스트리가 실제 데이터의 원본입니다. YAML 파일은 레지스트리를 채우는 방법 중 하나이며, 엔트리는 다른 소스에서 가져오거나 프로그래밍 방식으로 생성할 수도 있습니다.

정의 파일 형식

namespace와 함께 entries 배열 또는 최상위 name+kind가 있는 모든 YAML 파일이 유효한 정의 파일입니다. version은 선택적입니다:

version: "1.0"
namespace: app.api

entries:
  - name: get_user
    kind: function.lua
    meta:
      comment: Fetches user by ID
    source: file://get_user.lua
    method: handler
    modules:
      - sql
      - json

  - name: get_user.endpoint
    kind: http.endpoint
    meta:
      comment: User API endpoint
    method: GET
    path: /users/{id}
    func: get_user

필드	필수	설명
`version`	아니오	스키마 버전 (현재 `"1.0"`)
`namespace`	예	이 파일의 엔트리 네임스페이스
`entries`	예	엔트리 정의 배열

명명 규칙

의미 단위 구분에는 점(.)을, 단어 구분에는 밑줄(_)을 사용합니다:

# Function and its endpoint
- name: get_user              # The function
- name: get_user.endpoint     # Its HTTP endpoint

# Multiple endpoints for same function
- name: list_orders
- name: list_orders.endpoint.get
- name: list_orders.endpoint.post

# Routers
- name: api.public            # Public API router
- name: api.admin             # Admin API router

패턴: base_name.variant - 점은 의미 단위를 구분하고, 밑줄은 단위 내 단어를 구분합니다.

네임스페이스

네임스페이스는 점으로 구분된 식별자입니다:

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

필드	설명
`directories.src`	애플리케이션 소스 디렉토리, YAML 정의 파일을 재귀적으로 스캔
`directories.modules`	vendor된 모듈의 기본 디렉토리; 팩은 `<modules>/vendor/` 아래에 놓임
`options.unpack_modules`	팩을 직접 로드하는 대신 각 `.wapp`을 옆의 디렉토리로 추출 (기본값 `false`)
`modules[].name`	`org/module` 형식의 모듈 식별자
`modules[].version`	선택된 버전
`modules[].hash`	vendor된 팩이 일치해야 하는 아티팩트 다이제스트
`modules[].root`	선택된 배포 루트 표시; 최대 하나의 모듈만 가질 수 있음

vendor된 팩은 .wapp 파일로 보관됩니다. unpack_modules: true이면 각 모듈이 디렉토리로도 추출되고, 검증된 .wapp은 그 옆에 남습니다 — 설치는 팩을 찾으므로 팩이 없는 디렉토리는 다시 다운로드됩니다.

wippy.lock의 replacements: 섹션은 더 이상 사용되지 않습니다. 경고와 함께 여전히 로드되지만, 로컬 모듈 오버라이드는 런타임 설정 파일의 workspace.replacements 아래에 선언하세요. 의존성 관리를 참조하세요.

엔트리 정의

entries 배열의 각 item은 하나의 엔트리를 정의합니다. 다음 예와 같이 kind-specific field는 name, kind, meta 옆에 둘 수 있습니다.

entries:
  - name: hello
    kind: function.lua
    meta:
      comment: Returns hello world
    source: file://hello.lua
    method: handler
    modules:
      - http
      - json

  - name: hello.endpoint
    kind: http.endpoint
    meta:
      comment: Hello endpoint
    method: GET
    path: /hello
    func: hello

명시적 data: 필드도 지원됩니다. 이 필드가 있으면 그 값이 kind-specific payload 전체이므로 sibling kind-specific field와 함께 사용하지 마십시오.

entries:
  - name: config
    kind: registry.entry
    data:
      environment: production
      features:
        dark_mode: true

메타데이터

UI 표시용 정보는 meta에 지정합니다:

- name: payment_handler
  kind: function.lua
  meta:
    title: Payment Processor
    comment: Handles Stripe payments
  source: file://payment.lua

meta.title과 meta.comment는 registry consumer와 management interface가 표시할 수 있는 설명 정보에 사용합니다.

애플리케이션 엔트리

애플리케이션 수준 설정에는 registry.entry kind를 사용합니다:

- name: config
  kind: registry.entry
  meta:
    title: Application Settings
    type: application
  environment: production
  features:
    dark_mode: true
    beta_access: false

일반적인 엔트리 종류

종류	목적
`registry.entry`	일반 event dispatch 없이 저장되는 범용 데이터
`function.lua`	호출 가능한 Lua 함수
`process.lua`	장기 실행 프로세스
`http.service`	HTTP 서버
`http.router`	라우트 그룹
`http.endpoint`	HTTP 핸들러
`process.host`	프로세스 실행 host

엔트리 kind 레퍼런스는 엔트리 종류 가이드를 참조하십시오.

설정 파일

.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

참고

애플리케이션 아키텍처 — 애플리케이션을 slice와 layer로 구성하기
엔트리 종류 가이드 — 사용 가능한 엔트리 kind 검토하기
설정 가이드 — 런타임 옵션 설정하기
커스텀 엔트리 종류 — handler 구현하기(고급)