설정 어댑터 작성하기

원문 보기 위키 갱신 2026.10.03

설정 어댑터 작성하기 (Writing Config Adapters)

출처: Caddy 공식 문서

본문

여러 가지 이유로 JSON이 아닌 형식으로 Caddy를 설정하고 싶을 수 있어요. Caddy는 config adapter(설정 어댑터)를 통해 이 기능을 일급 지원해요.

선호하는 언어/문법/형식에 맞는 어댑터가 아직 없다면 직접 작성할 수 있어요!

템플릿

시작할 수 있는 템플릿이에요:

package myadapter

import (
	"fmt"

	"github.com/caddyserver/caddy/v2/caddyconfig"
)

func init() {
	caddyconfig.RegisterAdapter("adapter_name", MyAdapter{})
}

// MyAdapter adapts ____ to Caddy JSON.
type MyAdapter struct{
}

// Adapt adapts the body to Caddy JSON.
func (a MyAdapter) Adapt(body []byte, options map[string]interface{}) ([]byte, []caddyconfig.Warning, error) {
	// TODO: parse body and convert it to JSON
	return nil, nil, fmt.Errorf("not implemented")
}

RegisterAdapter()의 godoc을 참고하세요
'Adapter' 인터페이스의 godoc을 참고하세요

반환되는 JSON은 들여쓰기되지 않아야 해요. 항상 압축된(compact) 형태여야 해요. 호출자가 원한다면 언제든 예쁘게 만들 수 있어요.

config 어댑터는 Caddy 플러그인이지만 Caddy 모듈은 아니라는 점을 유의하세요. 설정의 일부에 통합되지 않기 때문이에요(하지만 편의를 위해 list-modules에 표시되기는 해요). 따라서 Provision()이나 Validate() 메서드가 없고 나머지 모듈 수명 주기를 따르지 않아요. 그들은 Adapter 인터페이스를 구현하고 어댑터로 등록되기만 하면 돼요.

json.RawMessage 타입(즉 모듈 필드)인 설정의 필드를 채울 때는 JSON()과 JSONModuleObject() 함수를 사용해요:

caddyconfig.JSON()은 모듈 이름을 포함하지 않고 모듈 값을 마샬링할 때 사용해요. (모듈 이름이 맵 키인 ModuleMap 필드에 주로 사용돼요.)
caddyconfig.JSONModuleObject()는 모듈 이름을 객체에 추가해 모듈 값을 마샬링할 때 사용해요. (그 외 거의 모든 곳에서 사용돼요.)

Caddyfile 서버 타입

커스텀 Caddyfile 형식을 구현하는 것도 가능해요. Caddyfile 어댑터는 단일 어댑터 구현이며 기본 "서버 타입"은 HTTP예요. 하지만 등록 시 대체 "서버 타입"을 지원해요. 예를 들어 HTTP Caddyfile은 이렇게 등록돼요:

func init() {
	caddyconfig.RegisterAdapter("caddyfile",  caddyfile.Adapter{ServerType: ServerType{}})
}

caddyfile.ServerType인터페이스를 구현하고 그에 따라 자신의 어댑터를 등록하면 돼요.

더 알아보기 (Learn more)

Caddy 공식 문서