어댑터 패턴
기존 API의 호출 방식과 값의 의미를 애플리케이션의 약속에 맞추는 구조 패턴.
· 마지막 업데이트: 2026-11-07 · 14 min read
개요
연결 규격이 다른 기기 사이에 끼우는 어댑터처럼, 소프트웨어의 어댑터도 양쪽의 사용 방식을 맞춰 준다. 규격만 다를 뿐, 양쪽이 하는 일은 같다.
실내 온도를 보여 주는 화면은 섭씨를 쓰는데 오래된 센서 API가 화씨를 반환하면, 둘 다 숫자라서 86을 그대로 넘겨도 문법 오류는 나지 않지만 화면에는 엉뚱한 온도가 뜬다. 화면은 그 숫자가 섭씨라고 믿는다. 호출하는 쪽이 기대하는 단위로 맞춰 주는 코드가 필요한 이유가 여기에 있다. 값이 틀렸다는 사실은 컴파일 단계에서 드러나지 않는다.
여기서는 화면이 기대하는 호출과 센서가 실제로 제공하는 호출을 갈라 둔다. 기존 객체의 호출 방식을 다른 인터페이스에 맞추는 구조가 어댑터(Adapter) 패턴이다. 여기서 인터페이스란 호출부가 믿고 쓰는 약속이며, ReadCelsius()를 부르면 섭씨 값이 나온다는 정도의 보장인 셈이다. 어댑터는 기존 센서를 고치지 않고 그 센서를 참조해 두며, 필요한 변환만 대신 맡는다.
나중에 켈빈 센서로 바꾸더라도, 그 센서에 맞는 어댑터를 하나 끼워 두면 화면 쪽 코드는 그대로 ReadCelsius()를 부른다. 센서마다 다른 사용법은 각자의 어댑터 안에 갇힌다. 교체할 때 손대는 곳이 어댑터 하나로 줄어든다.
UML
이 분리는 UML에서 세 클래스로 나뉘어 드러난다. RoomMonitor는 온도를 쓰는 호출부고, ICelsiusThermometer는 그 호출부가 요구하는 인터페이스다. FahrenheitAdapter는 이 인터페이스를 구현하되 실제 작업은 기존 LegacyThermometer에 넘긴다. 이렇게 다른 객체에 일을 맡기는 것을 위임이라고 부른다.
그림의 표기를 먼저 읽어 두면 호출 방향이 분명해진다. 실선 화살표는 객체를 참조하는 방향, 점선에 빈 삼각형이 붙은 것은 인터페이스 구현을 뜻한다. 호출은 RoomMonitor → FahrenheitAdapter → LegacyThermometer 순서로 들어가고, 돌아온 화씨 값은 어댑터가 섭씨로 바꿔서 넘긴다.
역사
Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides는 1994년에 출간한 Design Patterns에서 Adapter를 구조 패턴으로 정리했다. 네 저자를 가리키는 이름이 GoF다.1
책의 사례는 기존 텍스트 표시 도구를 그림 편집기의 도형 인터페이스에 맞춰 재사용하는 문제다. 상속으로 맞추는 클래스 어댑터와, 기존 객체를 참조하는 객체 어댑터를 구별한다. 위 UML과 아래 C# 코드는 객체 어댑터에 해당한다.2
표준 라이브러리에서도 이런 연결을 찾을 수 있다. Java의 InputStreamReader는 바이트를 읽는 InputStream을 받아 문자 인코딩 규칙에 따라 해석하고, 문자용 Reader 인터페이스로 사용하게 한다. 공식 문서에 따르면 1997년 출시된 JDK 1.1부터 표준 라이브러리에 포함되었다.3
왜 사용하는가?
화면과 로그, 경보가 각자 기존 센서를 직접 읽는다고 해 보면, 세 곳 모두 화씨 변환과 외부 API의 호출 방식을 알아야 한다. 호출부가 늘어날수록 같은 지식이 복사된다. 센서를 바꿀 때면 이 코드들을 같이 고쳐야 하니, 변환을 한 객체에 모으고 내부에서는 같은 약속을 쓰게 만든다.
메서드 이름만 바꿔서 끝나는 일이 아니라, 반환 단위와 인자 순서, 시간대, 실패 코드까지 호출부가 기대하는 의미에 맞춰야 한다. 외부 업체가 주는 SDK를 감쌀 때도 경계를 잡는 기준은 같다. 실패한 측정을 0도로 바꿔 버리면, 호출부는 장애를 실제 측정값으로 받아들인다. 그래서 어댑터가 흉내 내야 하는 것은 시그니처뿐이 아니다.
반대로 어댑터를 두지 않는 편이 나은 경우도 있다. 호출부가 하나뿐이고 계산도 한 번이면 변환 함수 하나로 충분하다. 어댑터 객체를 둘 이유는 여러 호출부가 같은 인터페이스를 공유하거나, 외부 구현을 갈아 끼워야 할 때 생긴다. 어댑터가 서로 다른 호출 약속을 맞춘다면, 데코레이터는 약속을 그대로 두고 동작만 덧붙인다. 퍼사드는 여러 하위 기능을 하나의 진입점으로 묶는 쪽에 가깝다.
예제
아래 예제는 화씨 값을 반환하는 기존 센서 인터페이스를 섭씨 기반의 실내 온도 모니터에 연결하는 구조를 보여 준다.
using System;
using System.Globalization;
var legacy = new LegacyThermometer(86m);
ICelsiusThermometer sensor = new FahrenheitAdapter(legacy);
new RoomMonitor(sensor).Print();
// 호출부는 센서 종류 대신 섭씨를 읽는 공통 약속을 사용한다.
public interface ICelsiusThermometer
{
decimal ReadCelsius();
}
public sealed class LegacyThermometer
{
private readonly decimal fahrenheit;
public LegacyThermometer(decimal fahrenheit) => this.fahrenheit = fahrenheit;
public decimal ReadFahrenheit() => fahrenheit;
}
// 화씨를 섭씨로 바꾸는 계산을 이 어댑터 안에 둔다.
public sealed class FahrenheitAdapter : ICelsiusThermometer
{
private readonly LegacyThermometer legacy;
public FahrenheitAdapter(LegacyThermometer legacy) => this.legacy = legacy;
public decimal ReadCelsius() => (legacy.ReadFahrenheit() - 32m) * 5m / 9m;
}
public sealed class RoomMonitor
{
private readonly ICelsiusThermometer sensor;
public RoomMonitor(ICelsiusThermometer sensor) => this.sensor = sensor;
public void Print()
{
string value = sensor.ReadCelsius().ToString("F1", CultureInfo.InvariantCulture);
Console.WriteLine($"Room: {value} Celsius");
}
}Room: 30.0 CelsiusRoomMonitor.Print()가 ReadCelsius()를 부르면 어댑터 쪽에서 ReadFahrenheit()가 실행되고, 를 거치면 86 °F가 30 °C가 된다. 5m 같은 표기는 decimal 값이므로 정수 나눗셈으로 계산하지 않는다. 호출부 어디에도 기존 센서의 타입이나 화씨 변환식은 나오지 않는다. 변환은 이 한 번의 호출 안에서 끝난다.
확장 예제
센서 두 종류와 실패 결과
센서가 둘이 되면 실패를 알리는 방식도 함께 정해야 한다. 이번에는 화씨 센서와 켈빈 센서를 함께 쓰는데, 화씨 센서는 성공 여부를 bool로 돌려주고, 켈빈 센서는 수치를 그대로 반환한다. 두 API의 생김새가 이렇게 다른데, 호출부가 그 차이를 알 필요는 없다. ICelsiusThermometer가 섭씨 측정의 성공 여부와, 실패했다면 그 이유까지 함께 돌려주도록 한 이유다.
결과는 성공 값과 오류 코드 가운데 하나만 담는다. Reading.Success에는 섭씨 값이 들어가고, Reading.Failure에는 오류 코드가 들어간다. Offline은 측정 자체가 불가능한 상태, InvalidReading은 이 예제에서 허용하지 않는 절대영도 미만의 값이다. 호출부 입장에서는 센서가 무엇이든 성공과 실패를 같은 방식으로 처리하면 된다.
using System;
using System.Globalization;
ICelsiusThermometer[] sensors =
{
new FahrenheitAdapter(new LegacySensor(86m, online: true)),
new KelvinAdapter(new KelvinSensor(300m)),
new FahrenheitAdapter(new LegacySensor(0m, online: false)),
new KelvinAdapter(new KelvinSensor(-1m))
};
foreach (ICelsiusThermometer sensor in sensors)
{
Reading result = sensor.ReadCelsius();
if (result is Reading.Success success)
Console.WriteLine("Celsius: " + success.Celsius.ToString("F2", CultureInfo.InvariantCulture));
if (result is Reading.Failure failure)
Console.WriteLine("Error: " + failure.Code);
}
public enum SensorError { Offline, InvalidReading }
public abstract record Reading
{
private Reading() { }
public sealed record Success(decimal Celsius) : Reading;
public sealed record Failure(SensorError Code) : Reading;
public static Reading FromCelsius(decimal value) => value < -273.15m
? new Failure(SensorError.InvalidReading)
: new Success(value);
}
// 호출부는 센서 종류 대신 섭씨 값 또는 실패라는 공통 결과를 사용한다.
public interface ICelsiusThermometer
{
Reading ReadCelsius();
}
public sealed class LegacySensor
{
private readonly decimal fahrenheit;
private readonly bool online;
public int Calls { get; private set; }
public LegacySensor(decimal fahrenheit, bool online)
{
this.fahrenheit = fahrenheit;
this.online = online;
}
public bool TryRead(out decimal value)
{
Calls++;
value = fahrenheit;
return online;
}
}
public sealed class KelvinSensor
{
private readonly decimal kelvin;
public KelvinSensor(decimal kelvin) => this.kelvin = kelvin;
public decimal ReadKelvin() => kelvin;
}
// 외부 API의 단위와 실패 의미를 이 어댑터 안에서 맞춘다.
public sealed class FahrenheitAdapter : ICelsiusThermometer
{
private readonly LegacySensor sensor;
public FahrenheitAdapter(LegacySensor sensor) => this.sensor = sensor;
public Reading ReadCelsius()
{
if (!sensor.TryRead(out decimal value))
return new Reading.Failure(SensorError.Offline);
if (value < -459.67m)
return new Reading.Failure(SensorError.InvalidReading);
return Reading.FromCelsius((value - 32m) / 9m * 5m);
}
}
public sealed class KelvinAdapter : ICelsiusThermometer
{
private readonly KelvinSensor sensor;
public KelvinAdapter(KelvinSensor sensor) => this.sensor = sensor;
public Reading ReadCelsius()
{
decimal value = sensor.ReadKelvin();
if (value < 0m)
return new Reading.Failure(SensorError.InvalidReading);
return Reading.FromCelsius(value - 273.15m);
}
}Celsius: 30.00
Celsius: 26.85
Error: Offline
Error: InvalidReading센서마다 다른 실패 신호가 어댑터를 지나며 하나로 모인다. 각 어댑터는 단위를 바꾼 다음 같은 결과 형식으로 돌려준다. 연결이 끊긴 화씨 센서는 수치를 쓰지 않고 Offline을 내놓고, -1 K는 InvalidReading으로 거절한다. 덕분에 호출부는 정상 측정값과 장애를 구별할 수 있다.
변환식의 계산 순서까지 어댑터가 챙긴다. 화씨 변환은 허용 범위를 먼저 확인하고, 9로 나눈 뒤에 5를 곱한다. 아주 큰 decimal 값에서 중간 곱셈이 넘치는 일을 피하려는 순서다. 이 검사가 잡아내는 것은 범위를 벗어난 입력과 통신 실패이며, 센서가 현실에서 정확히 측정했는지까지 알아내 주지는 않는다.
적용 범위
어댑터가 맡는 범위를 넘어서는 판단은 이렇게 남겨 둔다. 재시도, 마지막 값 사용, 기본값 반환은 이 어댑터의 동작에 넣지 않았다. 필요해지면 어느 실패를 몇 번까지 재시도할지, 이전 값을 언제까지 허용할지를 별도 정책으로 정해야 한다.
두 센서 클래스는 예제를 위한 대역이다. 실제 SDK가 예외를 던진다면 그 경계에서 호출부의 오류 계약으로 바꿔 주고, 취소와 연결 종료, 장비 수명도 실제 API에 맞춰 다뤄야 한다. 예제 코드를 실제 장비에 붙일 때 손볼 지점이 여기에 있다.
TypeScript 예제
센서별 단위 변환과 실패 판정은 어댑터가 맡고, 온도를 쓰는 쪽은 섭씨 결과만 받는다. 외부 API가 바뀌어도 화면마다 변환식을 고치지 않게 하려는 분리다. 다음 코드는 확장 예제의 두 센서와 실패 결과를 TypeScript로 옮긴다. 언어만 바뀌고 역할은 그대로다.
type Reading = { ok: true; celsius: number } |
{ ok: false; code: "Offline" | "InvalidReading" };
// 호출부는 센서 종류 대신 섭씨 값 또는 실패라는 공통 결과를 사용한다.
interface ICelsiusThermometer { readCelsius(): Reading; }
class LegacySensor {
constructor(private readonly fahrenheit: number, private readonly online: boolean) {}
tryRead(): { online: boolean; value: number } {
return { online: this.online, value: this.fahrenheit };
}
}
class KelvinSensor {
constructor(private readonly kelvin: number) {}
readKelvin(): number { return this.kelvin; }
}
// 외부 API의 단위와 실패 의미를 이 어댑터 안에서 맞춘다.
class FahrenheitAdapter implements ICelsiusThermometer {
constructor(private readonly sensor: LegacySensor) {}
readCelsius(): Reading {
const reading = this.sensor.tryRead();
if (!reading.online) return { ok: false, code: "Offline" };
if (!Number.isFinite(reading.value) || reading.value < -459.67)
return { ok: false, code: "InvalidReading" };
// 절대영도를 기준으로 계산해 경계값이 반올림 때문에 하한 아래로 내려가지 않게 한다.
return { ok: true, celsius: (reading.value + 459.67) / 9 * 5 - 273.15 };
}
}
class KelvinAdapter implements ICelsiusThermometer {
constructor(private readonly sensor: KelvinSensor) {}
readCelsius(): Reading {
const value = this.sensor.readKelvin();
if (!Number.isFinite(value) || value < 0) return { ok: false, code: "InvalidReading" };
return { ok: true, celsius: value - 273.15 };
}
}
const sensors: ICelsiusThermometer[] = [
new FahrenheitAdapter(new LegacySensor(86, true)),
new KelvinAdapter(new KelvinSensor(300)),
new FahrenheitAdapter(new LegacySensor(0, false)),
new KelvinAdapter(new KelvinSensor(-1)),
];
for (const sensor of sensors) {
const result = sensor.readCelsius();
console.log(result.ok ? "Celsius: " + result.celsius.toFixed(2) : "Error: " + result.code);
}Celsius: 30.00
Celsius: 26.85
Error: Offline
Error: InvalidReading계산 방식이 달라진 부분만 짚어 두자. number는 C# decimal과 달리 이진 부동소수점이므로 출력 자릿수는 toFixed(2)로 정했다. 유효하지 않은 값이나 오프라인 상태를 0도로 바꾸지 않는 것은 마찬가지다.
입력과 출력 타입을 잇는 Adapter<TSource, TTarget>
기존 센서는 밀리도 단위의 측정값을 주지만 호출부는 섭씨 숫자를 읽는 Reader<double>을 원한다고 하자. Adapter<TSource, TTarget>는 기존 값을 읽는 함수와 값을 바꾸는 함수를 받아, 호출부가 기대하는 Read() 계약으로 연결한다. 여기서는 센서 클래스 대신 함수 두 개로 같은 분리를 만든다.
타입 매개변수는 양쪽 타입이 다르다는 사실을 코드에 적어 두는 장치다. TSource와 TTarget은 서로 달라도 된다. 여기서는 LegacyReading을 double 또는 number로 바꾸며, 기존 센서가 Measure()라는 이름을 쓴다는 사실과 밀리도 환산은 어댑터를 조립하는 곳에 남는다. 호출부는 그 차이를 모르고 Read()만 호출한다.
C#
using System;
using System.Globalization;
var sensor = new LegacySensor();
IReader<double> reader = new Adapter<LegacyReading, double>(
sensor.Measure, value => value.MilliCelsius / 1000.0);
Console.WriteLine(reader.Read().ToString("F1", CultureInfo.InvariantCulture));
// TYPES
sealed record LegacyReading(int MilliCelsius);
sealed class LegacySensor
{
public LegacyReading Measure() => new(21500);
}
interface IReader<T> { T Read(); }
sealed class Adapter<TSource, TTarget> : IReader<TTarget>
{
private readonly Func<TSource> readSource;
private readonly Func<TSource, TTarget> convert;
public Adapter(Func<TSource> readSource, Func<TSource, TTarget> convert)
{ this.readSource = readSource; this.convert = convert; }
// 호출부에는 목표 계약만 보이고 기존 API와 단위 변환은 여기서 만난다.
public TTarget Read() => convert(readSource());
}21.5TypeScript
type LegacyReading = Readonly<{ milliCelsius: number }>;
class LegacySensor {
measure(): LegacyReading { return { milliCelsius: 21500 }; }
}
interface Reader<T> { read(): T; }
class Adapter<TSource, TTarget> implements Reader<TTarget> {
constructor(
private readonly readSource: () => TSource,
private readonly convert: (value: TSource) => TTarget,
) {}
// 기존 API의 이름과 단위는 호출부의 Reader 계약 밖으로 옮긴다.
read(): TTarget { return this.convert(this.readSource()); }
}
const sensor = new LegacySensor();
const reader: Reader<number> = new Adapter<LegacyReading, number>(
() => sensor.measure(), value => value.milliCelsius / 1000,
);
console.log(reader.read().toFixed(1));21.5형식이 연결됐다고 단위와 값의 범위까지 맞아지는 것은 아니므로 변환 함수에 그 규칙을 구현한다. 이 예제는 센서가 유효한 정수 밀리도 값을 준다는 조건에서 단위만 바꾼다.
타입 매개변수와 라이브러리 계약의 문법은 공식 문서에서 확인할 수 있다.4
같이 보기
각주
- Gamma, Helm, Johnson, Vlissides. Design Patterns (1994). 출판사 서지. ↩
- GoF. Adapter 저자 발췌. 클래스·객체 어댑터와 텍스트 표시 도구의 재사용 사례. ↩
- Oracle. InputStreamReader, Since 1.1. JVM 명세의 출시 연혁 표, JDK 1.1: February 1997. ↩
- C# generics; TypeScript generics ↩