YAML 및 프로젝트 구조

프로젝트 레이아웃, YAML 정의 파일, 명명 규칙.

디렉토리 레이아웃

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

YAML 정의 파일

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

파일 구조

version과 namespace가 있는 모든 YAML 파일이 유효합니다:

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

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

명명 규칙

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

# 함수와 엔드포인트
- 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 라우터

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

네임스페이스

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

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

엔트리 전체 ID는 네임스페이스와 이름을 결합합니다: app.api:get_user

소스 디렉토리

wippy.lock 파일은 Wippy가 정의를 로드하는 위치를 정의합니다:

directories:
  modules: .wippy
  src: ./src

Wippy는 이러한 디렉토리를 재귀적으로 스캔하여 YAML 파일을 찾습니다.

엔트리 정의

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 kind를 사용합니다:

- name: config
  kind: registry.entry
  meta:
    title: 애플리케이션 설정
    type: application
  environment: production
  features:
    dark_mode: true
    beta_access: false

일반적인 엔트리 종류

Kind	목적
`registry.entry`	범용 데이터
`function.lua`	호출 가능한 Lua 함수
`process.lua`	장기 실행 프로세스
`http.service`	HTTP 서버
`http.router`	라우트 그룹
`http.endpoint`	HTTP 핸들러
`process.host`	프로세스 슈퍼바이저

전체 레퍼런스는 엔트리 종류 가이드를 참조하세요.

설정 파일

.wippy.yaml

프로젝트 루트의 런타임 설정:

logger:
  level: info
  mode: production

host:
  worker_count: 16

http:
  address: :8080

모든 옵션은 설정 가이드를 참조하세요.

wippy.lock

소스 디렉토리 정의:

directories:
  modules: .wippy
  src: ./src

엔트리 참조

전체 ID 또는 상대 이름으로 엔트리를 참조합니다:

# 전체 ID (네임스페이스 간)
- name: main.router
  kind: http.router
  endpoints:
    - app.api:get_user.endpoint
    - app.api:list_orders.endpoint

# 같은 네임스페이스 - 이름만 사용
- name: get_user.endpoint
  kind: http.endpoint
  func: 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

참고

엔트리 종류 가이드 - 사용 가능한 엔트리 종류
설정 가이드 - 런타임 옵션
커스텀 엔트리 종류 - 핸들러 구현 (고급)