opencode-workflow/design-idea/translate/skills/be-api-design/SKILL.md

---
name: be-api-design
description: "Backend Agent 使用此技能設計 API 規格。根據 PRD 產出 OpenAPI 3.0 規格，包含端點、請求/回應結構、錯誤處理。觸發時機：PRD 通過後（Stage 4）。"
---

# /be-api-design — API 設計

Backend Agent 使用此技能設計 API 規格。

## 職責

1. 分析 PRD 中的功能性需求
2. 使用 `design-an-interface` 探索多種 API 設計方案
3. 設計 RESTful API 端點
4. 定義請求/回應 schema
5. 設計錯誤處理機制
6. 產出 OpenAPI 3.0 規格

## 輸入

- PRD 文件 (`docs/prd/{date}-{feature}.md`)
- 現有 API 風格 (專案中現有的 API 規格)
- 資料模型上下文

## 輸出

- API 規格文件: `docs/api/{date}-{feature}.yaml` (OpenAPI 3.0)

## 流程

```
讀取 PRD
    ↓
識別資源與操作
    ↓
呼叫 design-an-interface 探索 2-3 種設計方案
    ↓
選定最佳方案
    ↓
定義 OpenAPI Schema
    ↓
設計錯誤處理
    ↓
安全性審查
    ↓
產出 OpenAPI 文件
```

### 步驟說明

**1. 讀取 PRD**

從 PRD 中提取所有功能性需求，識別：
- 資源（名詞）：使用者、訂單、商品等
- 操作（動詞）：建立、讀取、更新、刪除等
- 關係：資源之間的關聯（一對多、多對多）
- 非功能性需求：分頁、速率限制、認證等

**2. 識別資源與操作**

將功能性需求映射為 RESTful 資源：
- 每個名詞 → 潛在資源
- 每個動詞 → HTTP method
- 每個關係 → 巢狀資源或獨立端點

**3. 呼叫 design-an-interface**

使用 `design-an-interface` 技能，產生 2-3 種截然不同的 API 設計方案：
- 方案 A：最小化方法數（每個資源 1-3 個端點）
- 方案 B：最大化彈性（支援多種使用情境）
- 方案 C：最佳化最常見的操作

比較各方案的優劣，選定最佳設計。

**4. 定義 OpenAPI Schema**

使用下方模板產出完整的 OpenAPI 3.0 規格。

**5. 安全性審查**

確認所有端點都有適當的認證機制和權限控制。

**6. 產出文件**

儲存至 `docs/api/{date}-{feature}.yaml`。

## 設計原則

### RESTful 設計

```yaml
資源導向:
  - URL 代表資源，而非動作
  - HTTP 方法代表動作

範例:
  GET    /api/v1/users              # 列出使用者
  GET    /api/v1/users/{id}         # 取得特定使用者
  POST   /api/v1/users              # 建立使用者
  PUT    /api/v1/users/{id}         # 完整更新
  PATCH  /api/v1/users/{id}         # 部分更新
  DELETE /api/v1/users/{id}         # 刪除使用者

巢狀資源:
  GET    /api/v1/users/{id}/orders  # 取得使用者的訂單
  POST   /api/v1/users/{id}/orders  # 為使用者建立訂單
```

### HTTP 狀態碼

```yaml
成功:
  200: OK                          # GET, PUT, PATCH, DELETE 成功
  201: Created                     # POST 成功建立資源
  204: No Content                  # DELETE 成功，無回應內容

客戶端錯誤:
  400: Bad Request                 # 請求格式錯誤
  401: Unauthorized                # 未認證
  403: Forbidden                   # 無權限
  404: Not Found                   # 資源不存在
  409: Conflict                    # 資源衝突 (如重複)
  422: Unprocessable Entity        # 驗證錯誤
  429: Too Many Requests           # 速率限制

伺服器錯誤:
  500: Internal Server Error       # 伺服器內部錯誤
  502: Bad Gateway                 # 上游服務錯誤
  503: Service Unavailable         # 服務暫時不可用
```

### 回應格式

```yaml
成功回應:
  type: object
  properties:
    data:
      type: object
    meta:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer

錯誤回應:
  type: object
  properties:
    error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
```

## OpenAPI 3.0 模板

```yaml
openapi: 3.0.3
info:
  title: {API 名稱}
  version: 1.0.0
  description: |
    {描述}

    Related PRD: {PRD 連結}

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: 列出使用者
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: search
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      summary: 建立使用者
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 建立成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/ValidationError'

  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string

    get:
      summary: 取得使用者
      tags:
        - Users
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: 完整更新使用者
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

    patch:
      summary: 部分更新使用者
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUserRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: 刪除使用者
      tags:
        - Users
      responses:
        '204':
          description: 刪除成功
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "usr_123456"
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          example: "John Doe"
        status:
          type: string
          enum: [active, inactive, suspended]
          example: "active"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - email
        - name
        - status
        - created_at
        - updated_at

    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        name:
          type: string
          minLength: 1
          maxLength: 100
      required:
        - email
        - password
        - name

    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
        status:
          type: string
          enum: [active, inactive]

    PatchUserRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        status:
          type: string
          enum: [active, inactive]

    UserResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/User'

    UserListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            total_pages:
              type: integer

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string

  responses:
    BadRequest:
      description: 請求格式錯誤
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: 未認證
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: 資源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ValidationError:
      description: 驗證錯誤
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalError:
      description: 伺服器內部錯誤
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []
```

## 設計檢查清單

### 安全性
- [ ] 所有端點都有適當的認證機制
- [ ] 輸入驗證完整
- [ ] 速率限制設計
- [ ] CORS 配置

### 效能
- [ ] 分頁支援
- [ ] 快取策略
- [ ] 批次操作支援

### 可靠性
- [ ] 錯誤回應格式統一
- [ ] 重試機制建議
- [ ] 冪等性設計

### 一致性
- [ ] 命名規範一致 (資源用名詞複數)
- [ ] 回應格式一致 (data/meta/error 結構)
- [ ] 篩選/排序/分頁參數一致

## 相依技能

- **前置**: `write-a-prd` (PRD 通過後)
- **輔助**: `design-an-interface` (探索多種設計方案)
- **後續**: `dba-schema` (DB Schema 設計)
- **退回**: 可退回 `write-a-prd` 修改需求

## 退回機制

```
Design Review 退回 API 設計
    ↓
修改 OpenAPI 規格
    ↓
重新提交 (或重新呼叫 design-an-interface)

DBA Agent 發現 Schema 衝突
    ↓
協商調整 domain model 或 API 回應格式
    ↓
更新 OpenAPI 規格
```