القائمة
API設計エージェント - リファクタリング後のマイクロサービスAPI設計。REST/GraphQL/gRPC/AsyncAPIの仕様書、API Gateway設計、認証・認可設計を策定。/design-api [対象パス] で呼び出し。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/majiayu000/claude-skill-registry --skill design-apiيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | design-api |
| description | API設計エージェント - リファクタリング後のマイクロサービスAPI設計。REST/GraphQL/gRPC/AsyncAPIの仕様書、API Gateway設計、認証・認可設計を策定。/design-api [対象パス] で呼び出し。 |
| user_invocable | true |
リファクタリング後のマイクロサービスAPIを設計するエージェントです。
このエージェントは、マイクロサービス設計の結果をもとに、以下を策定します：
以下の中間ファイルが存在すること：
01_analysis/ 配下の分析結果03_design/target-architecture.md03_design/scalardb-schema.md（存在する場合）設計結果は reports/03_design/ に出力します。
重要: 各ステップ完了時に即座にファイルを出力してください。
reports/03_design/
├── api-design-overview.md # API設計概要
├── api-specifications/ # API仕様書ディレクトリ
│ ├── openapi/ # OpenAPI (REST) 仕様
│ │ └── [service]-api.yaml
│ ├── graphql/ # GraphQL スキーマ
│ │ └── [service]-schema.graphql
│ ├── grpc/ # gRPC プロトコル定義
│ │ └── [service].proto
│ └── asyncapi/ # AsyncAPI (イベント) 仕様
│ └── [service]-events.yaml
├── api-gateway-design.md # API Gateway設計
└── api-security-design.md # 認証・認可設計
あなたはAPI設計の専門家です。以下の手順で設計を実行してください。
API設計の基本原則：
| 原則 | 説明 |
|---|---|
| Contract First | 実装前にAPI仕様を定義 |
| Consumer Driven | 利用者のニーズを優先 |
| Consistency | 命名規則、エラー形式の統一 |
| Versioning | 後方互換性を保つバージョン管理 |
| Security by Design | セキュリティを最初から考慮 |
| Documentation | 常に最新のドキュメント |
| Observability | トレーシング、ログ、メトリクス |
各サービス・ユースケースに適した通信パターンを選定：
## API通信パターン選定
### サービス別API方式
| サービス | 外部API | 内部API | イベント | 選定理由 |
|---------|--------|--------|---------|---------|
| Order Service | REST | gRPC | Kafka | CRUDメイン、高性能内部通信 |
| Product Service | GraphQL | gRPC | - | 柔軟なクエリ要件 |
| Notification Service | - | gRPC | Kafka | イベント駆動 |
### 通信パターン判断基準
| パターン | 適用条件 | メリット | デメリット |
|---------|---------|---------|----------|
| REST | CRUD操作、外部公開 | 標準的、ツール豊富 | オーバーフェッチ |
| GraphQL | 複雑なクエリ、BFF | 柔軟、効率的 | 学習コスト |
| gRPC | 内部通信、高性能 | 高速、型安全 | ブラウザ非対応 |
| AsyncAPI | イベント駆動 | 疎結合、スケーラブル | 複雑性 |
# URL設計規則
paths:
# リソース（複数形）
/orders:
get: 注文一覧取得
post: 注文作成
/orders/{orderId}:
get: 注文詳細取得
put: 注文更新
delete: 注文削除
# サブリソース
/orders/{orderId}/items:
get: 注文明細一覧
post: 注文明細追加
# アクション（動詞が必要な場合）
/orders/{orderId}/actions/cancel:
post: 注文キャンセル
openapi: 3.1.0
info:
title: "[Service Name] API"
version: "1.0.0"
description: |
[サービスの説明]
contact:
name: API Support
email: api-support@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://api-staging.example.com/v1
description: Staging
tags:
- name: orders
description: 注文関連API
paths:
/orders:
get:
summary: 注文一覧取得
operationId: listOrders
tags: [orders]
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageToken'
- name: status
in: query
schema:
[]
[]
[, , , ]
[, , , , ]
[, ]
## エラーレスポンス標準
### HTTPステータスコード
| コード | 意味 | 使用場面 |
|-------|-----|---------|
| 400 | Bad Request | バリデーションエラー |
| 401 | Unauthorized | 認証エラー |
| 403 | Forbidden | 認可エラー |
| 404 | Not Found | リソース不在 |
| 409 | Conflict | 競合（楽観ロック失敗等） |
| 422 | Unprocessable Entity | ビジネスルール違反 |
| 429 | Too Many Requests | レート制限超過 |
| 500 | Internal Server Error | サーバーエラー |
| 503 | Service Unavailable | サービス一時停止 |
### エラーレスポンス形式
```json
{
"code": "ORDER_ALREADY_CANCELLED",
"message": "注文は既にキャンセルされています",
"details": [
{
"field": "orderId",
"reason": "Order with id '123' is already in CANCELLED status"
}
],
"traceId": "abc123xyz",
"timestamp": "2024-01-15T10:30:00Z"
}
### Step 4: GraphQL設計
#### 4.1 スキーマ設計
```graphql
# schema.graphql
"""
注文サービス GraphQL スキーマ
"""
type Query {
"""注文を取得"""
order(id: ID!): Order
"""注文一覧を取得"""
orders(
filter: OrderFilter
pagination: PaginationInput
): OrderConnection!
"""顧客の注文を取得"""
ordersByCustomer(customerId: ID!): [Order!]!
}
type Mutation {
"""注文を作成"""
createOrder(input: CreateOrderInput!): CreateOrderPayload!
"""注文をキャンセル"""
cancelOrder(input: CancelOrderInput!): CancelOrderPayload!
"""注文ステータスを更新"""
updateOrderStatus(input: UpdateOrderStatusInput!): UpdateOrderStatusPayload!
}
type Subscription {
"""注文ステータス変更を購読"""
orderStatusChanged(orderId: ID!): OrderStatusChangedEvent!
}
# Types
type Order implements Node {
id: ID!
customer: Customer!
status: OrderStatus!
items: [OrderItem!]!
totalAmount: Money!
createdAt: DateTime!
updatedAt: DateTime!
}
type OrderItem {
id: ID!
product: Product!
quantity: Int!
unitPrice: Money!
subtotal: Money!
}
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
enum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
# Inputs
input CreateOrderInput {
customerId: ID!
items: [OrderItemInput!]!
shippingAddress: AddressInput!
}
input OrderItemInput {
productId: ID!
quantity: Int!
}
input OrderFilter {
status: [OrderStatus!]
customerId: ID
createdAfter: DateTime
createdBefore: DateTime
}
# Payloads
type CreateOrderPayload {
order: Order
errors: [UserError!]!
}
type UserError {
field: [String!]
message: String!
code: String!
}
# Scalars
scalar DateTime
scalar Money
## GraphQL設計原則
### 命名規則
- Query: `order`, `orders`, `ordersByCustomer`（名詞）
- Mutation: `createOrder`, `updateOrder`, `cancelOrder`（動詞+名詞）
- Subscription: `orderStatusChanged`（過去分詞+Event）
### ペイロードパターン
- Mutation結果は専用Payloadタイプを返す
- errorsフィールドでユーザー向けエラーを返す
- 成功時もエラー時も同じ型で返す
### ページネーション
- Relay Connection仕様に準拠
- edges, pageInfo, totalCountを含む
### N+1問題対策
- DataLoaderパターンを使用
- @defer, @streamディレクティブの活用
// order_service.proto
syntax = "proto3";
package order.v1;
option java_multiple_files = true;
option java_package = "com.example.order.v1";
option go_package = "github.com/example/order/v1;orderv1";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
// 注文サービス
service OrderService {
// 注文を作成
rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
// 注文を取得
rpc GetOrder(GetOrderRequest) returns (Order);
// 注文一覧を取得
rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
// 注文をキャンセル
rpc CancelOrder(CancelOrderRequest) returns (Order);
// 注文ステータスをストリーミング
rpc WatchOrderStatus(WatchOrderStatusRequest) returns (stream OrderStatusEvent);
}
// メッセージ定義
message Order {
string id = 1;
string customer_id = 2;
OrderStatus status = 3;
repeated OrderItem items = 4;
int64 total_amount = 5; // 金額は最小単位（円）
google.protobuf.Timestamp created_at = 6;
google.protobuf.Timestamp updated_at = 7;
}
message OrderItem {
string id = 1;
string product_id = 2;
int32 quantity = 3;
int64 unit_price = 4;
}
enum OrderStatus {
ORDER_STATUS_UNSPECIFIED = 0;
ORDER_STATUS_PENDING = 1;
ORDER_STATUS_CONFIRMED = 2;
ORDER_STATUS_SHIPPED = 3;
ORDER_STATUS_DELIVERED = 4;
ORDER_STATUS_CANCELLED = 5;
}
// リクエスト/レスポンス
message CreateOrderRequest {
string customer_id = 1;
repeated CreateOrderItem items = 2;
Address shipping_address = 3;
}
message CreateOrderItem {
string product_id = 1;
int32 quantity = 2;
}
message CreateOrderResponse {
Order order = 1;
}
message GetOrderRequest {
string id = 1;
}
message ListOrdersRequest {
int32 page_size = 1;
string page_token = 2;
OrderFilter filter = 3;
}
message OrderFilter {
repeated OrderStatus statuses = 1;
string customer_id = 2;
}
message ListOrdersResponse {
repeated Order orders = 1;
string next_page_token = 2;
int32 total_count = 3;
}
message CancelOrderRequest {
string id = 1;
string reason = 2;
}
message WatchOrderStatusRequest {
string order_id = 1;
}
message OrderStatusEvent {
string order_id = 1;
OrderStatus previous_status = 2;
OrderStatus current_status = 3;
google.protobuf.Timestamp changed_at = 4;
}
message Address {
string postal_code = 1;
string prefecture = 2;
string city = 3;
string street = 4;
string building = 5;
}
## gRPC設計原則
### バージョニング
- パッケージ名にバージョンを含める: `order.v1`
- 破壊的変更時は新バージョン作成: `order.v2`
### フィールド番号
- 1-15: 頻繁に使用するフィールド（1バイト）
- 16以降: それ以外のフィールド
- 削除したフィールド番号は再利用しない
### エラーハンドリング
- google.rpc.Statusを使用
- 詳細エラーはdetailsフィールドで返す
### ストリーミング
- Server Streaming: 大量データ、リアルタイム更新
- Client Streaming: バッチ処理
- Bidirectional: チャット、リアルタイム同期
# order-events.asyncapi.yaml
asyncapi: 3.0.0
info:
title: Order Events API
version: 1.0.0
description: 注文サービスが発行するイベント
servers:
production:
host: kafka.example.com:9092
protocol: kafka
description: Production Kafka
channels:
order.created:
address: order.created
messages:
orderCreated:
$ref: '#/components/messages/OrderCreated'
order.status.changed:
address: order.status.changed
messages:
orderStatusChanged:
$ref: '#/components/messages/OrderStatusChanged'
order.cancelled:
address: order.cancelled
messages:
orderCancelled:
$ref: '#/components/messages/OrderCancelled'
operations:
publishOrderCreated:
action: send
channel:
$ref: '#/channels/order.created'
[, , , ]
[, , , ]
[, , ]
[, ]
[, , , , ]
このステップ完了時に出力: reports/03_design/api-gateway-design.md
## API Gateway設計
### アーキテクチャ
```mermaid
graph TB
subgraph External["外部"]
Web[Web Client]
Mobile[Mobile App]
Partner[Partner System]
end
subgraph Gateway["API Gateway Layer"]
Kong[Kong Gateway]
subgraph Plugins
Auth[認証プラグイン]
RateLimit[レート制限]
Transform[変換]
Logging[ログ]
end
end
subgraph Internal["内部サービス"]
BFF[BFF Service]
Order[Order Service]
Product[Product Service]
User[User Service]
end
Web --> Kong
Mobile --> Kong
Partner --> Kong
Kong --> BFF
Kong --> Order
Kong --> Product
Kong --> User
| パス | バックエンド | 認証 | レート制限 |
|---|---|---|---|
/api/v1/orders/* | Order Service | JWT | 100 req/min |
/api/v1/products/* | Product Service | API Key | 1000 req/min |
/api/v1/users/* | User Service | JWT | 50 req/min |
/graphql | BFF Service | JWT | 200 req/min |
/partner/v1/* | Partner API | mTLS | 500 req/min |
# kong.yml
_format_version: "3.0"
services:
- name: order-service
url: http://order-service:8080
routes:
- name: order-route
paths:
- /api/v1/orders
strip_path: false
plugins:
- name: jwt
- name: rate-limiting
config:
minute: 100
policy: local
- name: correlation-id
config:
header_name: X-Correlation-ID
generator: uuid
- name: graphql-service
url: http://bff-service:8080
routes:
- name: graphql-route
paths:
- /graphql
methods:
- POST
plugins:
-
| クライアント種別 | 制限 | 超過時の対応 |
|---|---|---|
| 一般ユーザー | 100 req/min | 429 + Retry-After |
| プレミアムユーザー | 500 req/min | 429 + Retry-After |
| パートナー | 1000 req/min | 429 + 担当者通知 |
| 内部サービス | 制限なし | - |
### Step 8: 認証・認可設計
**このステップ完了時に出力**: `reports/03_design/api-security-design.md`
```markdown
## 認証・認可設計
### 認証方式
| 方式 | 用途 | 実装 |
|-----|-----|-----|
| JWT (OAuth2) | ユーザー認証 | Keycloak |
| API Key | パートナー認証 | Kong |
| mTLS | サービス間認証 | Istio |
| Service Account | 内部バッチ | Kubernetes SA |
### OAuth2フロー
```mermaid
sequenceDiagram
participant User
participant WebApp
participant Gateway as API Gateway
participant Keycloak
participant Service
User->>WebApp: ログイン要求
WebApp->>Keycloak: 認可コードフロー開始
Keycloak->>User: ログイン画面
User->>Keycloak: 認証情報入力
Keycloak->>WebApp: 認可コード
WebApp->>Keycloak: トークン要求
Keycloak->>WebApp: Access Token + Refresh Token
WebApp->>Gateway: API要求 + Bearer Token
Gateway->>Gateway: JWT検証
Gateway->>Service: 要求転送 + クレーム
Service->>Gateway: レスポンス
Gateway->>WebApp: レスポンス
{
"sub": "user-123",
"iss": "https://auth.example.com",
"aud": ["order-service", "product-service"],
"exp": 1704067200,
"iat": 1704063600,
"roles": ["customer", "premium"],
"permissions": ["orders:read", "orders:create"],
"tenant_id": "tenant-abc",
"metadata": {
"customer_tier": "gold"
}
}
| ロール | 権限 | 説明 |
|---|---|---|
| admin | *:* | 全権限 |
| operator | orders:*, products:read | 運用担当 |
| customer | orders:read:own, orders:create | 一般顧客 |
| partner | orders:read, products:read | パートナー |
| viewer | *:read | 閲覧のみ |
scopes:
orders:read: 注文の参照
orders:create: 注文の作成
orders:update: 注文の更新
orders:delete: 注文の削除
orders:read:own: 自分の注文のみ参照
products:read: 商品の参照
products:write: 商品の作成・更新
users:read: ユーザー情報の参照
users:write: ユーザー情報の更新
### Step 9: API バージョニング戦略
```markdown
## APIバージョニング戦略
### バージョニング方式
| 方式 | 例 | 採用 |
|-----|---|-----|
| URLパス | `/api/v1/orders` | ✅ 推奨 |
| クエリパラメータ | `?version=1` | - |
| ヘッダー | `Accept-Version: v1` | - |
| Accept | `Accept: application/vnd.example.v1+json` | - |
### 採用方式: URLパスバージョニング
**理由:**
- 明示的で分かりやすい
- キャッシュしやすい
- ドキュメント化しやすい
- API Gatewayでルーティングしやすい
### バージョン管理ルール
| ルール | 説明 |
|-------|------|
| メジャーバージョン | 破壊的変更時にインクリメント（v1 → v2） |
| 後方互換性 | フィールド追加は同一バージョン内で可 |
| 非推奨期間 | 旧バージョンは最低6ヶ月間サポート |
| サンセット | Sunset ヘッダーで廃止日を通知 |
### 非推奨通知
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jul 2025 00:00:00 GMT
Link: </api/v2/orders>; rel="successor-version"
### Step 10: API設計概要の出力
**最終出力**: `reports/03_design/api-design-overview.md`
### Step 11: Mermaid図の検証
出力したファイルのMermaid図を検証し、エラーがあれば修正：
```bash
# 出力ファイルのMermaid検証
/fix-mermaid ./reports/03_design
検証項目:
subgraph "API Gateway Layer"）## API設計概要
### サービス別API一覧
| サービス | REST | GraphQL | gRPC | Events | 仕様書 |
|---------|------|---------|------|--------|-------|
| Order Service | ✅ | - | ✅ | ✅ | [OpenAPI](./api-specifications/openapi/order-api.yaml) |
| Product Service | ✅ | ✅ | ✅ | - | [GraphQL](./api-specifications/graphql/product-schema.graphql) |
| User Service | ✅ | - | ✅ | ✅ | [OpenAPI](./api-specifications/openapi/user-api.yaml) |
| Notification Service | - | - | ✅ | ✅ | [AsyncAPI](./api-specifications/asyncapi/notification-events.yaml) |
### エンドポイント総覧
| エンドポイント | メソッド | サービス | 認証 | 説明 |
|--------------|--------|---------|-----|------|
| `/api/v1/orders` | GET | Order | JWT | 注文一覧 |
| `/api/v1/orders` | POST | Order | JWT | 注文作成 |
| `/api/v1/orders/{id}` | GET | Order | JWT | 注文詳細 |
| `/api/v1/products` | GET | Product | API Key | 商品一覧 |
| `/graphql` | POST | BFF | JWT | GraphQLエンドポイント |
### 共通仕様
- 認証: OAuth2 (JWT)
- エラー形式: RFC 7807 Problem Details
- ページネーション: Cursor-based
- 日時形式: ISO 8601 (UTC)
- 言語: Accept-Languageヘッダーで切り替え
API設計概要（設計原則、サービス別API一覧、エンドポイント総覧、共通仕様）
各サービスのAPI仕様書（OpenAPI、GraphQL、gRPC、AsyncAPI）
API Gateway設計（アーキテクチャ、ルーティング、レート制限、Kong設定）
認証・認可設計（認証方式、OAuth2フロー、JWT設計、RBAC）
# 既存APIの抽出
mcp__serena__find_symbol で Controller/Handler クラスを検索
mcp__serena__get_symbols_overview でエンドポイント一覧を取得
# OpenAPI検証
npx @stoplight/spectral-cli lint openapi.yaml
# GraphQLスキーマ検証
npx graphql-inspector validate schema.graphql
# AsyncAPI検証
npx @asyncapi/cli validate asyncapi.yaml
# OpenAPI → HTML
npx @redocly/cli build-docs openapi.yaml
# GraphQL → ドキュメント
npx graphql-markdown schema.graphql
# AsyncAPI → HTML
npx @asyncapi/cli generate fromTemplate asyncapi.yaml @asyncapi/html-template
| アンチパターン | 問題 | 推奨 |
|---|---|---|
| 動詞URL | /getOrders, /createOrder | リソース名 + HTTPメソッド |
| ネストが深いURL | /users/1/orders/2/items/3 | 最大2階層まで |
| バージョンなし | 破壊的変更時に問題 | URLパスでバージョン管理 |
| 曖昧なエラー | {"error": "failed"} | 構造化エラーレスポンス |
| 認証情報をURLに | ?token=xxx | Authorizationヘッダー |