---
id: TK-MOD-000
type: model
example: true
maturity: draft
tags: [api-client, sdk, architecture]
created: 2026-05-06
last_referenced: null
reference_count: 0
contributors: [alice]
source_project: project-alpha
evidence:
  - project: project-alpha
    date: 2026-05-06
    description: "冷启动导入时从代码结构中提取"
---

# API 客户端类型模型

## 实体定义

系统中有 4 种 API 客户端类型，各自承担不同职责：

| 类型 | 说明 | 连接数 | 消息方向 |
|------|------|--------|---------|
| WEB | 浏览器端 | 1:N（每用户多标签页） | 双向 |
| MOBILE | 移动端 App | 1:N（每用户多设备） | 双向 |
| SERVICE | 内部微服务 | 少量长连接 | 双向 |
| THIRD_PARTY | 第三方系统 | 少量 | 单向调用 |

## 关系

```
WEB/MOBILE ──→ API Gateway ──→ SERVICE
                   ↑
              THIRD_PARTY
```

## 关键约束

- WEB 的 clientId 格式：`WEB_{userId}_{sessionId}`
- MOBILE 的 clientId 格式：`MOBILE_{userId}_{deviceId}`
- SERVICE 使用固定的服务名作为 clientId
- 同一 clientId 不能同时存在两个连接（后连接踢掉前连接）

## 适用场景

涉及 API 网关、客户端鉴权、连接管理的功能开发。