Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

api-design-assistant

/api-design-assistant

Prowadzi projektowanie API według dobrych praktyk REST, GraphQL i gRPC, także przy wersjonowaniu i przeglądzie endpointów.

Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

84/ 100Klasa: dobry
Format9 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi projektowanie API według dobrych praktyk REST, GraphQL i gRPC, także przy wersjonowaniu i przeglądzie endpointów.

Oryginalny opis (EN)

引导 API 设计,遵循 REST、GraphQL 与 gRPC 最佳实践。 Use when: 设计 API、审查端点、API 版本策略决策。 Not for: 验证运行中的 API 是否符合消费端期待——请用 /contract-test;API 背后的 schema 设计——请用 /database。 Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 接口设计, 端点, 版本策略.

Jak działa

  1. 快速参考 — REST 惯例
  2. 设计工作流程
  3. 版本策略
  4. 使用方式
  5. 下一步引导
  6. 参考
  7. 版本历史
  8. 授权
Sekcje z nagłówków SKILL.md, w oryginale · 100 linii, 329 słów
Podgląd SKILL.md
---
source: ../../../../skills/api-design-assistant/SKILL.md
source_version: 1.0.0
translation_version: 1.1.0
last_synced: 2026-10-11
source_hash: 11f1ca291530
status: current
description: |
  引导 API 设计,遵循 REST、GraphQL 与 gRPC 最佳实践。
  Use when: 设计 API、审查端点、API 版本策略决策。
  Not for: 验证运行中的 API 是否符合消费端期待——请用 /contract-test;API 背后的 schema 设计——请用 /database。
  Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 接口设计, 端点, 版本策略.
---

# API 设计助手

> **语言**: [English](../../../../skills/api-design-assistant/SKILL.md) | 简体中文

引导 API 设计,遵循 REST、GraphQL 和 gRPC 最佳实践。

## 快速参考 — REST 惯例

### HTTP 方法

| 方法 | 用途 | 幂等性 |
|------|------|--------|
| GET | 读取资源 | 是 |
| POST | 创建资源 | 否 |
| PUT | 替换资源 | 是 |
| PATCH | 部分更新 | 否 |
| DELETE | 删除资源 | 是 |

### 状态码

| 代码 | 说明 |
|------|------|
| 200 | 成功 |
| 201 | 已创建 |
| 204 | 无内容(删除成功) |
| 400 | 请求格式错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 422 | 验证失败 |
| 429 | 请求过多(限流) |
| 500 | 服务器内部错误 |

### URL 命名规则

| 模式 | 示例 | 说明 |
|------|------|------|
| 集合 | `/users` | 资源集合 |
| 单一资源 | `/users/{id}` | 单一资源 |
| 子资源 | `/users/{id}/orders` | 子资源 |
| 动作 | `/users/{id}/activate` | 动作(仅限 POST) |

## 设计工作流程

```
DEFINE ──► DESIGN ──► VALIDATE ──► DOCUMENT
```

### 1. Define — 定义需求
厘清使用者、使用场景、数据模型和非功能性需求。

### 2. Design — 设计端点
套用 RESTful 惯例、定义请求/响应 Schema、规划版本策略。

### 3. Validate — 验证一致性
检查命名一致性、错误格式统一、分页模式。

### 4. Document — 生成文档
产出 OpenAPI/Swagger 规格或 GraphQL Schema 文档。

## 版本策略

| 策略 | 示例 | 优点 |
|------|------|------|
| URL 路径 | `/v1/users` | 简单、明确 |
| Header | `Accept: application/vnd.api+json;v=1` | URL 干净 |
| Query | `/users?version=1` | 容易测试 |

## 使用方式

- `/api-design` - 交互式 API 设计引导
- `/api-design /users` - 审查特定端点设计
- `/api-design --graphql` - GraphQL Schema 设计引导

## 下一步引导

`/api-design` 完成后,AI 助手应建议:

> **API 设计完成。建议下一步:**
> - 执行 `/sdd` 建立正式规格文档 ⭐ **推荐**
> - 执行 `/testing` 规划 API 测试策略
> - 执行 `/docs` 生成 API 文档
> - 审查安全性 → 执行 `/security`

## 参考

- 核心规范:[api-design-standards.md](../../../../core/api-design-standards.md)

## 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| 1.0.0 | 2026-03-23 | 初始版本 |

## 授权

CC BY 4.0 — 文档内容

Wersje

RepozytoriumWynikLicencja
Ta strona · AsiaOstrich/universal-dev-standards84MIT
ArabelaTso/Skills-4-SE100Apache-2.0
AsiaOstrich/universal-dev-standards95MIT

Migawka bazy z 13.11.2026 · wersja paczki b8efe1bc188f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90api-design
    Prowadzi projektowanie API według dobrych praktyk REST, GraphQL i gRPC: nazewnictwo, semantykę HTTP, wersjonowanie i punkty końcowe.
  • 90api-design
    Prowadzi projektowanie API zgodnie z dobrymi praktykami REST, GraphQL i gRPC: endpointy, przeglądy i strategię wersjonowania.
  • 90proof-api
    Buduje zestawy testów API: testy endpointów, kontraktowe i obciążeniowe dla REST, GraphQL i gRPC.
  • 100api-design
    Podaje dobre praktyki projektowania API REST, GraphQL i gRPC: kontrakty, wersjonowanie, OpenAPI 3.2, GraphQL Federation i strumieniowanie gRPC.
  • 100api-design
    Projektuje kontrakty REST, GraphQL i OpenAPI przed implementacją w podejściu API-first.
  • 90api-design
    Podpowiada wzorce projektowania API: nazewnictwo REST, paginację, błędy, schematy GraphQL, strumienie gRPC i wersjonowanie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.