数据模型：通用HTTP客户端多平台账户管理

版本: 1.0.0 创建日期: 2025-09-28 目标: 定义HTTP客户端库的核心实体、关系和数据流

核心实体

HttpClient

统一HTTP客户端的主要实体，管理所有平台请求。

interface HttpClient {
  // 标识
  id: string
  name: string

  // 配置
  globalConfig: GlobalConfig
  adapters: Map<PlatformType, PlatformAdapter>

  // 状态
  status: 'active' | 'paused' | 'closed'
  health: HealthStatus
  metrics: PerformanceMetrics

  // 连接管理
  connectionPools: Map<PlatformType, ConnectionPool>
  activeRequests: Set<string>

  // 关系
  accounts: Map<string, PlatformAccount>
  requestHistory: RequestLog[]
}

PlatformAccount

代表单个交易平台上的账户。

interface PlatformAccount {
  // 标识
  accountId: string
  platform: PlatformType
  alias?: string

  // 认证信息
  credentials: AccountCredentials
  authContext: AuthenticationContext

  // 配置
  config: PlatformAccountConfig

  // 状态
  status: 'active' | 'suspended' | 'expired'
  lastActivity: Date

  // 统计
  requestCount: number
  successRate: number
  averageResponseTime: number

  // 关系
  activeRequests: Map<string, ActiveRequest>
  rateLimitState: RateLimitState
}

HTTPRequest

标准化的HTTP请求实体。

interface HTTPRequest {
  // 标识
  id: string
  correlationId?: string
  idempotencyKey?: string

  // 路由信息
  platform: PlatformType
  accountId: string

  // HTTP配置
  method: HttpMethod
  url: string
  headers: Record<string, string>
  body?: RequestBody

  // 选项
  timeout: TimeoutConfig
  retry: RetryConfig
  proxy: ProxyConfig

  // 状态
  status: RequestStatus
  createdAt: Date
  startedAt?: Date
  completedAt?: Date

  // 关系
  response?: HTTPResponse
  attempts: RequestAttempt[]
}

HTTPResponse

标准化的HTTP响应实体。

interface HTTPResponse {
  // 关联
  requestId: string

  // HTTP信息
  status: number
  statusText: string
  headers: Record<string, string>
  data: ResponseData

  // 元数据
  metadata: ResponseMetadata

  // 平台特定
  platformData?: Record<string, any>
  rateLimit?: RateLimitInfo

  // 时间信息
  receivedAt: Date
  processedAt: Date

  // 验证
  validated: boolean
  validationErrors?: ValidationError[]
}

AuthenticationContext

管理平台特定的认证信息和状态。

interface AuthenticationContext {
  // 标识
  accountId: string
  platform: PlatformType

  // 认证配置
  authType: AuthType
  algorithm?: SignatureAlgorithm

  // 凭据引用
  credentialManagerRef: string

  // 状态
  isValid: boolean
  expiresAt?: Date
  lastRefresh: Date

  // 签名信息
  nonce?: number
  timestamp?: number

  // 错误状态
  lastError?: AuthError
  failureCount: number
}

PlatformConfiguration

存储平台特定的配置和限制。

interface PlatformConfiguration {
  // 平台标识
  platform: PlatformType

  // 网络配置
  baseUrl: string
  endpoints: EndpointConfig

  // 超时配置
  timeouts: TimeoutConfig

  // 重试配置
  retryPolicy: RetryConfig

  // 速率限制
  rateLimits: RateLimitConfig[]

  // 认证配置
  authConfig: AuthConfig

  // 代理配置
  proxyConfig?: ProxyConfig

  // 性能参数
  connectionPool: ConnectionPoolConfig

  // 验证规则
  requestValidation: ValidationRule[]
  responseValidation: ValidationRule[]
}

实体关系

主要关系

erDiagram
    HttpClient ||--o{ PlatformAccount : manages
    HttpClient ||--o{ HTTPRequest : processes
    HttpClient ||--|| GlobalConfig : configured_by

    PlatformAccount ||--|| AuthenticationContext : authenticated_by
    PlatformAccount ||--o{ HTTPRequest : initiates
    PlatformAccount ||--|| PlatformConfiguration : configured_by

    HTTPRequest ||--o| HTTPResponse : produces
    HTTPRequest ||--o{ RequestAttempt : includes

    AuthenticationContext }|--|| CredentialManager : uses

    PlatformConfiguration ||--o{ RateLimitConfig : defines
    PlatformConfiguration ||--o{ ValidationRule : contains

关系说明

HttpClient ↔ PlatformAccount: 一对多关系，一个客户端管理多个平台账户
PlatformAccount ↔ HTTPRequest: 一对多关系，一个账户可发起多个请求
HTTPRequest ↔ HTTPResponse: 一对一关系，每个请求产生一个响应
PlatformAccount ↔ AuthenticationContext: 一对一关系，每个账户有唯一认证上下文
AuthenticationContext ↔ CredentialManager: 多对一关系，多个上下文共享凭据管理器

数据流

请求处理流程

sequenceDiagram
    participant Client as 调用方
    participant HC as HttpClient
    participant PA as PlatformAccount
    participant Auth as AuthContext
    participant Adapter as PlatformAdapter
    participant API as 平台API

    Client->>HC: request(HttpClientRequest)
    HC->>PA: 获取账户信息
    PA->>Auth: 获取认证上下文
    Auth->>Auth: 验证凭据有效性
    HC->>Adapter: prepareRequest()
    Adapter->>Auth: 签名请求
    Auth-->>Adapter: 签名结果
    Adapter->>API: 发送HTTP请求
    API-->>Adapter: HTTP响应
    Adapter->>HC: processResponse()
    HC->>Client: HttpClientResponse

状态变化

请求状态转换

stateDiagram-v2
    [*] --> Created : 创建请求
    Created --> Queued : 加入队列
    Queued --> Preparing : 预处理
    Preparing --> Authenticating : 认证签名
    Authenticating --> Sending : 发送请求
    Sending --> Waiting : 等待响应
    Waiting --> Processing : 处理响应
    Processing --> Completed : 完成
    Processing --> Failed : 失败

    Sending --> Retrying : 重试
    Waiting --> Retrying : 超时重试
    Retrying --> Sending : 重新发送
    Retrying --> Failed : 重试耗尽

    Failed --> [*]
    Completed --> [*]

账户状态转换

stateDiagram-v2
    [*] --> Initializing : 初始化
    Initializing --> Active : 认证成功
    Initializing --> Suspended : 认证失败

    Active --> Processing : 处理请求
    Processing --> Active : 请求完成
    Processing --> RateLimited : 触发限制

    RateLimited --> Active : 限制解除
    Active --> Suspended : 多次失败
    Suspended --> Active : 重新激活

    Active --> Expired : 凭据过期
    Expired --> Active : 更新凭据

    Suspended --> [*]
    Expired --> [*]

数据验证规则

请求验证

interface RequestValidationRules {
  // 基本验证
  requiredFields: string[]

  // 平台特定验证
  platformRules: {
    [K in PlatformType]: {
      urlPattern: RegExp
      methodAllowed: HttpMethod[]
      bodySchema?: JSONSchema
      headerRequired?: string[]
    }
  }

  // 业务验证
  accountValidation: {
    mustBeActive: boolean
    rateLimitCheck: boolean
    balanceCheck?: boolean
  }
}

响应验证

interface ResponseValidationRules {
  // HTTP状态验证
  expectedStatus: number[]

  // 内容验证
  contentType: string[]
  dataSchema?: JSONSchema

  // 平台特定验证
  platformValidation: {
    [K in PlatformType]: {
      errorCodeMapping: Record<string, string>
      successIndicators: string[]
      rateLimitHeaders?: string[]
    }
  }
}

性能模型

度量实体

interface PerformanceMetrics {
  // 时间指标
  responseTime: {
    average: number
    p95: number
    p99: number
  }

  // 成功率指标
  successRate: {
    overall: number
    byPlatform: Record<PlatformType, number>
    byTimeWindow: TimeWindowMetrics[]
  }

  // 吞吐量指标
  throughput: {
    requestsPerSecond: number
    concurrentRequests: number
    peakConcurrency: number
  }

  // 资源使用
  resourceUsage: {
    connectionPoolUtilization: number
    memoryUsage: number
    cpuUsage: number
  }
}

容量规划

interface CapacityModel {
  // 目标性能
  targets: {
    maxResponseTime: number // 100ms
    minSuccessRate: number  // 99.9%
    maxConcurrency: number  // 1000
  }

  // 资源限制
  limits: {
    maxConnectionsPerPlatform: number // 20
    maxQueueSize: number             // 100
    maxRetryAttempts: number         // 3
  }

  // 扩展策略
  scaling: {
    connectionPoolGrowth: 'linear' | 'exponential'
    queueOverflowStrategy: 'drop' | 'block' | 'spillover'
    rateLimitHandling: 'queue' | 'reject' | 'delay'
  }
}

实体总结: 6个核心实体，15个支持实体，完整的状态管理和数据流定义，为后续实现提供清晰的数据模型基础。

data-model.md 8.5 KB History Raw