Adapter: подружить несовместимых

Adapter: подружить несовместимых

Внешний SDK почти никогда не говорит на том же языке, что и твой код. Adapter - это переходник, который снимает эту боль без переписывания всего вокруг.

Проблема

Ты подключил SDK для отправки SMS. У него метод Push(phone, msg) (int, error). А твой код ожидает интерфейс Send(to, text) error. Имена не совпадают, сигнатуры разные, возвращаемые типы другие.

Менять свой код под каждый SDK - плохая идея. Менять SDK - невозможно. Нужен переходник.

Решение: Adapter

Adapter - обёртка, которая транслирует один интерфейс в другой. Как переходник с европейской розетки на американскую: внутри ток тот же, но вилка подходит.

Adapter как переходник между интерфейсами

Адаптер над внешним SMS API

// Наш интерфейс - так мы хотим работать с SMS
type SmsSender interface {
    Send(to, text string) error
}

// Внешний клиент (из чужого SDK) - не наш интерфейс
type ThirdPartySmsClient struct{}
func (c *ThirdPartySmsClient) Push(phone string, msg string) (int, error) {
    // отправка через внешний API
    return 200, nil
}

// Адаптер - переводит наш интерфейс в вызовы SDK
type SmsAdapter struct {
    client *ThirdPartySmsClient
}

func (a *SmsAdapter) Send(to, text string) error {
    code, err := a.client.Push(to, text)
    if err != nil {
        return fmt.Errorf("sms send failed: %w", err)
    }
    if code != 200 {
        return fmt.Errorf("sms api returned code %d", code)
    }
    return nil
}

Теперь бизнес-логика зависит от SmsSender, а не от конкретного SDK - классическая иллюстрация DIP:

type NotificationService struct {
    sms SmsSender  // интерфейс, а не конкретный клиент
}

func (s *NotificationService) NotifyUser(phone, msg string) error {
    return s.sms.Send(phone, msg)
}

Сменили SDK? Написали новый адаптер - остальной код не трогаем.

// Наш интерфейс - так мы хотим работать с SMS
interface SmsSender
{
    public function send(string $to, string $text): void;
}

// Внешний клиент (из чужого SDK) - не наш интерфейс
final class ThirdPartySmsClient
{
    public function push(string $phone, string $msg): int
    {
        return 200;
    }
}

// Адаптер - переводит наш интерфейс в вызовы SDK
final class SmsAdapter implements SmsSender
{
    public function __construct(
        private readonly ThirdPartySmsClient $client,
    ) {}

    public function send(string $to, string $text): void
    {
        $code = $this->client->push($to, $text);
        if ($code !== 200) {
            throw new RuntimeException("sms api returned code $code");
        }
    }
}

Бизнес-логика зависит от интерфейса, а не от SDK:

final class NotificationService
{
    public function __construct(
        private readonly SmsSender $sms,
    ) {}

    public function notifyUser(string $phone, string $msg): void
    {
        $this->sms->send($phone, $msg);
    }
}

Сменили SDK? Написали новый адаптер - NotificationService не трогаем.

from typing import Protocol


class SmsSendError(Exception):
    """Наше исключение: SMS не отправлена - его и ловит бизнес-логика."""


# Наш интерфейс - так мы хотим работать с SMS
class SmsSender(Protocol):
    def send(self, to: str, text: str) -> None: ...


# Внешний клиент (из чужого SDK) - не наш интерфейс
class ThirdPartySmsClient:
    def push(self, phone: str, msg: str) -> int:
        # отправка через внешний API
        return 200


# Адаптер - переводит наш интерфейс в вызовы SDK
class SmsAdapter:
    def __init__(self, client: ThirdPartySmsClient) -> None:
        self._client = client

    def send(self, to: str, text: str) -> None:
        # Адаптер - граница слоя: исключения чужого SDK переводим в своё,
        # иначе бизнес-логике пришлось бы знать типы SDK. `from e` - не аналог
        # errors.Is: ловят по типу нового исключения, исходное - в __cause__
        try:
            code = self._client.push(to, text)
        except Exception as e:
            raise SmsSendError("sms send failed") from e
        if code != 200:
            raise SmsSendError(f"sms api returned code {code}")

Бизнес-логика зависит от протокола, а не от SDK:

class NotificationService:
    def __init__(self, sms: SmsSender) -> None:  # протокол, а не конкретный клиент
        self._sms = sms

    def notify_user(self, phone: str, msg: str) -> None:
        self._sms.send(phone, msg)


service = NotificationService(SmsAdapter(ThirdPartySmsClient()))
service.notify_user("+79001112233", "Welcome!")

Сменили SDK? Написали новый адаптер - NotificationService не трогаем. Вместо возврата ошибки, как в Go, адаптер бросает своё исключение и через raise ... from e сохраняет исходное - аналог %w.

Object Adapter vs Class Adapter

В классических языках есть два варианта:

Object Adapter (композиция)Class Adapter (наследование)
Адаптер содержит объект adapteeАдаптер наследует от adaptee
adapter.client.Push(...)super.Push(...)
Гибче: можно менять adapteeЖёстче: привязан к конкретному классу
Работает в Go ✅Не работает в Go ❌ (нет наследования)

В Go всегда Object Adapter - через поле структуры. Это и есть рекомендуемый подход.

ℹ️ Adapter в Go = почти всегда

Каждый раз, когда ты оборачиваешь внешнюю зависимость своим интерфейсом - ты пишешь Adapter. Это один из самых частых паттернов в Go backend-разработке.

Adapter в Go stdlib

os.File           реализует io.Reader, io.Writer, io.Closer
 - адаптирует системные вызовы ОС под стандартные интерфейсы

bytes.NewReader   принимает []byte и возвращает io.Reader
 - адаптирует слайс байт под интерфейс чтения

http.HandlerFunc  адаптирует функцию func(w, r) под интерфейс http.Handler
 - не нужно создавать структуру с методом ServeHTTP

http.HandlerFunc - элегантный пример: это адаптер, который превращает простую функцию в полноценный http.Handler. В PHP той же идее соответствует маленький класс-адаптер: он принимает замыкание и реализует нужный интерфейс (например, PSR-15 RequestHandlerInterface), вызывая замыкание внутри handle(). Один __invoke для этого не годится: интерфейс в PHP реализуется только явным implements и методом с нужным именем.

// Без адаптера - нужна структура
type myHandler struct{}
func (h myHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello"))
}

// С адаптером HandlerFunc - достаточно функции
http.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello"))
}))
<?php
declare(strict_types=1);

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

// Без адаптера - нужен отдельный класс
final class HelloHandler implements RequestHandlerInterface
{
    public function __construct(
        private readonly ResponseFactory $responses,
    ) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        return $this->responses->text('hello');
    }
}

// С адаптером - обычная функция-замыкание превращается в Handler
final class CallableHandler implements RequestHandlerInterface
{
    /** @param callable(ServerRequestInterface): ResponseInterface $fn */
    public function __construct(
        private $fn,
    ) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        return ($this->fn)($request);
    }
}

$router->add('/', new CallableHandler(
    fn (ServerRequestInterface $r): ResponseInterface => $responses->text('hello'),
));
from typing import Callable

Request = dict[str, str]
Response = bytes


# Без адаптера - нужен класс с методом serve_http
class MyHandler:
    def serve_http(self, req: Request) -> Response:
        return b"hello"


# С адаптером HandlerFunc - достаточно функции
class HandlerFunc:
    def __init__(self, fn: Callable[[Request], Response]) -> None:
        self._fn = fn

    def serve_http(self, req: Request) -> Response:
        return self._fn(req)


router.handle("/", HandlerFunc(lambda req: b"hello"))
# В Flask/FastAPI эту роль играет декоратор @app.get("/"):
# он берёт функцию и регистрирует её как объект-обработчик маршрута

Composability: обёртки над одним интерфейсом складываются

В Go обёртки легко комбинируются благодаря интерфейсам. Чаще всего в одной цепочке встречаются адаптер и несколько декораторов:

// Адаптер здесь один - os.File: приводит файловый дескриптор ОС к io.Reader.
// Дальше слои-декораторы: контракт io.Reader тот же, добавляется поведение.
file, err := os.Open("data.gz") // io.Reader (файл)
if err != nil {
    return err
}
defer file.Close()

gzReader, err := gzip.NewReader(file) // io.Reader (распаковка)
if err != nil {
    return err
}
defer gzReader.Close()

scanner := bufio.NewScanner(gzReader) // потребитель: даёт построчный API
for scanner.Scan() {
    fmt.Println(scanner.Text())
}
return scanner.Err()

Первые слои принимают и возвращают io.Reader, поэтому их можно складывать в любом порядке, а bufio.Scanner на конце потребляет поток и даёт построчный API (сам он уже не io.Reader). Строго говоря, gzip.NewReader и bufio.NewReader - это декораторы: интерфейс не меняется, добавляется поведение. Такая цепочка - основа Go I/O.

Когда НЕ использовать

Интерфейсы совпадают - если внешний SDK уже реализует нужный интерфейс, адаптер лишний.

Одноразовый вызов - если ты дёргаешь SDK в одном месте и не собираешься его менять, прямой вызов проще.

Adapter ≠ всё переименовать - адаптер не просто меняет имена методов. Он переводит вызов целиком: преобразует типы, обрабатывает ошибки, маппит коды ответов, но не добавляет бизнес-логику.

⚠️ Не путай Adapter и Facade

Adapter подгоняет ОДИН интерфейс под другой. Facade упрощает доступ к НЕСКОЛЬКИМ подсистемам. Если ты оборачиваешь один SDK - это Adapter. Если координируешь 3 сервиса - это Facade.

Связь с другими паттернами

Adapter + Factory - фабрика создаёт нужный адаптер по конфигу
Adapter + Decorator - адаптер меняет интерфейс, декоратор добавляет поведение
Adapter + DI - адаптер инжектится как реализация интерфейса

Adapter - это практическое воплощение DIP: домен объявляет свой интерфейс, адаптер живёт на периферии и переводит его в вызовы внешнего SDK.

Мини-задание

  • Оберни 1 внешний сервис (HTTP-клиент, SDK) адаптером со своим интерфейсом
  • Напиши мок для своего интерфейса и используй его в тесте вместо реального SDK
  • Посмотри как http.HandlerFunc адаптирует функцию в интерфейс - напиши аналогичный адаптер для своего кейса
  • Попробуй выстроить цепочку обёрток над io.Reader (файл → gzip → bufio) и для каждого слоя определи: адаптер это или декоратор

Зарегистрируйтесь бесплатно, чтобы пройти квиз, решить задание с автопроверкой, вести прогресс.