Claude Code для scaffold’а Go API: согласованные handler’ы и сервисы

Почему Go API становятся неуправляемыми, если паттерны не зафиксированы рано

Go API обычно стартуют чисто: несколько endpoint’ов, один-два человека, и всё живёт в головах. Затем API растёт, функции доставляются под давлением, и мелкие различия прокрадываются. Каждое из них кажется безобидным, но вместе они замедляют любые будущие изменения.

Типичный пример: один handler декодирует JSON в структуру и возвращает 400 с понятным сообщением, другой возвращает 422 с другой формой ответа, а третий логирует ошибки в другом формате. Ничто из этого не ломает компиляцию. Но всё это создаёт постоянную необходимость принимать решения и переписывать мелочи при добавлении нового кода.

Вы почувствуете беспорядок в таких местах как:

• Разные тела ошибок между endpoint’ами, из‑за этого клиентам нужны специальные кейсы.
• Сервисы, которые иногда возвращают сырые ошибки базы, а иногда «дружественные».
• Дрейф в нейминге (CreateUser, AddUser, RegisterUser), из‑за чего сложнее искать.
• Валидация, которая перемещается по коду, и те же баги постоянно возвращаются.

Под «scaffolding» здесь понимается повторяемый шаблон для новой работы: куда идёт код, что делает каждый слой и как выглядят ответы. Это не столько о генерации тонны кода, сколько о фиксации согласованной структуры.

Инструменты вроде Claude могут помочь быстро scaffold’ить новые endpoint’ы, но они полезны только если вы воспринимаете паттерн как правило. Вы определяете правила, ревьюите каждый дифф и запускаете тесты. Модель заполняет стандартные части; она не должна переопределять вашу архитектуру.

Выберите одно разделение слоёв: handler, service и доступ к данным

Go API остаётся простым в росте, когда каждый запрос идёт по одному и тому же пути. Перед тем как генерировать endpoint’ы, выберите одно разделение слоёв и придерживайтесь его.

Ответственности, простыми словами

Работа handler’а — только HTTP: прочитать запрос, вызвать сервис и записать ответ. В нём не должно быть бизнес-правил, SQL или логики «только для этого случая».

Сервис отвечает за use case: бизнес-правила, решения и оркестрацию между репозиториями или внешними вызовами. Он не должен знать про HTTP‑вопросы вроде статус-кодов, заголовков или того, как рендерятся ошибки.

Доступ к данным (репозиторий/стор) отвечает за детали персистенции. Он переводит намерение сервиса в SQL/запросы/транзакции. Он не должен навязывать бизнес-правила за пределами базовой целостности данных и не должен формировать API-ответы.

Контрольный список разделения, который остаётся практичным:

• Handler: разбирает вход, вызывает сервис, маппит ошибки в HTTP, пишет JSON
• Service: применяет бизнес-правила, вызывает репозитории, возвращает доменные результаты или типизированные ошибки
• Доступ к данным: выполняет запросы, маппит строки в структуры, возвращает ошибки хранилища
• Shared: общие типы ошибок и хелперы ответа
• Ни один слой не пропускает другой (handler никогда не вызывает репозиторий напрямую)

Одно правило для валидации

Выберите одно правило и не отступайте.

Простой подход:

• Handlers делают «shape validation» (обязательные поля, базовый формат).
• Services делают «meaning validation» (права, инварианты, состояние).

Пример: handler проверяет, что email присутствует и похож на email. Сервис проверяет, что email разрешён и ещё не используется.

Что переносится между слоями

Решите заранее, возвращают ли сервисы доменные типы или DTO.

Чистый дефолт: handler’ы используют request/response DTO, сервисы — доменные типы, а handler маппит доменный тип в response. Это держит сервис стабильным, даже если HTTP-контракт меняется.

Если маппинг кажется тяжёлым, всё равно держите это последовательно: пусть сервис возвращает доменный тип плюс типизированную ошибку, а JSON‑формирование остаётся в handler’е.

Определите стандартный ответ с ошибкой и карту статус-кодов

Если вы хотите, чтобы сгенерированные endpoint’ы выглядели так, будто их писал один человек, зафиксируйте формат ошибок как можно раньше. Генерация работает лучше, когда формат вывода не обсуждаем: одна JSON‑форма, одна карта статус-кодов и одно правило по тому, что можно показывать клиенту.

Начните с единого «конверта» ошибки, который возвращают все endpoint’ы при неудаче. Держите его маленьким и предсказуемым:

{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "details": {
    "fields": {
      "email": "must be a valid email address",
      "age": "must be greater than 0"
    }
  },
  "request_id": "req_01HR..."
}

Используйте code для машин (стабильный и предсказуемый) и message для людей (краткое и безопасное). Помещайте опциональные структурированные данные в details. Для валидации простая карта details.fields удобна для генерации и отображения в клиентах рядом с полями формы.

Далее зафиксируйте карту статус-кодов и придерживайтесь её. Чем меньше споров по каждому endpoint’у, тем лучше. Если вы хотите 400 и 422, сделайте разделение явным:

• bad_json -> 400 Bad Request (неверный JSON)
• validation_failed -> 422 Unprocessable Content (корректный JSON, неверные поля)
• not_found -> 404 Not Found
• conflict -> 409 Conflict (дубликат, рассогласование версий)
• unauthorized -> 401 Unauthorized
• forbidden -> 403 Forbidden
• internal -> 500 Internal Server Error

Решите, что логировать, а что возвращать. Хорошее правило: клиент получает безопасное сообщение и request_id; в логах — полный стек и внутренний контекст (SQL, входящие payload’ы upstream, ID пользователей), которые нельзя показывать клиенту.

Наконец, стандартизируйте request_id. Принимайте входной заголовок с ID, если он есть (от API‑gateway), иначе генерируйте его на краю (middleware). Кладите его в context, включайте в логи и возвращайте в каждом ответе об ошибке.

Расположение папок и нейминг, которые делают генерацию предсказуемой

Если вы хотите, чтобы scaffolding оставался согласованным, структура папок должна быть скучной и повторяемой. Генераторы следуют шаблонам, которые видны в проекте, но дрейф возникает, когда файлы разбросаны или имена меняются в зависимости от фичи.

Выберите одну конвенцию нейминга и не отступайте. Выберите одно слово для каждого понятия и придерживайтесь его: handler, service, repo, request, response. Если маршрут — POST /users, называйте файлы и типы вокруг users и create (а не иногда register, иногда addUser).

Простая структура, соответствующая распространённым слоям:

internal/
  httpapi/
    handlers/
    users_handler.go
  services/
    users_service.go
  data/
    users_repo.go
  apitypes/
    users_types.go

Решите, где лежат общие типы — это именно то место, где проекты часто путаются. Одно полезное правило:

• API request/response типы живут в internal/apitypes (соответствуют JSON и требованиям валидации).
• Доменные типы живут ближе к слою сервиса (соответствуют бизнес-правилам).

Если тип имеет JSON-тэги и предназначен для клиентов, обращайтесь с ним как с API-типом.

Держите зависимости handler’ов минимальными и сформулируйте это явно:

• Handlers импортируют только: routing/http, context, apitypes и services
• Services импортируют: доменные типы и доступ к данным
• Data access импортирует: драйвер базы данных и хелперы запросов
• Никакой handler не импортирует пакет базы данных напрямую

Напишите короткий паттерн-док в корне репозитория (обычный Markdown подходит). Включите дерево папок, правила нейминга и один маленький пример потока (handler -> service -> repo и в каких файлах что лежит). Это та самая точная справка, которую вы вставляете в генератор, чтобы новые endpoint’ы соответствовали структуре каждый раз.

Создайте один эталонный endpoint, который задаёт паттерн

Перед тем как генерировать десять endpoint’ов, сделайте один, которому вы доверяете. Это эталон: файл, на который вы указываете и говорите «Новый код должен выглядеть так». Можно написать его с нуля или отрефакторить существующий, пока он не станет соответствовать правилам.

Держите handler тонким. Один приём, который сильно помогает: положите интерфейс между handler’ом и сервисом, чтобы handler зависел от контракта, а не от конкретной структуры.

Добавьте небольшие комментарии в эталонном endpoint’е только там, где генерируемый код может запутаться. Объясните решения (почему 400 vs 422, почему create возвращает 201, зачем скрывать внутренние ошибки за общим сообщением). Пропустите комментарии, которые просто пересказывают код.

Когда эталонный endpoint работает, извлеките хелперы, чтобы у каждого нового endpoint’а было меньше шансов уйти в дрейф. Самые переиспользуемые хелперы обычно:

• Bind JSON и обработка некорректного тела
• Валидация ввода и возврат полевых ошибок
• Последовательная запись JSON-ответов
• Маппинг доменных ошибок в HTTP-статусы

Вот как «тонкий handler + интерфейс» может выглядеть на практике:

type UserService interface {
	CreateUser(ctx context.Context, in CreateUserInput) (User, error)
}

func (h *Handler) CreateUser(w http.ResponseWriter, r *http.Request) {
	var in CreateUserRequest
	if err := BindJSON(r, &in); err != nil {
		WriteError(w, ErrBadJSON) // 400: malformed JSON
		return
	}
	if err := Validate(in); err != nil {
		WriteError(w, err) // 422: validation details
		return
	}
	user, err := h.svc.CreateUser(r.Context(), in.ToInput())
	if err != nil {
		WriteError(w, err)
		return
	}
	WriteJSON(w, http.StatusCreated, user)
}

Закрепите это парой тестов (хотя бы небольшой таблицей тестов для маппинга ошибок). Генерация работает лучше, когда у неё есть одна чистая цель для имитации.

Пошагово: заставьте Claude сгенерировать endpoint, который совпадёт с паттерном

Согласованность начинается с того, что вы вставляете и что запрещаете. Для нового endpoint’а дайте две вещи:

1. Ваш эталонный endpoint («идеальный» пример)
2. Короткую заметку о паттерне, где указаны пакеты, функции и хелперы, которые обязаны использоваться

1) Сначала предоставьте контекст (reference + правила)

Включите handler, метод сервиса, request/response типы и любые общие хелперы, которые использует endpoint. Затем пропишите контракт простыми словами:

• Маршрут + метод (пример: POST /v1/widgets)
• Поля JSON запроса (обязательные vs опциональные)
• Форма JSON ответа
• Кейсы ошибок и статус-коды
• Файлы, которые вы ожидаете получить обратно (и только эти файлы)

Будьте явны в том, что должно совпадать: нейминги, пути пакетов и имена хелперов (WriteJSON, BindJSON, WriteError, ваш валидатор).

2) Попросите результат в точной форме, которую вы хотите

Жёсткая подсказка предотвращает «полезные» рефакторинги. Например:

Using the reference endpoint below and the pattern notes, generate a new endpoint.
Contract:
- Route: POST /v1/widgets
- Request: {"name": string, "color": string}
- Response: {"id": string, "name": string, "color": string, "createdAt": string}
- Errors: invalid JSON -> 400; validation -> 422; duplicate name -> 409; unexpected -> 500
Output ONLY these files:
1) internal/http/handlers/widgets_create.go
2) internal/service/widgets.go (add method only)
3) internal/types/widgets.go (add types only)
Do not change: router setup, existing error format, existing helpers, or unrelated files.
Must use: package paths and helper functions exactly as in the reference.

Если используете тесты — запрашивайте их явно (и указывайте имя тест‑файла). Иначе модель может пропустить тесты или придумать собственный тестовый сетап.

Сделайте быструю проверку диффа после генерации. Если сгенерированный код изменил общие хелперы, регистрацию роутера или стандартный формат ошибок — отклоняйте и жёстче повторяйте правила «не менять».

Шаблон подсказки, который можно переиспользовать для scaffold’а endpoint’ов

Выход будет таким же последовательным, как и вход. Быстрее всего избежать «почти правильного» кода — каждый раз переиспользовать одну шаблонную подсказку с небольшим фрагментом контекста из вашего репозитория.

Шаблон подсказки

Скопируйте, вставьте и заполните плейсхолдеры:

You are editing an existing Go HTTP API.

CONTEXT
- Folder tree (only the relevant parts):
  <paste a small tree: internal/http, internal/service, internal/repo, etc>
- Key types and patterns:
  - Handler signature style: <example>
  - Service interface style: <example>
  - Request/response DTOs live in: <package>
- Standard error response JSON:
  {
    "error": {
      "code": "invalid_argument",
      "message": "...",
      "details": {"field": "reason"}
    }
  }
- Status code map:
  invalid_json -> 400
  invalid_argument -> 422
  not_found -> 404
  conflict -> 409
  internal -> 500

TASK
Add a new endpoint: <METHOD> <PATH>
- Handler name: <Name>
- Service method: <Name>
- Request JSON example:
  {"name":"Acme"}
- Success response JSON example:
  {"id":"123","name":"Acme"}

CONSTRAINTS
- No new dependencies.
- Keep functions small and single-purpose.
- Match existing naming, folder layout, and error style exactly.
- Do not refactor unrelated files.

ACCEPTANCE CHECKS
- Code builds.
- Existing tests pass (add tests only if the repo already uses them for handlers/services).
- Run gofmt on changed files.

FINAL INSTRUCTION
Before writing code, list any assumptions you must make. If an assumption is risky, ask a short question instead.

Это работает, потому что заставляет три вещи: блок контекста (что уже есть), блок ограничений (что нельзя делать) и конкретные JSON‑примеры (чтобы формы не ушли в дрейф). Финальная инструкция — это предохранитель: если модель не уверена, она должна спросить, прежде чем вносить изменения.

Реалистичный пример: добавить Create endpoint без нарушения стиля

Допустим, вы хотите добавить endpoint «Create project». Цель проста: принять имя, применить пару правил, сохранить и вернуть новый ID. Сложность в том, чтобы сохранить разделение handler-service-repo и формат ошибок, который вы уже используете.

Согласованный поток выглядит так:

• Handler: bind JSON, базовая валидация полей, вызов сервиса
• Service: бизнес-правила (например, уникальность), вызов репозитория, возврат доменного результата
• Repo: писать в Postgres, вернуть сгенерированный ID

Вот запрос, который принимает handler:

{ "name": "Roadmap", "owner_id": "u_123" }

Успех — 201 Created. ID должен приходить из одного места всегда. Например, пусть Postgres его генерирует, а репозиторий возвращает:

{ "id": "p_456", "name": "Roadmap", "owner_id": "u_123", "created_at": "2026-01-09T12:34:56Z" }

Два реалистичных пути неудачи:

Если валидация не проходит (имя отсутствует или слишком короткое), верните полевую ошибку в вашем стандартном формате и выбранный статус-код:

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid request", "details": { "name": "must be at least 3 characters" } } }

Если имя должно быть уникально для владельца и сервис обнаруживает уже существующий проект, верните 409 Conflict:

{ "error": { "code": "PROJECT_NAME_TAKEN", "message": "Project name already exists", "details": { "name": "Roadmap" } } }

Одно решение, которое упрощает паттерн: handler проверяет «правильна ли форма запроса?», а сервис владеет вопросом «разрешено ли это?». Такое разделение делает сгенерированные endpoint’ы предсказуемыми.

Распространённые ошибки, разрушающие согласованность (и как их избежать)

Самый быстрый путь потерять согласованность — позволить генератору импровизировать.

Один из дрейфов — новая форма ошибки. Один endpoint возвращает {error: "..."}, другой {message: "..."}, третий добавляет вложенный объект. Исправляйте это, сохранив один конверт ошибок и одну карту статус-кодов в одном месте, затем требуйте, чтобы новые endpoint’ы переиспользовали их по пути импорта и имени функции. Если генератор предлагает новое поле — рассмотрите это как запрос на изменение API, а не как удобство.

Другой дрейф — раздутые handler’ы. Всё начинается невинно: валидировать, потом проверить права, потом запросить БД, потом ветвление по бизнес-правилам. Скоро каждый handler выглядит по‑разному. Держите правило: handler переводит HTTP в типизированные входы и выходы; сервисы владеют решениями; доступ к данным — запросами.

Несоответствие в нейминге тоже накапливается. Если один endpoint использует CreateUserRequest, а другой — NewUserPayload, вы потеряете время на поиск типов и написание glue‑кода. Выберите схему нейминга и отклоняйте новые имена без серьёзной причины.

Никогда не возвращайте сырые ошибки базы данных клиентам. Помимо утечки деталей, это создаёт несогласованные сообщения и статус-коды. Оборачивайте внутренние ошибки, логируйте причину и возвращайте стабильный публичный код.

Избегайте добавления новых библиотек «ради удобства». Каждая дополнительная валидация, хелпер роутера или пакет ошибок становится ещё одним стилем, который нужно поддерживать.

Защитные механизмы, которые предотвращают большую часть поломок:

• Требуйте, чтобы новые endpoint’ы переиспользовали существующие типы ошибок и хелперы.
• Держите handler’ы без бизнес-правил и доступа к базе.
• Принуждайте к единой конвенции нейминга для request/response структур.
• Маппьте внутренние ошибки в публичные коды, не возвращайте сырые ошибки.
• Добавляйте зависимости только при очевидной и документированной необходимости.

Если вы не можете сравнить два endpoint’а и увидеть одинаковую форму (импорты, поток, обработку ошибок), ужесточайте подсказку и регенерите перед мерджем.

Быстрая чек-лист перед мерджем сгенерированного endpoint’а

Перед мерджем сначала проверьте структуру. Если форма правильная, логические баги легче заметить.

Проверки структуры:

• Flow handler’а соответствует: bind input, validate, вызвать сервис, маппинг доменных ошибок в HTTP, записать ответ.
• Код сервиса содержит только бизнес-правила: без HTTP или JSON‑работы.
• Успешные ответы соответствуют вашему стилю (либо общий конверт повсюду, либо прямой JSON повсюду).
• Ошибки единообразны: те же поля JSON, те же коды, одинаковое поведение request_id.
• Нейминг и расположение скучные: имена файлов, функций и роутов совпадают с существующими, и всё отформатировано gofmt.

Проверки поведения:

• Запустите тесты и добавьте хотя бы один маленький тест для новой ветки handler/service.
• Подтвердите, что ошибки валидации возвращают тот же код и статус, что и похожие endpoint’ы.
• Спровоцируйте одну известную сервисную ошибку (например, not found или conflict) и подтвердите HTTP‑статус и форму JSON.
• Просканируйте на оставшиеся от копипаста следы: неверный путь, неправильное сообщение в логе, несоответствующие имена DTO.
• Сборка и запуск сервера локально, чтобы гарантировать корректность wiring и импортов.

Следующие шаги: стандартизируйте паттерн, затем безопасно масштабируйте генерацию

Воспринимайте паттерн как общий контракт, а не как предпочтение. Держите документ «как мы строим endpoint’ы» рядом с кодом и поддерживайте один эталонный endpoint, который показывает полный подход от конца до конца.

Масштабируйте генерацию маленькими пачками. Генерируйте 2–3 endpoint’а, которые покрывают разные сценарии (простой чтение, create с валидацией, update с not-found). Затем остановитесь и доработайте. Если в ревью постоянно всплывает один и тот же дрейф — обновите базовый документ и эталонный endpoint прежде чем генерировать дальше.

Цикл, который можно повторять:

• Запишите базу: имена файлов, имена функций, request/response структуры, коды ошибок и где происходит валидация.
• Держите один endpoint «золотым» и обновляйте его первым, когда паттерн меняется.
• Пакетно сгенерируйте пару endpoint’ов, проверьте консистентность, затем подправьте подсказку и документ паттерна.
• Рефакторите старые endpoint’ы порциями и держите путь отката, если поведение изменится.
• Слежение за метрикой: время на добавление endpoint’а, частота багов после мерджа или время в ревью.

Если нужен более жёсткий цикл билд‑ревью, платформа vibe-coding вроде Koder.ai (koder.ai) может помочь scaffold’ить и итерировать быстро в чат‑оркестровке, затем экспортировать код, когда он совпадает с вашим стандартом. Инструмент менее важен, чем правило: ваша baseline‑документация должна оставаться главным источником истины.