后端控制器模式

David-Li04062026-10-25查看 1251复制 68

该技能为跨任何框架设计后端控制器层提供通用指南。在实现 REST 端点、处理 HTTP 状态码、管理分页或构建 API 请求/响应处理结构时应使用此技能。

📘如何使用这个技能

1
复制技能内容·点击上方「Copy SKILL.md」复制全部内容，或 Download 下载到本地
2
打开你的 AI 客户端·支持 Claude Code、Trae、Cursor、ChatGPT、DeepSeek、Kimi 等任意 AI 助手
3
粘贴为系统提示/知识文件·Claude Code：放入 .claude/skills/ 目录；普通对话：作为首条消息发送并说「请严格按这份技能文档执行」
4
直接提出你的需求·AI 会按技能定义的工作流、格式和约束来处理，无需再解释背景

💡 提示：技能生效后，每次对话只需一句需求，AI 会按 SKILL.md 的流程执行。

SKILL.md2880 chars

---
name: backend-controller-pattern
description: This skill provides general guidelines for designing backend controller layers across any framework. It should be used when implementing REST endpoints, handling HTTP status codes, managing pagination, or structuring API request/response handling.
---

# Backend Controller Pattern Skill

**General guidelines for API Boundaries.**

for framework-specifics, see:
- **[NestJS Controllers](backend-controller-pattern-nestjs/SKILL.md)**

For validation/serialization rules, see:
- **[Data Validation](data-validation/SKILL.md)**

## Core Responsibilities

1. **Accept HTTP requests** (Method, Body, Query, Headers)
2. **Validate input** (Check format, required fields)
3. **Call Service Layer** (Delegate business logic)
4. **Serialize Response** (Transform/Filter data)
5. **Handle Errors** (Map exceptions to HTTP Status codes)

## HTTP Status Codes

**Use standard REST conventions**:

| Operation | Status | Meaning |
| :--- | :--- | :--- |
| **Create** | `201` | Created successfully |
| **Read** | `200` | Found and returned |
| **Update** | `200` | Updated successfully |
| **Delete** | `204` | Deleted (No Content) |
| **Error** | `4xx` | Client Error (Bad input, Auth) |
| **Error** | `5xx` | Server Error (Bug, Downtime) |

## Input Validation

**Principle: Validate at the Gate.**

- **Never** let invalid data reach business logic.
- **Never** trust client input (even from your own frontend).
- **Transform** API format (`snake_case`) to Internal format (`camelCase`).

See **[Data Validation Skill](data-validation/SKILL.md)** for detailed Schema definitions.

## Response Serialization

**Principle: Filter at the Exit.**

- **Always** return consistent JSON structures.
- **Never** expose Database IDs (`BigInt`), use UIDs (`string`).
- **Never** expose internal fields (`password`, `deletedAt`).
- **Transform** Internal format (`camelCase`) to API format (`snake_case`).

## Pagination

**Principle: Always Limit Lists.**

Unbounded queries are a DoS vector and performance killer.

**Standard Response Format**:
```json
{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 150
  }
}
```

## Authorized vs Authenticated

**Understand the difference**:

- **Authentication (401)**: "Who are you?" (Login check)
- **Authorization (403)**: "Are you allowed?" (Permission check)

## Layer Boundaries

**Strict separation of concerns**:

```
[ HTTP Controller ]  <-- Knows about Requests, Responses, Status Codes
        |
        v
[ Business Service ] <-- Knows about Logic, Transactions, Domain Errors
        |
        v
[ Data Repository ]  <-- Knows about Database, SQL, ORM
```

**Anti-Patterns**:
- ❌ **Controller running SQL queries** (Leaky abstraction)
- ❌ **Controller containing complex logic** (Fat controller)
- ❌ **Service returning HTTP objects** (Service coupled to transport)

来源：skillsdirectory

后端控制器模式

📘如何使用这个技能

评论0