integration-spec

集成规范编写指南

擅长编写全面的集成规范，作为系统之间的契约。

核心组成部分

每份集成规范都必须包含：

• 集成概述：目的、范围和高层架构
• 身份验证与授权：安全机制和令牌处理
• 端点定义：包含请求/响应架构的完整 API 契约
• 数据模型：所有数据对象的结构化定义
• 错误处理：全面的错误代码和恢复流程
• 速率限制：限流规则和配额管理
• 时序图：交互流程的可视化表示
• 测试场景：集成测试用例和验证标准

集成规范模板

# Integration Specification: [System A] ↔ [System B]

**Version:** 1.0.0
**Last Updated:** [Date]
**Authors:** [Names]
**Status:** [Draft/Review/Approved/Production]

## 1. Overview

### 1.1 Purpose
[Brief description of why this integration exists]

### 1.2 Scope
- In Scope: [What this integration covers]
- Out of Scope: [What this integration does not cover]

### 1.3 Architecture Diagram
[Include diagram showing systems, data flow, and key components]

## 2. Authentication & Authorization

### 2.1 Authentication Method
[OAuth 2.0 / API Key / JWT / mTLS]

### 2.2 Credential Management
[How credentials are obtained, stored, and rotated]

## 3. Endpoints

[Detailed endpoint specifications]

## 4. Data Models

[Complete schema definitions]

## 5. Error Handling

[Error codes and recovery procedures]

## 6. Rate Limiting

[Throttling rules and quotas]

## 7. Testing

[Test scenarios and validation criteria]

身份验证规范

authentication:
  type: "Bearer Token (OAuth 2.0)"
  flow: "Client Credentials"

  endpoints:
    token:
      url: "https://api.example.com/oauth/token"
      method: "POST"
      content_type: "application/x-www-form-urlencoded"

  request:
    grant_type: "client_credentials"
    client_id: "{CLIENT_ID}"
    client_secret: "{CLIENT_SECRET}"
    scope: "read write"

  response:
    access_token: "string"
    token_type: "Bearer"
    expires_in: 3600
    scope: "read write"

  usage:
    header: "Authorization: Bearer {access_token}"
    content_type: "application/json"

  token_refresh:
    automatic: true
    threshold_seconds: 300  # Refresh 5 min before expiry
    retry_attempts: 3
    retry_delay_seconds: 5

  security_requirements:
    - "Store credentials in secure vault (not in code)"
    - "Use HTTPS for all requests"
    - "Implement token caching to reduce auth calls"
    - "Log authentication failures for monitoring"

端点文档标准

# POST /api/v1/orders

endpoint:
  method: "POST"
  path: "/api/v1/orders"
  description: "Create a new order in the system"

headers:
  required:
    Authorization: "Bearer {access_token}"
    Content-Type: "application/json"
    X-Request-ID: "string (UUID) - for request tracing"
  optional:
    X-Idempotency-Key: "string - prevents duplicate processing"

request:
  body:
    type: "object"
    required: ["customer_id", "items"]
    properties:
      customer_id:
        type: "string"
        description: "Unique customer identifier"
        constraints: "max 50 characters, alphanumeric"
        example: "CUST-12345"
      items:
        type: "array"
        minItems: 1
        maxItems: 100
        items:
          type: "object"
          required: ["product_id", "quantity"]
          properties:
            product_id:
              type: "string"
              description: "Product SKU"
              example: "SKU-001"
            quantity:
              type: "integer"
              minimum: 1
              maximum: 999
              example: 2
            unit_price:
              type: "number"
              format: "decimal"
              description: "Price per unit (2 decimal places)"
              example: 29.99
      shipping_address:
        type: "object"
        required: ["street", "city", "postal_code", "country"]
        properties:
          street:
            type: "string"
            maxLength: 100
          city:
            type: "string"
            maxLength: 50
          postal_code:
            type: "string"
            pattern: "^\\d{5}(-\\d{4})?$"
          country:
            type: "string"
            format: "ISO 3166-1 alpha-2"

responses:
  201:
    description: "Order created successfully"
    body:
      order_id: "ORD-12345678"
      status: "pending"
      total_amount: 299.99
      currency: "USD"
      created_at: "2024-01-15T10:30:00Z"
      estimated_delivery: "2024-01-20T10:00:00Z"
      tracking_url: "https://api.example.com/orders/ORD-12345678/track"

  400:
    description: "Invalid request"
    body:
      error_code: "VALIDATION_ERROR"
      message: "Request validation failed"
      details:
        - field: "items[0].quantity"
          error: "Must be between 1 and 999"

  401:
    description: "Authentication failed"
    body:
      error_code: "UNAUTHORIZED"
      message: "Invalid or expired access token"

  409:
    description: "Conflict"
    body:
      error_code: "DUPLICATE_ORDER"
      message: "Order with this idempotency key already exists"
      existing_order_id: "ORD-12345678"

  429:
    description: "Rate limit exceeded"
    headers:
      Retry-After: "60"
      X-RateLimit-Limit: "100"
      X-RateLimit-Remaining: "0"
      X-RateLimit-Reset: "1704067200"

错误处理规范

error_format:
  standard_response:
    error_code: "string - machine-readable error code"
    message: "string - human-readable description"
    details: "array - specific field errors (optional)"
    request_id: "string - for support reference"
    timestamp: "string - ISO 8601 datetime"

error_codes:
  VALIDATION_ERROR:
    http_status: 400
    description: "Request body failed validation"
    retry_strategy: "Do not retry - fix request and resubmit"
    resolution: "Check error details for specific field issues"

  INVALID_CUSTOMER:
    http_status: 400
    description: "Customer ID not found or inactive"
    retry_strategy: "Do not retry - verify customer data"
    resolution: "Validate customer exists and has active status"

  UNAUTHORIZED:
    http_status: 401
    description: "Invalid or expired authentication"
    retry_strategy: "Refresh token and retry once"
    resolution: "Obtain new access token"

  FORBIDDEN:
    http_status: 403
    description: "Insufficient permissions"
    retry_strategy: "Do not retry"
    resolution: "Contact admin to verify API scopes"

  NOT_FOUND:
    http_status: 404
    description: "Requested resource does not exist"
    retry_strategy: "Do not retry"
    resolution: "Verify resource ID is correct"

  CONFLICT:
    http_status: 409
    description: "Resource state conflict"
    retry_strategy: "Fetch current state and reconcile"
    resolution: "Check existing resource and merge changes"

  RATE_LIMIT_EXCEEDED:
    http_status: 429
    description: "Too many requests"
    retry_strategy: "Wait for Retry-After header duration"
    resolution: "Implement exponential backoff"
    headers:
      Retry-After: "Seconds to wait before retry"
      X-RateLimit-Reset: "Unix timestamp when limit resets"

  INTERNAL_ERROR:
    http_status: 500
    description: "Unexpected server error"
    retry_strategy: "Retry with exponential backoff (max 3 attempts)"
    resolution: "If persists, contact support with request_id"

  SERVICE_UNAVAILABLE:
    http_status: 503
    description: "Service temporarily unavailable"
    retry_strategy: "Retry with exponential backoff"
    resolution: "Check status page, retry after delay"

Webhook 规范

webhooks:
  overview:
    description: "Real-time event notifications via HTTP POST"
    delivery: "At-least-once delivery guarantee"
    format: "JSON payload with HMAC signature"

  configuration:
    endpoint_url: "Your HTTPS endpoint"
    secret_key: "Shared secret for signature verification"
    events: ["order.created", "order.updated", "order.cancelled"]

  security:
    signature_header: "X-Webhook-Signature"
    signature_algorithm: "HMAC-SHA256"
    timestamp_header: "X-Webhook-Timestamp"
    replay_prevention: "Reject if timestamp > 5 minutes old"

  verification_example:
    python: |
      import hmac
      import hashlib

      def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
          expected = hmac.new(
              secret.encode(),
              payload,
              hashlib.sha256
          ).hexdigest()
          return hmac.compare_digest(f"sha256={expected}", signature)

  payload_structure:
    event_id: "string - unique event identifier"
    event_type: "string - e.g., order.created"
    timestamp: "string - ISO 8601"
    data:
      object_type: "string - e.g., order"
      object_id: "string - resource identifier"
      changes: "object - changed fields (for update events)"

  retry_policy:
    attempts: 5
    schedule:
      - "Immediate"
      - "1 minute"
      - "5 minutes"
      - "30 minutes"
      - "2 hours"
    success_criteria: "HTTP 2xx response within 30 seconds"
    failure_action: "Event logged, alert sent, manual retry available"

  expected_response:
    status: "2xx within 30 seconds"
    body: "Optional - ignored"

  events:
    order.created:
      description: "Fired when a new order is created"
      payload:
        order_id: "string"
        customer_id: "string"
        total_amount: "number"
        items: "array"
        created_at: "string"

    order.updated:
      description: "Fired when order status changes"
      payload:
        order_id: "string"
        previous_status: "string"
        current_status: "string"
        updated_at: "string"

速率限制规范

rate_limits:
  default:
    requests_per_minute: 100
    requests_per_day: 10000
    burst_allowance: "150% for up to 30 seconds"

  per_endpoint:
    "/api/v1/orders":
      method: "POST"
      limit: "100 requests/minute"
      reason: "Write operation - higher resource cost"

    "/api/v1/orders":
      method: "GET"
      limit: "300 requests/minute"
      reason: "Read operation - cached responses"

    "/api/v1/search":
      limit: "60 requests/minute"
      reason: "Expensive search operation"

  headers:
    X-RateLimit-Limit: "Requests allowed per window"
    X-RateLimit-Remaining: "Requests remaining"
    X-RateLimit-Reset: "Unix timestamp when window resets"

  exceeded_response:
    status: 429
    body:
      error_code: "RATE_LIMIT_EXCEEDED"
      message: "Rate limit exceeded"
      retry_after: 60

  best_practices:
    - "Implement client-side rate limiting"
    - "Use exponential backoff on 429 responses"
    - "Cache responses where possible"
    - "Batch operations when available"

时序图示例

sequenceDiagram
    participant Client
    participant API Gateway
    participant Order Service
    participant Payment Service
    participant Inventory Service
    participant Notification Service

    Client->>API Gateway: POST /api/v1/orders
    API Gateway->>API Gateway: Validate Token
    API Gateway->>Order Service: Create Order

    Order Service->>Inventory Service: Reserve Items
    Inventory Service-->>Order Service: Reservation Confirmed

    Order Service->>Payment Service: Process Payment
    Payment Service-->>Order Service: Payment Success

    Order Service->>Order Service: Update Order Status
    Order Service-->>API Gateway: Order Created (201)
    API Gateway-->>Client: Order Response

    Order Service--)Notification Service: order.created Event
    Notification Service--)Client: Webhook: order.created

测试场景

test_scenarios:
  happy_path:
    name: "Successful order creation"
    preconditions:
      - "Valid customer account exists"
      - "Products are in stock"
      - "Payment method is valid"
    request:
      method: "POST"
      path: "/api/v1/orders"
      body: "{valid order payload}"
    expected:
      status: 201
      response_contains: ["order_id", "status", "total_amount"]
    postconditions:
      - "Order record created in database"
      - "Inventory reserved"
      - "Payment processed"
      - "Webhook sent"

  validation_errors:
    - name: "Missing required field"
      request: "{order without customer_id}"
      expected_status: 400
      expected_error: "VALIDATION_ERROR"

    - name: "Invalid quantity"
      request: "{order with quantity: 0}"
      expected_status: 400
      expected_error: "VALIDATION_ERROR"

  edge_cases:
    - name: "Insufficient inventory"
      setup: "Set product stock to 0"
      expected_status: 409
      expected_error: "INSUFFICIENT_INVENTORY"

    - name: "Payment failure"
      setup: "Configure payment service to decline"
      expected_status: 402
      expected_error: "PAYMENT_FAILED"
      postcondition: "Inventory reservation released"

  idempotency:
    name: "Duplicate request handling"
    steps:
      - "Send order with X-Idempotency-Key: abc123"
      - "Response: 201 Created, order_id: ORD-001"
      - "Send same request with same idempotency key"
      - "Response: 200 OK, order_id: ORD-001 (same order)"

环境配置

environments:
  sandbox:
    base_url: "https://api-sandbox.example.com"
    purpose: "Development and testing"
    rate_limits: "10x production limits"
    data: "Test data, reset daily at 00:00 UTC"
    credentials: "Separate sandbox API keys"

  staging:
    base_url: "https://api-staging.example.com"
    purpose: "Pre-production validation"
    rate_limits: "Same as production"
    data: "Anonymized production-like data"

  production:
    base_url: "https://api.example.com"
    sla:
      uptime: "99.9%"
      response_time_p95: "<200ms"
      response_time_p99: "<500ms"
    maintenance_window: "Sundays 02:00-04:00 UTC"
    support: "[email protected]"

最佳实践

1. 对所有内容进行版本控制 — 在 URL 和标头中指定版本
2. 幂等性 — 记录幂等操作
3. 错误详情 — 提供足够的调试信息
4. 速率限制透明度 — 始终在 headers 中返回限制信息
5. Webhook 可靠性 — 重试策略和签名验证
6. 环境一致性 — sandbox 应尽可能接近 production