1 Gateway 宣贯文档

1.1 文档目标

本文用于团队内部宣贯 gateway 的设计价值、架构能力、配置方法、扩展路径与测试方式，帮助研发、测试、运维快速建立统一认知，降低接入和联调成本。

1.2 背景与价值

在多协议、多业务并行演进的场景下，直接在业务服务侧处理接入协议会带来以下问题：

• 协议适配逻辑分散，重复开发成本高
• 业务服务与接入细节耦合，迭代风险大
• 新业务上线需要跨多个模块改造，交付周期长

gateway 的核心价值：

• 统一入口：支持 HTTP、私有 TCP、MQTT 等协议接入
• 统一抽象：通过 Context/Message 统一请求模型
• 插件化扩展：接入插件与业务插件可独立扩展
• 配置驱动：路由与服务映射通过 YAML 管理
• 高性能处理：事件驱动 + 线程池（ThreadPool）异步处理

1.3 架构总览

gateway 采用分层插件化架构：

• 接入层（Access Layer）：协议适配（HTTP/TCP）
• 核心框架（Core Framework）：配置、插件、路由、上下文管理
• 业务层（Business Layer）：Service/Action/Topic 业务处理

1.3.1 分层设计图（逻辑视图）

flowchart LR
    Client["Client（客户端）"] --> Access["Access Layer（接入层）\nHTTP/TCP/MQTT"]
    Access --> Core["Core Framework（核心框架）\nConfigManager / PluginManager / Router / Context"]
    Core --> Biz["Business Layer（业务层）\nApiBusinessPlugin / TopicBusinessPlugin"]
    Biz --> DC["DataCenter（后端服务）"]

    Core -. "插件加载" .-> Access
    Core -. "插件加载" .-> Biz

1.3.2 请求处理设计图（时序视图）

sequenceDiagram
    participant C as Client（客户端）
    participant A as AccessPlugin
    participant R as Router
    participant B as BusinessPlugin
    participant D as DataCenter

    C->>A: 协议请求（HTTP/TCP）
    A->>A: 协议解析 + 构建 Context
    A->>R: route(context)
    R->>R: 路由匹配 + 参数提取
    R->>B: process(context)
    B->>D: 调用后端服务
    D-->>B: 业务响应
    B-->>A: 回填 Context 响应
    A-->>C: 协议响应

请求主链路：

1. AccessPlugin 接收请求并构建 Context
2. Router 根据 pattern 与 priority 匹配路由
3. BusinessPlugin 处理业务并调用后端
4. Context 统一回包到对应协议连接

1.4 运行机制

1.4.1 初始化阶段

• 读取 gateway.yaml
• 加载接入层与业务层插件动态库
• 初始化路由规则、线程池与事件循环

1.4.2 启动阶段

• 先启动业务插件，再启动接入插件
• 接入插件注册路由回调后监听端口

1.4.3 消息处理阶段

• 协议消息标准化为 Context/Message
• 路由匹配并提取路径参数（如 namespace/service/cmd）
• 业务插件处理并回填响应
• 长短连接由协议上下文控制（如 TCP is_last）

1.5 配置体系（gateway.yaml）

核心配置分四块：

• server：线程数等全局配置
• access_plugins：接入插件名称、端口、动态库路径
• routes：路径模式、业务插件映射、优先级
• business_plugins：业务插件路径与服务配置

实践建议：

• 路由按“精确优先、通配兜底”设计
• 高优先级规则放前且做冲突检查
• 插件命名、通道命名保持一致规范

1.6 扩展指南

1.6.1 新增接入协议（Access Plugin）

最小步骤：

1. 实现 AccessPlugin 接口
2. 完成协议到 Context/Message 的转换
3. 导出 createPlugin 工厂函数
4. 在 access_plugins 中新增配置

1.6.2 新增业务能力（Business Plugin）

最小步骤：

1. 实现 BusinessPlugin 接口
2. 解析 metadata 并处理业务逻辑
3. 调用后端服务并回填响应
4. 在 business_plugins 与 routes 中绑定

1.6.3 扩展边界说明

当前文档中提到的 FilterChain、部分限流和热更新能力为预留或未完全落地能力，宣贯时应明确“现状能力”与“规划能力”的边界，避免错误预期。

1.7 测试与验收建议

推荐以 tcp_access_test_tool 覆盖三种模式：

• Service：请求-响应正确性
• Action：异步与状态回传正确性
• Topic：订阅、推送、退订闭环

建议验收指标：

• 功能正确率：请求成功率、错误码准确性
• 性能指标：吞吐、延迟、连接稳定性
• 稳定性指标：长稳运行、异常恢复、资源占用

1.8 使用示例（可直接演示）

1.8.1 路由 + 业务配置最小示例

routes:
  - pattern: /api/{namespace}/{service}/{cmd}
    business: api
    priority: 10

business_plugins:
  - name: api
    path: dc_api_plugin.so
    enabled: true
    config:
      services:
        core:
          - name: param
            channel: parameter_server
            type: service
            cmd:
              - name: query
                reqType: ParamMsg.SearchParasReq
                rspType: ParamMsg.SearchRspsMsg

1.8.2 HTTP 调用示例

curl -X POST "http://127.0.0.1:8200/api/core/param/query" \
  -H "Content-Type: application/json" \
  -d '{"id": 1001, "key": "demo"}'

预期结果：

• URL 中的 core/param/query 被路由提取为 namespace/service/cmd
• api 业务插件根据配置找到对应命令并转发到后端

1.8.3 TCP 测试工具示例（Service 模式）

{
  "host": "127.0.0.1",
  "port": 8202,
  "url": "/api/core/param/query",
  "verbose": true,
  "reqTypeName": "ParamMsg.SearchParasReq",
  "rspTypeName": "ParamMsg.SearchRspsMsg",
  "requestBody": {
    "id": 1001,
    "key": "demo"
  },
  "clientCount": 1,
  "frequency": 10,
  "messageCount": 100
}

运行方式：

./tcp_access_test_tool -c test_config.json

1.8.4 Topic 订阅示例（TCP）

{
  "host": "127.0.0.1",
  "port": 8202,
  "url": "/topic/core/test",
  "verbose": true,
  "requestBody": "subscribe /aa/bb/",
  "topicName": "/aa/bb/",
  "messageCount": 10
}

1.9 常见问题（FAQ）

1.9.1 路由不生效

• 检查 pattern 与实际 URL 是否一致
• 检查 business 名称是否与插件名一致
• 检查优先级是否被其他规则覆盖

1.9.2 插件加载失败

• 检查动态库路径与部署目录
• 检查是否正确导出 createPlugin
• 检查插件依赖库是否齐全

1.9.3 TCP 响应异常

• 检查消息封包格式（长度头 + protobuf 体）
• 检查 message_id 是否透传一致
• 检查 is_last 语义是否符合业务模式