# backend-api-design

Задаёт агенту правила проектирования RPC-API: тонкий контроллер, менеджер с бизнес-логикой, репозиторий только для доступа к данным. Пригодится при создании новых эндпоинтов и разборе чужих паттернов.

- скилл · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 109
- Автор: c0x12c
- Лицензия: не указана · policy=link-only · показываем только описание, файл — у автора
- Исходник: https://github.com/c0x12c/ai-toolkit/tree/HEAD/toolkit/skills/backend-api-design/SKILL.md
- Обновлён: 2026-06-18
- HTML: https://affpapa.org/nevibecode/skills/backend-api-design

## Что делает

Скилл описывает жёсткие правила URL: никаких path-параметров, только `@QueryValue`; единственный ресурс — в единственном числе (`/employee`), коллекция — во множественном (`/employees`), действия выносятся в подпути вроде `/delete`, `/restore`, `/sync`. Все изменения — через `@Post`, `@Put`, `@Delete` и `@Patch` не используются.

Слои расписаны по ролям. Контроллер разбирает query-параметры с значениями по умолчанию, делегирует менеджеру и разворачивает `Either` через `.throwOrValue()`. Менеджер возвращает `Either<ClientException, T>`, оборачивает операции с базой в `transaction(db.primary) { }` и проверяет бизнес-правила. Репозиторий читает с `db.replica`, пишет в `db.primary` и всегда отсекает удалённые записи через `deletedAt.isNull()`.

Отдельный раздел про грабли. Многозначные `@QueryValue` требуют явного snake_case-имени: пишите `@QueryValue("project_id") projectId: UUID`, иначе Micronaut ищет параметр по буквальному имени, а фронтенд шлёт `project_id`. Второй вызов `.where {}` затирает первое условие — нужен `.andWhere {}`. И без `@ExecuteOn(TaskExecutors.IO)` suspend-функции могут зависнуть или уехать не в тот пул потоков, так что аннотация нужна каждому контроллеру.

## Установка

### Claude Code (родная платформа)

1. **Через Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-code
```

2. **Вручную: положить файлы**
- Файл: `~/.claude/skills/backend-api-design/SKILL.md` — Папка скилла целиком; для одного проекта — .claude/skills/backend-api-design/

### Codex

1. **Через Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a codex
```

2. **Вручную: положить файлы**
- Файл: `.agents/skills/backend-api-design/SKILL.md` — Для всех проектов — ~/.agents/skills/

### Cursor

1. **Через Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a cursor
```

2. **Вручную: положить файлы**
- Файл: `.cursor/skills/backend-api-design/SKILL.md` — Cursor читает и .agents/skills/, и .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install c0x12c/ai-toolkit backend-api-design
```

2. **Вручную: положить файлы**
- Файл: `.github/skills/backend-api-design/SKILL.md`

### Gemini CLI

1. **Через Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a gemini-cli
```

2. **Командой платформы**
```bash
gemini skills install https://github.com/c0x12c/ai-toolkit --path toolkit/skills/backend-api-design
```

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/skills/backend-api-design/SKILL.md` — Старый путь .windsurf/skills/ тоже читается

### OpenCode

**Через Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a opencode
```

### Claude.ai

**Claude.ai**
- Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/c0x12c/ai-toolkit/tree/HEAD/toolkit/skills/backend-api-design/SKILL.md

## Когда брать
- спроектировать контракт нового эндпоинта без path-параметров
- разложить бизнес-логику по контроллеру, менеджеру и репозиторию
- вынести транзакцию и возврат ошибок в менеджер, а не в контроллер
- поймать репозиторий, заинжекченный прямо в контроллер
- собрать постраничный ответ с items, total, page, limit и hasMore

## Примеры запросов агенту
- Спроектируй эндпоинты для сотрудников по правилам скилла: список, создание, удаление, восстановление
- Разбери этот контроллер и скажи, что нарушает слоистую архитектуру
- Добавь пагинацию в метод списка сотрудников, ответ собери как EmployeeListResponse

## Похожие
- [api-design-principles](https://affpapa.org/nevibecode/skills/sickn33-api-design-principles.md) — скилл · 1000 установок
- [api-design-patterns](https://affpapa.org/nevibecode/skills/bobmatnyc-api-design-patterns.md) — скилл · 566 установок
- [alchemy-api](https://affpapa.org/nevibecode/skills/alchemy-api.md) — скилл · 1600 установок
- [backend-architect](https://affpapa.org/nevibecode/agents/backend-architect.md) — субагент · 23691 установка
- [rest-api-design](https://affpapa.org/nevibecode/skills/secondsky-rest-api-design.md) — скилл · 586 установок
- [kotlin-api-design](https://affpapa.org/nevibecode/skills/kotlin-api-design.md) — скилл · 949 установок

Из того же набора: [c0x12c/ai-toolkit](https://affpapa.org/nevibecode/by/c0x12c/ai-toolkit.md) — 11 карточек

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md