Techlex网关 - 接入指南

本文档介绍如何接入 Techlex 网关服务，包括环境说明、鉴权机制、签名算法、请求规范及常见问题处理。

**适用对象：** 需要调用网关接口的内部系统或外部系统开发人员

---

## 一、环境说明

### 1.1 网关地址

| 环境 | 内部网关 | 外部网关 |
|------|----------|----------|
| UAT | `https://tsg-uat-internal.tqsys.cn` | `https://tsg-uat-external.tqls.cn` |
| VER | `https://tsg-ver-internal.tqsys.cn` | `https://tsg-ver-external.tqls.cn` |
| 生产环境`铁骑` | `https://tsg-prd-internal.tqsys.cn` | `https://tsg-prd-external.tqls.cn` |
| 生产环境`圣迪乐` | `https://tsg-prd-internal.sundaily.cn` | `https://tsg-prd-external.sundaily.cn` |

> **接入原则**：部署在公司内部的系统接入内部网关，外部系统接入外部网关 (京东、淘宝、支付宝等为外部系统)

### 1.2 请求路径规则

完整请求路径格式：`{网关域名}{接口路径}`

**示例：**
```
https://tsg-uat-internal.tqsys.cn/api/service/abc
```

---

## 二、快速开始

### 2.1 申请凭证

向网关服务方申请以下凭证：
- **appKey**：应用标识（AK）
- **appSecret**：应用密钥（SK）
- **SSystem**：源系统标识，标识文档：https://doc.tqsys.cn/doc/340
- **DSystem**：目标系统标识，标识文档：https://doc.tqsys.cn/doc/340

### 2.2 调用流程

```
1. 获取凭证（appKey + appSecret）
   ↓
2. 生成签名（timestamp + path + version + appSecret）
   ↓
3. 组装请求头（7个必填参数）
   ↓
4. 发起 HTTP 请求
   ↓
5. 处理响应结果
```

---

## 三、签名算法

### 3.1 代码实现

#### Java 实现（内部系统）

**方式一：Java源代码实现**

```java
/**
 * 生成 Techlex 网关签名参数
 * 
 * @param url       请求URL
 * @param appKey    应用密钥，用于标识调用方身份
 * @param appSecret 应用密钥，用于生成签名摘要
 * @return 包含签名所需参数的Map，需将其中的键值对添加到HTTP请求头中
 */
public Map<String, String> getSignMap(String url, String appKey, String appSecret) {
    Logger log = LoggerFactory.getLogger(Object.class);
    log.info("生成 Techlex 网关签名参数开始，url: {}, appKey: {}", url, appKey);
    Map<String, String> map = new HashMap<>();

try {
        String timestamp = String.valueOf(LocalDateTime.now().toInstant(ZoneOffset.of("+8")).toEpochMilli());
        map.put("timestamp", timestamp);
        map.put("version", "1.0.0");
        map.put("path", cn.hutool.core.util.URLUtil.url(url).getPath()); // 获取请求路径（验签时仅使用请求路径，不包含参数）

// 参数排序并拼接
        List<String> storedKeys = Arrays.stream(map.keySet().toArray(new String[]{}))
                .sorted(Comparator.naturalOrder())
                .collect(Collectors.toList());
        
        final String sign = storedKeys.stream()
                .map(key -> String.join("", key, map.get(key)))
                .collect(Collectors.joining())
                .trim()
                .concat(appSecret);
        
        // MD5加密并转大写
        String signLast = DigestUtils.md5DigestAsHex(sign.getBytes()).toUpperCase();
        
        map.put("appKey", appKey);
        map.put("sign", signLast);
        map.put("GUID", UUID.randomUUID().toString().replaceAll("-", ""));
    } catch (Exception e) {
        log.error(url + " 生成签名参数异常", e);
    }

log.info("生成 Techlex 网关签名参数完成，url: {}, 签名参数: {}", url, map);
    return map;
}
```

**方式二：使用官方 JAR 包**

```xml
<dependency>
    <groupId>com.techlex.web.common</groupId>
    <artifactId>public-common</artifactId>
    <version>0.1.1</version>
</dependency>
```

```java
public static void main(String[] args) throws Exception {
    String server = "";
    String appKey = "";
    String appSecret = "";
    String path = "";
    String timestamp = String.valueOf(
        LocalDateTime.now().toInstant(ZoneOffset.of("+8")).toEpochMilli()
    );
    
    GateWaySign gateWaySign = new GateWaySign(server, appKey, appSecret);
    String sign = gateWaySign.getSign(timestamp, path);
}
```

### 3.2 算法说明

网关采用 MD5 签名机制，确保请求的完整性和时效性。

**签名公式：**
```
sign = MD5(参数拼接字符串 + appSecret).toUpperCase()
```

### 3.3 签名步骤

#### 步骤 1：准备基础参数

| 参数 | 类型 | 说明 | 示例 |
|------|------|------|------|
| timestamp | String | 13位毫秒时间戳（有效期5分钟） | `1571711067186` |
| path | String | 请求路径（不含查询参数） | `/api/service/abc` |
| version | String | 版本号（固定值） | `1.0.0` |

#### 步骤 2：参数排序

按参数名 ASCII 码升序排序：
```
path → timestamp → version
```

#### 步骤 3：拼接字符串

格式：`key1value1key2value2key3value3`

**示例：**
```
path/api/service/abctimestamp1571711067186version1.0.0
```

#### 步骤 4：追加 appSecret

```
path/api/service/abctimestamp1571711067186version1.0.0506EEB535CF740D7A755CB4B9F4A1536
```

#### 步骤 5：MD5 加密并转大写

```
A021BF82BE342668B78CD9ADE593D683
```

---

## 四、请求规范

### 4.1 请求头参数

所有请求必须包含以下 7 个请求头：

| 参数 | 必填 | 说明 | 示例值 |
|------|------|------|--------|
| timestamp | 是 | 签名时间戳（13位毫秒） | `1571711067186` |
| appKey | 是 | 应用标识（AK） | `1TEST123456781` |
| sign | 是 | 签名值（MD5大写） | `A90E66763793BDBC817CF3B52AAAC041` |
| version | 是 | 版本号（固定 `1.0.0`） | `1.0.0` |
| SSystem | 是 | 源系统标识 | `CCS` |
| DSystem | 是 | 目标系统标识 | `SRM` |
| GUID | 是 | 全局唯一标识符（32位） | `B4FC1D3087DF5088ED53B1E0D384DC3A` |

### 4.2 完整请求示例

**场景：** CCS 系统调用 SRM 系统的 `/api/service/abc` 接口

**请求行：**
```http
POST https://tsg-uat-internal.tqsys.cn/api/service/abc
```

**请求头：**
```http
Content-Type: application/json
timestamp: 1571711067186
appKey: 1TEST123456781
sign: A90E66763793BDBC817CF3B52AAAC041
version: 1.0.0
SSystem: CCS
DSystem: SRM
GUID: B4FC1D3087DF5088ED53B1E0D384DC3A
```

**请求体：**
```json
{
    "param1": "value1",
    "param2": "value2"
}
```

### 4.3 cURL 示例

```bash
curl -X POST 'https://tsg-uat-internal.tqsys.cn/api/service/abc' \
  -H 'Content-Type: application/json' \
  -H 'timestamp: 1571711067186' \
  -H 'appKey: 1TEST123456781' \
  -H 'sign: A90E66763793BDBC817CF3B52AAAC041' \
  -H 'version: 1.0.0' \
  -H 'SSystem: CCS' \
  -H 'DSystem: SRM' \
  -H 'GUID: B4FC1D3087DF5088ED53B1E0D384DC3A' \
  -d '{"param1": "value1"}'
```

---

## 五、错误处理

### 5.1 网关层错误

| 错误码 | 错误信息 | 原因 | 解决方案 |
|--------|----------|------|----------|
| 401 | `sign parameters are incomplete!` | 签名参数缺失 | 检查请求头是否包含全部 7 个必填参数 |
| 401 | `signature value is error!` | 签名值错误 | 1. 验证 appKey/appSecret 是否正确<br>2. 检查签名算法逻辑<br>3. 确认时间戳未过期 |
| -107 | `divide:Can not find selector` | DSystem 配置错误 | 联系网关管理员确认 DSystem 值 |
| -102 | `divide:Rule not found!` | 路由规则未配置 | 确认请求路径是否在网关中注册 |
| -119 | `Can not find healthy upstream url` | 上游服务不可用 | 检查 DSystem 对应的后端服务状态 |

### 5.2 业务层错误

| 错误码 | 说明 | 处理方式 |
|--------|------|----------|
| 500 | 下游系统内部错误 | 联系下游系统负责人排查 |
| 504 | 网关超时 | 检查下游系统响应时间（默认超时 60 秒） |
| 200 | 请求成功 | 解析 `data` 字段获取业务数据 |

### 5.3 排查建议

**签名错误排查清单：**
- [ ] appKey 和 appSecret 是否正确
- [ ] 时间戳是否为 13 位毫秒级
- [ ] 时间戳是否在 5 分钟有效期内
- [ ] path 是否只包含路径（不含查询参数）
- [ ] 参数是否按 ASCII 升序排序
- [ ] MD5 结果是否转为大写
- [ ] GUID 是否全局唯一

---

## 六、注意事项

### 6.1 安全要求

1. **凭证保护**：appSecret 严禁暴露在客户端代码或日志中
2. **时间同步**：确保服务器时间准确，建议配置 NTP 服务
3. **GUID 唯一性**：每次请求必须生成新的 GUID，避免重复
4. **HTTPS 传输**：生产环境必须使用 HTTPS 协议

### 6.2 性能建议

1. **连接复用**：使用连接池复用 HTTP 连接
2. **超时设置**：建议设置合理的连接超时和读取超时
3. **重试机制**：对于 5xx 错误可实现指数退避重试
4. **缓存策略**：对于固定 path 的请求可缓存签名（注意时间戳有效期）

### 6.3 开发建议

1. 先在 UAT 环境完成联调测试
2. 使用 VER 环境进行验收测试
3. 生产环境切换前进行完整回归测试
4. 保留完整的请求日志便于问题排查

---

## 七、常见问题

### Q1：签名一直报错 401？

**A：** 按以下顺序排查：
1. 确认 appKey 和 appSecret 是否正确
2. 打印签名拼接字符串，手动验证 MD5 结果
3. 检查时间戳是否过期（超过 5 分钟）
4. 确认 path 是否只包含路径部分

### Q2：如何获取 SSystem 和 DSystem？

**A：** 这两个参数由网关管理员分配，申请凭证时会一并提供。

### Q3：支持哪些 HTTP 方法？

**A：** 支持 GET、POST、PUT、DELETE 等标准 HTTP 方法，签名算法相同。

### Q4：查询参数需要参与签名吗？

**A：** 不需要。签名仅对请求路径（path）进行验签，查询参数不参与签名计算。

---

## 附录

### A. 术语表

| 术语 | 说明 |
|------|------|
| AK | Access Key，访问密钥标识 |
| SK | Secret Key，密钥 |
| GUID | Globally Unique Identifier，全局唯一标识符 |
| MD5 | Message-Digest Algorithm 5，消息摘要算法 |
| timestamp | 时间戳，13 位毫秒数 |